# Sterowanie agentami z kodu: Claude Agent SDK, Codex SDK i Cursor SDK

URL: https://developertoolkit.ai/pl/workflows/automate/agent-sdks/
Description: Kiedy sterować agentem z kodu zamiast go wyzwalać i czym różnią się Claude Agent SDK, Codex SDK i Cursor SDK – z jednym zadaniem triażu CI napisanym w każdym.

Claude Agent SDK, Codex SDK i Cursor SDK pozwalają, by agenta kodującego uruchamiał program, a nie człowiek: uruchamia go, ogranicza mu narzędzia, odczytuje typowany wynik i później wznawia pracę. SDK wybierz wtedy, gdy kod musi się rozgałęziać na podstawie tego, co znalazł agent; jednorazowy krok CI nadal lepiej obsłuży `claude -p` albo `codex exec`.

CI robi się czerwone o 2:10. Zanim ktokolwiek zajrzy, w kolejce czekają trzy kolejne pushe, a pierwsze pół godziny poranka schodzi na czytaniu 4000 linii logu tylko po to, by się dowiedzieć, że znowu zawiódł niestabilny test. Bota już próbowałeś: krok workflow przekazuje log do `claude -p` i publikuje odpowiedź jako komentarz. To pomaga, ale taki bot nie uruchomi ponownie niestabilnego testu i nie poczeka na wynik, nie otworzy drugiej sesji z prawem zapisu tylko wtedy, gdy werdykt brzmi „regresja”, a nikt nie wie, ile kosztował w zeszłym miesiącu. W tym miejscu przestajesz agenta wyzwalać i zaczynasz nim sterować z kodu.

Ta strona jest dla programistów, którzy budują taką automatyzację, i dla tech leadów, którzy decydują, na jakim SDK zespół się ustandaryzuje. Porównuje trzy SDK w pięciu wymiarach, które przesądzają o wyborze – sesje, narzędzia, uprawnienia, strumieniowanie i koszt – i pokazuje to samo zadanie napisane w każdym z nich.

## Co wyniesiesz z porównania SDK agentów

- Tabelę decyzyjną „wyzwolić czy oskryptować”, którą zastosujesz do każdego pomysłu na automatyzację.
- Porównanie trzech SDK pod kątem sesji, narzędzi, uprawnień, strumieniowania, ustrukturyzowanego wyniku i kosztu, sprawdzone na opublikowanych pakietach 26.09.2026.
- Runner triażu nieudanego przebiegu CI napisany trzy razy – w Claude Agent SDK, Codex SDK i Cursor SDK – ze wspólnym promptem i wspólnym JSON Schema oraz workflow GitHub Actions, który go wywołuje.
- Bramki, dzięki którym jego wynikowi można ufać bez czytania każdego przebiegu, i błędy, które pojawiają się najpierw.

## Oskryptować agenta czy go wyzwolić?

Większość zadań typu „agent w CI” nigdy nie potrzebuje SDK. Wyzwalacz – GitHub Action, zaplanowana automatyzacja albo pojedyncze wywołanie CLI w trybie headless – przyjmuje prompt i zwraca komentarz, plik albo pull request. SDK uzasadnia dodatkowy kod dopiero wtedy, gdy logika orkiestracji mieszka w twoim programie.

