diff --git a/docs/api-reference/agent-run-logs.mdx b/docs/api-reference/agent-run-logs.mdx index fe0457741..68e5fad44 100644 --- a/docs/api-reference/agent-run-logs.mdx +++ b/docs/api-reference/agent-run-logs.mdx @@ -1,14 +1,10 @@ --- -title: "Agent Run Logs API" -sidebarTitle: "Agent Run Logs" +title: "Retrieving Traces" +sidebarTitle: "Retrieving Traces" icon: "list" iconType: "solid" --- - - This endpoint is currently in **ALPHA** status and is subject to change. We welcome your feedback to help improve this API. - - The Agent Run Logs API allows you to retrieve detailed execution logs for agent runs, providing insights into the agent's thought process, tool usage, and execution flow. ## Endpoint @@ -27,12 +23,12 @@ Authorization: Bearer YOUR_API_TOKEN ## Parameters -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `org_id` | integer | Yes | Your organization ID | -| `agent_run_id` | integer | Yes | The ID of the agent run to retrieve logs for | -| `skip` | integer | No | Number of logs to skip for pagination (default: 0) | -| `limit` | integer | No | Maximum number of logs to return (default: 100, max: 100) | +| Parameter | Type | Required | Description | +| -------------- | ------- | -------- | --------------------------------------------------------- | +| `org_id` | integer | Yes | Your organization ID | +| `agent_run_id` | integer | Yes | The ID of the agent run to retrieve logs for | +| `skip` | integer | No | Number of logs to skip for pagination (default: 0) | +| `limit` | integer | No | Maximum number of logs to return (default: 100, max: 100) | ## Response Structure @@ -80,25 +76,25 @@ Each log entry in the `logs` array contains the following fields: ### Core Fields -| Field | Type | Description | -|-------|------|-------------| -| `agent_run_id` | integer | The ID of the agent run this log belongs to | -| `created_at` | string | ISO 8601 timestamp when the log entry was created | -| `message_type` | string | The type of log entry (see [Log Types](#log-types) below) | +| Field | Type | Description | +| -------------- | ------- | --------------------------------------------------------- | +| `agent_run_id` | integer | The ID of the agent run this log belongs to | +| `created_at` | string | ISO 8601 timestamp when the log entry was created | +| `message_type` | string | The type of log entry (see [Log Types](#log-types) below) | ### Agent Reasoning Fields -| Field | Type | Description | -|-------|------|-------------| +| Field | Type | Description | +| --------- | -------------- | --------------------------------------------------------------- | | `thought` | string \| null | The agent's internal reasoning or thought process for this step | ### Tool Execution Fields -| Field | Type | Description | -|-------|------|-------------| -| `tool_name` | string \| null | Name of the tool being executed (e.g., "ripgrep_search", "file_write") | -| `tool_input` | object \| null | JSON object containing the parameters passed to the tool | -| `tool_output` | object \| null | JSON object containing the tool's execution results | +| Field | Type | Description | +| ------------- | ------------------------ | ------------------------------------------------------------------------------ | +| `tool_name` | string \| null | Name of the tool being executed (e.g., "ripgrep_search", "file_write") | +| `tool_input` | object \| null | JSON object containing the parameters passed to the tool | +| `tool_output` | object \| null | JSON object containing the tool's execution results | | `observation` | object \| string \| null | The agent's observation of the tool execution results or other contextual data | ## Log Types @@ -107,35 +103,35 @@ The `message_type` field indicates the type of log entry. Here are the possible ### Plan Agent Types -| Type | Description | -|------|-------------| -| `ACTION` | The agent is executing a tool or taking an action | -| `PLAN_EVALUATION` | The agent is evaluating or updating its plan | -| `FINAL_ANSWER` | The agent is providing its final response or conclusion | -| `ERROR` | An error occurred during execution | -| `USER_MESSAGE` | A message from the user (e.g., interruptions or additional context) | -| `USER_GITHUB_ISSUE_COMMENT` | A comment from a GitHub issue that the agent is processing | +| Type | Description | +| --------------------------- | ------------------------------------------------------------------- | +| `ACTION` | The agent is executing a tool or taking an action | +| `PLAN_EVALUATION` | The agent is evaluating or updating its plan | +| `FINAL_ANSWER` | The agent is providing its final response or conclusion | +| `ERROR` | An error occurred during execution | +| `USER_MESSAGE` | A message from the user (e.g., interruptions or additional context) | +| `USER_GITHUB_ISSUE_COMMENT` | A comment from a GitHub issue that the agent is processing | ### PR Agent Types -| Type | Description | -|------|-------------| -| `INITIAL_PR_GENERATION` | The agent is generating the initial pull request | -| `DETECT_PR_ERRORS` | The agent is detecting errors in a pull request | -| `FIX_PR_ERRORS` | The agent is fixing errors found in a pull request | -| `PR_CREATION_FAILED` | Pull request creation failed | -| `PR_EVALUATION` | The agent is evaluating a pull request | +| Type | Description | +| ----------------------- | -------------------------------------------------- | +| `INITIAL_PR_GENERATION` | The agent is generating the initial pull request | +| `DETECT_PR_ERRORS` | The agent is detecting errors in a pull request | +| `FIX_PR_ERRORS` | The agent is fixing errors found in a pull request | +| `PR_CREATION_FAILED` | Pull request creation failed | +| `PR_EVALUATION` | The agent is evaluating a pull request | ### Commit Agent Types -| Type | Description | -|------|-------------| +| Type | Description | +| ------------------- | ------------------------------- | | `COMMIT_EVALUATION` | The agent is evaluating commits | ### Link Types -| Type | Description | -|------|-------------| +| Type | Description | +| ---------------- | ----------------------------------- | | `AGENT_RUN_LINK` | A link to another related agent run | ## Field Population Patterns @@ -143,22 +139,26 @@ The `message_type` field indicates the type of log entry. Here are the possible Different log types populate different fields: ### ACTION Logs + - Always have: `tool_name`, `tool_input`, `tool_output` - Often have: `thought`, `observation` - Example: Tool executions like searching code, editing files, creating PRs ### PLAN_EVALUATION Logs + - Always have: `thought` - May have: `observation` - Rarely have: Tool-related fields - Example: Agent reasoning about next steps ### ERROR Logs + - Always have: `observation` (containing error details) - May have: `tool_name` (if error occurred during tool execution) - Example: Failed tool executions or system errors ### FINAL_ANSWER Logs + - Always have: `observation` (containing the final response) - May have: `thought` - Example: Agent's final response to the user @@ -208,12 +208,12 @@ while True: url = f"https://api.codegen.com/v1/organizations/67890/agent/run/12345/logs?skip={skip}&limit={limit}" response = requests.get(url, headers=headers) data = response.json() - + all_logs.extend(data['logs']) - + if len(data['logs']) < limit: break # No more logs - + skip += limit print(f"Retrieved {len(all_logs)} total logs") @@ -234,26 +234,34 @@ for error_log in error_logs: ## Common Use Cases ### 1. Building Monitoring Dashboards + Use the logs to create dashboards showing: + - Agent execution progress - Tool usage patterns - Error rates and types - Execution timelines ### 2. Debugging Agent Behavior + Analyze logs to understand: + - Why an agent made certain decisions - Where errors occurred in the execution flow - What tools were used and their results ### 3. Audit and Compliance + Track agent actions for: + - Code change auditing - Compliance reporting - Security monitoring ### 4. Performance Analysis + Monitor: + - Tool execution times - Common failure patterns - Agent reasoning efficiency @@ -265,13 +273,13 @@ Monitor: ## Error Responses -| Status Code | Description | -|-------------|-------------| -| 400 | Bad Request - Invalid parameters | -| 401 | Unauthorized - Invalid or missing API token | -| 403 | Forbidden - Insufficient permissions | -| 404 | Not Found - Agent run not found | -| 429 | Too Many Requests - Rate limit exceeded | +| Status Code | Description | +| ----------- | ------------------------------------------- | +| 400 | Bad Request - Invalid parameters | +| 401 | Unauthorized - Invalid or missing API token | +| 403 | Forbidden - Insufficient permissions | +| 404 | Not Found - Agent run not found | +| 429 | Too Many Requests - Rate limit exceeded | ## Feedback and Support @@ -282,6 +290,6 @@ Since this endpoint is in ALPHA, we'd love your feedback! Please reach out throu - Email: support@codegen.com - The structure and fields of this API may change as we gather feedback and improve the service. We'll provide advance notice of any breaking changes. + The structure and fields of this API may change as we gather feedback and + improve the service. We'll provide advance notice of any breaking changes. - diff --git a/docs/api-reference/authentication.mdx b/docs/api-reference/authentication.mdx new file mode 100644 index 000000000..89cc7cc01 --- /dev/null +++ b/docs/api-reference/authentication.mdx @@ -0,0 +1,53 @@ +--- +title: "Authentication" +sidebarTitle: "Authentication" +icon: "key" +--- + +All Codegen API endpoints require authentication using Bearer tokens. You'll need both an API token and your organization ID to get started. + +## Get Your Credentials + + + Visit the developer settings to generate your API token and find your + organization ID. + + +## Required Information + +### API Token + +Your personal API token authenticates all requests to the Codegen API. This token is tied to your user account and inherits your permissions within organizations. + +### Organization ID + +Most API endpoints require an organization ID to specify which organization's resources you want to access. You can find your organization ID in the developer settings. + +## Using Your Credentials + +### REST API + +Include your API token in the Authorization header for all requests: + +```bash +curl -H "Authorization: Bearer YOUR_API_TOKEN" \ + "https://api.codegen.com/v1/organizations/YOUR_ORG_ID/agent/run" +``` + +### Python SDK + +The Python SDK makes authentication simple: + +```python +from codegen import Agent + +# Initialize with your credentials +agent = Agent(org_id="YOUR_ORG_ID", token="YOUR_API_TOKEN") + +# The SDK handles authentication automatically +task = agent.run(prompt="Fix the bug in user authentication") +``` diff --git a/docs/api-reference/overview.mdx b/docs/api-reference/overview.mdx new file mode 100644 index 000000000..fe545009b --- /dev/null +++ b/docs/api-reference/overview.mdx @@ -0,0 +1,132 @@ +--- +title: "Codegen API" +sidebarTitle: "Overview" +icon: "code" +--- + +The Codegen API provides programmatic access to create and manage AI agents, enabling you to integrate Codegen's capabilities into your own applications and workflows. + +## What You Can Do + +**[Create and manage AI agents](/api-reference/agents/create-agent-run)** that can write code, fix bugs, and handle development tasks across your repositories with full programmatic control over their execution and monitoring. **[Access your organization data](/api-reference/organizations/get-organizations)** including users, repositories, integrations, and **[programmatically retrieve detailed agent traces](/api-reference/agent-run-logs)** for analysis and debugging. + + + All agents created through the API are fully configurable and viewable in the + Codegen web UI at codegen.com, allowing seamless integration between + programmatic and manual workflows. + + + + Not seeing a capability you want? Get in touch! Join our [community + Slack](https://community.codegen.com) or email us at support@codegen.com. + + +## Authentication + +All API endpoints require authentication using Bearer tokens and your organization ID. + + + Get your API token and organization ID to start using the Codegen API. + + +## Rate Limits + +The API includes rate limiting to ensure fair usage: + +- **Standard endpoints**: 60 requests per 30 seconds +- **Agent creation**: 10 requests per minute +- **Setup commands**: 5 requests per minute +- **Log analysis**: 5 requests per minute + +## Getting Started + +### 1. Create Your First Agent Run + +```bash +curl -X POST "https://api.codegen.com/v1/organizations/{org_id}/agent/run" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "prompt": "Add error handling to the user authentication function", + "repo_id": 123 + }' +``` + +### 2. Check Agent Status + +```bash +curl "https://api.codegen.com/v1/organizations/{org_id}/agent/run/{agent_run_id}" \ + -H "Authorization: Bearer YOUR_API_KEY" +``` + +### 3. Resume with Follow-up + +```bash +curl -X POST "https://api.codegen.com/v1/organizations/{org_id}/agent/run/resume" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "agent_run_id": 456, + "prompt": "Also add unit tests for the error handling" + }' +``` + +## Use Cases + +**Automated Workflows** + +- Trigger agents from CI/CD pipelines when builds fail +- Create agents in response to issue tracking system events +- Automate code reviews and quality checks + +**Custom Integrations** + +- Build Codegen into your existing development tools +- Create custom dashboards for agent activity +- Integrate with internal systems and workflows + +**Batch Operations** + +- Process multiple repositories with consistent changes +- Generate setup commands for new projects +- Analyze logs across multiple sandbox environments + +## Explore the API + + + Explore all available endpoints with detailed schemas and examples. + + + + Learn how to retrieve and analyze detailed agent execution logs. + + +## SDKs and Tools + +For easier integration, we recommend using our Python SDK which provides a simple wrapper around the API: + + + Use the Codegen Python SDK for a pythonic interface to create and manage + agents programmatically. + + +**Also available:** + +- **[CLI Tool](/introduction/cli)** - Command-line interface for common API operations + + + The API is RESTful and returns JSON responses. All endpoints support standard + HTTP status codes and include detailed error messages for troubleshooting. + diff --git a/docs/capabilities/analytics.mdx b/docs/capabilities/analytics.mdx index 2c9101f68..e8b950d0c 100644 --- a/docs/capabilities/analytics.mdx +++ b/docs/capabilities/analytics.mdx @@ -8,7 +8,11 @@ What impact are code agents having on your codebase (and your finances) today? H Codegen Analytics was built to answer these questions and more. - Analyze cost breakdown + Analyze cost breakdown + Select LLM providers, configure custom API keys, and optimize performance settings. diff --git a/docs/docs.json b/docs/docs.json index d76ccd00e..2ee8e2d51 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -18,6 +18,7 @@ "pages": [ "introduction/overview", "introduction/prompting", + "introduction/support", "introduction/community", "introduction/about", "introduction/faq" @@ -81,34 +82,20 @@ { "tab": "API Reference", "groups": [ + { + "group": "Guides", + "pages": [ + "api-reference/overview", + "api-reference/authentication", + "api-reference/agent-run-logs" + ] + }, { "group": "Endpoints", "openapi": { "source": "/api-reference/openapi3.json", "directory": "api-reference" } - }, - { - "group": "Guides", - "pages": ["api-reference/agent-run-logs"] - } - ] - }, - { - "tab": "Blog", - "groups": [ - { - "group": "Blog", - "pages": ["blog/posts", "blog/devin", "blog/act-via-code"] - } - ] - }, - { - "tab": "Changelog", - "groups": [ - { - "group": "Changelog", - "pages": ["changelog/changelog"] } ] } diff --git a/docs/images/cost-breakdown.png b/docs/images/cost-breakdown.png index 2020d471f..82d20b34c 100644 Binary files a/docs/images/cost-breakdown.png and b/docs/images/cost-breakdown.png differ diff --git a/docs/integrations/integrations.mdx b/docs/integrations/integrations.mdx index 0b27bbdb2..bb25474ea 100644 --- a/docs/integrations/integrations.mdx +++ b/docs/integrations/integrations.mdx @@ -4,7 +4,7 @@ sidebarTitle: "Overview" icon: "plug" --- -Frontier agents can work effectively with hundreds of "tools", enabling them to work seamlessly across your existing development stack. +Codegen agents can work effectively with hundreds of "tools", enabling them to work seamlessly across your existing development stack. + ## Core Development diff --git a/docs/introduction/overview.mdx b/docs/introduction/overview.mdx index aab7d5258..3761da1be 100644 --- a/docs/introduction/overview.mdx +++ b/docs/introduction/overview.mdx @@ -5,15 +5,15 @@ icon: "robot" iconType: "solid" --- -Codegen helps you run frontier code agents at scale. It provides the necessary building blocks (sandboxes, integrations, telemetry) for successful enterprise code agent deployments across thousands of teams today. - -Think of it as an AI coworker that can understand and solve coding challenges, access your codebase instantly, and interact directly with your development tools. +[Codegen](https://codegen.com) helps you run frontier code agents at scale. It provides the necessary building blocks (sandboxes, integrations, telemetry) for successful enterprise code agent deployments across thousands of teams today. Focus on higher-level tasks and leverage Codegen agents to do the low-level labor of software engineering. +Think of it as an AI coworker that can understand and solve coding challenges, access your codebase instantly, and interact directly with your development tools. + ## What Can Codegen Agents Do? Codegen agents come equipped with a versatile set of tools and capabilities: @@ -23,37 +23,29 @@ Codegen agents come equipped with a versatile set of tools and capabilities: Analyze requirements, implement features, fix bugs, write tests, and improve documentation based on your prompts. - - Review PRs, suggest changes, comment on issues, create branches, commit - code, and manage repositories. - - - Update ticket statuses, add comments, link PRs to issues, and create new - tasks based on findings. - - + Send notifications, ask for clarification, report progress, and interact directly with your team in Slack channels. - + + Update statuses, add comments, link PRs to issues, and create new tasks. + Support for Jira, Linear, Clickup and Monday.com. + + + Review PRs, suggest changes, comment on issues, create branches, commit + code, and manage repositories. + + Safely run code, install dependencies, and test changes in an isolated environment. - - Access up-to-date information, research libraries, and find documentation - online. + + Connect with Slack, Linear, Figma, databases, and extend capabilities with + custom MCP tools. @@ -91,22 +83,32 @@ Integrating Codegen into your workflow is designed to be quick and easy: -## Enterprise-Grade Security +## Security & Compliance -Codegen is SOC 2 Type II certified, ensuring your code and data are handled with the highest standards for security, privacy, and compliance. +Codegen is [SOC 2 Type I & II certified](https://codegen.com/security/soc2) and performs regular pen tests, ensuring your code and data are handled with the highest standards for security, privacy, and compliance. -## Ready to Start? +Learn more about our security practices here. - - Codegen is free to install. Get started in just a few clicks. - - Learn how to use Codegen for common code transformation tasks. + Details on Codegen's security practices and more + + + View SOC-2 documents and pen test results + + + +## Install Now + +Create an account via Github OAuth and install our [Github application](https://github.com/apps/codegen-sh) to get started. + + + + Codegen's Github app is free to install. Get started in just a few clicks. diff --git a/docs/introduction/sdk.mdx b/docs/introduction/sdk.mdx index 2c9f7d0ab..833439ac3 100644 --- a/docs/introduction/sdk.mdx +++ b/docs/introduction/sdk.mdx @@ -4,7 +4,7 @@ sidebarTitle: "Python SDK" icon: "python" --- -The [Codegen SDK](https://github.com/codegen-sh/codegen-sdk) enables developers to programmatically interact with [Codegen](https://codegen.com) SWE agents via API. +The [Codegen SDK](https://github.com/codegen-sh/codegen-sdk) is a thin pythonic wrapper around the **[Codegen API](/api-reference/overview)** with all the same capabilities for creating and managing AI agents programmatically. Go to [developer settings](https://codegen.sh/token) to generate an API token @@ -29,30 +29,14 @@ if task.status == "completed": print(task.result) # Result often contains code, summaries, or links ``` - - Codegen agents can research code, create PRs, modify Linear tickets, and more. - - ## Installation -Install the SDK using pip or uv: +Install the [codegen](https://pypi.org/project/codegen/) package from PyPI: ```bash -pip install codegen -# or uv pip install codegen ``` -## What can I do with the Codegen SDK? - -The Codegen SDK is your gateway to programmatically interacting with your AI Software Engineer. You can use it to: - -- **Automate development tasks**: Assign tasks like implementing features, fixing bugs, writing tests, or improving documentation to the agent. -- **Integrate AI into your workflows**: Trigger agent tasks from your CI/CD pipelines, scripts, or other development tools. -- **Provide context and guidance**: Supply the agent with specific instructions, relevant code snippets, or background information to ensure it performs tasks according to your requirements. - -Essentially, the SDK allows you to leverage Codegen's AI capabilities wherever you can run Python code. - ## Get Started import { diff --git a/docs/introduction/support.mdx b/docs/introduction/support.mdx new file mode 100644 index 000000000..5dcfdb223 --- /dev/null +++ b/docs/introduction/support.mdx @@ -0,0 +1,40 @@ +--- +title: "Support" +sidebarTitle: "Support" +icon: "headset" +--- + +Need help with Codegen? We're here to support you every step of the way. + +## Get Help + + + + Email us directly at support@codegen.com for technical issues and questions. + + + + Join our active community for peer support, tips, and discussions. + + + +## Team Plans & Above + +All Team plans and above get a **shared Slack channel with our team** for direct access to Codegen engineers and priority support. + +## Enterprise Support + + + Codegen offers forward deployed engagements for organizations looking for + hands-on implementation support. Get in touch if you need dedicated assistance + with your Codegen deployment. + + + + Response times vary by plan level. Team and Enterprise customers receive + priority support with faster response times. + diff --git a/docs/settings/agent-behavior.mdx b/docs/settings/agent-behavior.mdx index 9dc917f00..320a2015c 100644 --- a/docs/settings/agent-behavior.mdx +++ b/docs/settings/agent-behavior.mdx @@ -9,7 +9,7 @@ Configure the types of behaviors you'd like the AI agent to exhibit. These setti Customize how agents interact with your team and approach code modifications. diff --git a/docs/settings/claude-code.mdx b/docs/settings/claude-code.mdx index 97a02c991..55e8767e6 100644 --- a/docs/settings/claude-code.mdx +++ b/docs/settings/claude-code.mdx @@ -4,7 +4,18 @@ sidebarTitle: "Claude Code" icon: "code" --- -Claude Code is an enhanced agent implementation that leverages Anthropic's Claude Code SDK to provide superior coding capabilities. When enabled, your Codegen agents run within the Claude Code harness by default, offering improved code understanding, generation, and debugging capabilities. +Users can configure Codegen to run Claude Code as the main agent loop. For some organizations and tasks, this can lead to improved agent performance. + + + Enable Claude Code mode in your model configuration settings to enhance agent + capabilities. + + +OpenAI Codex and Gemini CLI support are coming soon. ## What is Claude Code? @@ -25,18 +36,14 @@ Claude Code can be enabled at the organization level through your model configur 3. Toggle the setting to "Enabled" 4. Select your preferred Claude Code model (typically Claude 4 Sonnet) - - Claude Code Settings UI - - ## How It Works When Claude Code is enabled, Codegen automatically: -1. **Agent Selection**: Uses the Claude Code agent implementation instead of the default LangGraph agent -2. **Tool Integration**: Provides access to all Codegen tools through MCP (Model Context Protocol) -3. **Sandbox Environment**: Runs within a specialized Modal sandbox with Claude Code SDK -4. **Validation**: Applies configurable hooks to ensure proper workflow completion +1. **Sandbox Execution**: Runs Claude Code in a secure **[sandbox environment](/sandboxes/overview)** for safe code execution and testing +2. **MCP Integration**: Provides access to all your **[integrations](/integrations/integrations)** through MCP (Model Context Protocol) for seamless tool coordination +3. **Enhanced Logging**: Captures detailed logs using Claude Code hooks, which are displayed in the agent UI on codegen.com for full transparency and debugging +4. **Full Feature Compatibility**: Manages interactions with Slack, Linear, and other project management tools, while maintaining the complete PR lifecycle including **[automatic check fixing](/capabilities/checks-autofixer)** and code reviews ## Key Features @@ -119,16 +126,19 @@ Claude Code is particularly effective for: ### Common Issues **Claude Code not activating:** + - Verify the setting is enabled in organization model configuration - Check that feature flags are properly configured for your organization - Ensure users have the appropriate permissions **Tool integration problems:** + - MCP integration is automatic with Claude Code - no additional configuration needed - Check sandbox logs for any MCP server startup issues - Verify that required tools are available in your organization's configuration **Performance concerns:** + - Claude Code may have slightly different response times compared to standard agents - Monitor usage patterns and adjust model selection if needed - Consider user preferences for performance-sensitive workflows @@ -143,8 +153,8 @@ If you encounter issues with Claude Code: Claude Code is a premium feature that may require specific plan levels or - feature flag enablement. Contact your Codegen representative if you don't - see the Claude Code options in your settings. + feature flag enablement. Contact your Codegen representative if you don't see + the Claude Code options in your settings. ## Migration from Standard Agents diff --git a/docs/settings/model-configuration.mdx b/docs/settings/model-configuration.mdx index 7bb567f54..71bb20159 100644 --- a/docs/settings/model-configuration.mdx +++ b/docs/settings/model-configuration.mdx @@ -1,11 +1,20 @@ --- title: "LLM Configuration" -sidebarTitle: "Model Config" -icon: "brain-circuit" +sidebarTitle: "Model Choice" +icon: "microchip" --- Codegen offers flexibility in choosing the Large Language Model (LLM) that powers your agent, allowing you to select from various providers and specific models. You can also configure custom API keys and base URLs if you have specific arrangements or need to use self-hosted models. + + Choose your LLM provider, select models, and configure custom API keys for + your organization. + + ## Accessing LLM Configuration LLM Configuration settings are applied globally for your entire organization. You can access and modify these settings by navigating to: @@ -26,12 +35,21 @@ As shown in the UI, you can generally configure the following: - Google (Gemini) - **LLM Model:** Once a provider is selected, you can choose a specific model from that provider's offerings (e.g., Claude 4 Sonnet, GPT-4, Gemini Pro). +## Enhanced Agent Modes + +For improved agent performance, you can enable Claude Code mode which runs agents in Anthropic's specialized coding environment: + + + Configure agents to run in Claude Code harness for enhanced coding + capabilities and superior development assistance. + + ## Model Recommendation While Codegen provides access to a variety of models for experimentation and - specific use cases, **we highly encourage the use of Anthropic's Claude 4 Sonnet**. - Our internal testing and prompt engineering are heavily optimized + specific use cases, **we highly encourage the use of Anthropic's Claude 4 + Sonnet**. Our internal testing and prompt engineering are heavily optimized for Claude 4 Sonnet, and it consistently delivers the best performance, reliability, and cost-effectiveness for most software engineering tasks undertaken by Codegen agents. Other models are made available primarily for @@ -40,14 +58,31 @@ As shown in the UI, you can generally configure the following: ## Custom API Keys and Base URLs -For advanced users or those with specific enterprise agreements with LLM providers, Codegen may allow you to use your own API keys and, in some cases, custom base URLs (e.g., for Azure OpenAI deployments or other proxy/gateway services). +For advanced users or those with specific enterprise agreements with LLM providers, Codegen allows you to use your own API keys and, in some cases, custom base URLs (e.g., for Azure OpenAI deployments or other proxy/gateway services). + + + Set up custom API keys for OpenAI, Anthropic, Google, and Grok models. + + +We currently support custom API keys for: + +- **OpenAI** - GPT-4, GPT-4 Turbo, and other OpenAI models +- **Anthropic** - Claude 4 Sonnet, Claude 4 Opus, and Claude 4 Haiku +- **Google** - Gemini Pro and other Google AI models +- **Grok** - Grok models from xAI + +**Benefits of custom API keys:** - **Custom API Key:** If you provide your own API key, usage will be billed to your account with the respective LLM provider. - **Custom Base URL:** This allows Codegen to route LLM requests through a different endpoint than the provider's default API. - Using the default Codegen-managed LLM configuration (especially with Claude - 4 Sonnet) is recommended for most users to ensure optimal performance and to + Using the default Codegen-managed LLM configuration (especially with Claude 4 + Sonnet) is recommended for most users to ensure optimal performance and to benefit from our continuous prompt improvements. diff --git a/docs/settings/organization-rules.mdx b/docs/settings/organization-rules.mdx index 681be60bc..b57bd79af 100644 --- a/docs/settings/organization-rules.mdx +++ b/docs/settings/organization-rules.mdx @@ -41,6 +41,7 @@ To configure Organization Rules: Here are some common examples of Organization Rules: ### Git Workflow Standards + ``` Always use git add . when staging changes for commit Never use git push --force under any circumstances @@ -48,6 +49,7 @@ Always create descriptive commit messages following conventional commit format ``` ### Code Quality Standards + ``` Always include comprehensive error handling in new functions Follow the existing code style and formatting conventions @@ -56,6 +58,7 @@ Include JSDoc comments for all public functions ``` ### Security Guidelines + ``` Never commit sensitive information like API keys or passwords Always validate user input before processing @@ -63,6 +66,7 @@ Use environment variables for configuration values ``` ### Documentation Requirements + ``` Update README files when adding new features Include inline comments for complex logic @@ -72,21 +76,25 @@ Document any breaking changes in commit messages ## Best Practices ### Keep Rules Clear and Specific + - Write rules that are easy to understand and follow - Be specific about what you want the agent to do or avoid - Use clear, actionable language ### Avoid Conflicting Rules + - Ensure Organization Rules don't contradict each other - Consider how they might interact with Repository Rules - Test rules with different types of tasks ### Regular Review and Updates + - Periodically review your Organization Rules for relevance - Update rules as your organization's practices evolve - Remove outdated or unnecessary rules ### Balance Global vs Repository-Specific Rules + - Use Organization Rules for truly universal standards - Reserve Repository Rules for project-specific requirements - Avoid duplicating rules between levels @@ -94,6 +102,7 @@ Document any breaking changes in commit messages ## Troubleshooting ### Rules Not Being Applied + If your Organization Rules don't seem to be working: 1. **Check Rule Syntax**: Ensure your rules are clearly written and unambiguous @@ -102,6 +111,7 @@ If your Organization Rules don't seem to be working: 4. **Rule Conflicts**: Look for contradictory instructions that might confuse the agent ### Agent Behavior Issues + If the agent isn't following your rules as expected: 1. **Simplify Rules**: Break complex rules into smaller, more specific instructions @@ -112,7 +122,6 @@ If the agent isn't following your rules as expected: - **[Repository Rules](/settings/repo-rules)**: Set repository-specific rules that can override Organization Rules - **[Agent Permissions](/settings/agent-permissions)**: Control what actions the agent can perform -- **[Model Configuration](/settings/model-configuration)**: Configure which AI model the agent uses +- **[Model Choice](/settings/model-configuration)**: Configure which AI model the agent uses Organization Rules provide a powerful way to maintain consistency across your entire organization while still allowing flexibility for individual repositories. Use them to establish your organization's coding culture and ensure all agent interactions align with your standards. - diff --git a/docs/settings/repo-rules.mdx b/docs/settings/repo-rules.mdx index 000d47d59..9c3b81f4b 100644 --- a/docs/settings/repo-rules.mdx +++ b/docs/settings/repo-rules.mdx @@ -4,97 +4,28 @@ sidebarTitle: "Agent Rules" icon: "shield-check" --- -Agent Rules in Codegen act as persistent instructions or "system prompts" for the AI agent, guiding its behavior by enforcing coding standards, conventions, and preferences. These rules are automatically included in the agent's context during each task to ensure consistent behavior across your organization and repositories. - -## Rule Hierarchy - -Codegen supports a hierarchical rule system with three levels: - -1. **User Rules** - Personal preferences that apply to all your work across organizations -2. **Organization Rules** - Apply to all repositories within your organization -3. **Repository Rules** - Apply to a specific repository and override higher-level rules when conflicts exist - - - **Rule Precedence**: Repository rules take precedence over organization rules, which take precedence over user rules when conflicts exist. This allows you to set personal defaults, organization-wide standards, and repository-specific customizations. - - -## Types of Rules - -Each level supports two types of rule configuration: - -### Manual Rules -Rules configured directly through the Codegen web interface at [codegen.com/repos](https://codegen.com/repos) (for repository rules) or organization settings (for organization rules). - -### Automatic Rule File Detection -Rules automatically discovered from files in your repository (repository level only). - - - - +Agent rules are text prompts that provide instructions to AI agents about coding standards, conventions, and preferences. These text-based rules are automatically injected into the agent's context during each task. ## How Agent Rules Work -When an agent is assigned a task, all applicable rules are automatically included in the agent's context as "Mandatory User Rules." The agent sees these rules alongside the actual task or prompt it receives, ensuring consistent behavior. +When an agent starts working, it receives all applicable rules as text prompts in its context: -**Rule Resolution Process:** -1. **User Rules** are loaded first (if configured in your personal settings) -2. **Organization Rules** are loaded next (if configured for your organization) -3. **Repository Rules** are loaded next (if configured for the specific repository) -4. **Higher-level rules override lower-level rules** when conflicts exist (Repository > Organization > User) -5. **Automatic rule files** are discovered and included (repository level only) -6. All rules are combined and presented to the agent as mandatory constraints +1. **[User Rules](https://codegen.com/settings/personal-prompts)** - Your personal coding preferences and style +2. **[Organization Rules](https://codegen.com/settings/organization-rules)** - Organization-wide standards and conventions +3. **[Repository Rules](https://codegen.com/repos)** - Project-specific requirements and guidelines -For example, if you have a user rule "Always use semicolons in JavaScript," your organization has a rule "Use TypeScript for all new code," and a specific repository has a rule "Use JavaScript for this legacy project," the repository rule takes precedence, followed by the organization rule, then your personal user rule. - -## Configuring Agent Rules - -### User Rules - -User rules are personal preferences that apply to all your work across organizations. These are perfect for setting your individual coding style, preferred tools, or workflow preferences. - -**To configure user rules:** -1. Navigate to your personal settings in the Codegen web interface -2. Look for the "User Rules" or "Personal Agent Rules" section -3. Enter your personal preferences and coding standards -4. Click "Save" to apply them across all organizations and repositories you work with - - - User rules are ideal for personal preferences like "Always include detailed commit messages," "Prefer functional programming patterns," or "Use specific linting configurations." - +The agent is instructed to prefer **User > Repository > Organization** rules when there are conflicts, but these are guidance rather than hard constraints. The agent considers all rules as context when making decisions. - **Coming Soon**: User-level rules are currently being implemented and will be available in an upcoming release. The infrastructure is in place, and this feature will allow you to set personal coding preferences that follow you across all organizations. + Rules are text prompts, not strict settings. Agents use them as guidance + alongside the specific task you've given them. -### Organization Rules - -Organization rules apply to all repositories within your organization and serve as default behavior guidelines. - -**To configure organization rules:** -1. Navigate to your organization settings in the Codegen web interface -2. Look for the "Organization Rules" section -3. Enter your organization-wide rules in the text area -4. Click "Save" to apply them to all repositories in your organization - - Organization rules are perfect for setting coding standards, commit message conventions, or testing requirements that should apply across all your repositories. + Codegen automatically detects `AGENTS.md` and other rules files. [Learn + more](#automatic-rule-file-detection) -### Repository Rules - -Repository rules apply to a specific repository and override any conflicting organization rules. - -**To configure repository rules:** -1. Navigate to [codegen.com/repos](https://codegen.com/repos) -2. Select the repository for which you want to set rules -3. Look for the "Repository Rules" section in the repository's settings -4. Enter your repository-specific rules in the text area -5. Click "Save" to apply them - - - - - ## Automatic Rule File Detection In addition to manual repository rules, Codegen automatically discovers and includes agent rule files from your repository when the agent starts working on it. This happens automatically whenever the `set_active_codebase` tool is used. @@ -103,43 +34,48 @@ In addition to manual repository rules, Codegen automatically discovers and incl Codegen automatically searches for the following types of rule files in your repository: + + You can customize which rule file patterns to match by configuring glob + patterns in your repository settings at + [codegen.com/repos](https://codegen.com/repos) (select your repository, then + configure rule file patterns). + + +- **`AGENTS.md`** - preferred default. [Learn more](https://agents.md) +- **`CLAUDE.md`** - Claude assistant rules - **`.cursorrules`** - Cursor AI editor rules -- **`.clinerules`** - Cline AI assistant rules +- **`.clinerules`** - Cline AI assistant rules - **`.windsurfrules`** - Windsurf AI editor rules -- **`**/*.mdc`** - Markdown files with `.mdc` extension anywhere in the repository -- **`.cursor/rules/**/*.mdc`** - Markdown files in the `.cursor/rules/` directory structure -- **`CLAUDE.md`**, **`AGENTS.md`**, **`AGENT.md`** - top-level docs commonly used to instruct AI agents +- **`**/\*.mdc`** - Markdown files with `.mdc` extension anywhere in the repository +- **`.cursor/rules/**/\*.mdc`** - Markdown files in the `.cursor/rules/` directory structure ### How Automatic Detection Works 1. **File Discovery**: When you switch to a repository, Codegen uses `ripgrep` to search for files matching the supported patterns 2. **Content Extraction**: The content of discovered files is read and processed + - **New**: The content is encoded to preserve formatting during transport, then decoded before being presented to the agent + 3. **Size Limitation (25k global budget)**: All rule files combined are truncated to fit within a 25,000 character global budget to ensure optimal performance 4. **Context Integration**: The rule content is automatically included in the agent's context alongside any manual repository rules ### Example Rule Files -Here are examples of how you might structure automatic rule files in your repository: +Here are examples of how you might structure agent rules in your repository: -**`.cursorrules` example:** -``` -Use TypeScript for all new code -Follow the existing code style in the repository -Always add JSDoc comments for public functions -Prefer functional components over class components in React -``` +**`AGENTS.md` example:** -**`.cursor/rules/backend.mdc` example:** ```markdown # Backend Development Rules ## Database + - Use Prisma for database operations - Always use transactions for multi-step operations - Include proper error handling for all database calls ## API Design + - Follow REST conventions - Use proper HTTP status codes - Include request/response validation @@ -157,11 +93,14 @@ When rules are discovered, they are displayed in the AgentTrace under the `SetAc - **Editor Integration**: Many AI-powered editors already support these file formats - Automatic rule files work alongside manual repository rules. Both types of rules are combined and provided to the agent for maximum context. + Automatic rule files work alongside manual repository rules. Both types of + rules are combined and provided to the agent for maximum context. - If your rule files exceed the global 25,000 character budget, they will be truncated per-file and/or at the aggregate level. Keep rule files concise or split them into focused files. + If your rule files exceed the global 25,000 character budget, they will be + truncated per-file and/or at the aggregate level. Keep rule files concise or + split them into focused files. ## Common Use Cases and Examples @@ -209,20 +148,3 @@ Perfect for repository-specific requirements that may override organization defa - **Build and Deployment:** - "Run `npm run build` before committing to ensure the build passes." - "This repository deploys automatically on merge to main - ensure all tests pass." - -### Rule Hierarchy in Action - -Here's how user, organization, and repository rules work together: - -**User Rule:** "I prefer detailed error messages with context" -**Organization Rule:** "Use TypeScript for all new code" -**Repository Rule:** "This legacy project uses JavaScript - do not convert existing files" -**Result:** The agent will use JavaScript for this specific repository (repository rule wins), but will still include detailed error messages (user rule applies) since there's no conflict. - - - Keep your rules concise and clear. Overly complex or numerous rules might confuse the agent or lead to suboptimal performance. Focus on the most critical guidelines for your organization and repositories. - - - - All agent rules (user, organization, repository, and automatic rule files) are applied *in addition* to any global prompting strategies or agent capabilities. They provide a hierarchical layer of instruction that helps ensure consistent behavior across your personal work, organization, and codebases. -{" "} diff --git a/docs/settings/settings.mdx b/docs/settings/settings.mdx index 004b4171f..8a1a75e0f 100644 --- a/docs/settings/settings.mdx +++ b/docs/settings/settings.mdx @@ -12,20 +12,7 @@ Configure Codegen to work perfectly with your development workflow. Customize ag className="w-full aspect-[3456/2160] rounded-sm" /> -## Repository Configuration - - - - Set repository-specific rules and coding standards that agents automatically - follow when working on your codebase. - - - -## Agent Configuration +## Agent & Repository Settings -## Team Management +## Organization Settings + + Set repository-specific rules and coding standards that agents automatically + follow when working on your codebase. + + Manage team members and control access through hierarchical role permissions for admins, managers, and members. -## Global Configuration +## Model Configuration - - + + Choose your preferred LLM provider and model, configure custom API keys, and optimize performance settings. @@ -71,13 +63,11 @@ Configure Codegen to work perfectly with your development workflow. Customize ag ## Getting Started -Settings are organized into repository-level and organization-level configurations: +Settings are organized into logical groups for easy configuration: -- **Repository Rules** apply to specific repositories and help agents understand your coding standards and project-specific requirements -- **Agent Behavior** controls how agents interact with users and approach code modifications -- **Agent Permissions** defines what actions agents are allowed to perform across your organization -- **Team & User Roles** manages team member access through hierarchical permissions (Member, Manager, Admin) -- **Model Configuration** applies globally to your organization and controls which AI models power your agents +- **Agent & Repository Settings** - Core agent behavior and permissions that define how agents work +- **Organization Settings** - Repository rules and team management for organizational control +- **Model Configuration** - AI model selection and API key configuration for performance optimization Start by configuring repository rules for your most active repositories, then