Skip to content

guanyang/open-agent-hub / skills/claude-api

claude-api

Unverified

Reference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).

FileKindSize
LICENSE.txtmarkdown11.1 KB
SKILL.mdskill md102.7 KB
csharp/claude-api.mdmarkdown15.3 KB
csharp/claude-api/README.mdmarkdown18.5 KB
csharp/claude-api/batches.mdmarkdown413 B
csharp/claude-api/files-api.mdmarkdown900 B
csharp/claude-api/streaming.mdmarkdown787 B
csharp/claude-api/tool-use.mdmarkdown7.4 KB
curl/examples.mdmarkdown9.5 KB
curl/managed-agents.mdmarkdown10.5 KB
go/claude-api.mdmarkdown14.4 KB
go/claude-api/README.mdmarkdown8.3 KB
go/claude-api/files-api.mdmarkdown936 B
go/claude-api/streaming.mdmarkdown1.0 KB
go/claude-api/tool-use.mdmarkdown9.8 KB
go/managed-agents/README.mdmarkdown21.9 KB
java/claude-api.mdmarkdown15.5 KB
java/claude-api/README.mdmarkdown11.7 KB
java/claude-api/files-api.mdmarkdown1.2 KB
java/claude-api/streaming.mdmarkdown655 B
java/claude-api/tool-use.mdmarkdown10.9 KB
java/managed-agents/README.mdmarkdown20.0 KB
php/claude-api.mdmarkdown11.5 KB
php/claude-api/README.mdmarkdown6.4 KB
php/claude-api/batches.mdmarkdown447 B
php/claude-api/files-api.mdmarkdown476 B
php/claude-api/streaming.mdmarkdown682 B
php/claude-api/tool-use.mdmarkdown9.5 KB
php/managed-agents/README.mdmarkdown16.2 KB
python/agent-sdk/README.mdmarkdown12.4 KB
python/agent-sdk/patterns.mdmarkdown9.0 KB
python/claude-api/README.mdmarkdown20.1 KB
python/claude-api/batches.mdmarkdown5.6 KB
python/claude-api/files-api.mdmarkdown4.4 KB
python/claude-api/sdk-upgrade.mdmarkdown28.1 KB
python/claude-api/streaming.mdmarkdown11.7 KB
python/claude-api/tool-use.mdmarkdown20.9 KB
python/managed-agents/README.mdmarkdown14.5 KB
ruby/claude-api.mdmarkdown3.4 KB
ruby/claude-api/README.mdmarkdown4.7 KB
ruby/claude-api/streaming.mdmarkdown235 B
ruby/claude-api/tool-use.mdmarkdown2.6 KB
ruby/managed-agents/README.mdmarkdown11.9 KB
shared/admin-api.mdmarkdown11.3 KB
shared/agent-design.mdmarkdown8.5 KB
shared/anthropic-cli.mdmarkdown23.4 KB
shared/claude-platform-on-aws.mdmarkdown4.3 KB
shared/cost-optimization.mdmarkdown57.1 KB
shared/error-codes.mdmarkdown20.3 KB
shared/evals/build-eval.mdmarkdown53.5 KB
shared/evals/cost-hillclimb.mdmarkdown31.0 KB
shared/evals/eval-audit.mdmarkdown27.2 KB
shared/evals/eval-hillclimb.mdmarkdown67.5 KB
shared/evals/report/SCHEMA.mdmarkdown15.7 KB
shared/evals/report/build-report-lite.mjsscript26.7 KB
shared/evals/report/runner-scaffold.mjsscript32.4 KB
shared/live-sources.mdmarkdown17.3 KB
shared/managed-agents-api-reference.mdmarkdown34.5 KB
shared/managed-agents-client-patterns.mdmarkdown11.8 KB
shared/managed-agents-core.mdmarkdown32.7 KB
shared/managed-agents-environments.mdmarkdown13.9 KB
shared/managed-agents-events.mdmarkdown25.4 KB
shared/managed-agents-memory.mdmarkdown11.1 KB
shared/managed-agents-multiagent.mdmarkdown65.1 KB
shared/managed-agents-onboarding-from-quickstart.mdmarkdown19.3 KB
shared/managed-agents-onboarding-from-url.mdmarkdown31.9 KB
shared/managed-agents-onboarding.mdmarkdown16.4 KB
shared/managed-agents-outcomes.mdmarkdown8.8 KB
shared/managed-agents-overview.mdmarkdown14.2 KB
shared/managed-agents-quickstarts/bug-hunter.mdmarkdown7.9 KB
shared/managed-agents-quickstarts/contract-tracker.mdmarkdown1.8 KB
shared/managed-agents-quickstarts/data-analyst.mdmarkdown1.5 KB
shared/managed-agents-quickstarts/deep-researcher.mdmarkdown2.4 KB
shared/managed-agents-quickstarts/explainer-video-maker.mdmarkdown4.8 KB
shared/managed-agents-quickstarts/field-monitor.mdmarkdown2.1 KB
shared/managed-agents-quickstarts/incident-commander.mdmarkdown1.7 KB
shared/managed-agents-quickstarts/performance-tuner.mdmarkdown11.1 KB
shared/managed-agents-quickstarts/sprint-retro-facilitator.mdmarkdown2.0 KB
shared/managed-agents-quickstarts/structured-extractor.mdmarkdown1.5 KB
shared/managed-agents-quickstarts/support-agent.mdmarkdown1.4 KB
shared/managed-agents-quickstarts/support-to-eng-escalator.mdmarkdown1.8 KB
shared/managed-agents-quickstarts/watchlist-scanner.mdmarkdown5.5 KB
shared/managed-agents-scheduled-deployments.mdmarkdown9.3 KB
shared/managed-agents-self-hosted-sandboxes.mdmarkdown27.3 KB
shared/managed-agents-tools.mdmarkdown37.0 KB
shared/managed-agents-webhooks.mdmarkdown11.1 KB
shared/model-migration.mdmarkdown338.1 KB
shared/models.mdmarkdown17.1 KB
shared/platform-availability.mdmarkdown7.2 KB
shared/preserved-thinking-migration.mdmarkdown62.5 KB
shared/preserved-thinking-migration/causes.mdmarkdown38.8 KB
shared/preserved-thinking-migration/drop_block_probe.pyscript65.0 KB
shared/preserved-thinking-migration/prefix_diff.pyscript91.8 KB
shared/prompt-audit.mdmarkdown48.2 KB
shared/prompt-caching.mdmarkdown32.3 KB
shared/token-counting.mdmarkdown1.6 KB
shared/tool-use-concepts.mdmarkdown43.3 KB
typescript/agent-sdk/README.mdmarkdown10.6 KB
typescript/agent-sdk/patterns.mdmarkdown4.6 KB
typescript/claude-api/README.mdmarkdown15.5 KB
typescript/claude-api/batches.mdmarkdown2.5 KB
typescript/claude-api/files-api.mdmarkdown2.3 KB
typescript/claude-api/streaming.mdmarkdown9.3 KB
typescript/claude-api/tool-use.mdmarkdown23.7 KB
typescript/managed-agents/README.mdmarkdown13.7 KB