| Twoje zadanie wymaga… | Wystarczy wyzwalacz | Sięgnij po SDK |
| --- | --- | --- |
| Jeden prompt na wejściu, jeden wynik na wyjściu | `claude -p --output-format json`, `codex exec --json -o out.json`, tryb print w Cursorze, `anthropics/claude-code-action@v1`, `openai/codex-action@v1`, Cursor Automations | — |
| Typowanego wyniku, który konsumuje skrypt | `claude -p --json-schema`, `codex exec --output-schema FILE` | Gdy od wartości zależy następny krok |
| Różnych kroków zależnie od wyniku (ponowne uruchomienie, etykieta, sesja naprawcza) | Tylko przez kruchy klej w shellu | Tak: rozgałęzienie w kodzie, wznowienie tej samej sesji |
| Narzędzi, które wołają twoje systemy (zgłoszenia, feature flagi, wewnętrzne API) | Serwer MCP, który wdrażasz i utrzymujesz | Narzędzia w procesie: `createSdkMcpServer` w Claude, `customTools` w Cursorze |
| Decyzji o uprawnieniu przy każdym wywołaniu („pozwól na `git show`, zabroń `git push`, o resztę zapytaj usługę”) | Statyczne listy dozwolonych i zabronionych | Callback `canUseTool` i hooki w Claude |
| Postępu na żywo we własnym interfejsie, bocie albo logu | Śledzenie pliku JSONL | Typowane strumienie zdarzeń we wszystkich trzech SDK |
| Rozliczenia kosztu per przebieg, zespół albo klient | Parsowanie JSON-a z CLI | Pola kosztu lub zużycia w wyniku |
| Wielu agentów koordynowanych przez twój kod | — | Tak; zobacz [wzorce orkiestracji wielu agentów](/pl/workflows/automate/orchestration-patterns/) |

Reguła praktyczna: jeśli zadanie da się opisać jednym promptem ze stałym wynikiem, zostaw wyzwalacz. Jeśli łapiesz się na pisaniu instrukcji `if` wokół odpowiedzi agenta, przejdź na SDK. Opcje na poziomie CLI opisują osobno [automatyzacja w Claude Code](/pl/claude-code/automate/automation/) i [tryb nieinteraktywny Codeksa](/pl/codex/automate/non-interactive/).

## Czym różnią się Claude Agent SDK, Codex SDK i Cursor SDK?

Wszystkie trzy zamykają w bibliotece własnego agenta kodującego dostawcy: te same narzędzia, te same pliki instrukcji projektu i ten sam katalog modeli, których używasz interaktywnie. Różnią się tym, o czym może decydować twój kod. Wszystko poniżej odczytano z opublikowanych pakietów TypeScript 26.09.2026.

| | Claude Agent SDK | Codex SDK | Cursor SDK |
| --- | --- | --- | --- |
| Sprawdzone pakiety | 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 |
| Co działa pod spodem | Binarka Claude Code instalowana jako pakiet platformowy | CLI `codex` z `@openai/codex`, z którym SDK rozmawia przez JSONL na stdin i stdout | Agent lokalny albo agent chmurowy w izolowanej maszynie wirtualnej, gdy przekażesz `cloud` |
| Środowisko | Node 18+ | Node 18+ | Node 22.13+ |
| Punkt wejścia | `query({ prompt, options })`, asynchroniczny generator wiadomości | `new Codex().startThread()`, potem `thread.run()` albo `thread.runStreamed()` | `Agent.create()`, potem `agent.send()` zwracające `Run` |
| Sesje | `session_id` w każdej wiadomości; `resume`, `continue`, `forkSession` | `id` wątku; `codex.resumeThread(id)`; wątki zapisują się w `~/.codex/sessions` | `agentId`; `Agent.resume(id)`; agenci lokalni zapisują się w magazynie SQLite albo JSONL, ID agentów chmurowych zaczynają się od `bc-` |
| Ograniczanie narzędzi | `tools` ustala zestaw narzędzi; `allowedTools` tylko automatycznie zatwierdza; `disallowedTools` usuwa | Brak listy narzędzi; granicę wyznacza tryb sandboksa | `tools` i `disallowedTools` (tylko agenci lokalni) |
| Własne narzędzia | Serwer MCP w procesie przez `createSdkMcpServer()` i `tool()`, plus `mcpServers` | Serwery MCP z konfiguracji Codeksa | Callbacki `customTools` (tylko lokalnie), plus `mcpServers` |
| Uprawnienia | `permissionMode` (`default`, `acceptEdits`, `plan`, `dontAsk`, `auto`, `bypassPermissions`), callback `canUseTool`, hooki takie jak `PreToolUse` | `sandboxMode` (`read-only`, `workspace-write`, `danger-full-access`) plus `approvalPolicy` (`never`, `on-request`, `on-failure`, `untrusted`) | `local.sandboxOptions`, `local.autoReview` (Auto-review Cursora oparty na klasyfikatorze); agenta chmurowego izoluje jego maszyna wirtualna |
| Strumieniowanie | Każda wiadomość na bieżąco; `includePartialMessages` dodaje przyrosty tokenów | `runStreamed()` zwraca `thread.started`, `item.*`, `turn.completed`, `turn.failed`, `error` | `run.stream()` oraz callbacki `onStep` i `onDelta` w `send()` |
| Ustrukturyzowany wynik | `outputFormat: { type: 'json_schema', schema }` → `structured_output` w wyniku | `outputSchema` dla tury → JSON w `finalResponse` | Brak opcji schematu w 1.0.32; raport przechwytujesz przez własne narzędzie |
| Limity i koszt | `maxTurns`, `maxBudgetUsd`; `total_cost_usd` w wyniku, opisany w typach jako szacunek | `usage` w tokenach przy `turn.completed`; brak pola w dolarach i brak limitu kosztu; anulowanie przez `AbortSignal` | `agent.getUsage()` zwraca tokeny i koszt w centach, który może spóźniać się względem przebiegu; anulowanie przez `run.cancel()` |
| Model | Domyślny model Claude Code, chyba że ustawisz `model` | Domyślny model Codeksa, chyba że ustawisz `model`; `modelReasoningEffort` | `model` jest wymagany dla agentów lokalnych; listę ID daje `Cursor.models.list()` |

