# Driving agents from code: Claude Agent SDK, Codex SDK and Cursor SDK

URL: https://developertoolkit.ai/en/workflows/automate/agent-sdks/
Description: When to script a coding agent instead of triggering one, and how the Claude Agent SDK, Codex SDK and Cursor SDK differ, with one CI-triage job written in each.

The Claude Agent SDK, the Codex SDK and the Cursor SDK let a program, not a person, run a coding agent: start it, restrict its tools, read a typed result and resume it later. Use an SDK when your code must branch on what the agent found; for a one-shot CI step, `claude -p` or `codex exec` is enough.

CI goes red at 02:10. By the time anyone looks, three more pushes have queued behind it, and the first half hour of the morning goes on reading 4,000 lines of log to learn that a test was flaky again. You already tried a bot: a workflow step that pipes the log into `claude -p` and posts the answer as a comment. It helps, but it cannot rerun the flaky test and wait, it cannot open a second, write-enabled session only when the verdict is "regression", and nobody knows what it cost last month. That is the point where you stop triggering an agent and start driving one from code.

This page is for developers who build that automation and for tech leads who decide which SDK a team standardises on. It compares the three SDKs on the five things that decide the choice — sessions, tools, permissions, streaming and cost — and writes the same job in each.

## What you'll walk away with from the agent SDK comparison

- A decision table for "trigger it or script it" that you can apply to any automation idea.
- A comparison of the three SDKs on sessions, tools, permissions, streaming, structured output and cost, checked against the published packages on 2026-09-26.
- A CI-failure triage runner written three times — Claude Agent SDK, Codex SDK, Cursor SDK — sharing one prompt and one JSON Schema, plus the GitHub Actions workflow that calls it.
- The gates that make its output trustworthy without a person reading every run, and the failure modes that bite first.

## Should you script the agent or trigger it?

Most "agent in CI" jobs never need an SDK. A trigger — a GitHub Action, a scheduled automation or a single headless CLI call — takes a prompt and produces a comment, a file or a pull request. An SDK earns its extra code only when the orchestration logic lives in your program.

| Your job needs… | Trigger is enough | Reach for the SDK |
| --- | --- | --- |
| One prompt in, one result out | `claude -p --output-format json`, `codex exec --json -o out.json`, Cursor's print mode, `anthropics/claude-code-action@v1`, `openai/codex-action@v1`, Cursor Automations | — |
| A typed result a script consumes | `claude -p --json-schema`, `codex exec --output-schema FILE` | When the next step depends on the value |
| Different next steps per result (rerun, label, open a fix session) | Only with brittle shell glue | Yes: branch in code, resume the same session |
| Tools that call your own systems (ticketing, feature flags, internal APIs) | An MCP server you deploy and maintain | In-process tools: Claude `createSdkMcpServer`, Cursor `customTools` |
| A per-call permission decision ("allow `git show`, deny `git push`, ask the service for the rest") | Static allow and deny lists | Claude's `canUseTool` callback and hooks |
| Live progress in your own UI, bot or log | Tail a JSONL file | Typed event streams in all three SDKs |
| Spend accounting per run, per team or per customer | Scrape the CLI's JSON | Cost or usage fields on the result |
| Many agents coordinated by your code | — | Yes; see [multi-agent orchestration patterns](/en/workflows/automate/orchestration-patterns/) |

The rule of thumb: if you can describe the job as a single prompt with a fixed output, keep it a trigger. If you catch yourself writing `if` statements around the agent's answer, move to an SDK. The CLI-level options are covered per tool in [Claude Code automation](/en/claude-code/automate/automation/) and [Codex non-interactive mode](/en/codex/automate/non-interactive/).

## How do the Claude Agent SDK, Codex SDK and Cursor SDK differ?

All three put the vendor's own coding agent behind a library: the same tools, the same project instruction files and the same model catalogue you use interactively. They differ in what they let your code decide. Everything below was read from the published TypeScript packages on 2026-09-26.

