Skip to content

Tightens docs #1248

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Sep 15, 2025
Merged

Tightens docs #1248

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
10ad5de
.
jayhack Sep 14, 2025
c89fba5
.
jayhack Sep 14, 2025
fb3fa63
.
jayhack Sep 14, 2025
73ce193
.
jayhack Sep 14, 2025
5c2ae0a
.
jayhack Sep 14, 2025
dbfeda5
.
jayhack Sep 15, 2025
e1860ed
.
jayhack Sep 15, 2025
f9a9f98
.
jayhack Sep 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 63 additions & 55 deletions docs/api-reference/agent-run-logs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,10 @@
---
title: "Agent Run Logs API"
sidebarTitle: "Agent Run Logs"
title: "Retrieving Traces"
sidebarTitle: "Retrieving Traces"
icon: "list"
iconType: "solid"
---

<Warning>
This endpoint is currently in **ALPHA** status and is subject to change. We welcome your feedback to help improve this API.
</Warning>

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
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -107,58 +103,62 @@ 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

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
Expand Down Expand Up @@ -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")
Expand All @@ -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
Expand All @@ -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

Expand All @@ -282,6 +290,6 @@ Since this endpoint is in ALPHA, we'd love your feedback! Please reach out throu
- Email: support@codegen.com

<Note>
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.
</Note>

53 changes: 53 additions & 0 deletions docs/api-reference/authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

<Card
title="Get API Token & Organization ID"
icon="key"
href="https://codegen.com/token"
>
Visit the developer settings to generate your API token and find your
organization ID.
</Card>

## 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")
```
Loading