Trzy konsekwencje łatwo przeoczyć w tabeli:

- **Tylko Claude pozwala kodowi decydować o każdym wywołaniu narzędzia.** `canUseTool` i hooki `PreToolUse` widzą każde wywołanie, zanim się wykona. Codex SDK daje granicę sandboksa zamiast callbacku (w `@openai/codex-sdk` 0.157.1 nie ma hooka per wywołanie), a Cursor SDK – listy narzędzi i Auto-review.
- **Agent SDK domyślnie nie startuje w trybie auto.** Od Claude Code v2.1.283 (oba kanały wydań w dniu 2026-10-12) sesje interaktywne startują w trybie auto, ale Agent SDK i `claude -p` nadal startują w ręcznym trybie uprawnień (`default`), poza zewnętrznymi dostawcami i wyłączoną telemetrią, gdzie od v2.1.285 startują w trybie auto. Zadanie bez nadzoru, które liczy na odpowiedzi na pytania o zgodę, utknie albo dostanie odmowę, więc wybierz `dontAsk` z jawną listą dozwolonych poleceń.
- **Tylko Cursor SDK potrafi przekazać pracę do maszyny wirtualnej w chmurze.** Przekazanie `cloud: { repos: [...] }` uruchamia agenta na infrastrukturze Cursora, a ten może sam otworzyć pull request (`autoCreatePR`). Listy narzędzi, własne narzędzia i własny prompt systemowy działają w 1.0.32 tylko lokalnie, a połączenie `tools` z `cloud` rzuca `ConfigurationError`.

Model nie jest powodem wyboru SDK: każde z nich domyślnie używa domyślnego modelu swojego narzędzia. Zacznij od niego i dostrój poziom wysiłku (effort), zanim zmienisz model, a aktualne nazwy i ceny sprawdzaj w [przeglądzie modeli](/pl/ecosystem/models/).

## To samo zadanie trzy razy: triaż nieudanego przebiegu CI

