6 ファイル変更+282-95
この更新の概要
Agent SDKのPython向けドキュメントが大幅に拡充され、構造化出力におけるJSON Schema draft-07の準拠が必須要件として明示されました。サブエージェント機能において、メイン会話の出力スタイルや自動メモリが継承されない仕様が詳細に記述されています。また、TypeScript SDKのisolationプロパティに新しい選択肢としてremoteが追加されました。これらにより、エージェントの動作制御とメモリ管理の仕様がより具体化されています。
SDKがJSON Schema draft-07を期待するため、Zodを使用する際にtargetオプションを指定する必要があることや、出力失敗時のエラーハンドリング方法が追加されました。
@@ -131,6 +131,8 @@ Instead of writing JSON Schema by hand, you can use [Zod](https://zod.dev/) (Typ
The example below defines a schema for a feature implementation plan with a summary, list of steps (each with complexity level), and potential risks. The agent plans the feature and returns a typed `FeaturePlan` object. You can then access properties like `plan.summary` and iterate over `plan.steps` with full type safety.
The SDK validates schemas with JSON Schema draft-07, so schemas that declare a newer version are rejected. Zod targets draft 2020-12 by default, so pass `target: "draft-7"` when converting your schema.
```typescript TypeScript theme={null}
import { z } from "zod";
import { query } from "@anthropic-ai/claude-agent-sdk";
@@ -151,8 +153,8 @@ const FeaturePlan = z.object({
type FeaturePlan = z.infer<typeof FeaturePlan>;
// Convert to JSON Schema
const schema = z.toJSONSchema(FeaturePlan);
// Convert to JSON Schema using the draft-07 target the SDK expects
const schema = z.toJSONSchema(FeaturePlan, { target: "draft-7" });
// Use in query
try {
@@ -242,7 +244,7 @@ asyncio.run(main())
The `outputFormat` (TypeScript) or `output_format` (Python) option accepts an object with:
- `type`: Set to `"json_schema"` for structured outputs
- `schema`: A [JSON Schema](https://json-schema.org/understanding-json-schema/about) object defining your output structure. You can generate this from a Zod schema with `z.toJSONSchema()` or a Pydantic model with `.model_json_schema()`
- `schema`: A [JSON Schema](https://json-schema.org/understanding-json-schema/about) object defining your output structure. You can generate this from a Zod schema with `z.toJSONSchema(schema, { target: "draft-7" })` or a Pydantic model with `.model_json_schema()`
The SDK supports standard JSON Schema features including all basic types (object, array, string, number, boolean, null), `enum`, `const`, `required`, nested objects, and `$ref` definitions. For the full list of supported features and limitations, see [JSON Schema limitations](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#json-schema-limitations).
@@ -364,7 +366,7 @@ asyncio.run(main())
## Error handling
Structured output generation can fail when the agent cannot produce valid JSON matching your schema. This typically happens when the schema is too complex for the task, the task itself is ambiguous, or the agent hits its retry limit trying to fix validation errors. It can also happen without any validation failure: a [model fallback](/en/model-config#automatic-model-fallback) can retract an already-completed output mid-stream, and if no retry replaces it the run ends with the same error. Check the `errors` field on the result message to tell the two causes apart before debugging your schema.
Structured output generation can fail when the agent cannot produce valid JSON matching your schema. This typically happens when the schema is too complex for the task, the task itself is ambiguous, or the agent hits its retry limit trying to fix validation errors. It can also happen without any validation failure: a [model fallback](/en/model-config#automatic-model-fallback) can retract an already-completed output mid-stream, and if no retry replaces it the run ends with the same error. Check the `errors` list on the result message to tell the two causes apart before debugging your schema.
When an error occurs, the result message has a `subtype` indicating what went wrong:
@@ -373,7 +375,7 @@ When an error occurs, the result message has a `subtype` indicating what went wr
| `success` | Output was generated and validated successfully |
| `error_max_structured_output_retries` | No valid output remained after multiple attempts (validation failures, or a model-fallback retraction with no successful retry) |
The example below checks the `subtype` field to determine whether the output was generated successfully or if you need to handle a failure:
A result can also end with subtype `success` but no `structured_output` value, for example when the run completes without the agent producing a structured output. Treat that case as a failure as well. The example below treats a result as successful only when the `subtype` is `success` and `structured_output` is present, and handles every other result as a failure:
```typescript TypeScript theme={null}
import { query } from "@anthropic-ai/claude-agent-sdk";
@@ -403,6 +405,8 @@ try {
console.log(msg.structured_output);
} else if (msg.subtype === "error_max_structured_output_retries") {
console.error("Could not produce valid output");
} else {
console.error("Run ended without a structured output");
}
}
}
@@ -443,6 +447,8 @@ async def main():
print(message.structured_output)
elif message.subtype == "error_max_structured_output_retries":
print("Could not produce valid output")
else:
print("Run ended without a structured output")
except Exception as error:
# A single-shot query() raises after yielding an error result.
# If the failure was an error result, the subtype branches above
@@ -797,7 +797,7 @@ type PermissionMode =
| "bypassPermissions" // Bypass permission checks; explicit ask rules still prompt
| "plan" // Planning mode - explore without editing
| "dontAsk" // Don't prompt for permissions, deny if not pre-approved
| "auto"; // Use a model classifier to approve or deny each tool call
| "auto"; // Model classifier approves or denies permission prompts
```
### `CanUseTool`
@@ -1829,7 +1829,7 @@ type AgentInput = {
run_in_background?: boolean;
name?: string;
mode?: "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan";
isolation?: "worktree";
isolation?: "worktree" | "remote";
};
```
@@ -372,6 +372,8 @@ This limit applies only to `MEMORY.md`. CLAUDE.md files are loaded in full regar
Topic files like `debugging.md` or `patterns.md` are not loaded at startup. Claude reads them on demand using its standard file tools when it needs the information.
The main conversation's auto memory isn't loaded into [subagents](/en/sub-agents#what-loads-at-startup); the exception is a [fork](/en/sub-agents#fork-the-current-conversation), which inherits the parent conversation and system prompt. A subagent's own auto memory, enabled with the subagent `memory` field, is a separate directory.
Claude reads and writes memory files during your session. When you see "Writing memory" or "Recalled memory" in the Claude Code interface, Claude is actively updating or reading from `~/.claude/projects/<project>/memory/`.
### Audit and edit your memory
@@ -94,6 +94,8 @@ Output styles directly modify Claude Code's system prompt.
- All output styles trigger reminders for Claude to adhere to the output style instructions during the conversation.
- Custom output styles leave out Claude Code's built-in software engineering instructions, such as how to scope changes, write comments, and verify work, unless `keep-coding-instructions` is set to `true`.
Output styles apply to the main conversation only: a [subagent runs its own system prompt](/en/sub-agents#what-loads-at-startup), so styles don't change how subagents respond. A [fork](/en/sub-agents#fork-the-current-conversation) is the exception, because it inherits the parent's full system prompt.
Token usage depends on the style. Adding instructions to the system prompt increases input tokens, though prompt caching reduces this cost after the first request in a session. The built-in Explanatory and Learning styles produce longer responses than Default by design, which increases output tokens. For custom styles, output token usage depends on what your instructions tell Claude to produce.
## Comparisons to related features
@@ -296,6 +296,8 @@ Subagents inherit the [internal tools](/en/tools-reference) and MCP tools availa
- `ScheduleWakeup`
- `WaitForMcpServers`
The `Agent` tool itself is inherited, so a subagent can [spawn nested subagents](#spawn-nested-subagents).
To restrict tools, use the `tools` field as an allowlist or the `disallowedTools` field as a denylist. This example uses `tools` to allow only Read, Grep, Glob, and Bash. The subagent can't edit files, write files, or use any MCP tools:
```yaml
@@ -812,7 +814,7 @@ A non-fork subagent's initial context contains:
- **System prompt**: the agent's own prompt plus environment details that Claude Code appends, not the full Claude Code system prompt. Custom subagents define theirs in the [markdown body](#write-subagent-files) or `prompt` field. Built-in agents have predefined prompts.
- **Task message**: the delegation prompt Claude writes when it hands off the work.
- **CLAUDE.md and memory**: every level of the [memory hierarchy](/en/memory#how-claude-md-files-load) the main conversation loads, including `~/.claude/CLAUDE.md`, project rules, `CLAUDE.local.md`, and managed policy files. The built-in Explore and Plan agents skip this.
- **CLAUDE.md files**: every level of the [CLAUDE.md hierarchy](/en/memory#how-claude-md-files-load) the main conversation loads, including `~/.claude/CLAUDE.md`, project rules, `CLAUDE.local.md`, and managed policy files. The built-in Explore and Plan agents skip this.
- **Git status**: a snapshot taken at the start of the parent session. Absent when the working directory isn't a Git repository or when [`includeGitInstructions`](/en/settings#available-settings) is `false`. Explore and Plan skip it regardless.
- **Preloaded skills**: full content of any skill named in the agent's [`skills` field](#preload-skills-into-subagents). Built-in agents don't preload skills.
- **Sibling roster**: a system reminder listing `main` and every other named agent in the session, each a valid `to` value for [`SendMessage`](#resume-subagents). Requires Claude Code v2.1.206 or later. The roster appears only when the subagent's tools include `SendMessage` and at least one other agent has a name, whether Claude named it when spawning it or it runs as an [agent team](/en/agent-teams) teammate. It is a snapshot taken when the subagent starts, so agents named later don't appear.
@@ -821,6 +823,12 @@ Explore and Plan are the only subagents that omit CLAUDE.md and git status. Ther
The main conversation reads Explore and Plan results with full CLAUDE.md context, so most rules don't need to reach the subagent itself. If a rule must, such as "ignore the `vendor/` directory," restate it in the prompt you give Claude when delegating.
Some main-conversation state never reaches a non-fork subagent:
- **Output style**: a subagent runs its own system prompt, so your [output style](/en/output-styles) doesn't shape its responses, except in a [fork](#fork-the-current-conversation).
- **Auto memory**: the main conversation's [auto memory](/en/memory#auto-memory) isn't loaded. To give a subagent persistent memory of its own, use the [`memory` field](#enable-persistent-memory).
- **Context window size**: a subagent's context window is sized by its own model, not the parent's. Delegating to a model with a smaller window gives that subagent the smaller window.
#### Resume subagents
Each subagent invocation creates a new instance with fresh context. To continue an existing subagent's work instead of starting over, ask Claude to resume it.