| | Claude Agent SDK | Codex SDK | Cursor SDK |
| --- | --- | --- | --- |
| Packages checked | npm `@anthropic-ai/claude-agent-sdk` 0.3.283, PyPI `claude-agent-sdk` 0.2.160 | npm `@openai/codex-sdk` 0.157.1, PyPI `openai-codex` 0.157.1 | npm `@cursor/sdk` 1.0.32, PyPI `cursor-sdk` 1.0.32 |
| What runs underneath | The Claude Code binary, installed as a platform package | The `codex` CLI from `@openai/codex`, spoken to over JSONL on stdin and stdout | A local agent, or a cloud agent in an isolated VM when you pass `cloud` |
| Runtime | Node 18+ | Node 18+ | Node 22.13+ |
| Entry point | `query({ prompt, options })`, an async generator of messages | `new Codex().startThread()`, then `thread.run()` or `thread.runStreamed()` | `Agent.create()`, then `agent.send()` returning a `Run` |
| Sessions | `session_id` on every message; `resume`, `continue`, `forkSession` | Thread `id`; `codex.resumeThread(id)`; threads persist in `~/.codex/sessions` | `agentId`; `Agent.resume(id)`; local agents persist in a SQLite or JSONL store, cloud agent IDs start with `bc-` |
| Restricting tools | `tools` sets the toolset; `allowedTools` only auto-approves; `disallowedTools` removes | No per-tool list; the sandbox mode bounds what commands can do | `tools` and `disallowedTools` (local agents only) |
| Your own tools | In-process MCP server via `createSdkMcpServer()` and `tool()`, plus `mcpServers` | MCP servers from Codex configuration | `customTools` callbacks (local only), plus `mcpServers` |
| Permissions | `permissionMode` (`default`, `acceptEdits`, `plan`, `dontAsk`, `auto`, `bypassPermissions`), `canUseTool` callback, hooks such as `PreToolUse` | `sandboxMode` (`read-only`, `workspace-write`, `danger-full-access`) plus `approvalPolicy` (`never`, `on-request`, `on-failure`, `untrusted`) | `local.sandboxOptions`, `local.autoReview` (Cursor's classifier-backed Auto-review); a cloud agent is isolated by its VM |
| Streaming | Every message as it happens; `includePartialMessages` adds token deltas | `runStreamed()` yields `thread.started`, `item.*`, `turn.completed`, `turn.failed`, `error` | `run.stream()`, plus `onStep` and `onDelta` callbacks on `send()` |
| Structured output | `outputFormat: { type: 'json_schema', schema }` → `structured_output` on the result | `outputSchema` per turn → JSON in `finalResponse` | No schema option in 1.0.32; capture the report through a custom tool |
| Limits and cost | `maxTurns`, `maxBudgetUsd`; `total_cost_usd` on the result, documented as an estimate | Token `usage` on `turn.completed`; no dollar field and no spend cap; cancel with an `AbortSignal` | `agent.getUsage()` returns tokens and cost in cents, which can lag the run; cancel with `run.cancel()` |
| Model | Claude Code's default unless you set `model` | Codex's default unless you set `model`; `modelReasoningEffort` | `model` is required for local agents; list IDs with `Cursor.models.list()` |

Three consequences are easy to miss in the table:

- **Only Claude lets code decide each tool call.** `canUseTool` and `PreToolUse` hooks see every call before it runs. The Codex SDK gives you a sandbox boundary instead of a callback (no per-call hook in `@openai/codex-sdk` 0.157.1), and the Cursor SDK gives you tool lists and Auto-review.
- **The Agent SDK does not start in auto mode by default.** From Claude Code v2.1.283 (both release channels on 2026-10-12), interactive sessions start in auto mode, but the Agent SDK and `claude -p` still start in the Manual (`default`) permission mode, except on third-party providers or with telemetry off, where they start in auto mode from v2.1.285. An unattended job that relies on prompts being answered stalls or is denied, so pick `dontAsk` with an explicit allowlist.
- **Cursor's SDK is the only one that can hand the work to a cloud VM.** Passing `cloud: { repos: [...] }` runs the agent on Cursor's infrastructure and can open the pull request itself (`autoCreatePR`). Tool lists, custom tools and a custom system prompt are local-only in 1.0.32, and combining `tools` with `cloud` throws a `ConfigurationError`.

Model choice is not a reason to pick an SDK: each defaults to its tool's default model. Start there, tune effort before you switch models, and check the current names and prices on the [models hub](/en/ecosystem/models/).

## The same job three times: triage a failing CI run

The job: when the `CI` workflow fails, download the failed steps' log, find the first real failure, reproduce it, rerun it to rule out flakiness, and write a `triage.json` with a category (`regression`, `flaky`, `infra`, `test-bug`), the failing tests, a suspect commit, evidence and a next step. The agent must not edit anything. A later step decides what to do with the verdict.

The three runners share one prompt and one schema, so a switch between vendors changes only the runner file.

```ts title="ci/triage-spec.ts"
export const triageSchema = {
  type: 'object',
  properties: {
    category: { type: 'string', enum: ['regression', 'flaky', 'infra', 'test-bug'] },
    failing_tests: { type: 'array', items: { type: 'string' } },
    suspect_commit: { type: 'string' },
    evidence: { type: 'string' },
    next_step: { type: 'string' },
  },
  required: ['category', 'failing_tests', 'suspect_commit', 'evidence', 'next_step'],
  additionalProperties: false,
};

export const triagePrompt = `CI failed on this commit. The job log is in ci-failure.log.
Triage it; do not fix anything and do not edit any file.
1. Find the first real failure in the log (skip cascading errors).
2. Reproduce only the failing test(s) with: npx vitest run <file>.
3. Run it twice more. Passes on a rerun => "flaky".
4. Network, runner, secret or cache errors => "infra".
5. Otherwise read git log -5 and the diff of the suspect commit;
   decide "regression" (code broke) or "test-bug" (test is wrong).
Cite log lines and command output as evidence. Use "unknown" for
suspect_commit when you cannot name one.`;
```

**Cursor**

The Cursor SDK has no output-schema option, so the runner gives the agent a `submit_triage` custom tool whose input schema is the triage schema. The tool call's arguments are the report. A local agent needs an explicit model ID; list the IDs your key can use with `Cursor.models.list()` and store one in `CURSOR_MODEL_ID`.

```ts title="ci/triage-cursor.ts"
import { writeFile } from 'node:fs/promises';
import { Agent, type SDKJsonValue } from '@cursor/sdk';
import { triagePrompt, triageSchema } from './triage-spec.js';

let report: Record<string, SDKJsonValue> | undefined;

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY,
  model: { id: process.env.CURSOR_MODEL_ID! }, // required for local agents
  disallowedTools: ['edit', 'delete', 'applyAgentDiff'],
  local: {
    cwd: process.env.TRIAGE_DIR, // the failing commit, checked out apart from this runner
    settingSources: [], // no project rules, hooks or MCP config from the commit under triage
    customTools: {
      submit_triage: {
        description: 'Submit the final triage report. Call it exactly once, at the end.',
        inputSchema: triageSchema,
        execute: (args) => {
          report = args;
          return 'recorded';
        },
      },
    },
  },
});

try {
  const run = await agent.send(`${triagePrompt}\nFinish by calling submit_triage.`);
  const timer = setTimeout(() => void run.cancel(), 10 * 60_000);
  for await (const message of run.stream()) {
    if (message.type === 'tool_call' && message.status === 'completed') console.log('tool', message.name);
  }
  const result = await run.wait();
  clearTimeout(timer);
  if (result.status !== 'finished' || !report) throw new Error(`triage ${result.status}, no report`);
  await writeFile('triage.json', JSON.stringify(report, null, 2));
  const usage = await agent.getUsage(); // cost can lag the run
  console.log(`agent ${agent.agentId}`, usage.usage, usage.cost);
} finally {
  agent.close();
}
```

`disallowedTools` removes the edit tools, but `shell` stays, and a shell can still write files. The `git diff --exit-code` step in the workflow below is what enforces "no edits".

**Claude Code**

The Claude Agent SDK has every control this job needs in one options object: a restricted toolset, an allowlist of Bash commands, a mode that denies everything else, a turn and dollar cap, and schema-checked output.

```ts title="ci/triage-claude.ts"
import { writeFile } from 'node:fs/promises';
import { query } from '@anthropic-ai/claude-agent-sdk';
import { triagePrompt, triageSchema } from './triage-spec.js';

for await (const msg of query({
  prompt: triagePrompt,
  options: {
    cwd: process.env.TRIAGE_DIR, // the failing commit, checked out apart from this runner
    tools: ['Read', 'Grep', 'Glob', 'Bash'], // no Edit, no Write
    allowedTools: ['Read', 'Grep', 'Glob', 'Bash(npx vitest run *)', 'Bash(git log *)', 'Bash(git show *)'],
    permissionMode: 'dontAsk', // anything that would prompt is denied
    settingSources: [], // no settings, hooks or CLAUDE.md from the commit under triage
    maxTurns: 30,
    maxBudgetUsd: 2,
    outputFormat: { type: 'json_schema', schema: triageSchema },
  },
})) {
  if (msg.type !== 'result') continue;
  if (msg.subtype !== 'success') throw new Error(`triage stopped: ${msg.subtype}`);
  await writeFile('triage.json', JSON.stringify(msg.structured_output, null, 2));
  console.log(`session ${msg.session_id}, ~$${msg.total_cost_usd.toFixed(2)}, ${msg.num_turns} turns`);
}
```

`allowedTools` does not shrink the toolset; it only pre-approves. The `tools` line is what removes `Edit` and `Write`. A run that hits the caps ends with `subtype` set to `error_max_turns` or `error_max_budget_usd`, which the runner turns into a failed step.

**Codex**

The Codex SDK bounds the agent with a sandbox rather than a tool list, and it takes the schema per turn. There is no spend cap, so a timeout signal stands in for one.

```ts title="ci/triage-codex.ts"
import { writeFile } from 'node:fs/promises';
import { Codex } from '@openai/codex-sdk';
import { triagePrompt, triageSchema } from './triage-spec.js';

const codex = new Codex({ apiKey: process.env.CODEX_API_KEY });
const thread = codex.startThread({
  workingDirectory: process.env.TRIAGE_DIR, // the failing commit, checked out apart from this runner
  sandboxMode: 'workspace-write', // tests may write caches; the git-diff gate catches edits
  approvalPolicy: 'never', // nobody is there to approve
  networkAccessEnabled: false,
});

const timeout = AbortSignal.timeout(10 * 60_000);
const { events } = await thread.runStreamed(triagePrompt, { outputSchema: triageSchema, signal: timeout });

let report = '';
for await (const event of events) {
  if (event.type === 'item.completed' && event.item.type === 'command_execution') {
    console.log(`$ ${event.item.command} -> exit ${event.item.exit_code}`);
  }
  if (event.type === 'item.completed' && event.item.type === 'agent_message') report = event.item.text;
  if (event.type === 'turn.failed') throw new Error(event.error.message);
  if (event.type === 'error') throw new Error(event.message);
  if (event.type === 'turn.completed') console.log('tokens', event.usage);
}
if (!report) throw new Error('triage produced no report');
await writeFile('triage.json', report); // JSON, because outputSchema was set
console.log(`thread ${thread.id}`);
```

`read-only` is the stricter sandbox, but a test runner that writes a cache or a coverage file fails under it and the agent then reports a false "infra". `workspace-write` with the network off plus the diff gate is the practical middle.

All three files type-check with TypeScript 5 (`strict`, `NodeNext`) against the package versions in the comparison table. Run them with `npx tsx ci/triage-<tool>.ts`.

### Wire the runner into GitHub Actions

The workflow is the same for all three SDKs apart from the last `run` line and its secret.

```yaml title=".github/workflows/ci-triage.yml"
name: ci-triage
on:
  workflow_run:
    workflows: [CI]
    types: [completed]
permissions:
  contents: read
  actions: read
jobs:
  triage:
    # Only failed runs, and never code from a fork: this job holds API keys.
    if: >-
      github.event.workflow_run.conclusion == 'failure' &&
      github.event.workflow_run.head_repository.full_name == github.repository
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - name: Check out the runner and prompt from the default branch (trusted)
        uses: actions/checkout@v7
        with:
          persist-credentials: false
          path: trusted
      - name: Check out the failing commit into its own directory (untrusted)
        uses: actions/checkout@v7
        with:
          persist-credentials: false
          ref: ${{ github.event.workflow_run.head_sha }}
          path: pr
          fetch-depth: 20
      - uses: actions/setup-node@v7
        with:
          node-version: 22 # the Cursor SDK needs 22.13+
      - run: npm ci
        working-directory: trusted
      - run: npm ci # the failing commit's test dependencies, installed before any key is in the environment
        working-directory: pr
      - run: gh run view "$RUN_ID" --log-failed > pr/ci-failure.log
        env:
          GH_TOKEN: ${{ github.token }}
          GH_REPO: ${{ github.repository }}
          RUN_ID: ${{ github.event.workflow_run.id }}
      - run: npx tsx ci/triage-claude.ts # or triage-codex.ts / triage-cursor.ts
        working-directory: trusted
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          TRIAGE_DIR: ${{ github.workspace }}/pr
      - run: git diff --exit-code # the triage must leave tracked files untouched
        working-directory: pr
      - uses: actions/upload-artifact@v7
        with:
          name: triage
          path: trusted/triage.json
```

The runner, its prompt and its dependencies come from the default branch in `trusted/`; the failing commit sits in `pr/`, where the agent reads it and runs its tests. That split stops a branch from replacing the runner, the prompt or the agent's settings. It cannot stop the commit's own tests from running with the key in the environment, which the reproduce step needs, so this is acceptable only because the job refuses fork commits: everything that reaches it was pushed by someone with write access. Give the job its own API key with a spending limit.

For the Codex runner, pass `CODEX_API_KEY`; for the Cursor runner, pass `CURSOR_API_KEY` and `CURSOR_MODEL_ID`. Check your vendor's terms for running unattended on an API key versus a subscription login before you pick the credential.

### Branch on the verdict: where the SDK pays for itself

Up to here, `claude -p --json-schema` or `codex exec --output-schema` would have done the same job. The SDK becomes worth its code when the next step depends on the answer and reuses the agent's context:

1. Read `triage.json` and validate it against `triageSchema` with a JSON Schema validator. A report that fails validation fails the job; nobody acts on it.

2. On `flaky`, rerun the failed jobs (`gh run rerun <run-id> --failed`; this step needs `actions: write` on its job) and add the test to your quarantine list. No second agent session.

3. On `infra`, post the evidence to the on-call channel and stop.

4. On `regression` or `test-bug`, resume the same session with write access in a new branch, so the agent keeps what it already read:
   - Claude Agent SDK: `query({ prompt, options: { resume: sessionId, tools: { type: 'preset', preset: 'claude_code' }, permissionMode: 'acceptEdits' } })`.
   - Codex SDK: `codex.resumeThread(threadId, { sandboxMode: 'workspace-write' })`, then `thread.run(...)`.
   - Cursor SDK: `agent.send(...)` on the same agent, or `Agent.resume(agentId)` from a later job; the tool restrictions are not persisted, so pass them again.

5. The fix session opens a pull request that carries the triage report as evidence, and it goes through the same gates as any other agent change: see [the evidence bundle an agent's pull request must carry](/en/workflows/ship/evidence-bundle/).

The GitHub Actions runner is ephemeral, so a session saved on it is gone when the job ends. To resume in a later job, persist the session store (`~/.claude/projects`, `~/.codex/sessions` or the Cursor local store) as an artifact, or keep the whole flow in one job.

## Copy-paste prompts for building an SDK runner

**Copy-paste prompt: scaffold the triage runner in your repository**

```text
Add a CI-failure triage runner to this repository using the Claude Agent SDK
(@anthropic-ai/claude-agent-sdk). Requirements:
- ci/triage-spec.ts exports a JSON Schema (category: regression | flaky | infra |
  test-bug, failing_tests, suspect_commit, evidence, next_step; additionalProperties
  false) and the triage prompt. Adapt the reproduce command to this repo's test runner;
  read package.json and the CI workflow to find it.
- ci/triage-claude.ts calls query() with tools limited to Read, Grep, Glob, Bash;
  allowedTools pre-approving only the test command, git log and git show;
  permissionMode 'dontAsk'; settingSources []; cwd from TRIAGE_DIR; maxTurns 30; maxBudgetUsd 2;
  outputFormat json_schema. Write structured_output to triage.json; throw on any
  result subtype other than 'success'.
- .github/workflows/ci-triage.yml runs on workflow_run failure of our CI workflow,
  skips runs whose head repository is a fork, checks out the default branch into
  trusted/ and the failing commit into pr/, downloads the failed log into pr/ with
  gh run view --log-failed, runs the triage from trusted/ with TRIAGE_DIR=pr, then
  git diff --exit-code in pr/, then uploads triage.json.
Type-check the new files with the repo's TypeScript config. Do not touch other files.
```

**Copy-paste prompt: audit a triage report before anyone acts on it**

```text
You are auditing an automated CI triage, not redoing it. Inputs: triage.json and
ci-failure.log in the working directory. For each claim in triage.json:
1. Quote the log line or command output that supports it. If none exists, mark the
   claim UNSUPPORTED.
2. Check that "category" follows from the evidence: flaky requires a passing rerun,
   infra requires a runner/network/secret/cache error, regression or test-bug
   requires a named commit and the failing assertion.
3. Check that suspect_commit exists in git log -20.
Output JSON: {"verdict": "accept" | "reject", "unsupported_claims": [...],
"reason": "..."}. Do not run tests and do not edit files.
```

Run the audit prompt with a different model or vendor than the runner, so the author never grades itself; [model-graded checks](/en/workflows/test/model-graded-checks/) covers how to calibrate such a judge.

## How do you prove the triage is right without reading every run?

Treat the runner like any other production code path whose output other automation acts on. The gates, in the order they fire:

1. **Schema.** The SDK validates the output shape (Claude, Codex) or the custom tool's input schema constrains it (Cursor). Your step validates it again before acting, because a run that hits a cap can end with no report at all.
2. **No side effects.** `git diff --exit-code` fails the job if the agent changed a tracked file. Tool restrictions reduce the chance; the diff proves it.
3. **Caps.** `maxTurns` and `maxBudgetUsd` on Claude, a timeout on Codex and Cursor, and `timeout-minutes` on the job. A capped run is a failed run, never a partial verdict.
4. **A golden set.** Collect past failed runs with a label a person already agreed on, including flaky, infra and regression cases. Replay the runner on them after every SDK, model or prompt change, and track agreement. Decide in advance what agreement you require before the runner may rerun jobs or label issues on its own; until then it only comments.
5. **An independent audit.** The audit prompt above, run by another model, rejects verdicts whose evidence does not appear in the log.
6. **Telemetry.** Log the session or thread ID, turns, tokens and cost for every run, and join them to the CI run ID. The [agent observability page](/en/workflows/operate/agent-observability/) shows the dashboard: run success, cost per accepted verdict and override rate.

**Who signs off:** the on-call developer owns every action the runner proposes until the golden-set agreement meets the bar the tech lead set. After that, the tech lead signs off on widening its authority one action at a time, starting with reruns of flaky tests.

## What breaks when you drive agents from an SDK?

**The traps that bite first**

- **`allowedTools` treated as a restriction.** In the Claude Agent SDK it only pre-approves. The agent still has every tool not removed through `tools` or `disallowedTools`.
- **The runner's personal settings leak in.** Omitting `settingSources` loads every source (user, project, local) in the Claude Agent SDK. Pass `[]` when the working directory holds code nobody reviewed, as the failing commit here does, so neither the image's `~/.claude` nor the commit's `.claude/settings.json` hooks, `.mcp.json` or `CLAUDE.md` load into a run that holds your key. Use `['project']` only for a trusted checkout. The Cursor SDK has the same option for local agents.
- **Look-alike packages.** The Python Codex SDK is `openai-codex`; `openai-codex-sdk` on PyPI is not OpenAI's. The OpenAI Agents SDK (`openai-agents`, `@openai/agents`) is a general agent framework, not the Codex coding agent. "Claude Code SDK" is the old name of the Claude Agent SDK.
- **Fork pull requests with secrets.** A `workflow_run` job runs with your API keys against the failing commit. Without the `head_repository` check, anyone can open a pull request whose test file tells the agent to print the environment.

| Symptom | Cause | Recovery |
| --- | --- | --- |
| The Claude run ends with `error_max_budget_usd` or `error_max_turns` and no report | The cap is too low for the repository's log size, or the agent is looping on a noisy log | Trim the log to the failed step before the run (`--log-failed` already helps), then raise one cap at a time and record the new cost in the golden-set run |
| The Codex run hangs until the timeout | A command waited for input or the network with `networkAccessEnabled: false` | Read the last `command_execution` item in the streamed log; add the non-interactive flag to the reproduce command in the prompt |
| Every Codex verdict is "infra" | `read-only` sandbox, and the test runner needs to write a cache | Switch to `workspace-write` and keep the diff gate |
| Cursor's `Agent.create` throws `ConfigurationError` | `tools`, `disallowedTools` or `systemPrompt` combined with `cloud` (and `customTools` is local-only too) | Run the triage as a local agent, or drop those options for the cloud agent and restrict it through the prompt and the repository access you grant |
| Cursor reports `finished` but `report` is undefined | The agent answered in text and never called `submit_triage` | Treat it as a failure (the runner already throws); repeat the instruction to call the tool at the end of the prompt, and send one follow-up on the same agent asking for the call |
| Cost on the Cursor usage call is missing | Billing data lags the run | Read `agent.getUsage()` again in a later step, or join the usage export by agent ID |
| A resumed session in a later job is "not found" | The session lived on the previous ephemeral runner | Upload the session store as an artifact, or keep triage and fix in one job |
| The SDK and a globally installed CLI behave differently | The SDK drives its own pinned binary, and your global CLI is another version | Pin the SDK version in `package.json` and upgrade on purpose; the Claude Agent SDK accepts `pathToClaudeCodeExecutable` when you must use a specific binary |

## Which SDK should a team standardise on?

Pick by where the team already works and by the control the job needs, not by the model: each SDK drives its own vendor's agent and default model.

- **Choose the Claude Agent SDK** when the job needs per-call permission decisions, hooks, in-process tools and a hard dollar cap in the same place. It has the widest control surface of the three.
- **Choose the Codex SDK** when the team already runs Codex and a sandbox boundary is the control you trust. It is the thinnest wrapper, and its per-turn schema makes multi-step pipelines on one thread straightforward.
- **Choose the Cursor SDK** when you want the agent to run on Cursor's cloud VMs and open the pull request itself, or when the team's rules and skills already live in Cursor.

For a lead, the standardisation decision is mostly about the shared parts: one prompt and schema file per job, one set of gates, one golden set and one cost dashboard. With those in place, switching the runner file is a small change, as the three tabs above show.

## Where to go next with agent SDKs

- [The Claude Agent SDK in depth](/en/claude-code/automate/agent-sdk/) — Sessions, hooks, subagents, in-process MCP tools and a full CI triage bot.
- [Building with the Codex SDK](/en/codex/automate/codex-sdk/) — Threads, resumption, structured output and configuration overrides.
- [The Cursor SDK and the Cloud Agents API](/en/cursor-ide/automate/cursor-sdk/) — Local and cloud agents from scripts, and a PR opened from a failing check.
- [From issue to pull request with no hands on the keyboard](/en/workflows/automate/issue-to-pr-pipeline/) — The end-to-end pipeline this triage runner plugs into.
- [Multi-agent orchestration patterns](/en/workflows/automate/orchestration-patterns/) — Planner, workers and judge, when your code coordinates several agents.
- [Agent frameworks and SDKs in the ecosystem](/en/ecosystem/frameworks/) — Where the vendor SDKs sit next to general agent frameworks.