Zadanie: gdy workflow `CI` się wyłoży, pobierz log nieudanych kroków, znajdź pierwszy prawdziwy błąd, odtwórz go, uruchom ponownie, by wykluczyć niestabilność, i zapisz `triage.json` z kategorią (`regression`, `flaky`, `infra`, `test-bug`), nieudanymi testami, podejrzanym commitem, dowodami i następnym krokiem. Agentowi nie wolno niczego edytować. O tym, co zrobić z werdyktem, decyduje późniejszy krok.

Trzy runnery dzielą jeden prompt i jeden schemat, więc zmiana dostawcy zmienia tylko plik runnera.

```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**

Cursor SDK nie ma opcji schematu wyniku, dlatego runner daje agentowi własne narzędzie `submit_triage`, którego schemat wejścia to schemat triażu. Argumenty wywołania tego narzędzia są raportem. Agent lokalny wymaga jawnego ID modelu; listę ID dostępnych dla twojego klucza zwraca `Cursor.models.list()`, a wybrane ID zapisz w `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` usuwa narzędzia edycji, ale `shell` zostaje, a z shella nadal da się zapisać plik. Regułę „bez edycji” egzekwuje dopiero krok `git diff --exit-code` w workflow poniżej.

**Claude Code**

Claude Agent SDK ma w jednym obiekcie opcji wszystko, czego potrzebuje to zadanie: ograniczony zestaw narzędzi, listę dozwolonych poleceń Bash, tryb odrzucający całą resztę, limit tur i dolarów oraz wynik sprawdzany schematem.

```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` nie zmniejsza zestawu narzędzi, tylko zatwierdza z góry. `Edit` i `Write` usuwa linia `tools`. Przebieg, który uderzy w limit, kończy się `subtype` równym `error_max_turns` albo `error_max_budget_usd`, a runner zamienia to w nieudany krok.

**Codex**

Codex SDK ogranicza agenta sandboksem zamiast listy narzędzi i przyjmuje schemat dla każdej tury. Limitu kosztu nie ma, więc zastępuje go sygnał z limitem czasu.

```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` to ostrzejszy sandbox, ale runner testów, który zapisuje cache albo plik pokrycia, wyłoży się pod nim, a agent zgłosi wtedy fałszywe „infra”. `workspace-write` z wyłączoną siecią plus bramka diffu to rozsądny środek.

Wszystkie trzy pliki przechodzą sprawdzanie typów w TypeScript 5 (`strict`, `NodeNext`) z wersjami pakietów z tabeli porównawczej. Uruchamiasz je przez `npx tsx ci/triage-<narzędzie>.ts`.

### Podłącz runner do GitHub Actions

Workflow jest taki sam dla wszystkich trzech SDK, z wyjątkiem ostatniej linii `run` i jej sekretu.

```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
```

Runner, jego prompt i zależności pochodzą z gałęzi domyślnej w `trusted/`; nieudany commit leży w `pr/`, gdzie agent go czyta i uruchamia jego testy. Ten podział nie pozwala gałęzi podmienić runnera, promptu ani ustawień agenta. Nie powstrzyma jednak testów samego commita przed uruchomieniem z kluczem w środowisku, a tego wymaga krok odtwarzania błędu, więc jest to do przyjęcia tylko dlatego, że job odrzuca commity z forków: wszystko, co do niego trafia, wypchnął ktoś z prawem zapisu. Daj jobowi osobny klucz API z limitem wydatków.

Dla runnera Codeksa przekaż `CODEX_API_KEY`, dla runnera Cursora – `CURSOR_API_KEY` i `CURSOR_MODEL_ID`. Zanim wybierzesz poświadczenie, sprawdź w warunkach dostawcy, czy praca bez nadzoru ma iść na kluczu API, czy na logowaniu z subskrypcji.

### Rozgałęzienie na werdykcie: tu SDK zaczyna się opłacać

Do tego miejsca tę samą pracę wykonałoby `claude -p --json-schema` albo `codex exec --output-schema`. SDK jest warte swojego kodu wtedy, gdy następny krok zależy od odpowiedzi i korzysta z kontekstu, który agent już zebrał:

1. Odczytaj `triage.json` i zwaliduj go względem `triageSchema` walidatorem JSON Schema. Raport, który nie przejdzie walidacji, oblewa zadanie; nikt na jego podstawie nie działa.

2. Przy `flaky` uruchom ponownie nieudane joby (`gh run rerun <run-id> --failed`; ten krok wymaga `actions: write` w swoim jobie) i dopisz test do listy kwarantanny. Bez drugiej sesji agenta.

3. Przy `infra` wyślij dowody na kanał dyżurny i zakończ.

4. Przy `regression` albo `test-bug` wznów tę samą sesję z prawem zapisu na nowej gałęzi, żeby agent zachował to, co już przeczytał:
   - Claude Agent SDK: `query({ prompt, options: { resume: sessionId, tools: { type: 'preset', preset: 'claude_code' }, permissionMode: 'acceptEdits' } })`.
   - Codex SDK: `codex.resumeThread(threadId, { sandboxMode: 'workspace-write' })`, potem `thread.run(...)`.
   - Cursor SDK: `agent.send(...)` na tym samym agencie albo `Agent.resume(agentId)` z późniejszego joba; ograniczenia narzędzi nie są zapisywane, więc przekaż je ponownie.

5. Sesja naprawcza otwiera pull request z raportem triażu jako dowodem i przechodzi przez te same bramki co każda inna zmiana agenta: zobacz [pakiet dowodów, który musi nieść pull request agenta](/pl/workflows/ship/evidence-bundle/).

Runner GitHub Actions jest efemeryczny, więc zapisana na nim sesja znika razem z końcem joba. Żeby wznowić ją w późniejszym jobie, zapisz magazyn sesji (`~/.claude/projects`, `~/.codex/sessions` albo lokalny magazyn Cursora) jako artefakt albo trzymaj cały przepływ w jednym jobie.

## Prompty do skopiowania przy budowie runnera SDK

**Prompt do skopiowania: zbuduj runner triażu w swoim repozytorium**

```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.
```

**Prompt do skopiowania: audyt raportu triażu, zanim ktoś na nim zadziała**

```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.
```

Prompt audytowy uruchamiaj na innym modelu albo u innego dostawcy niż runner, żeby autor nigdy nie oceniał sam siebie; jak skalibrować takiego sędziego, opisują [kontrole oceniane przez model](/pl/workflows/test/model-graded-checks/).

## Jak udowodnić, że triaż jest trafny, bez czytania każdego przebiegu?

Traktuj runner jak każdą inną produkcyjną ścieżkę kodu, na której wyniku działa kolejna automatyzacja. Bramki w kolejności, w jakiej się uruchamiają:

1. **Schemat.** SDK waliduje kształt wyniku (Claude, Codex) albo ogranicza go schemat wejścia własnego narzędzia (Cursor). Twój krok waliduje go ponownie przed działaniem, bo przebieg, który uderzy w limit, może skończyć się bez raportu.
2. **Brak skutków ubocznych.** `git diff --exit-code` oblewa zadanie, jeśli agent zmienił śledzony plik. Ograniczenia narzędzi zmniejszają ryzyko; diff to udowadnia.
3. **Limity.** `maxTurns` i `maxBudgetUsd` w Claude, limit czasu w Codeksie i Cursorze oraz `timeout-minutes` na jobie. Przebieg zatrzymany limitem to przebieg nieudany, nigdy częściowy werdykt.
4. **Złoty zbiór.** Zbierz dawne nieudane przebiegi z etykietą, co do której ludzie już się zgodzili, w tym przypadki `flaky`, `infra` i `regression`. Odtwarzaj na nich runner po każdej zmianie SDK, modelu albo promptu i śledź zgodność. Zanim runner zacznie sam uruchamiać joby ponownie albo nadawać etykiety, ustal z góry, jakiej zgodności wymagasz; do tego czasu tylko komentuje.
5. **Niezależny audyt.** Prompt audytowy powyżej, uruchomiony na innym modelu, odrzuca werdykty, których dowodów nie ma w logu.
6. **Telemetria.** Loguj ID sesji albo wątku, liczbę tur, tokeny i koszt każdego przebiegu i łącz je z ID przebiegu CI. Strona o [obserwowalności agentów](/pl/workflows/operate/agent-observability/) pokazuje dashboard: odsetek udanych przebiegów, koszt zaakceptowanego werdyktu i odsetek werdyktów odrzuconych przez ludzi.

**Kto zatwierdza:** dyżurny programista odpowiada za każde działanie proponowane przez runner, dopóki zgodność na złotym zbiorze nie osiągnie progu ustalonego przez tech leada. Potem tech lead zatwierdza poszerzanie uprawnień runnera po jednym działaniu naraz, zaczynając od ponownego uruchamiania niestabilnych testów.

## Co się psuje, gdy sterujesz agentami przez SDK?

**Pułapki, które uderzają najpierw**

- **`allowedTools` traktowane jak ograniczenie.** W Claude Agent SDK to wyłącznie wstępna zgoda. Agent nadal ma każde narzędzie, którego nie usunięto przez `tools` albo `disallowedTools`.
- **Przeciekają osobiste ustawienia runnera.** Pominięcie `settingSources` w Claude Agent SDK ładuje wszystkie źródła (user, project, local). Przekaż `[]`, gdy katalog roboczy zawiera kod, którego nikt nie przejrzał, jak tutaj nieudany commit, żeby do przebiegu z twoim kluczem nie trafiło ani `~/.claude` z obrazu, ani hooki z `.claude/settings.json`, `.mcp.json` czy `CLAUDE.md` z tego commita. `['project']` stosuj tylko dla zaufanego checkoutu. Cursor SDK ma tę samą opcję dla agentów lokalnych.
- **Pakiety o podobnych nazwach.** Pythonowe Codex SDK to `openai-codex`; `openai-codex-sdk` na PyPI nie pochodzi od OpenAI. OpenAI Agents SDK (`openai-agents`, `@openai/agents`) to ogólny framework agentowy, a nie agent kodujący Codex. „Claude Code SDK” to dawna nazwa Claude Agent SDK.
- **Pull requesty z forków a sekrety.** Job `workflow_run` działa z twoimi kluczami API na nieudanym commicie. Bez sprawdzenia `head_repository` każdy może otworzyć pull request z plikiem testu, który każe agentowi wypisać zmienne środowiskowe.

| Objaw | Przyczyna | Wyjście z sytuacji |
| --- | --- | --- |
| Przebieg Claude kończy się `error_max_budget_usd` albo `error_max_turns` bez raportu | Limit jest za niski przy rozmiarze logów repozytorium albo agent kręci się w zaszumionym logu | Przytnij log do nieudanego kroku przed przebiegiem (`--log-failed` już w tym pomaga), potem podnoś po jednym limicie i zapisz nowy koszt w przebiegu na złotym zbiorze |
| Przebieg Codeksa wisi do limitu czasu | Polecenie czekało na wejście albo na sieć przy `networkAccessEnabled: false` | Przeczytaj ostatni element `command_execution` w strumieniowanym logu; dopisz w prompcie flagę nieinteraktywną do polecenia odtwarzającego |
| Każdy werdykt Codeksa to „infra” | Sandbox `read-only`, a runner testów musi zapisać cache | Przełącz na `workspace-write` i zachowaj bramkę diffu |
| `Agent.create` w Cursorze rzuca `ConfigurationError` | `tools`, `disallowedTools` albo `systemPrompt` w połączeniu z `cloud` (a `customTools` też działa tylko lokalnie) | Uruchom triaż jako agenta lokalnego albo usuń te opcje dla agenta chmurowego i ogranicz go promptem oraz dostępem do repozytorium, jaki mu dajesz |
| Cursor zgłasza `finished`, ale `report` jest pusty | Agent odpowiedział tekstem i nigdy nie wywołał `submit_triage` | Traktuj to jako porażkę (runner już rzuca wyjątek); powtórz na końcu promptu polecenie wywołania narzędzia i wyślij na tym samym agencie jedną wiadomość z prośbą o wywołanie |
| Brakuje kosztu w odczycie zużycia z Cursora | Dane rozliczeniowe spóźniają się względem przebiegu | Odczytaj `agent.getUsage()` ponownie w późniejszym kroku albo połącz eksport zużycia po ID agenta |
| Wznowiona w późniejszym jobie sesja jest „not found” | Sesja żyła na poprzednim, efemerycznym runnerze | Wgraj magazyn sesji jako artefakt albo trzymaj triaż i naprawę w jednym jobie |
| SDK i globalnie zainstalowane CLI zachowują się inaczej | SDK steruje własną przypiętą binarką, a twoje globalne CLI ma inną wersję | Przypnij wersję SDK w `package.json` i aktualizuj świadomie; Claude Agent SDK przyjmuje `pathToClaudeCodeExecutable`, gdy musisz użyć konkretnej binarki |

## Na którym SDK zespół powinien się ustandaryzować?

Wybieraj według tego, gdzie zespół już pracuje, i kontroli, jakiej wymaga zadanie, a nie według modelu: każde SDK steruje agentem swojego dostawcy i jego domyślnym modelem.

- **Wybierz Claude Agent SDK**, gdy zadanie potrzebuje w jednym miejscu decyzji o uprawnieniach przy każdym wywołaniu, hooków, narzędzi w procesie i twardego limitu w dolarach. Ma najszerszą powierzchnię kontroli z całej trójki.
- **Wybierz Codex SDK**, gdy zespół już pracuje z Codeksem, a kontrolą, której ufasz, jest granica sandboksa. To najcieńsza nakładka, a schemat per tura ułatwia wieloetapowe potoki na jednym wątku.
- **Wybierz Cursor SDK**, gdy agent ma pracować na maszynach wirtualnych Cursora w chmurze i sam otwierać pull request albo gdy reguły i skille zespołu już mieszkają w Cursorze.

Dla leada decyzja o standardzie dotyczy głównie części wspólnych: jednego pliku z promptem i schematem na zadanie, jednego zestawu bramek, jednego złotego zbioru i jednego dashboardu kosztów. Gdy to masz, wymiana pliku runnera jest drobną zmianą, co pokazują trzy zakładki powyżej.

## Co dalej z SDK agentów

- [Claude Agent SDK w szczegółach](/pl/claude-code/automate/agent-sdk/) — Sesje, hooki, subagenci, narzędzia MCP w procesie i kompletny bot triażu CI.
- [Budowanie z Codex SDK](/pl/codex/automate/codex-sdk/) — Wątki, wznawianie, ustrukturyzowany wynik i nadpisywanie konfiguracji.
- [Cursor SDK i Cloud Agents API](/pl/cursor-ide/automate/cursor-sdk/) — Agenci lokalni i chmurowi uruchamiani ze skryptów oraz PR otwarty z nieudanego checku.
- [Od zgłoszenia do pull requesta bez rąk na klawiaturze](/pl/workflows/automate/issue-to-pr-pipeline/) — Kompletny potok, do którego podłącza się ten runner triażu.
- [Wzorce orkiestracji wielu agentów](/pl/workflows/automate/orchestration-patterns/) — Planista, wykonawcy i sędzia, gdy twój kod koordynuje kilku agentów.
- [Frameworki agentowe i SDK w ekosystemie](/pl/ecosystem/frameworks/) — Gdzie SDK dostawców stoją obok ogólnych frameworków agentowych.
