Skip to content

Commit 27cd628

Browse files
jayhackjayhack
authored
Tightens docs (#1248)
1 parent f321b49 commit 27cd628

17 files changed

+480
-300
lines changed

‎docs/api-reference/agent-run-logs.mdx‎

Lines changed: 63 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,10 @@
11
---
2-
title: "Agent Run Logs API"
3-
sidebarTitle: "Agent Run Logs"
2+
title: "Retrieving Traces"
3+
sidebarTitle: "Retrieving Traces"
44
icon: "list"
55
iconType: "solid"
66
---
77

8-
<Warning>
9-
This endpoint is currently in **ALPHA** status and is subject to change. We welcome your feedback to help improve this API.
10-
</Warning>
11-
128
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.
139

1410
## Endpoint
@@ -27,12 +23,12 @@ Authorization: Bearer YOUR_API_TOKEN
2723

2824
## Parameters
2925

30-
| Parameter | Type | Required | Description |
31-
|-----------|------|----------|-------------|
32-
| `org_id` | integer | Yes | Your organization ID |
33-
| `agent_run_id` | integer | Yes | The ID of the agent run to retrieve logs for |
34-
| `skip` | integer | No | Number of logs to skip for pagination (default: 0) |
35-
| `limit` | integer | No | Maximum number of logs to return (default: 100, max: 100) |
26+
| Parameter | Type | Required | Description |
27+
| -------------- | ------- | -------- | --------------------------------------------------------- |
28+
| `org_id` | integer | Yes | Your organization ID |
29+
| `agent_run_id` | integer | Yes | The ID of the agent run to retrieve logs for |
30+
| `skip` | integer | No | Number of logs to skip for pagination (default: 0) |
31+
| `limit` | integer | No | Maximum number of logs to return (default: 100, max: 100) |
3632

3733
## Response Structure
3834

@@ -80,25 +76,25 @@ Each log entry in the `logs` array contains the following fields:
8076

8177
### Core Fields
8278

83-
| Field | Type | Description |
84-
|-------|------|-------------|
85-
| `agent_run_id` | integer | The ID of the agent run this log belongs to |
86-
| `created_at` | string | ISO 8601 timestamp when the log entry was created |
87-
| `message_type` | string | The type of log entry (see [Log Types](#log-types) below) |
79+
| Field | Type | Description |
80+
| -------------- | ------- | --------------------------------------------------------- |
81+
| `agent_run_id` | integer | The ID of the agent run this log belongs to |
82+
| `created_at` | string | ISO 8601 timestamp when the log entry was created |
83+
| `message_type` | string | The type of log entry (see [Log Types](#log-types) below) |
8884

8985
### Agent Reasoning Fields
9086

91-
| Field | Type | Description |
92-
|-------|------|-------------|
87+
| Field | Type | Description |
88+
| --------- | -------------- | --------------------------------------------------------------- |
9389
| `thought` | string \| null | The agent's internal reasoning or thought process for this step |
9490

9591
### Tool Execution Fields
9692

97-
| Field | Type | Description |
98-
|-------|------|-------------|
99-
| `tool_name` | string \| null | Name of the tool being executed (e.g., "ripgrep_search", "file_write") |
100-
| `tool_input` | object \| null | JSON object containing the parameters passed to the tool |
101-
| `tool_output` | object \| null | JSON object containing the tool's execution results |
93+
| Field | Type | Description |
94+
| ------------- | ------------------------ | ------------------------------------------------------------------------------ |
95+
| `tool_name` | string \| null | Name of the tool being executed (e.g., "ripgrep_search", "file_write") |
96+
| `tool_input` | object \| null | JSON object containing the parameters passed to the tool |
97+
| `tool_output` | object \| null | JSON object containing the tool's execution results |
10298
| `observation` | object \| string \| null | The agent's observation of the tool execution results or other contextual data |
10399

104100
## Log Types
@@ -107,58 +103,62 @@ The `message_type` field indicates the type of log entry. Here are the possible
107103

108104
### Plan Agent Types
109105

110-
| Type | Description |
111-
|------|-------------|
112-
| `ACTION` | The agent is executing a tool or taking an action |
113-
| `PLAN_EVALUATION` | The agent is evaluating or updating its plan |
114-
| `FINAL_ANSWER` | The agent is providing its final response or conclusion |
115-
| `ERROR` | An error occurred during execution |
116-
| `USER_MESSAGE` | A message from the user (e.g., interruptions or additional context) |
117-
| `USER_GITHUB_ISSUE_COMMENT` | A comment from a GitHub issue that the agent is processing |
106+
| Type | Description |
107+
| --------------------------- | ------------------------------------------------------------------- |
108+
| `ACTION` | The agent is executing a tool or taking an action |
109+
| `PLAN_EVALUATION` | The agent is evaluating or updating its plan |
110+
| `FINAL_ANSWER` | The agent is providing its final response or conclusion |
111+
| `ERROR` | An error occurred during execution |
112+
| `USER_MESSAGE` | A message from the user (e.g., interruptions or additional context) |
113+
| `USER_GITHUB_ISSUE_COMMENT` | A comment from a GitHub issue that the agent is processing |
118114

119115
### PR Agent Types
120116

121-
| Type | Description |
122-
|------|-------------|
123-
| `INITIAL_PR_GENERATION` | The agent is generating the initial pull request |
124-
| `DETECT_PR_ERRORS` | The agent is detecting errors in a pull request |
125-
| `FIX_PR_ERRORS` | The agent is fixing errors found in a pull request |
126-
| `PR_CREATION_FAILED` | Pull request creation failed |
127-
| `PR_EVALUATION` | The agent is evaluating a pull request |
117+
| Type | Description |
118+
| ----------------------- | -------------------------------------------------- |
119+
| `INITIAL_PR_GENERATION` | The agent is generating the initial pull request |
120+
| `DETECT_PR_ERRORS` | The agent is detecting errors in a pull request |
121+
| `FIX_PR_ERRORS` | The agent is fixing errors found in a pull request |
122+
| `PR_CREATION_FAILED` | Pull request creation failed |
123+
| `PR_EVALUATION` | The agent is evaluating a pull request |
128124

129125
### Commit Agent Types
130126

131-
| Type | Description |
132-
|------|-------------|
127+
| Type | Description |
128+
| ------------------- | ------------------------------- |
133129
| `COMMIT_EVALUATION` | The agent is evaluating commits |
134130

135131
### Link Types
136132

137-
| Type | Description |
138-
|------|-------------|
133+
| Type | Description |
134+
| ---------------- | ----------------------------------- |
139135
| `AGENT_RUN_LINK` | A link to another related agent run |
140136

141137
## Field Population Patterns
142138

143139
Different log types populate different fields:
144140

145141
### ACTION Logs
142+
146143
- Always have: `tool_name`, `tool_input`, `tool_output`
147144
- Often have: `thought`, `observation`
148145
- Example: Tool executions like searching code, editing files, creating PRs
149146

150147
### PLAN_EVALUATION Logs
148+
151149
- Always have: `thought`
152150
- May have: `observation`
153151
- Rarely have: Tool-related fields
154152
- Example: Agent reasoning about next steps
155153

156154
### ERROR Logs
155+
157156
- Always have: `observation` (containing error details)
158157
- May have: `tool_name` (if error occurred during tool execution)
159158
- Example: Failed tool executions or system errors
160159

161160
### FINAL_ANSWER Logs
161+
162162
- Always have: `observation` (containing the final response)
163163
- May have: `thought`
164164
- Example: Agent's final response to the user
@@ -208,12 +208,12 @@ while True:
208208
url = f"https://api.codegen.com/v1/organizations/67890/agent/run/12345/logs?skip={skip}&limit={limit}"
209209
response = requests.get(url, headers=headers)
210210
data = response.json()
211-
211+
212212
all_logs.extend(data['logs'])
213-
213+
214214
if len(data['logs']) < limit:
215215
break # No more logs
216-
216+
217217
skip += limit
218218

219219
print(f"Retrieved {len(all_logs)} total logs")
@@ -234,26 +234,34 @@ for error_log in error_logs:
234234
## Common Use Cases
235235

236236
### 1. Building Monitoring Dashboards
237+
237238
Use the logs to create dashboards showing:
239+
238240
- Agent execution progress
239241
- Tool usage patterns
240242
- Error rates and types
241243
- Execution timelines
242244

243245
### 2. Debugging Agent Behavior
246+
244247
Analyze logs to understand:
248+
245249
- Why an agent made certain decisions
246250
- Where errors occurred in the execution flow
247251
- What tools were used and their results
248252

249253
### 3. Audit and Compliance
254+
250255
Track agent actions for:
256+
251257
- Code change auditing
252258
- Compliance reporting
253259
- Security monitoring
254260

255261
### 4. Performance Analysis
262+
256263
Monitor:
264+
257265
- Tool execution times
258266
- Common failure patterns
259267
- Agent reasoning efficiency
@@ -265,13 +273,13 @@ Monitor:
265273

266274
## Error Responses
267275

268-
| Status Code | Description |
269-
|-------------|-------------|
270-
| 400 | Bad Request - Invalid parameters |
271-
| 401 | Unauthorized - Invalid or missing API token |
272-
| 403 | Forbidden - Insufficient permissions |
273-
| 404 | Not Found - Agent run not found |
274-
| 429 | Too Many Requests - Rate limit exceeded |
276+
| Status Code | Description |
277+
| ----------- | ------------------------------------------- |
278+
| 400 | Bad Request - Invalid parameters |
279+
| 401 | Unauthorized - Invalid or missing API token |
280+
| 403 | Forbidden - Insufficient permissions |
281+
| 404 | Not Found - Agent run not found |
282+
| 429 | Too Many Requests - Rate limit exceeded |
275283

276284
## Feedback and Support
277285

@@ -282,6 +290,6 @@ Since this endpoint is in ALPHA, we'd love your feedback! Please reach out throu
282290
- Email: [email protected]
283291

284292
<Note>
285-
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.
293+
The structure and fields of this API may change as we gather feedback and
294+
improve the service. We'll provide advance notice of any breaking changes.
286295
</Note>
287-

‎docs/api-reference/authentication.mdx‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
title: "Authentication"
3+
sidebarTitle: "Authentication"
4+
icon: "key"
5+
---
6+
7+
All Codegen API endpoints require authentication using Bearer tokens. You'll need both an API token and your organization ID to get started.
8+
9+
## Get Your Credentials
10+
11+
<Card
12+
title="Get API Token & Organization ID"
13+
icon="key"
14+
href="https://codegen.com/token"
15+
>
16+
Visit the developer settings to generate your API token and find your
17+
organization ID.
18+
</Card>
19+
20+
## Required Information
21+
22+
### API Token
23+
24+
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.
25+
26+
### Organization ID
27+
28+
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.
29+
30+
## Using Your Credentials
31+
32+
### REST API
33+
34+
Include your API token in the Authorization header for all requests:
35+
36+
```bash
37+
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
38+
"https://api.codegen.com/v1/organizations/YOUR_ORG_ID/agent/run"
39+
```
40+
41+
### Python SDK
42+
43+
The Python SDK makes authentication simple:
44+
45+
```python
46+
from codegen import Agent
47+
48+
# Initialize with your credentials
49+
agent = Agent(org_id="YOUR_ORG_ID", token="YOUR_API_TOKEN")
50+
51+
# The SDK handles authentication automatically
52+
task = agent.run(prompt="Fix the bug in user authentication")
53+
```

0 commit comments

Comments
 (0)