shared/managed-agents-client-patterns.md

View on GitHub
# Managed Agents - Common Client Patterns

Patterns you'll write on the client side when driving a Managed Agent session, grounded in working SDK examples.

Code samples are TypeScript - other languages follow the same shape; see `{lang}/managed-agents/README.md` (cURL and C#: `curl/managed-agents.md`) for equivalents.

---

## 1. Lossless stream reconnect

**Problem:** SSE has no replay. If the connection drops mid-session, a naive reconnect re-opens the stream from "now" and you silently miss every event emitted in between.

**Solution:** on reconnect, fetch the full event history via `events.list()` *before* consuming the live stream, and dedupe on event ID as the live stream catches up.

```ts
const seenEventIds = new Set<string>()
const stream = await client.beta.sessions.events.stream(session.id)

// Stream is now open and buffering server-side. Read history first.
for await (const event of client.beta.sessions.events.list(session.id)) {
  seenEventIds.add(event.id)
  handle(event)
}

// Tail the live stream. Dedupe only gates handle() - terminal checks must run
// even for already-seen events, or a terminal event that was in the history
// response gets skipped by `continue` and the loop never exits.
for await (const event of stream) {
  if (!seenEventIds.has(event.id)) {
    seenEventIds.add(event.id)
    handle(event)
  }
  if (event.type === 'session.status_terminated') break
  if (event.type === 'session.status_idle' && event.stop_reason.type !== 'requires_action') break
}
```

---

## 2. `processed_at` - queued vs processed

Every event on the stream carries `processed_at` (ISO 8601), set when the event finishes processing. For client-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`) it's `null` while the event is queued behind earlier ones, and populated once the agent processes it - so the same event appears on the stream twice, once with `null` and once with a timestamp. (Exception: a `user.interrupt` sent while the session is paused at its budget is accepted and ignored - it never appears at all; see `shared/managed-agents-events.md` § Reaching a session budget.)

**Three event types skip the queued phase:** `user.define_outcome`, `user.custom_tool_result`, and `user.tool_result` are processed on receipt and echoed back with `processed_at` already populated. A pending -> acknowledged UI that assumes "first sighting is always `null`" will never clear for these - treat a populated `processed_at` on first sighting as immediately acknowledged.

```ts
for await (const event of stream) {
  if (event.type === 'user.message') {
    if (event.processed_at == null) onQueued(event.id)
    else onProcessed(event.id, event.processed_at)
  }
}
```

Use this to drive pending -> acknowledged UI state for anything you send. How you map a locally-rendered optimistic message to the server-assigned `event.id` is application-specific (typically via the return value of `events.send()` or FIFO ordering).

---

## 3. Interrupt a running session

Send `user.interrupt` as a normal event. The session keeps running until it reaches a safe boundary, then goes idle.

```ts
await client.beta.sessions.events.send(session.id, {
  events: [{ type: 'user.interrupt' }],
})

// Drain until the session is truly done - see Pattern 5 for the full gate.
for await (const event of stream) {
  if (event.type === 'session.status_terminated') break
  if (
    event.type === 'session.status_idle' &&
    event.stop_reason.type !== 'requires_action'
  ) break
}
```

Reference: `interrupt.ts` - sends the interrupt the moment it sees `span.model_request_start`, drains to idle, then verifies via `sessions.retrieve()`.

---

## 4. `tool_confirmation` round-trip

When a call evaluates to `ask` - the tool has `permission_policy: { type: 'always_ask' }`, or it has `{ type: 'auto' }` and the server reached no determination - the `agent.tool_use` / `agent.mcp_tool_use` event carries `evaluated_permission === 'ask'` and the session goes idle waiting for a decision. Respond with `user.tool_confirmation`.

```ts
for await (const event of stream) {
  if ((event.type === 'agent.tool_use' || event.type === 'agent.mcp_tool_use') && event.evaluated_permission === 'ask') {
    await client.beta.sessions.events.send(session.id, {
      events: [{
        type: 'user.tool_confirmation',
        tool_use_id: event.id,         // not a toolu_ id - use event.id
        result: (await approve(event)) ? 'allow' : 'deny', // you write approve(): ask a person or apply your own rule; deny when unattended
        // deny_message: '...',        // optional, only with result: 'deny'
      }],
    })
  }
}
```

Key points:
- `tool_use_id` is `event.id` (typically `sevt_...`), **not** a `toolu_...` ID.
- `result` is `'allow' | 'deny'`. Use `deny_message` to tell the model *why* you denied - it gets surfaced back to the agent.
- Multiple pending tools: respond once per `agent.tool_use` / `agent.mcp_tool_use` event with `evaluated_permission === 'ask'`.
- Gate on `evaluated_permission === 'ask'`, not on the policy you configured - it covers `always_ask` and `auto`-indeterminate alike. Calls the server **denies** under `auto` (`evaluated_permission === 'deny'`, `evaluation.evaluated_permission.reason_code === 'high_risk'`) never enter this flow: the agent gets an error tool result and the session keeps running; sending a confirmation for one is a 400.
- Log `event.evaluation` for audit (`type` + `reason_code`), and tolerate a `type` or `reason_code` you don't recognize - branch on known values, pass unknown ones through.

Reference: `tool-permissions.ts`.

---

## 5. Correct idle-break gate

Do not break on `session.status_idle` alone. The session goes idle transiently - e.g. between parallel tool executions, while waiting for a `user.tool_confirmation`, or while awaiting a `user.custom_tool_result`. Break when idle with a non-`requires_action` `stop_reason` (terminal, or `budget_reached` - resumable only by a budget update, so break unless you intend to change or remove the budget), or on `session.status_terminated`.

```ts
for await (const event of stream) {
  handle(event)
  if (event.type === 'session.status_terminated') break
  if (event.type === 'session.status_idle') {
    if (event.stop_reason.type === 'requires_action') continue // waiting on you - handle it
    break // end_turn, retries_exhausted, or budget_reached - see list below
  }
}
```

`stop_reason.type` values on `session.status_idle`:
- `requires_action` - agent is waiting on a client-side event (tool confirmation, custom tool result). Handle it, don't break. **Self-hosted exception:** if the session went `requires_action`-idle with no pending `agent.tool_use` / `agent.mcp_tool_use` (`ask`) or `agent.custom_tool_use` to answer, the worker failed the claimed work item (typically a memory-store mount error, logged only on the worker host). Don't `continue` forever on that - surface it, fix the host, and send `user.interrupt` to re-queue the work (`shared/managed-agents-self-hosted-sandboxes.md` § Memory stores -> Troubleshooting).
- `retries_exhausted` - terminal failure. Break, then check `sessions.retrieve()` for the error state.
- `end_turn` - normal completion.
- `budget_reached` - the session hit its spend cap and paused. Not terminal and not resumable by any event: change (typically raise) or remove the session's `budget` to resume, or treat it as done. A `session.usage` event with the final cost immediately precedes this idle. See `shared/managed-agents-core.md` § Session budgets.

---

## 6. Post-idle status-write race

The SSE stream emits `session.status_idle` slightly before the session's queryable status reflects it. Clients that break on idle and immediately call `sessions.delete()` or `sessions.archive()` will intermittently 400 with "cannot delete/archive while running."

Poll before cleanup:

```ts
let s
for (let i = 0; i < 10; i++) {
  s = await client.beta.sessions.retrieve(session.id)
  if (s.status !== 'running') break
  await new Promise(r => setTimeout(r, 200))
}
if (s?.status !== 'running') {
  await client.beta.sessions.archive(session.id)
} // else: still running after 2s - don't archive, let it settle or escalate
```

---

## 7. Stream-first, then send

Always open the stream **before** sending the kickoff event. Otherwise the agent may process the event and emit the first events before your consumer is attached, and you'll miss them.

```ts
const stream = await client.beta.sessions.events.stream(session.id)
await client.beta.sessions.events.send(session.id, {
  events: [{ type: 'user.message', content: [{ type: 'text', text: 'Hello' }] }],
})
for await (const event of stream) { /* ... */ }
```

The `Promise.all([stream, send])` shape works too, but stream-first is simpler and has the same effect - the stream starts buffering the moment it's opened.

---

## 8. File-mount gotchas

**The mounted resource has a different `file_id` than the file you uploaded.** Session creation makes a session-scoped copy.

```ts
const uploaded = await client.beta.files.upload({ file })
// uploaded.id         -> the original file
const session = await client.beta.sessions.create({
  /* ... */
  resources: [{ type: 'file', file_id: uploaded.id, mount_path: '/data.csv' }],
})
// session.resources[0].file_id !== uploaded.id  <- different IDs
```

Delete the original via `files.delete(uploaded.id)`; the session-scoped copy is garbage-collected with the session. `mount_path` must be absolute - see `shared/managed-agents-environments.md`.

---

## 9. Secrets for non-MCP APIs and CLIs - keep them host-side via custom tools

**Problem:** you want the agent to call a third-party API or run a CLI that needs a secret (API key, token, service-account credential), but you can't or don't want to hand the secret to a vault.

**First check:** for cloud environments, the first-class answer is now a vault `environment_variable` credential - the agent's shell sees an opaque placeholder and the real secret is substituted at egress. See `shared/managed-agents-tools.md` -> Vaults. Use this pattern instead when that doesn't fit: **self-hosted sandboxes** (env-var credentials not yet supported there), clients that reject the placeholder via local format validation, secrets that must never leave your infrastructure, or calls that need host-side binaries.

**Solution:** move the authenticated call to your side. Declare a custom tool on the agent; when the agent emits `agent.custom_tool_use`, your orchestrator (the process reading the SSE stream) executes the call with its own credentials and responds with `user.custom_tool_result`. The container never sees the key.

```ts
// Agent template: declare the tool, no credentials
tools: [{ type: 'custom', name: 'linear_graphql', input_schema: { /* query, vars */ } }]

// Orchestrator: handle the call with host-side creds
for await (const event of stream) {
  if (event.type === 'agent.custom_tool_use' && event.name === 'linear_graphql') {
    const result = await linear.request(event.input.query, event.input.vars) // host's key
    await client.beta.sessions.events.send(session.id, {
      events: [{
        type: 'user.custom_tool_result',
        custom_tool_use_id: event.id,
        content: [{ type: 'text', text: JSON.stringify(result) }],
      }],
    })
  }
}
```

Same shape works for `gh` CLI, local eval scripts, or anything else that needs host-side auth or binaries.

**Security note:** this does not expose a public endpoint. `agent.custom_tool_use` arrives on the SSE stream your orchestrator already holds open with your Anthropic API key, and `user.custom_tool_result` goes back via `events.send()` under the same key. Your orchestrator is a client, not a server - nothing unauthenticated is listening.

**Do not embed API keys in the system prompt or user messages as a workaround.** Prompts and messages are stored in the session's event history, returned by `events.list()`, and included in compaction summaries - a secret placed there is durably persisted and readable via the API for the life of the session.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall