1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Agent SDK ãªãã¡ã¬ã³ã¹ - Python
6
7> Python Agent SDK ã®å®å
šãª API ãªãã¡ã¬ã³ã¹ããã¹ãŠã®é¢æ°ãåãã¯ã©ã¹ãå«ã¿ãŸãã
8
9## ã€ã³ã¹ããŒã«
10
11```bash theme={null}
12pip install claude-agent-sdk
13```
14
15## `query()` ãš `ClaudeSDKClient` ã®éžæ
16
17Python SDK 㯠Claude Code ãšå¯Ÿè©±ããããã® 2 ã€ã®æ¹æ³ãæäŸããŸãã
18
19### ã¯ã€ãã¯æ¯èŒ
20
21| æ©èœ | `query()` | `ClaudeSDKClient` |
22| :------------ | :------------ | :---------------- |
23| **ã»ãã·ã§ã³** | æ¯åæ°ããã»ãã·ã§ã³ãäœæ | åãã»ãã·ã§ã³ãåå©çš |
24| **äŒè©±** | åäžã®äº€æ | åãã³ã³ããã¹ãå
ã®è€æ°ã®äº€æ |
25| **æ¥ç¶** | èªåçã«ç®¡ç | æåå¶åŸ¡ |
26| **ã¹ããªãŒãã³ã°å
¥å** | â
ãµããŒã | â
ãµããŒã |
27| **å²ã蟌ã¿** | â ãµããŒããªã | â
ãµããŒã |
28| **Hooks** | â
ãµããŒã | â
ãµããŒã |
29| **ã«ã¹ã¿ã ããŒã«** | â
ãµããŒã | â
ãµããŒã |
30| **äŒè©±ãç¶ãã** | â æ¯åæ°ããã»ãã·ã§ã³ | â
äŒè©±ãä¿æ |
31| **ãŠãŒã¹ã±ãŒã¹** | 1 åéãã®ã¿ã¹ã¯ | ç¶ç¶çãªäŒè©± |
32
33### `query()` ã䜿çšããå ŽåïŒæ¯åæ°ããã»ãã·ã§ã³ïŒ
34
35**æé©ãªçšéïŒ**
36
37* äŒè©±å±¥æŽãäžèŠãª 1 åéãã®è³ªå
38* åã®äº€æããã®ã³ã³ããã¹ããäžèŠãªç¬ç«ããã¿ã¹ã¯
39* ã·ã³ãã«ãªèªååã¹ã¯ãªãã
40* æ¯åæ°ããéå§ãããå Žå
41
42### `ClaudeSDKClient` ã䜿çšããå ŽåïŒç¶ç¶çãªäŒè©±ïŒ
43
44**æé©ãªçšéïŒ**
45
46* **äŒè©±ãç¶ãã** - Claude ãã³ã³ããã¹ããèšæ¶ããå¿
èŠãããå Žå
47* **ãã©ããŒã¢ãã質å** - åã®åçã«åºã¥ããŠæ§ç¯ãã
48* **ã€ã³ã¿ã©ã¯ãã£ããªã¢ããªã±ãŒã·ã§ã³** - ãã£ããã€ã³ã¿ãŒãã§ãŒã¹ãREPL
49* **å¿çé§åããžãã¯** - 次ã®ã¢ã¯ã·ã§ã³ã Claude ã®å¿çã«äŸåããå Žå
50* **ã»ãã·ã§ã³å¶åŸ¡** - äŒè©±ã©ã€ããµã€ã¯ã«ãæ瀺çã«ç®¡çãã
51
52## é¢æ°
53
54### `query()`
55
56Claude Code ãšã®åã€ã³ã¿ã©ã¯ã·ã§ã³ã®ããã«æ°ããã»ãã·ã§ã³ãäœæããŸããã¡ãã»ãŒãžãå°çããã«ã€ããŠçæãããéåæã€ãã¬ãŒã¿ãè¿ããŸãã`query()` ãžã®ååŒã³åºãã¯ãåã®ã€ã³ã¿ã©ã¯ã·ã§ã³ã®ã¡ã¢ãªãªãã§æ°ããéå§ããŸãã
57
58```python theme={null}
59async def query(
60 *,
61 prompt: str | AsyncIterable[dict[str, Any]],
62 options: ClaudeAgentOptions | None = None,
63 transport: Transport | None = None
64) -> AsyncIterator[Message]
65```
66
67#### ãã©ã¡ãŒã¿
68
69| ãã©ã¡ãŒã¿ | å | 説æ |
70| :---------- | :--------------------------- | :------------------------------------------------------ |
71| `prompt` | `str \| AsyncIterable[dict]` | å
¥åããã³ããïŒæååãŸãã¯ã¹ããªãŒãã³ã°ã¢ãŒãçšã®éåæã€ãã¬ãŒã¿ïŒ |
72| `options` | `ClaudeAgentOptions \| None` | ãªãã·ã§ã³ã®èšå®ãªããžã§ã¯ãïŒNone ã®å Žå㯠`ClaudeAgentOptions()` ãããã©ã«ãïŒ |
73| `transport` | `Transport \| None` | CLI ããã»ã¹ãšã®éä¿¡çšã®ãªãã·ã§ã³ã®ã«ã¹ã¿ã ãã©ã³ã¹ããŒã |
74
75#### æ»ãå€
76
77äŒè©±ããã®ã¡ãã»ãŒãžãçæãã `AsyncIterator[Message]` ãè¿ããŸãã
78
79#### äŸ - ãªãã·ã§ã³ä»ã
80
81```python theme={null}
82import asyncio
83from claude_agent_sdk import query, ClaudeAgentOptions
84
85
86async def main():
87 options = ClaudeAgentOptions(
88 system_prompt="You are an expert Python developer",
89 permission_mode="acceptEdits",
90 cwd="/home/user/project",
91 )
92
93 async for message in query(prompt="Create a Python web server", options=options):
94 print(message)
95
96
97asyncio.run(main())
98```
99
100### `tool()`
101
102åå®å
šæ§ãåãã MCP ããŒã«ãå®çŸ©ããããã®ãã³ã¬ãŒã¿ã
103
104```python theme={null}
105def tool(
106 name: str,
107 description: str,
108 input_schema: type | dict[str, Any],
109 annotations: ToolAnnotations | None = None
110) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]
111```
112
113#### ãã©ã¡ãŒã¿
114
115| ãã©ã¡ãŒã¿ | å | 説æ |
116| :------------- | :----------------------------------------------- | :------------------------------------- |
117| `name` | `str` | ããŒã«ã®äžæã®èå¥å |
118| `description` | `str` | ããŒã«ãäœããããã®äººéãèªãã説æ |
119| `input_schema` | `type \| dict[str, Any]` | ããŒã«ã®å
¥åãã©ã¡ãŒã¿ãå®çŸ©ããã¹ããŒãïŒä»¥äžãåç
§ïŒ |
120| `annotations` | [`ToolAnnotations`](#tool-annotations)` \| None` | ã¯ã©ã€ã¢ã³ãã«åäœãã³ããæäŸãããªãã·ã§ã³ã® MCP ããŒã«ã¢ãããŒã·ã§ã³ |
121
122#### å
¥åã¹ããŒããªãã·ã§ã³
123
1241. **ã·ã³ãã«ãªåãããã³ã°**ïŒæšå¥šïŒïŒ
125
126 ```python theme={null}
127 {"text": str, "count": int, "enabled": bool}
128 ```
129
1302. **JSON Schema 圢åŒ**ïŒè€éãªæ€èšŒçšïŒïŒ
131 ```python theme={null}
132 {
133 "type": "object",
134 "properties": {
135 "text": {"type": "string"},
136 "count": {"type": "integer", "minimum": 0},
137 },
138 "required": ["text"],
139 }
140 ```
141
142#### æ»ãå€
143
144ããŒã«å®è£
ãã©ãããã`SdkMcpTool` ã€ã³ã¹ã¿ã³ã¹ãè¿ããã³ã¬ãŒã¿é¢æ°ã
145
146#### äŸ
147
148```python theme={null}
149from claude_agent_sdk import tool
150from typing import Any
151
152
153@tool("greet", "Greet a user", {"name": str})
154async def greet(args: dict[str, Any]) -> dict[str, Any]:
155 return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}
156```
157
158#### `ToolAnnotations`
159
160`mcp.types` ããåãšã¯ã¹ããŒãïŒ`from claude_agent_sdk import ToolAnnotations` ãšããŠãå©çšå¯èœïŒããã¹ãŠã®ãã£ãŒã«ãã¯ãªãã·ã§ã³ã®ãã³ãã§ããã¯ã©ã€ã¢ã³ãã¯ã»ãã¥ãªãã£æ±ºå®ã®ããã«ãããã«äŸåãã¹ãã§ã¯ãããŸããã
161
162| ãã£ãŒã«ã | å | ããã©ã«ã | 説æ |
163| :---------------- | :------------- | :------ | :---------------------------------------------------------------------------- |
164| `title` | `str \| None` | `None` | ããŒã«ã®äººéãèªããé¡å |
165| `readOnlyHint` | `bool \| None` | `False` | `True` ã®å ŽåãããŒã«ã¯ãã®ç°å¢ãå€æŽããŸãã |
166| `destructiveHint` | `bool \| None` | `True` | `True` ã®å ŽåãããŒã«ã¯ç Žå£çãªæŽæ°ãå®è¡ããå¯èœæ§ããããŸãïŒ`readOnlyHint` ã `False` ã®å Žåã®ã¿æå³ããããŸãïŒ |
167| `idempotentHint` | `bool \| None` | `False` | `True` ã®å ŽåãåãåŒæ°ã§ã®ç¹°ãè¿ãåŒã³åºãã¯è¿œå ã®å¹æããããŸããïŒ`readOnlyHint` ã `False` ã®å Žåã®ã¿æå³ããããŸãïŒ |
168| `openWorldHint` | `bool \| None` | `True` | `True` ã®å ŽåãããŒã«ã¯å€éšãšã³ãã£ãã£ãšå¯Ÿè©±ããŸãïŒäŸïŒWeb æ€çŽ¢ïŒã`False` ã®å ŽåãããŒã«ã®ãã¡ã€ã³ã¯éããŠããŸãïŒäŸïŒã¡ã¢ãªããŒã«ïŒ |
169
170```python theme={null}
171from claude_agent_sdk import tool, ToolAnnotations
172from typing import Any
173
174
175@tool(
176 "search",
177 "Search the web",
178 {"query": str},
179 annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
180)
181async def search(args: dict[str, Any]) -> dict[str, Any]:
182 return {"content": [{"type": "text", "text": f"Results for: {args['query']}"}]}
183```
184
185### `create_sdk_mcp_server()`
186
187Python ã¢ããªã±ãŒã·ã§ã³å
ã§å®è¡ãããã€ã³ããã»ã¹ MCP ãµãŒããŒãäœæããŸãã
188
189```python theme={null}
190def create_sdk_mcp_server(
191 name: str,
192 version: str = "1.0.0",
193 tools: list[SdkMcpTool[Any]] | None = None
194) -> McpSdkServerConfig
195```
196
197#### ãã©ã¡ãŒã¿
198
199| ãã©ã¡ãŒã¿ | å | ããã©ã«ã | 説æ |
200| :-------- | :------------------------------ | :-------- | :--------------------------- |
201| `name` | `str` | - | ãµãŒããŒã®äžæã®èå¥å |
202| `version` | `str` | `"1.0.0"` | ãµãŒããŒããŒãžã§ã³æåå |
203| `tools` | `list[SdkMcpTool[Any]] \| None` | `None` | `@tool` ãã³ã¬ãŒã¿ã§äœæãããããŒã«é¢æ°ã®ãªã¹ã |
204
205#### æ»ãå€
206
207`ClaudeAgentOptions.mcp_servers` ã«æž¡ãããšãã§ãã `McpSdkServerConfig` ãªããžã§ã¯ããè¿ããŸãã
208
209#### äŸ
210
211```python theme={null}
212from claude_agent_sdk import tool, create_sdk_mcp_server
213
214
215@tool("add", "Add two numbers", {"a": float, "b": float})
216async def add(args):
217 return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]}
218
219
220@tool("multiply", "Multiply two numbers", {"a": float, "b": float})
221async def multiply(args):
222 return {"content": [{"type": "text", "text": f"Product: {args['a'] * args['b']}"}]}
223
224
225calculator = create_sdk_mcp_server(
226 name="calculator",
227 version="2.0.0",
228 tools=[add, multiply], # Pass decorated functions
229)
230
231# Use with Claude
232options = ClaudeAgentOptions(
233 mcp_servers={"calc": calculator},
234 allowed_tools=["mcp__calc__add", "mcp__calc__multiply"],
235)
236```
237
238### `list_sessions()`
239
240ã¡ã¿ããŒã¿ãå«ãéå»ã®ã»ãã·ã§ã³ããªã¹ãããŸãããããžã§ã¯ããã£ã¬ã¯ããªã§ãã£ã«ã¿ãããããã¹ãŠã®ãããžã§ã¯ãå
šäœã®ã»ãã·ã§ã³ããªã¹ãããŸããåæçã§ããããã«è¿ããŸãã
241
242```python theme={null}
243def list_sessions(
244 directory: str | None = None,
245 limit: int | None = None,
246 include_worktrees: bool = True
247) -> list[SDKSessionInfo]
248```
249
250#### ãã©ã¡ãŒã¿
251
252| ãã©ã¡ãŒã¿ | å | ããã©ã«ã | 説æ |
253| :------------------ | :------------ | :----- | :---------------------------------------------------------- |
254| `directory` | `str \| None` | `None` | ã»ãã·ã§ã³ããªã¹ããããã£ã¬ã¯ããªãçç¥ããå Žåããã¹ãŠã®ãããžã§ã¯ãå
šäœã®ã»ãã·ã§ã³ãè¿ããŸã |
255| `limit` | `int \| None` | `None` | è¿ãã»ãã·ã§ã³ã®æå€§æ° |
256| `include_worktrees` | `bool` | `True` | `directory` ã git ãªããžããªå
ã«ããå Žåããã¹ãŠã® worktree ãã¹ããã®ã»ãã·ã§ã³ãå«ããŸã |
257
258#### æ»ãå€ã®åïŒ`SDKSessionInfo`
259
260| ãããã㣠| å | 説æ |
261| :-------------- | :------------ | :---------------------------------------------------- |
262| `session_id` | `str` | äžæã®ã»ãã·ã§ã³èå¥å |
263| `summary` | `str` | 衚瀺ã¿ã€ãã«ïŒã«ã¹ã¿ã ã¿ã€ãã«ãèªåçæããããµããªãŒããŸãã¯æåã®ããã³ãã |
264| `last_modified` | `int` | ãšããã¯ä»¥éã®ããªç§åäœã§ã®æåŸã®å€æŽæå» |
265| `file_size` | `int \| None` | ã»ãã·ã§ã³ãã¡ã€ã«ãµã€ãºïŒãã€ãïŒïŒãªã¢ãŒãã¹ãã¬ãŒãžããã¯ãšã³ãã®å Žå㯠`None`ïŒ |
266| `custom_title` | `str \| None` | ãŠãŒã¶ãŒãèšå®ããã»ãã·ã§ã³ã¿ã€ãã« |
267| `first_prompt` | `str \| None` | ã»ãã·ã§ã³å
ã®æåã®æå³ã®ãããŠãŒã¶ãŒããã³ãã |
268| `git_branch` | `str \| None` | ã»ãã·ã§ã³çµäºæã® Git ãã©ã³ã |
269| `cwd` | `str \| None` | ã»ãã·ã§ã³ã®äœæ¥ãã£ã¬ã¯ã㪠|
270| `tag` | `str \| None` | ãŠãŒã¶ãŒãèšå®ããã»ãã·ã§ã³ã¿ã°ïŒ[`tag_session()`](#tag-session) ãåç
§ïŒ |
271| `created_at` | `int \| None` | ãšããã¯ä»¥éã®ããªç§åäœã§ã®ã»ãã·ã§ã³äœææå» |
272
273#### äŸ
274
275ãããžã§ã¯ãã® 10 åã®ææ°ã»ãã·ã§ã³ãåºåããŸããçµæ㯠`last_modified` ã®éé ã§ãœãŒãããããããæåã®é
ç®ãææ°ã§ãã`directory` ãçç¥ãããšãã¹ãŠã®ãããžã§ã¯ãå
šäœãæ€çŽ¢ããŸãã
276
277```python theme={null}
278from claude_agent_sdk import list_sessions
279
280for session in list_sessions(directory="/path/to/project", limit=10):
281 print(f"{session.summary} ({session.session_id})")
282```
283
284### `get_session_messages()`
285
286éå»ã®ã»ãã·ã§ã³ããã¡ãã»ãŒãžãååŸããŸããåæçã§ããããã«è¿ããŸãã
287
288```python theme={null}
289def get_session_messages(
290 session_id: str,
291 directory: str | None = None,
292 limit: int | None = None,
293 offset: int = 0
294) -> list[SessionMessage]
295```
296
297#### ãã©ã¡ãŒã¿
298
299| ãã©ã¡ãŒã¿ | å | ããã©ã«ã | 説æ |
300| :----------- | :------------ | :----- | :--------------------------------------- |
301| `session_id` | `str` | å¿
é | ã¡ãã»ãŒãžãååŸããã»ãã·ã§ã³ ID |
302| `directory` | `str \| None` | `None` | æ€çŽ¢ãããããžã§ã¯ããã£ã¬ã¯ããªãçç¥ããå Žåããã¹ãŠã®ãããžã§ã¯ããæ€çŽ¢ããŸã |
303| `limit` | `int \| None` | `None` | è¿ãã¡ãã»ãŒãžã®æå€§æ° |
304| `offset` | `int` | `0` | éå§ãã ã¹ãããããã¡ãã»ãŒãžæ° |
305
306#### æ»ãå€ã®åïŒ`SessionMessage`
307
308| ãããã㣠| å | 説æ |
309| :------------------- | :----------------------------- | :------------ |
310| `type` | `Literal["user", "assistant"]` | ã¡ãã»ãŒãžããŒã« |
311| `uuid` | `str` | äžæã®ã¡ãã»ãŒãžèå¥å |
312| `session_id` | `str` | ã»ãã·ã§ã³èå¥å |
313| `message` | `Any` | çã®ã¡ãã»ãŒãžã³ã³ãã³ã |
314| `parent_tool_use_id` | `None` | å°æ¥ã®äœ¿çšã®ããã«äºçŽæžã¿ |
315
316#### äŸ
317
318```python theme={null}
319from claude_agent_sdk import list_sessions, get_session_messages
320
321sessions = list_sessions(limit=1)
322if sessions:
323 messages = get_session_messages(sessions[0].session_id)
324 for msg in messages:
325 print(f"[{msg.type}] {msg.uuid}")
326```
327
328### `get_session_info()`
329
330ãããžã§ã¯ããã£ã¬ã¯ããªå
šäœãã¹ãã£ã³ããã«ãID ã§ã·ã³ã°ã«ã»ãã·ã§ã³ã®ã¡ã¿ããŒã¿ãèªã¿åããŸããåæçã§ããããã«è¿ããŸãã
331
332```python theme={null}
333def get_session_info(
334 session_id: str,
335 directory: str | None = None,
336) -> SDKSessionInfo | None
337```
338
339#### ãã©ã¡ãŒã¿
340
341| ãã©ã¡ãŒã¿ | å | ããã©ã«ã | 説æ |
342| :----------- | :------------ | :----- | :------------------------------------------- |
343| `session_id` | `str` | å¿
é | æ€çŽ¢ããã»ãã·ã§ã³ã® UUID |
344| `directory` | `str \| None` | `None` | ãããžã§ã¯ããã£ã¬ã¯ããªãã¹ãçç¥ããå Žåããã¹ãŠã®ãããžã§ã¯ããã£ã¬ã¯ããªãæ€çŽ¢ããŸã |
345
346[`SDKSessionInfo`](#return-type-sdk-session-info) ãè¿ãããã»ãã·ã§ã³ãèŠã€ãããªãå Žå㯠`None`ã
347
348#### äŸ
349
350ãããžã§ã¯ããã£ã¬ã¯ããªãã¹ãã£ã³ããã«ãã·ã³ã°ã«ã»ãã·ã§ã³ã®ã¡ã¿ããŒã¿ãæ€çŽ¢ããŸããåã®å®è¡ããã»ãã·ã§ã³ ID ãæ¢ã«æã£ãŠããå Žåã«äŸ¿å©ã§ãã
351
352```python theme={null}
353from claude_agent_sdk import get_session_info
354
355info = get_session_info("550e8400-e29b-41d4-a716-446655440000")
356if info:
357 print(f"{info.summary} (branch: {info.git_branch}, tag: {info.tag})")
358```
359
360### `rename_session()`
361
362ã«ã¹ã¿ã ã¿ã€ãã«ãšã³ããªãè¿œå ããããšã§ã»ãã·ã§ã³ã®ååãå€æŽããŸããç¹°ãè¿ãåŒã³åºãã¯å®å
šã§ããææ°ã®ã¿ã€ãã«ãåªå
ãããŸããåæçã§ãã
363
364```python theme={null}
365def rename_session(
366 session_id: str,
367 title: str,
368 directory: str | None = None,
369) -> None
370```
371
372#### ãã©ã¡ãŒã¿
373
374| ãã©ã¡ãŒã¿ | å | ããã©ã«ã | 説æ |
375| :----------- | :------------ | :----- | :------------------------------------------- |
376| `session_id` | `str` | å¿
é | ååãå€æŽããã»ãã·ã§ã³ã® UUID |
377| `title` | `str` | å¿
é | æ°ããã¿ã€ãã«ã空çœãã¹ããªããããåŸã空ã§ãªãå¿
èŠããããŸã |
378| `directory` | `str \| None` | `None` | ãããžã§ã¯ããã£ã¬ã¯ããªãã¹ãçç¥ããå Žåããã¹ãŠã®ãããžã§ã¯ããã£ã¬ã¯ããªãæ€çŽ¢ããŸã |
379
380`session_id` ãæå¹ãª UUID ã§ãªãå ŽåããŸã㯠`title` ã空ã®å Žå㯠`ValueError` ãçºçãããŸããã»ãã·ã§ã³ãèŠã€ãããªãå Žå㯠`FileNotFoundError`ã
381
382#### äŸ
383
384ææ°ã®ã»ãã·ã§ã³ã®ååãå€æŽããŠãåŸã§èŠã€ããããããŸããæ°ããã¿ã€ãã«ã¯ããã®åŸã®èªã¿åã㧠[`SDKSessionInfo.custom_title`](#return-type-sdk-session-info) ã«è¡šç€ºãããŸãã
385
386```python theme={null}
387from claude_agent_sdk import list_sessions, rename_session
388
389sessions = list_sessions(directory="/path/to/project", limit=1)
390if sessions:
391 rename_session(sessions[0].session_id, "Refactor auth module")
392```
393
394### `tag_session()`
395
396ã»ãã·ã§ã³ã«ã¿ã°ãä»ããŸãã`None` ãæž¡ããŠã¿ã°ãã¯ãªã¢ããŸããç¹°ãè¿ãåŒã³åºãã¯å®å
šã§ããææ°ã®ã¿ã°ãåªå
ãããŸããåæçã§ãã
397
398```python theme={null}
399def tag_session(
400 session_id: str,
401 tag: str | None,
402 directory: str | None = None,
403) -> None
404```
405
406#### ãã©ã¡ãŒã¿
407
408| ãã©ã¡ãŒã¿ | å | ããã©ã«ã | 説æ |
409| :----------- | :------------ | :----- | :---------------------------------------------- |
410| `session_id` | `str` | å¿
é | ã¿ã°ãä»ããã»ãã·ã§ã³ã® UUID |
411| `tag` | `str \| None` | å¿
é | ã¿ã°æååããŸãã¯ã¯ãªã¢ããå Žå㯠`None`ãä¿ååã« Unicode ãµãã¿ã€ãºãããŸã |
412| `directory` | `str \| None` | `None` | ãããžã§ã¯ããã£ã¬ã¯ããªãã¹ãçç¥ããå Žåããã¹ãŠã®ãããžã§ã¯ããã£ã¬ã¯ããªãæ€çŽ¢ããŸã |
413
414`session_id` ãæå¹ãª UUID ã§ãªãå ŽåããŸãã¯ãµãã¿ã€ãºåŸã« `tag` ã空ã®å Žå㯠`ValueError` ãçºçãããŸããã»ãã·ã§ã³ãèŠã€ãããªãå Žå㯠`FileNotFoundError`ã
415
416#### äŸ
417
418ã»ãã·ã§ã³ã«ã¿ã°ãä»ããŠãããåŸã®èªã¿åãã§ãã®ã¿ã°ã§ãã£ã«ã¿ããŸããæ¢åã®ã¿ã°ãã¯ãªã¢ããã«ã¯ `None` ãæž¡ããŸãã
419
420```python theme={null}
421from claude_agent_sdk import list_sessions, tag_session
422
423# Tag a session
424tag_session("550e8400-e29b-41d4-a716-446655440000", "needs-review")
425
426# Later: find all sessions with that tag
427for session in list_sessions(directory="/path/to/project"):
428 if session.tag == "needs-review":
429 print(session.summary)
430```
431
432## ã¯ã©ã¹
433
434### `ClaudeSDKClient`
435
436**è€æ°ã®äº€æã«ããã£ãŠã»ãã·ã§ã³ãç¶æããŸãã** ãã㯠TypeScript SDK ã® `query()` é¢æ°ãå
éšçã«ã©ã®ããã«æ©èœãããã® Python åçç©ã§ããäŒè©±ãç¶ããããšãã§ããã¯ã©ã€ã¢ã³ããªããžã§ã¯ããäœæããŸãã
437
438#### äž»ãªæ©èœ
439
440* **ã»ãã·ã§ã³ç¶ç¶æ§**ïŒè€æ°ã® `query()` åŒã³åºãã«ããã£ãŠäŒè©±ã³ã³ããã¹ããç¶æããŸã
441* **åãäŒè©±**ïŒã»ãã·ã§ã³ã¯åã®ã¡ãã»ãŒãžãä¿æããŸã
442* **å²ã蟌ã¿ãµããŒã**ïŒã¿ã¹ã¯éäžã§å®è¡ãåæ¢ã§ããŸã
443* **æ瀺çãªã©ã€ããµã€ã¯ã«**ïŒã»ãã·ã§ã³ã®éå§ãšçµäºãå¶åŸ¡ããŸã
444* **å¿çé§åãããŒ**ïŒå¿çã«åå¿ããŠãã©ããŒã¢ãããéä¿¡ã§ããŸã
445* **ã«ã¹ã¿ã ããŒã«ãš hooks**ïŒã«ã¹ã¿ã ããŒã«ïŒ`@tool` ãã³ã¬ãŒã¿ã§äœæïŒãš hooks ããµããŒãããŸã
446
447```python theme={null}
448class ClaudeSDKClient:
449 def __init__(self, options: ClaudeAgentOptions | None = None, transport: Transport | None = None)
450 async def connect(self, prompt: str | AsyncIterable[dict] | None = None) -> None
451 async def query(self, prompt: str | AsyncIterable[dict], session_id: str = "default") -> None
452 async def receive_messages(self) -> AsyncIterator[Message]
453 async def receive_response(self) -> AsyncIterator[Message]
454 async def interrupt(self) -> None
455 async def set_permission_mode(self, mode: str) -> None
456 async def set_model(self, model: str | None = None) -> None
457 async def rewind_files(self, user_message_id: str) -> None
458 async def get_mcp_status(self) -> McpStatusResponse
459 async def reconnect_mcp_server(self, server_name: str) -> None
460 async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None
461 async def stop_task(self, task_id: str) -> None
462 async def get_server_info(self) -> dict[str, Any] | None
463 async def disconnect(self) -> None
464```
465
466#### ã¡ãœãã
467
468| ã¡ãœãã | 説æ |
469| :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- |
470| `__init__(options)` | ãªãã·ã§ã³ã®èšå®ã§ã¯ã©ã€ã¢ã³ããåæåããŸã |
471| `connect(prompt)` | ãªãã·ã§ã³ã®åæããã³ãããŸãã¯ã¡ãã»ãŒãžã¹ããªãŒã 㧠Claude ã«æ¥ç¶ããŸã |
472| `query(prompt, session_id)` | ã¹ããªãŒãã³ã°ã¢ãŒãã§æ°ãããªã¯ãšã¹ããéä¿¡ããŸã |
473| `receive_messages()` | Claude ããã®ãã¹ãŠã®ã¡ãã»ãŒãžãéåæã€ãã¬ãŒã¿ãšããŠåãåããŸã |
474| `receive_response()` | ResultMessage ãå«ããŸã§ã®ã¡ãã»ãŒãžãåãåããŸã |
475| `interrupt()` | å²ã蟌ã¿ä¿¡å·ãéä¿¡ããŸãïŒã¹ããªãŒãã³ã°ã¢ãŒãã§ã®ã¿æ©èœïŒ |
476| `set_permission_mode(mode)` | çŸåšã®ã»ãã·ã§ã³ã®ããŒããã·ã§ã³ã¢ãŒããå€æŽããŸã |
477| `set_model(model)` | çŸåšã®ã»ãã·ã§ã³ã®ã¢ãã«ãå€æŽããŸããããã©ã«ãã«ãªã»ããããã«ã¯ `None` ãæž¡ããŸã |
478| `rewind_files(user_message_id)` | ãã¡ã€ã«ãæå®ããããŠãŒã¶ãŒã¡ãã»ãŒãžã®ç¶æ
ã«åŸ©å
ããŸãã`enable_file_checkpointing=True` ãå¿
èŠã§ãã[ãã¡ã€ã«ãã§ãã¯ãã€ã³ã](/ja/agent-sdk/file-checkpointing) ãåç
§ |
479| `get_mcp_status()` | ãã¹ãŠã®èšå®æžã¿ MCP ãµãŒããŒã®ã¹ããŒã¿ã¹ãååŸããŸãã[`McpStatusResponse`](#mcp-status-response) ãè¿ããŸã |
480| `reconnect_mcp_server(server_name)` | 倱æãããåæããã MCP ãµãŒããŒãžã®åæ¥ç¶ãè©Šã¿ãŸã |
481| `toggle_mcp_server(server_name, enabled)` | ã»ãã·ã§ã³äžã« MCP ãµãŒããŒãæå¹ãŸãã¯ç¡å¹ã«ããŸããç¡å¹ã«ãããšãã®ããŒã«ãåé€ãããŸã |
482| `stop_task(task_id)` | å®è¡äžã®ããã¯ã°ã©ãŠã³ãã¿ã¹ã¯ãåæ¢ããŸããã¹ããŒã¿ã¹ `"stopped"` ã® [`TaskNotificationMessage`](#task-notification-message) ãã¡ãã»ãŒãžã¹ããªãŒã ã«ç¶ããŸã |
483| `get_server_info()` | ã»ãã·ã§ã³ ID ãšæ©èœãå«ããµãŒããŒæ
å ±ãååŸããŸã |
484| `disconnect()` | Claude ããåæããŸã |
485
486#### ã³ã³ããã¹ããããŒãžã£ãŒãµããŒã
487
488ã¯ã©ã€ã¢ã³ãã¯èªåæ¥ç¶ç®¡çã®ããã®éåæã³ã³ããã¹ããããŒãžã£ãŒãšããŠäœ¿çšã§ããŸãïŒ
489
490```python theme={null}
491async with ClaudeSDKClient() as client:
492 await client.query("Hello Claude")
493 async for message in client.receive_response():
494 print(message)
495```
496
497> **éèŠïŒ** ã¡ãã»ãŒãžãå埩åŠçããå Žåãæ©æã«çµäºããããã« `break` ã䜿çšããããšã¯é¿ããŠãã ããããã㯠asyncio ã¯ãªãŒã³ã¢ããã®åé¡ãåŒãèµ·ããå¯èœæ§ããããŸãã代ããã«ãå埩ãèªç¶ã«å®äºããããããã©ã°ã䜿çšããŠå¿
èŠãªãã®ãèŠã€ãããšãã远跡ããŠãã ããã
498
499#### äŸ - äŒè©±ãç¶ãã
500
501```python theme={null}
502import asyncio
503from claude_agent_sdk import ClaudeSDKClient, AssistantMessage, TextBlock, ResultMessage
504
505
506async def main():
507 async with ClaudeSDKClient() as client:
508 # First question
509 await client.query("What's the capital of France?")
510
511 # Process response
512 async for message in client.receive_response():
513 if isinstance(message, AssistantMessage):
514 for block in message.content:
515 if isinstance(block, TextBlock):
516 print(f"Claude: {block.text}")
517
518 # Follow-up question - the session retains the previous context
519 await client.query("What's the population of that city?")
520
521 async for message in client.receive_response():
522 if isinstance(message, AssistantMessage):
523 for block in message.content:
524 if isinstance(block, TextBlock):
525 print(f"Claude: {block.text}")
526
527 # Another follow-up - still in the same conversation
528 await client.query("What are some famous landmarks there?")
529
530 async for message in client.receive_response():
531 if isinstance(message, AssistantMessage):
532 for block in message.content:
533 if isinstance(block, TextBlock):
534 print(f"Claude: {block.text}")
535
536
537asyncio.run(main())
538```
539
540#### äŸ - ClaudeSDKClient ã§ã®ã¹ããªãŒãã³ã°å
¥å
541
542```python theme={null}
543import asyncio
544from claude_agent_sdk import ClaudeSDKClient
545
546
547async def message_stream():
548 """Generate messages dynamically."""
549 yield {
550 "type": "user",
551 "message": {"role": "user", "content": "Analyze the following data:"},
552 }
553 await asyncio.sleep(0.5)
554 yield {
555 "type": "user",
556 "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"},
557 }
558 await asyncio.sleep(0.5)
559 yield {
560 "type": "user",
561 "message": {"role": "user", "content": "What patterns do you see?"},
562 }
563
564
565async def main():
566 async with ClaudeSDKClient() as client:
567 # Stream input to Claude
568 await client.query(message_stream())
569
570 # Process response
571 async for message in client.receive_response():
572 print(message)
573
574 # Follow-up in same session
575 await client.query("Should we be concerned about these readings?")
576
577 async for message in client.receive_response():
578 print(message)
579
580
581asyncio.run(main())
582```
583
584#### äŸ - å²ã蟌ã¿ã®äœ¿çš
585
586```python theme={null}
587import asyncio
588from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, ResultMessage
589
590
591async def interruptible_task():
592 options = ClaudeAgentOptions(allowed_tools=["Bash"], permission_mode="acceptEdits")
593
594 async with ClaudeSDKClient(options=options) as client:
595 # Start a long-running task
596 await client.query("Count from 1 to 100 slowly, using the bash sleep command")
597
598 # Let it run for a bit
599 await asyncio.sleep(2)
600
601 # Interrupt the task
602 await client.interrupt()
603 print("Task interrupted!")
604
605 # Drain the interrupted task's messages (including its ResultMessage)
606 async for message in client.receive_response():
607 if isinstance(message, ResultMessage):
608 print(f"Interrupted task finished with subtype={message.subtype!r}")
609 # subtype is "error_during_execution" for interrupted tasks
610
611 # Send a new command
612 await client.query("Just say hello instead")
613
614 # Now receive the new response
615 async for message in client.receive_response():
616 if isinstance(message, ResultMessage) and message.subtype == "success":
617 print(f"New result: {message.result}")
618
619
620asyncio.run(interruptible_task())
621```
622
623<Note>
624 **å²ã蟌ã¿åŸã®ãããã¡åäœïŒ** `interrupt()` ã¯åæ¢ä¿¡å·ãéä¿¡ããŸãããã¡ãã»ãŒãžãããã¡ãã¯ãªã¢ããŸãããå²ã蟌ãŸããã¿ã¹ã¯ã«ãã£ãŠæ¢ã«çæãããã¡ãã»ãŒãžïŒ`subtype="error_during_execution"` ã® `ResultMessage` ãå«ãïŒã¯ã¹ããªãŒã ã«æ®ããŸããæ°ããã¯ãšãªã®å¿çãèªãåã«ã`receive_response()` ã§ãããããã¬ã€ã³ããå¿
èŠããããŸãã`interrupt()` ã®çŽåŸã«æ°ããã¯ãšãªãéä¿¡ãã`receive_response()` ã 1 åã ãåŒã³åºããšãå²ã蟌ãŸããã¿ã¹ã¯ã®ã¡ãã»ãŒãžãåãåãããæ°ããã¯ãšãªã®å¿çã§ã¯ãããŸããã
625</Note>
626
627#### äŸ - é«åºŠãªããŒããã·ã§ã³å¶åŸ¡
628
629```python theme={null}
630from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
631from claude_agent_sdk.types import (
632 PermissionResultAllow,
633 PermissionResultDeny,
634 ToolPermissionContext,
635)
636
637
638async def custom_permission_handler(
639 tool_name: str, input_data: dict, context: ToolPermissionContext
640) -> PermissionResultAllow | PermissionResultDeny:
641 """Custom logic for tool permissions."""
642
643 # Block writes to system directories
644 if tool_name == "Write" and input_data.get("file_path", "").startswith("/system/"):
645 return PermissionResultDeny(
646 message="System directory write not allowed", interrupt=True
647 )
648
649 # Redirect sensitive file operations
650 if tool_name in ["Write", "Edit"] and "config" in input_data.get("file_path", ""):
651 safe_path = f"./sandbox/{input_data['file_path']}"
652 return PermissionResultAllow(
653 updated_input={**input_data, "file_path": safe_path}
654 )
655
656 # Allow everything else
657 return PermissionResultAllow(updated_input=input_data)
658
659
660async def main():
661 options = ClaudeAgentOptions(
662 can_use_tool=custom_permission_handler, allowed_tools=["Read", "Write", "Edit"]
663 )
664
665 async with ClaudeSDKClient(options=options) as client:
666 await client.query("Update the system config file")
667
668 async for message in client.receive_response():
669 # Will use sandbox path instead
670 print(message)
671
672
673asyncio.run(main())
674```
675
676## å
677
678<Note>
679 **`@dataclass` vs `TypedDict`ïŒ** ãã® SDK 㯠2 çš®é¡ã®åã䜿çšããŸãã`@dataclass` ã§è£
食ãããã¯ã©ã¹ïŒ`ResultMessage`ã`AgentDefinition`ã`TextBlock` ãªã©ïŒã¯å®è¡æã«ãªããžã§ã¯ãã€ã³ã¹ã¿ã³ã¹ã§ãããå±æ§ã¢ã¯ã»ã¹ããµããŒãããŸãïŒ`msg.result`ã`TypedDict` ã§å®çŸ©ãããã¯ã©ã¹ïŒ`ThinkingConfigEnabled`ã`McpStdioServerConfig`ã`SyncHookJSONOutput` ãªã©ïŒã¯**å®è¡æã«ãã¬ãŒã³ãª dict** ã§ãããããŒã¢ã¯ã»ã¹ãå¿
èŠã§ãïŒ`config["budget_tokens"]`ã`config.budget_tokens` ã§ã¯ãªãã`ClassName(field=value)` åŒã³åºãæ§æã¯äž¡æ¹ã§æ©èœããŸãããdataclass ã®ã¿ãå±æ§ãæã€ãªããžã§ã¯ããçæããŸãã
680</Note>
681
682### `SdkMcpTool`
683
684`@tool` ãã³ã¬ãŒã¿ã§äœæããã SDK MCP ããŒã«ã®å®çŸ©ã
685
686```python theme={null}
687@dataclass
688class SdkMcpTool(Generic[T]):
689 name: str
690 description: str
691 input_schema: type[T] | dict[str, Any]
692 handler: Callable[[T], Awaitable[dict[str, Any]]]
693 annotations: ToolAnnotations | None = None
694```
695
696| ãããã㣠| å | 説æ |
697| :------------- | :----------------------------------------- | :--------------------------------------------------------------------------------------- |
698| `name` | `str` | ããŒã«ã®äžæã®èå¥å |
699| `description` | `str` | 人éãèªãã説æ |
700| `input_schema` | `type[T] \| dict[str, Any]` | å
¥åæ€èšŒçšã®ã¹ããŒã |
701| `handler` | `Callable[[T], Awaitable[dict[str, Any]]]` | ããŒã«å®è¡ãåŠçããéåæé¢æ° |
702| `annotations` | `ToolAnnotations \| None` | ãªãã·ã§ã³ã® MCP ããŒã«ã¢ãããŒã·ã§ã³ïŒäŸïŒ`readOnlyHint`ã`destructiveHint`ã`openWorldHint`ïŒã`mcp.types` ãã |
703
704### `Transport`
705
706ã«ã¹ã¿ã ãã©ã³ã¹ããŒãå®è£
ã®æœè±¡åºæ¬ã¯ã©ã¹ãããã䜿çšããŠãã«ã¹ã¿ã ãã£ãã«ïŒäŸïŒããŒã«ã«ãµãããã»ã¹ã®ä»£ããã«ãªã¢ãŒãæ¥ç¶ïŒãä»ã㊠Claude ããã»ã¹ãšéä¿¡ããŸãã
707
708<Warning>
709 ããã¯äœã¬ãã«ã®å
éš API ã§ããã€ã³ã¿ãŒãã§ãŒã¹ã¯å°æ¥ã®ãªãªãŒã¹ã§å€æŽãããå¯èœæ§ããããŸããã«ã¹ã¿ã å®è£
ã¯ãã€ã³ã¿ãŒãã§ãŒã¹ã®å€æŽã«åãããŠæŽæ°ããå¿
èŠããããŸãã
710</Warning>
711
712```python theme={null}
713from abc import ABC, abstractmethod
714from collections.abc import AsyncIterator
715from typing import Any
716
717
718class Transport(ABC):
719 @abstractmethod
720 async def connect(self) -> None: ...
721
722 @abstractmethod
723 async def write(self, data: str) -> None: ...
724
725 @abstractmethod
726 def read_messages(self) -> AsyncIterator[dict[str, Any]]: ...
727
728 @abstractmethod
729 async def close(self) -> None: ...
730
731 @abstractmethod
732 def is_ready(self) -> bool: ...
733
734 @abstractmethod
735 async def end_input(self) -> None: ...
736```
737
738| ã¡ãœãã | 説æ |
739| :---------------- | :---------------------------------------- |
740| `connect()` | ãã©ã³ã¹ããŒããæ¥ç¶ããéä¿¡ã®æºåãããŸã |
741| `write(data)` | çããŒã¿ïŒJSON + æ¹è¡ïŒããã©ã³ã¹ããŒãã«æžã蟌ã¿ãŸã |
742| `read_messages()` | 解æããã JSON ã¡ãã»ãŒãžãçæããéåæã€ãã¬ãŒã¿ |
743| `close()` | æ¥ç¶ãéããŠãªãœãŒã¹ãã¯ãªãŒã³ã¢ããããŸã |
744| `is_ready()` | ãã©ã³ã¹ããŒããéåä¿¡ã§ããå Žå㯠`True` ãè¿ããŸã |
745| `end_input()` | å
¥åã¹ããªãŒã ãéããŸãïŒäŸïŒãµãããã»ã¹ãã©ã³ã¹ããŒãã® stdin ãéããïŒ |
746
747ã€ã³ããŒãïŒ`from claude_agent_sdk import Transport`
748
749### `ClaudeAgentOptions`
750
751Claude Code ã¯ãšãªã®èšå® dataclassã
752
753```python theme={null}
754@dataclass
755class ClaudeAgentOptions:
756 tools: list[str] | ToolsPreset | None = None
757 allowed_tools: list[str] = field(default_factory=list)
758 system_prompt: str | SystemPromptPreset | None = None
759 mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
760 permission_mode: PermissionMode | None = None
761 continue_conversation: bool = False
762 resume: str | None = None
763 max_turns: int | None = None
764 max_budget_usd: float | None = None
765 disallowed_tools: list[str] = field(default_factory=list)
766 model: str | None = None
767 fallback_model: str | None = None
768 betas: list[SdkBeta] = field(default_factory=list)
769 output_format: dict[str, Any] | None = None
770 permission_prompt_tool_name: str | None = None
771 cwd: str | Path | None = None
772 cli_path: str | Path | None = None
773 settings: str | None = None
774 add_dirs: list[str | Path] = field(default_factory=list)
775 env: dict[str, str] = field(default_factory=dict)
776 extra_args: dict[str, str | None] = field(default_factory=dict)
777 max_buffer_size: int | None = None
778 debug_stderr: Any = sys.stderr # Deprecated
779 stderr: Callable[[str], None] | None = None
780 can_use_tool: CanUseTool | None = None
781 hooks: dict[HookEvent, list[HookMatcher]] | None = None
782 user: str | None = None
783 include_partial_messages: bool = False
784 fork_session: bool = False
785 agents: dict[str, AgentDefinition] | None = None
786 setting_sources: list[SettingSource] | None = None
787 sandbox: SandboxSettings | None = None
788 plugins: list[SdkPluginConfig] = field(default_factory=list)
789 max_thinking_tokens: int | None = None # Deprecated: use thinking instead
790 thinking: ThinkingConfig | None = None
791 effort: Literal["low", "medium", "high", "max"] | None = None
792 enable_file_checkpointing: bool = False
793 session_store: SessionStore | None = None
794```
795
796| ãããã㣠| å | ããã©ã«ã | 説æ |
797| :---------------------------- | :------------------------------------------------------------------------------------- | :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
798| `tools` | `list[str] \| ToolsPreset \| None` | `None` | ããŒã«èšå®ãClaude Code ã®ããã©ã«ãããŒã«ã«ã¯ `{"type": "preset", "preset": "claude_code"}` ã䜿çšããŸã |
799| `allowed_tools` | `list[str]` | `[]` | ããã³ãããªãã§èªåæ¿èªããããŒã«ããã㯠Claude ããããã®ããŒã«ã®ã¿ã«å¶éããŸããããªã¹ããããŠããªãããŒã«ã¯ `permission_mode` ãš `can_use_tool` ã«ãã©ãŒã«ã¹ã«ãŒããŸãã`disallowed_tools` ã䜿çšããŠããŒã«ããããã¯ããŸãã[ããŒããã·ã§ã³](/ja/agent-sdk/permissions#allow-and-deny-rules) ãåç
§ |
800| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | ã·ã¹ãã ããã³ããèšå®ãã«ã¹ã¿ã ããã³ããã®å Žåã¯æååãæž¡ãããClaude Code ã®ã·ã¹ãã ããã³ããã®å Žå㯠`{"type": "preset", "preset": "claude_code"}` ã䜿çšããŸããããªã»ãããæ¡åŒµããã«ã¯ `"append"` ãè¿œå ããŸã |
801| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP ãµãŒããŒèšå®ãŸãã¯èšå®ãã¡ã€ã«ãžã®ãã¹ |
802| `permission_mode` | `PermissionMode \| None` | `None` | ããŒã«äœ¿çšã®ããŒããã·ã§ã³ã¢ãŒã |
803| `continue_conversation` | `bool` | `False` | ææ°ã®äŒè©±ãç¶ãã |
804| `resume` | `str \| None` | `None` | åéããã»ãã·ã§ã³ ID |
805| `max_turns` | `int \| None` | `None` | æ倧 agentic ã¿ãŒã³æ°ïŒããŒã«äœ¿çšã©ãŠã³ãããªããïŒ |
806| `max_budget_usd` | `float \| None` | `None` | ã¯ã©ã€ã¢ã³ãåŽã®ã³ã¹ãæšå®ããã® USD å€ã«éãããšãã«ã¯ãšãªãåæ¢ããŸãã`total_cost_usd` ãšåãæšå®ãšæ¯èŒãããŸãã[ã³ã¹ããšäœ¿çšç¶æ³ã远跡](/ja/agent-sdk/cost-tracking) ã§ç²ŸåºŠã®æ³šæäºé
ãåç
§ |
807| `disallowed_tools` | `list[str]` | `[]` | åžžã«æåŠããããŒã«ãæåŠã«ãŒã«ãæåã«ãã§ãã¯ããã`allowed_tools` ãš `permission_mode`ïŒ`bypassPermissions` ãå«ãïŒããªãŒããŒã©ã€ãããŸã |
808| `enable_file_checkpointing` | `bool` | `False` | ãã¡ã€ã«å€æŽè¿œè·¡ãæå¹ã«ããŠå·»ãæ»ããå¯èœã«ããŸãã[ãã¡ã€ã«ãã§ãã¯ãã€ã³ã](/ja/agent-sdk/file-checkpointing) ãåç
§ |
809| `model` | `str \| None` | `None` | 䜿çšãã Claude ã¢ãã« |
810| `fallback_model` | `str \| None` | `None` | ãã©ã€ããªã¢ãã«ã倱æããå Žåã«äœ¿çšãããã©ãŒã«ããã¯ã¢ãã« |
811| `betas` | `list[SdkBeta]` | `[]` | æå¹ã«ããããŒã¿æ©èœãå©çšå¯èœãªãªãã·ã§ã³ã«ã€ããŠã¯ [`SdkBeta`](#sdk-beta) ãåç
§ |
812| `output_format` | `dict[str, Any] \| None` | `None` | æ§é åå¿çã®åºå圢åŒïŒäŸïŒ`{"type": "json_schema", "schema": {...}}`ïŒã詳现ã«ã€ããŠã¯ [æ§é ååºå](/ja/agent-sdk/structured-outputs) ãåç
§ |
813| `permission_prompt_tool_name` | `str \| None` | `None` | ããŒããã·ã§ã³ããã³ããçšã® MCP ããŒã«å |
814| `cwd` | `str \| Path \| None` | `None` | çŸåšã®äœæ¥ãã£ã¬ã¯ã㪠|
815| `cli_path` | `str \| Path \| None` | `None` | Claude Code CLI å®è¡å¯èœãã¡ã€ã«ãžã®ã«ã¹ã¿ã ãã¹ |
816| `settings` | `str \| None` | `None` | èšå®ãã¡ã€ã«ãžã®ãã¹ |
817| `add_dirs` | `list[str \| Path]` | `[]` | Claude ãã¢ã¯ã»ã¹ã§ããè¿œå ãã£ã¬ã¯ã㪠|
818| `env` | `dict[str, str]` | `{}` | ç¶æ¿ãããããã»ã¹ç°å¢ã®äžã«ããŒãžãããç°å¢å€æ°ã[ç°å¢å€æ°](/ja/env-vars) ã§ãåºç€ãšãªã CLI ãèªã¿èŸŒãå€æ°ãåç
§ |
819| `extra_args` | `dict[str, str \| None]` | `{}` | CLI ã«çŽæ¥æž¡ãè¿œå CLI åŒæ° |
820| `max_buffer_size` | `int \| None` | `None` | CLI stdout ããããã¡ãªã³ã°ããå Žåã®æ倧ãã€ãæ° |
821| `debug_stderr` | `Any` | `sys.stderr` | *éæšå¥š* - ãããã°åºåçšã®ãã¡ã€ã«ã®ãããªãªããžã§ã¯ãã代ããã« `stderr` ã³ãŒã«ããã¯ã䜿çšããŠãã ãã |
822| `stderr` | `Callable[[str], None] \| None` | `None` | CLI ããã® stderr åºåçšã®ã³ãŒã«ããã¯é¢æ° |
823| `can_use_tool` | [`CanUseTool`](#can-use-tool) ` \| None` | `None` | ããŒã«ããŒããã·ã§ã³ã³ãŒã«ããã¯é¢æ°ã詳现ã«ã€ããŠã¯ [ããŒããã·ã§ã³å](#can-use-tool) ãåç
§ |
824| `hooks` | `dict[HookEvent, list[HookMatcher]] \| None` | `None` | ã€ãã³ããã€ã³ã¿ãŒã»ããããããã® hook èšå® |
825| `user` | `str \| None` | `None` | ãŠãŒã¶ãŒèå¥å |
826| `include_partial_messages` | `bool` | `False` | éšåçãªã¡ãã»ãŒãžã¹ããªãŒãã³ã°ã€ãã³ããå«ããŸããæå¹ã«ãããšã[`StreamEvent`](#stream-event) ã¡ãã»ãŒãžãçæãããŸã |
827| `fork_session` | `bool` | `False` | `resume` ã§åéããå Žåãå
ã®ã»ãã·ã§ã³ãç¶ãã代ããã«æ°ããã»ãã·ã§ã³ ID ã«ãã©ãŒã¯ããŸã |
828| `agents` | `dict[str, AgentDefinition] \| None` | `None` | ããã°ã©ã ã§å®çŸ©ããããµããšãŒãžã§ã³ã |
829| `plugins` | `list[SdkPluginConfig]` | `[]` | ããŒã«ã«ãã¹ããã«ã¹ã¿ã ãã©ã°ã€ã³ãèªã¿èŸŒã¿ãŸãã詳现ã«ã€ããŠã¯ [ãã©ã°ã€ã³](/ja/agent-sdk/plugins) ãåç
§ |
830| `sandbox` | [`SandboxSettings`](#sandbox-settings) ` \| None` | `None` | ããã°ã©ã ã§ãµã³ãããã¯ã¹åäœãèšå®ããŸãã詳现ã«ã€ããŠã¯ [ãµã³ãããã¯ã¹èšå®](#sandbox-settings) ãåç
§ |
831| `setting_sources` | `list[SettingSource] \| None` | `None`ïŒCLI ããã©ã«ãïŒãã¹ãŠã®ãœãŒã¹ïŒ | èªã¿èŸŒããã¡ã€ã«ã·ã¹ãã èšå®ãå¶åŸ¡ããŸãã`[]` ãæž¡ããŠãŠãŒã¶ãŒããããžã§ã¯ããããŒã«ã«èšå®ãç¡å¹ã«ããŸãã管çããªã·ãŒèšå®ã¯åžžã«èªã¿èŸŒãŸããŸãã[Claude Code æ©èœã䜿çš](/ja/agent-sdk/claude-code-features#what-settingsources-does-not-control) ãåç
§ |
832| `max_thinking_tokens` | `int \| None` | `None` | *éæšå¥š* - æèãããã¯ã®æ倧ããŒã¯ã³æ°ã代ããã« `thinking` ã䜿çšããŠãã ãã |
833| `thinking` | [`ThinkingConfig`](#thinking-config) ` \| None` | `None` | æ¡åŒµæèåäœãå¶åŸ¡ããŸãã`max_thinking_tokens` ããåªå
ãããŸã |
834| `effort` | `Literal["low", "medium", "high", "max"] \| None` | `None` | æèã®æ·±ãã®åªåã¬ãã« |
835| `session_store` | [`SessionStore`](/ja/agent-sdk/session-storage#the-session-store-interface) ` \| None` | `None` | ã»ãã·ã§ã³ãã©ã³ã¹ã¯ãªãããå€éšããã¯ãšã³ãã«ãã©ãŒãªã³ã°ããŠãä»»æã®ãã¹ããããããåéã§ããããã«ããŸãã[ã»ãã·ã§ã³ãå€éšã¹ãã¬ãŒãžã«æ°žç¶å](/ja/agent-sdk/session-storage) ãåç
§ |
836
837### `OutputFormat`
838
839æ§é ååºåæ€èšŒã®èšå®ãããã `ClaudeAgentOptions` ã® `output_format` ãã£ãŒã«ãã« dict ãšããŠæž¡ããŸãïŒ
840
841```python theme={null}
842# Expected dict shape for output_format
843{
844 "type": "json_schema",
845 "schema": {...}, # Your JSON Schema definition
846}
847```
848
849| ãã£ãŒã«ã | å¿
é | 説æ |
850| :------- | :- | :-------------------------------------------- |
851| `type` | ã¯ã | JSON Schema æ€èšŒã®å Žå㯠`"json_schema"` ã§ããå¿
èŠããããŸã |
852| `schema` | ã¯ã | åºåæ€èšŒçšã® JSON Schema å®çŸ© |
853
854### `SystemPromptPreset`
855
856ãªãã·ã§ã³ã®è¿œå ãå«ã Claude Code ã®ããªã»ããã·ã¹ãã ããã³ããã䜿çšããããã®èšå®ã
857
858```python theme={null}
859class SystemPromptPreset(TypedDict):
860 type: Literal["preset"]
861 preset: Literal["claude_code"]
862 append: NotRequired[str]
863 exclude_dynamic_sections: NotRequired[bool]
864```
865
866| ãã£ãŒã«ã | å¿
é | 説æ |
867| :------------------------- | :-- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
868| `type` | ã¯ã | ããªã»ããã·ã¹ãã ããã³ããã䜿çšããã«ã¯ `"preset"` ã§ããå¿
èŠããããŸã |
869| `preset` | ã¯ã | Claude Code ã®ã·ã¹ãã ããã³ããã䜿çšããã«ã¯ `"claude_code"` ã§ããå¿
èŠããããŸã |
870| `append` | ããã | ããªã»ããã·ã¹ãã ããã³ããã«è¿œå ããè¿œå ã®æ瀺 |
871| `exclude_dynamic_sections` | ããã | äœæ¥ãã£ã¬ã¯ããªãgit ã¹ããŒã¿ã¹ãã¡ã¢ãªãã¹ãªã©ã®ã»ãã·ã§ã³ããšã®ã³ã³ããã¹ããã·ã¹ãã ããã³ããããæåã®ãŠãŒã¶ãŒã¡ãã»ãŒãžã«ç§»åããŸãããŠãŒã¶ãŒãšãã·ã³å
šäœã§ã®ããã³ãããã£ãã·ã¥ã®åå©çšãæ¹åããŸãã[ã·ã¹ãã ããã³ãããå€æŽ](/ja/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) ãåç
§ |
872
873### `SettingSource`
874
875SDK ãèšå®ãèªã¿èŸŒããã¡ã€ã«ã·ã¹ãã ããŒã¹ã®èšå®ãœãŒã¹ãå¶åŸ¡ããŸãã
876
877```python theme={null}
878SettingSource = Literal["user", "project", "local"]
879```
880
881| å€ | 説æ | å Žæ |
882| :---------- | :----------------------- | :---------------------------- |
883| `"user"` | ã°ããŒãã«ãŠãŒã¶ãŒèšå® | `~/.claude/settings.json` |
884| `"project"` | å
±æãããžã§ã¯ãèšå®ïŒããŒãžã§ã³ç®¡çïŒ | `.claude/settings.json` |
885| `"local"` | ããŒã«ã«ãããžã§ã¯ãèšå®ïŒgitignoredïŒ | `.claude/settings.local.json` |
886
887#### ããã©ã«ãåäœ
888
889`setting_sources` ãçç¥ãããã `None` ã®å Žåã`query()` 㯠Claude Code CLI ãšåããã¡ã€ã«ã·ã¹ãã èšå®ãèªã¿èŸŒã¿ãŸãïŒãŠãŒã¶ãŒããããžã§ã¯ããããŒã«ã«ã管çããªã·ãŒèšå®ã¯ãã¹ãŠã®å Žåã«èªã¿èŸŒãŸããŸãããã®ãªãã·ã§ã³ã«é¢ä¿ãªãèªã¿èŸŒãŸããå
¥åã«ã€ããŠã¯ [settingSources ãå¶åŸ¡ããªããã®](/ja/agent-sdk/claude-code-features#what-settingsources-does-not-control) ãåç
§ããããããç¡å¹ã«ããæ¹æ³ãåç
§ããŠãã ããã
890
891#### setting\_sources ã䜿çšããçç±
892
893**ãã¡ã€ã«ã·ã¹ãã èšå®ãç¡å¹ã«ããïŒ**
894
895```python theme={null}
896# Do not load user, project, or local settings from disk
897from claude_agent_sdk import query, ClaudeAgentOptions
898
899async for message in query(
900 prompt="Analyze this code",
901 options=ClaudeAgentOptions(
902 setting_sources=[]
903 ),
904):
905 print(message)
906```
907
908<Note>
909 Python SDK 0.1.59 以åã§ã¯ã空ã®ãªã¹ãã¯ãªãã·ã§ã³ãçç¥ããã®ãšåãããã«æ±ãããŠããããã`setting_sources=[]` ã¯ãã¡ã€ã«ã·ã¹ãã èšå®ãç¡å¹ã«ããŸããã§ããã空ã®ãªã¹ããæå¹ã«ãªãå¿
èŠãããå Žåã¯ãæ°ãããªãªãŒã¹ã«ã¢ããã°ã¬ãŒãããŠãã ãããTypeScript SDK ã¯åœ±é¿ãåããŸããã
910</Note>
911
912**ãã¹ãŠã®ãã¡ã€ã«ã·ã¹ãã èšå®ãæ瀺çã«èªã¿èŸŒãïŒ**
913
914```python theme={null}
915from claude_agent_sdk import query, ClaudeAgentOptions
916
917async for message in query(
918 prompt="Analyze this code",
919 options=ClaudeAgentOptions(
920 setting_sources=["user", "project", "local"]
921 ),
922):
923 print(message)
924```
925
926**ç¹å®ã®èšå®ãœãŒã¹ã®ã¿ãèªã¿èŸŒãïŒ**
927
928```python theme={null}
929# Load only project settings, ignore user and local
930async for message in query(
931 prompt="Run CI checks",
932 options=ClaudeAgentOptions(
933 setting_sources=["project"] # Only .claude/settings.json
934 ),
935):
936 print(message)
937```
938
939**ãã¹ããš CI ç°å¢ïŒ**
940
941```python theme={null}
942# Ensure consistent behavior in CI by excluding local settings
943async for message in query(
944 prompt="Run tests",
945 options=ClaudeAgentOptions(
946 setting_sources=["project"], # Only team-shared settings
947 permission_mode="bypassPermissions",
948 ),
949):
950 print(message)
951```
952
953**SDK ã®ã¿ã®ã¢ããªã±ãŒã·ã§ã³ïŒ**
954
955```python theme={null}
956# Define everything programmatically.
957# Pass [] to opt out of filesystem setting sources.
958async for message in query(
959 prompt="Review this PR",
960 options=ClaudeAgentOptions(
961 setting_sources=[],
962 agents={...},
963 mcp_servers={...},
964 allowed_tools=["Read", "Grep", "Glob"],
965 ),
966):
967 print(message)
968```
969
970**CLAUDE.md ãããžã§ã¯ãæ瀺ãèªã¿èŸŒãïŒ**
971
972```python theme={null}
973# Load project settings to include CLAUDE.md files
974async for message in query(
975 prompt="Add a new feature following project conventions",
976 options=ClaudeAgentOptions(
977 system_prompt={
978 "type": "preset",
979 "preset": "claude_code", # Use Claude Code's system prompt
980 },
981 setting_sources=["project"], # Loads CLAUDE.md from project
982 allowed_tools=["Read", "Write", "Edit"],
983 ),
984):
985 print(message)
986```
987
988#### èšå®ã®åªå
é äœ
989
990è€æ°ã®ãœãŒã¹ãèªã¿èŸŒãŸããå Žåãèšå®ã¯ãã®åªå
é äœïŒæé«ããæäœïŒã§ããŒãžãããŸãïŒ
991
9921. ããŒã«ã«èšå®ïŒ`.claude/settings.local.json`ïŒ
9932. ãããžã§ã¯ãèšå®ïŒ`.claude/settings.json`ïŒ
9943. ãŠãŒã¶ãŒèšå®ïŒ`~/.claude/settings.json`ïŒ
995
996`agents` ãš `allowed_tools` ãªã©ã®ããã°ã©ã çãªãªãã·ã§ã³ã¯ããŠãŒã¶ãŒããããžã§ã¯ããããŒã«ã«ã®ãã¡ã€ã«ã·ã¹ãã èšå®ããªãŒããŒã©ã€ãããŸãã管çããªã·ãŒèšå®ã¯ããã°ã©ã çãªãªãã·ã§ã³ããåªå
ãããŸãã
997
998### `AgentDefinition`
999
1000ããã°ã©ã ã§å®çŸ©ããããµããšãŒãžã§ã³ãã®èšå®ã
1001
1002```python theme={null}
1003@dataclass
1004class AgentDefinition:
1005 description: str
1006 prompt: str
1007 tools: list[str] | None = None
1008 disallowedTools: list[str] | None = None
1009 model: str | None = None
1010 skills: list[str] | None = None
1011 memory: Literal["user", "project", "local"] | None = None
1012 mcpServers: list[str | dict[str, Any]] | None = None
1013 initialPrompt: str | None = None
1014 maxTurns: int | None = None
1015 background: bool | None = None
1016 effort: Literal["low", "medium", "high", "max"] | int | None = None
1017 permissionMode: PermissionMode | None = None
1018```
1019
1020| ãã£ãŒã«ã | å¿
é | 説æ |
1021| :---------------- | :-- | :-------------------------------------------------------------------------------------------------------------- |
1022| `description` | ã¯ã | ãã®ãšãŒãžã§ã³ãã䜿çšããå Žåã®èªç¶èšèªèª¬æ |
1023| `prompt` | ã¯ã | ãšãŒãžã§ã³ãã®ã·ã¹ãã ããã³ãã |
1024| `tools` | ããã | èš±å¯ãããããŒã«åã®é
åãçç¥ããå Žåããã¹ãŠã®ããŒã«ãç¶æ¿ããŸã |
1025| `disallowedTools` | ããã | ãšãŒãžã§ã³ãã®ããŒã«ã»ããããåé€ããããŒã«åã®é
å |
1026| `model` | ããã | ãã®ãšãŒãžã§ã³ãã®ã¢ãã«ãªãŒããŒã©ã€ãã`"sonnet"`ã`"opus"`ã`"haiku"`ã`"inherit"` ãªã©ã®ãšã€ãªã¢ã¹ããŸãã¯å®å
šãªã¢ãã« ID ãåãå
¥ããŸããçç¥ããå Žåãã¡ã€ã³ã¢ãã«ã䜿çšããŸã |
1027| `skills` | ããã | ãã®ãšãŒãžã§ã³ããå©çšå¯èœãªã¹ãã«åã®ãªã¹ã |
1028| `memory` | ããã | ãã®ãšãŒãžã§ã³ãã®ã¡ã¢ãªãœãŒã¹ïŒ`"user"`ã`"project"`ããŸã㯠`"local"` |
1029| `mcpServers` | ããã | ãã®ãšãŒãžã§ã³ããå©çšå¯èœãª MCP ãµãŒããŒãåãšã³ããªã¯ãµãŒããŒåãŸãã¯ã€ã³ã©ã€ã³ `{name: config}` dict ã§ã |
1030| `initialPrompt` | ããã | ãã®ãšãŒãžã§ã³ããã¡ã€ã³ã¹ã¬ãããšãŒãžã§ã³ããšããŠå®è¡ãããå Žåãæåã®ãŠãŒã¶ãŒã¿ãŒã³ãšããŠèªåéä¿¡ãããŸã |
1031| `maxTurns` | ããã | ãšãŒãžã§ã³ããåæ¢ããåã®æ倧 agentic ã¿ãŒã³æ° |
1032| `background` | ããã | åŒã³åºããããšãã«ãã®ãšãŒãžã§ã³ããããããã³ã°ãããªãããã¯ã°ã©ãŠã³ãã¿ã¹ã¯ãšããŠå®è¡ããŸã |
1033| `effort` | ããã | ãã®ãšãŒãžã§ã³ãã®æšè«åªåã¬ãã«ãååä»ãã¬ãã«ãŸãã¯æŽæ°ãåãå
¥ããŸã |
1034| `permissionMode` | ããã | ãã®ãšãŒãžã§ã³ãå
ã®ããŒã«å®è¡ã®ããŒããã·ã§ã³ã¢ãŒãã[`PermissionMode`](#permission-mode) ãåç
§ |
1035
1036<Note>
1037 `AgentDefinition` ãã£ãŒã«ãå㯠`disallowedTools`ã`permissionMode`ã`maxTurns` ãªã©ã® camelCase ã䜿çšããŸãããããã®åå㯠TypeScript SDK ãšå
±æããã wire 圢åŒã«çŽæ¥ããããããŸãããã㯠`disallowed_tools` ãš `permission_mode` ãªã©ã®åçã®ãããã¬ãã«ãã£ãŒã«ãã« Python snake\_case ã䜿çšãã `ClaudeAgentOptions` ãšã¯ç°ãªããŸãã`AgentDefinition` 㯠dataclass ã§ãããããsnake\_case ããŒã¯ãŒããæž¡ããšæ§ç¯æã« `TypeError` ãçºçããŸãã
1038</Note>
1039
1040### `PermissionMode`
1041
1042ããŒã«å®è¡ãå¶åŸ¡ããããã®ããŒããã·ã§ã³ã¢ãŒãã
1043
1044```python theme={null}
1045PermissionMode = Literal[
1046 "default", # Standard permission behavior
1047 "acceptEdits", # Auto-accept file edits
1048 "plan", # Planning mode - no execution
1049 "dontAsk", # Deny anything not pre-approved instead of prompting
1050 "bypassPermissions", # Bypass all permission checks (use with caution)
1051]
1052```
1053
1054### `CanUseTool`
1055
1056ããŒã«ããŒããã·ã§ã³ã³ãŒã«ããã¯é¢æ°ã®åãšã€ãªã¢ã¹ã
1057
1058```python theme={null}
1059CanUseTool = Callable[
1060 [str, dict[str, Any], ToolPermissionContext], Awaitable[PermissionResult]
1061]
1062```
1063
1064ã³ãŒã«ããã¯ã¯ä»¥äžãåãåããŸãïŒ
1065
1066* `tool_name`ïŒåŒã³åºãããããŒã«ã®åå
1067* `input_data`ïŒããŒã«ã®å
¥åãã©ã¡ãŒã¿
1068* `context`ïŒè¿œå æ
å ±ãå«ã `ToolPermissionContext`
1069
1070`PermissionResult`ïŒ`PermissionResultAllow` ãŸã㯠`PermissionResultDeny`ïŒãè¿ããŸãã
1071
1072### `ToolPermissionContext`
1073
1074ããŒã«ããŒããã·ã§ã³ã³ãŒã«ããã¯ã«æž¡ãããã³ã³ããã¹ãæ
å ±ã
1075
1076```python theme={null}
1077@dataclass
1078class ToolPermissionContext:
1079 signal: Any | None = None # Future: abort signal support
1080 suggestions: list[PermissionUpdate] = field(default_factory=list)
1081```
1082
1083| ãã£ãŒã«ã | å | 説æ |
1084| :------------ | :----------------------- | :----------------- |
1085| `signal` | `Any \| None` | å°æ¥ã®äžæ¢ä¿¡å·ãµããŒãçšã«äºçŽæžã¿ |
1086| `suggestions` | `list[PermissionUpdate]` | CLI ããã®ããŒããã·ã§ã³æŽæ°ææ¡ |
1087
1088### `PermissionResult`
1089
1090ããŒããã·ã§ã³ã³ãŒã«ããã¯çµæã® Union åã
1091
1092```python theme={null}
1093PermissionResult = PermissionResultAllow | PermissionResultDeny
1094```
1095
1096### `PermissionResultAllow`
1097
1098ããŒã«åŒã³åºããèš±å¯ãã¹ãããšã瀺ãçµæã
1099
1100```python theme={null}
1101@dataclass
1102class PermissionResultAllow:
1103 behavior: Literal["allow"] = "allow"
1104 updated_input: dict[str, Any] | None = None
1105 updated_permissions: list[PermissionUpdate] | None = None
1106```
1107
1108| ãã£ãŒã«ã | å | ããã©ã«ã | 説æ |
1109| :-------------------- | :------------------------------- | :-------- | :----------------- |
1110| `behavior` | `Literal["allow"]` | `"allow"` | "allow" ã§ããå¿
èŠããããŸã |
1111| `updated_input` | `dict[str, Any] \| None` | `None` | å
ã®ä»£ããã«äœ¿çšããå€æŽãããå
¥å |
1112| `updated_permissions` | `list[PermissionUpdate] \| None` | `None` | é©çšããããŒããã·ã§ã³æŽæ° |
1113
1114### `PermissionResultDeny`
1115
1116ããŒã«åŒã³åºããæåŠãã¹ãããšã瀺ãçµæã
1117
1118```python theme={null}
1119@dataclass
1120class PermissionResultDeny:
1121 behavior: Literal["deny"] = "deny"
1122 message: str = ""
1123 interrupt: bool = False
1124```
1125
1126| ãã£ãŒã«ã | å | ããã©ã«ã | 説æ |
1127| :---------- | :---------------- | :------- | :-------------------- |
1128| `behavior` | `Literal["deny"]` | `"deny"` | "deny" ã§ããå¿
èŠããããŸã |
1129| `message` | `str` | `""` | ããŒã«ãæåŠãããçç±ã説æããã¡ãã»ãŒãž |
1130| `interrupt` | `bool` | `False` | çŸåšã®å®è¡ãå²ã蟌ããã©ãã |
1131
1132### `PermissionUpdate`
1133
1134ããã°ã©ã ã§ããŒããã·ã§ã³ãæŽæ°ããããã®èšå®ã
1135
1136```python theme={null}
1137@dataclass
1138class PermissionUpdate:
1139 type: Literal[
1140 "addRules",
1141 "replaceRules",
1142 "removeRules",
1143 "setMode",
1144 "addDirectories",
1145 "removeDirectories",
1146 ]
1147 rules: list[PermissionRuleValue] | None = None
1148 behavior: Literal["allow", "deny", "ask"] | None = None
1149 mode: PermissionMode | None = None
1150 directories: list[str] | None = None
1151 destination: (
1152 Literal["userSettings", "projectSettings", "localSettings", "session"] | None
1153 ) = None
1154```
1155
1156| ãã£ãŒã«ã | å | 説æ |
1157| :------------ | :---------------------------------------- | :-------------------- |
1158| `type` | `Literal[...]` | ããŒããã·ã§ã³æŽæ°æäœã®ã¿ã€ã |
1159| `rules` | `list[PermissionRuleValue] \| None` | è¿œå /眮æ/åé€æäœçšã®ã«ãŒã« |
1160| `behavior` | `Literal["allow", "deny", "ask"] \| None` | ã«ãŒã«ããŒã¹ã®æäœã®åäœ |
1161| `mode` | `PermissionMode \| None` | setMode æäœã®ã¢ãŒã |
1162| `directories` | `list[str] \| None` | ãã£ã¬ã¯ããªè¿œå /åé€æäœçšã®ãã£ã¬ã¯ã㪠|
1163| `destination` | `Literal[...] \| None` | ããŒããã·ã§ã³æŽæ°ãé©çšããå Žæ |
1164
1165### `PermissionRuleValue`
1166
1167ããŒããã·ã§ã³æŽæ°ã§è¿œå ã眮æããŸãã¯åé€ããã«ãŒã«ã
1168
1169```python theme={null}
1170@dataclass
1171class PermissionRuleValue:
1172 tool_name: str
1173 rule_content: str | None = None
1174```
1175
1176### `ToolsPreset`
1177
1178Claude Code ã®ããã©ã«ãããŒã«ã»ããã䜿çšããããã®ããªã»ããããŒã«èšå®ã
1179
1180```python theme={null}
1181class ToolsPreset(TypedDict):
1182 type: Literal["preset"]
1183 preset: Literal["claude_code"]
1184```
1185
1186### `ThinkingConfig`
1187
1188æ¡åŒµæèåäœãå¶åŸ¡ããŸãã3 ã€ã®èšå®ã® UnionïŒ
1189
1190```python theme={null}
1191class ThinkingConfigAdaptive(TypedDict):
1192 type: Literal["adaptive"]
1193
1194
1195class ThinkingConfigEnabled(TypedDict):
1196 type: Literal["enabled"]
1197 budget_tokens: int
1198
1199
1200class ThinkingConfigDisabled(TypedDict):
1201 type: Literal["disabled"]
1202
1203
1204ThinkingConfig = ThinkingConfigAdaptive | ThinkingConfigEnabled | ThinkingConfigDisabled
1205```
1206
1207| ããªã¢ã³ã | ãã£ãŒã«ã | 説æ |
1208| :--------- | :--------------------- | :-------------------------- |
1209| `adaptive` | `type` | Claude ã¯é©å¿çã«æèããã¿ã€ãã³ã°ã決å®ããŸã |
1210| `enabled` | `type`ã`budget_tokens` | ç¹å®ã®ããŒã¯ã³äºç®ã§æèãæå¹ã«ããŸã |
1211| `disabled` | `type` | æèãç¡å¹ã«ããŸã |
1212
1213ããã㯠`TypedDict` ã¯ã©ã¹ã§ãããããå®è¡æã«ã¯ãã¬ãŒã³ãª dict ã§ããdict ãªãã©ã«ãšããŠæ§ç¯ããããã¯ã©ã¹ãã³ã³ã¹ãã©ã¯ã¿ã®ããã«åŒã³åºããŸããã©ã¡ãã `dict` ãçæããŸãã`config["budget_tokens"]` ã§ãã£ãŒã«ãã«ã¢ã¯ã»ã¹ãã`config.budget_tokens` ã§ã¯ãªãïŒ
1214
1215```python theme={null}
1216from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled
1217
1218# Option 1: dict literal (recommended, no import needed)
1219options = ClaudeAgentOptions(thinking={"type": "enabled", "budget_tokens": 20000})
1220
1221# Option 2: constructor-style (returns a plain dict)
1222config = ThinkingConfigEnabled(type="enabled", budget_tokens=20000)
1223print(config["budget_tokens"]) # 20000
1224# config.budget_tokens would raise AttributeError
1225```
1226
1227### `SdkBeta`
1228
1229SDK ããŒã¿æ©èœã® Literal åã
1230
1231```python theme={null}
1232SdkBeta = Literal["context-1m-2025-08-07"]
1233```
1234
1235`ClaudeAgentOptions` ã® `betas` ãã£ãŒã«ãã§äœ¿çšããŠããŒã¿æ©èœãæå¹ã«ããŸãã
1236
1237<Warning>
1238 `context-1m-2025-08-07` ããŒã¿ã¯ 2026 幎 4 æ 30 æ¥æç¹ã§å»æ¢ãããŸããããã®ããããŒã Claude Sonnet 4.5 ãŸã㯠Sonnet 4 ã§æž¡ããšå¹æããªããæšæºã® 200k ããŒã¯ã³ã³ã³ããã¹ããŠã£ã³ããŠãè¶
ãããªã¯ãšã¹ãã¯ãšã©ãŒãè¿ããŸãã1M ããŒã¯ã³ã³ã³ããã¹ããŠã£ã³ããŠã䜿çšããã«ã¯ã[Claude Sonnet 4.6ãClaude Opus 4.6ããŸã㯠Claude Opus 4.7](https://platform.claude.com/docs/en/about-claude/models/overview) ã«ç§»è¡ããŠãã ããããããã«ã¯ãããŒã¿ããããŒãªãã§æšæºäŸ¡æ Œã§ 1M ã³ã³ããã¹ããå«ãŸããŸãã
1239</Warning>
1240
1241### `McpSdkServerConfig`
1242
1243`create_sdk_mcp_server()` ã§äœæããã SDK MCP ãµãŒããŒã®èšå®ã
1244
1245```python theme={null}
1246class McpSdkServerConfig(TypedDict):
1247 type: Literal["sdk"]
1248 name: str
1249 instance: Any # MCP Server instance
1250```
1251
1252### `McpServerConfig`
1253
1254MCP ãµãŒããŒèšå®ã® Union åã
1255
1256```python theme={null}
1257McpServerConfig = (
1258 McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig
1259)
1260```
1261
1262#### `McpStdioServerConfig`
1263
1264```python theme={null}
1265class McpStdioServerConfig(TypedDict):
1266 type: NotRequired[Literal["stdio"]] # Optional for backwards compatibility
1267 command: str
1268 args: NotRequired[list[str]]
1269 env: NotRequired[dict[str, str]]
1270```
1271
1272#### `McpSSEServerConfig`
1273
1274```python theme={null}
1275class McpSSEServerConfig(TypedDict):
1276 type: Literal["sse"]
1277 url: str
1278 headers: NotRequired[dict[str, str]]
1279```
1280
1281#### `McpHttpServerConfig`
1282
1283```python theme={null}
1284class McpHttpServerConfig(TypedDict):
1285 type: Literal["http"]
1286 url: str
1287 headers: NotRequired[dict[str, str]]
1288```
1289
1290### `McpServerStatusConfig`
1291
1292[`get_mcp_status()`](#methods) ã«ãã£ãŠå ±åããã MCP ãµãŒããŒã®èšå®ãããã¯ããã¹ãŠã® [`McpServerConfig`](#mcp-server-config) ãã©ã³ã¹ããŒãããªã¢ã³ããããã³ claude.ai ãéããŠãããã·ããããµãŒããŒçšã®åºåã®ã¿ã® `claudeai-proxy` ããªã¢ã³ãã® Union ã§ãã
1293
1294```python theme={null}
1295McpServerStatusConfig = (
1296 McpStdioServerConfig
1297 | McpSSEServerConfig
1298 | McpHttpServerConfig
1299 | McpSdkServerConfigStatus
1300 | McpClaudeAIProxyServerConfig
1301)
1302```
1303
1304`McpSdkServerConfigStatus` 㯠[`McpSdkServerConfig`](#mcp-sdk-server-config) ã®ã·ãªã¢ã©ã€ãºå¯èœãªåœ¢åŒã§ã`type`ïŒ`"sdk"`ïŒãš `name`ïŒ`str`ïŒãã£ãŒã«ãã®ã¿ã§ããã€ã³ããã»ã¹ `instance` ã¯çç¥ãããŸãã`McpClaudeAIProxyServerConfig` ã«ã¯ `type`ïŒ`"claudeai-proxy"`ïŒã`url`ïŒ`str`ïŒã`id`ïŒ`str`ïŒãã£ãŒã«ãããããŸãã
1305
1306### `McpStatusResponse`
1307
1308[`ClaudeSDKClient.get_mcp_status()`](#methods) ããã®å¿çããµãŒããŒã¹ããŒã¿ã¹ã®ãªã¹ãã `mcpServers` ããŒã®äžã«ã©ããããŸãã
1309
1310```python theme={null}
1311class McpStatusResponse(TypedDict):
1312 mcpServers: list[McpServerStatus]
1313```
1314
1315### `McpServerStatus`
1316
1317æ¥ç¶ããã MCP ãµãŒããŒã®ã¹ããŒã¿ã¹ã[`McpStatusResponse`](#mcp-status-response) ã«å«ãŸããŸãã
1318
1319```python theme={null}
1320class McpServerStatus(TypedDict):
1321 name: str
1322 status: McpServerConnectionStatus # "connected" | "failed" | "needs-auth" | "pending" | "disabled"
1323 serverInfo: NotRequired[McpServerInfo]
1324 error: NotRequired[str]
1325 config: NotRequired[McpServerStatusConfig]
1326 scope: NotRequired[str]
1327 tools: NotRequired[list[McpToolInfo]]
1328```
1329
1330| ãã£ãŒã«ã | å | 説æ |
1331| :----------- | :---------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
1332| `name` | `str` | ãµãŒããŒå |
1333| `status` | `str` | `"connected"`ã`"failed"`ã`"needs-auth"`ã`"pending"`ããŸã㯠`"disabled"` ã®ãããã |
1334| `serverInfo` | `dict`ïŒãªãã·ã§ã³ïŒ | ãµãŒããŒåãšããŒãžã§ã³ïŒ`{"name": str, "version": str}`ïŒ |
1335| `error` | `str`ïŒãªãã·ã§ã³ïŒ | ãµãŒããŒãæ¥ç¶ã«å€±æããå Žåã®ãšã©ãŒã¡ãã»ãŒãž |
1336| `config` | [`McpServerStatusConfig`](#mcp-server-status-config)ïŒãªãã·ã§ã³ïŒ | ãµãŒããŒèšå®ã[`McpServerConfig`](#mcp-server-config) ãšåã圢ç¶ïŒstdioãSSEãHTTPããŸã㯠SDKïŒãããã³ claude.ai ãéããŠæ¥ç¶ããããµãŒããŒçšã® `claudeai-proxy` ããªã¢ã³ã |
1337| `scope` | `str`ïŒãªãã·ã§ã³ïŒ | èšå®ã¹ã³ãŒã |
1338| `tools` | `list`ïŒãªãã·ã§ã³ïŒ | ãã®ãµãŒããŒãæäŸããããŒã«ãåããŒã«ã«ã¯ `name`ã`description`ã`annotations` ãã£ãŒã«ãããããŸã |
1339
1340### `SdkPluginConfig`
1341
1342SDK ã§ãã©ã°ã€ã³ãèªã¿èŸŒãããã®èšå®ã
1343
1344```python theme={null}
1345class SdkPluginConfig(TypedDict):
1346 type: Literal["local"]
1347 path: str
1348```
1349
1350| ãã£ãŒã«ã | å | 説æ |
1351| :----- | :----------------- | :-------------------------------------- |
1352| `type` | `Literal["local"]` | `"local"` ã§ããå¿
èŠããããŸãïŒçŸåšããŒã«ã«ãã©ã°ã€ã³ã®ã¿ãµããŒãïŒ |
1353| `path` | `str` | ãã©ã°ã€ã³ãã£ã¬ã¯ããªãžã®çµ¶å¯Ÿãã¹ãŸãã¯çžå¯Ÿãã¹ |
1354
1355**äŸïŒ**
1356
1357```python theme={null}
1358plugins = [
1359 {"type": "local", "path": "./my-plugin"},
1360 {"type": "local", "path": "/absolute/path/to/plugin"},
1361]
1362```
1363
1364ãã©ã°ã€ã³ã®äœæãšäœ¿çšã«é¢ããå®å
šãªæ
å ±ã«ã€ããŠã¯ã[ãã©ã°ã€ã³](/ja/agent-sdk/plugins) ãåç
§ããŠãã ããã
1365
1366## ã¡ãã»ãŒãžå
1367
1368### `Message`
1369
1370ãã¹ãŠã®å¯èœãªã¡ãã»ãŒãžã® Union åã
1371
1372```python theme={null}
1373Message = (
1374 UserMessage
1375 | AssistantMessage
1376 | SystemMessage
1377 | ResultMessage
1378 | StreamEvent
1379 | RateLimitEvent
1380)
1381```
1382
1383### `UserMessage`
1384
1385ãŠãŒã¶ãŒå
¥åã¡ãã»ãŒãžã
1386
1387```python theme={null}
1388@dataclass
1389class UserMessage:
1390 content: str | list[ContentBlock]
1391 uuid: str | None = None
1392 parent_tool_use_id: str | None = None
1393 tool_use_result: dict[str, Any] | None = None
1394```
1395
1396| ãã£ãŒã«ã | å | 説æ |
1397| :------------------- | :-------------------------- | :----------------------------- |
1398| `content` | `str \| list[ContentBlock]` | ããã¹ããŸãã¯ã³ã³ãã³ããããã¯ãšããŠã®ã¡ãã»ãŒãžã³ã³ãã³ã |
1399| `uuid` | `str \| None` | äžæã®ã¡ãã»ãŒãžèå¥å |
1400| `parent_tool_use_id` | `str \| None` | ãã®ã¡ãã»ãŒãžãããŒã«çµæå¿çã®å Žåã®ããŒã«äœ¿çš ID |
1401| `tool_use_result` | `dict[str, Any] \| None` | 該åœããå Žåã®ããŒã«çµæããŒã¿ |
1402
1403### `AssistantMessage`
1404
1405ã³ã³ãã³ããããã¯ä»ãã®ã¢ã·ã¹ã¿ã³ãå¿çã¡ãã»ãŒãžã
1406
1407```python theme={null}
1408@dataclass
1409class AssistantMessage:
1410 content: list[ContentBlock]
1411 model: str
1412 parent_tool_use_id: str | None = None
1413 error: AssistantMessageError | None = None
1414 usage: dict[str, Any] | None = None
1415 message_id: str | None = None
1416```
1417
1418| ãã£ãŒã«ã | å | 説æ |
1419| :------------------- | :------------------------------------------------------------- | :--------------------------------------------------------------- |
1420| `content` | `list[ContentBlock]` | å¿çå
ã®ã³ã³ãã³ããããã¯ã®ãªã¹ã |
1421| `model` | `str` | å¿çãçæããã¢ãã« |
1422| `parent_tool_use_id` | `str \| None` | ããããã¹ããããå¿çã®å Žåã®ããŒã«äœ¿çš ID |
1423| `error` | [`AssistantMessageError`](#assistant-message-error) ` \| None` | å¿çããšã©ãŒã«ééããå Žåã®ãšã©ãŒå |
1424| `usage` | `dict[str, Any] \| None` | ã¡ãã»ãŒãžããšã®ããŒã¯ã³äœ¿çšç¶æ³ïŒ[`ResultMessage.usage`](#result-message) ãšåãããŒïŒ |
1425| `message_id` | `str \| None` | API ã¡ãã»ãŒãž IDã1 ã€ã®ã¿ãŒã³ããã®è€æ°ã®ã¡ãã»ãŒãžã¯åã ID ãå
±æããŸã |
1426
1427### `AssistantMessageError`
1428
1429ã¢ã·ã¹ã¿ã³ãã¡ãã»ãŒãžã®å¯èœãªãšã©ãŒã¿ã€ãã
1430
1431```python theme={null}
1432AssistantMessageError = Literal[
1433 "authentication_failed",
1434 "billing_error",
1435 "rate_limit",
1436 "invalid_request",
1437 "server_error",
1438 "max_output_tokens",
1439 "unknown",
1440]
1441```
1442
1443### `SystemMessage`
1444
1445ã¡ã¿ããŒã¿ä»ãã®ã·ã¹ãã ã¡ãã»ãŒãžã
1446
1447```python theme={null}
1448@dataclass
1449class SystemMessage:
1450 subtype: str
1451 data: dict[str, Any]
1452```
1453
1454### `ResultMessage`
1455
1456ã³ã¹ããšäœ¿çšç¶æ³æ
å ±ãå«ãæçµçµæã¡ãã»ãŒãžã
1457
1458```python theme={null}
1459@dataclass
1460class ResultMessage:
1461 subtype: str
1462 duration_ms: int
1463 duration_api_ms: int
1464 is_error: bool
1465 num_turns: int
1466 session_id: str
1467 total_cost_usd: float | None = None
1468 usage: dict[str, Any] | None = None
1469 result: str | None = None
1470 stop_reason: str | None = None
1471 structured_output: Any = None
1472 model_usage: dict[str, Any] | None = None
1473```
1474
1475`usage` dict ã«ã¯ãååšããå Žåã以äžã®ããŒãå«ãŸããŸãïŒ
1476
1477| ã㌠| å | 説æ |
1478| ----------------------------- | ----- | ------------------------------ |
1479| `input_tokens` | `int` | æ¶è²»ãããç·å
¥åããŒã¯ã³ã |
1480| `output_tokens` | `int` | çæãããç·åºåããŒã¯ã³ã |
1481| `cache_creation_input_tokens` | `int` | æ°ãããã£ãã·ã¥ãšã³ããªãäœæããããã«äœ¿çšãããããŒã¯ã³ã |
1482| `cache_read_input_tokens` | `int` | æ¢åã®ãã£ãã·ã¥ãšã³ããªããèªã¿åãããããŒã¯ã³ã |
1483
1484`model_usage` dict ã¯ã¢ãã«åãã¢ãã«ããšã®äœ¿çšç¶æ³ã«ãããããŸããå
éš dict ããŒã¯ camelCase ã䜿çšããŸããããã¯ãåºã«ãªã CLI ããã»ã¹ããå€æŽãããã«æž¡ãããå€ã§ãããTypeScript [`ModelUsage`](/ja/agent-sdk/typescript#model-usage) åãšäžèŽããããã§ãïŒ
1485
1486| ã㌠| å | 説æ |
1487| -------------------------- | ------- | --------------------------------------------------------------------------------------------- |
1488| `inputTokens` | `int` | ãã®ã¢ãã«ã®å
¥åããŒã¯ã³ã |
1489| `outputTokens` | `int` | ãã®ã¢ãã«ã®åºåããŒã¯ã³ã |
1490| `cacheReadInputTokens` | `int` | ãã®ã¢ãã«ã®ãã£ãã·ã¥èªã¿åãããŒã¯ã³ã |
1491| `cacheCreationInputTokens` | `int` | ãã®ã¢ãã«ã®ãã£ãã·ã¥äœæããŒã¯ã³ã |
1492| `webSearchRequests` | `int` | ãã®ã¢ãã«ãè¡ã£ã Web æ€çŽ¢ãªã¯ãšã¹ãã |
1493| `costUSD` | `float` | ãã®ã¢ãã«ã®æšå® USD ã³ã¹ããã¯ã©ã€ã¢ã³ãåŽã§èšç®ãããŸãã[ã³ã¹ããšäœ¿çšç¶æ³ã远跡](/ja/agent-sdk/cost-tracking) ã§è«æ±ã®æ³šæäºé
ãåç
§ããŠãã ããã |
1494| `contextWindow` | `int` | ãã®ã¢ãã«ã®ã³ã³ããã¹ããŠã£ã³ããŠãµã€ãºã |
1495| `maxOutputTokens` | `int` | ãã®ã¢ãã«ã®æ倧åºåããŒã¯ã³å¶éã |
1496
1497### `StreamEvent`
1498
1499ã¹ããªãŒãã³ã°äžã®éšåçãªã¡ãã»ãŒãžæŽæ°ã®ããã®ã¹ããªãŒã ã€ãã³ãã`ClaudeAgentOptions` 㧠`include_partial_messages=True` ã®å Žåã®ã¿åãåãããŸãã`from claude_agent_sdk.types import StreamEvent` ã§ã€ã³ããŒãããŠãã ããã
1500
1501```python theme={null}
1502@dataclass
1503class StreamEvent:
1504 uuid: str
1505 session_id: str
1506 event: dict[str, Any] # The raw Claude API stream event
1507 parent_tool_use_id: str | None = None
1508```
1509
1510| ãã£ãŒã«ã | å | 説æ |
1511| :------------------- | :--------------- | :----------------------------- |
1512| `uuid` | `str` | ãã®ã€ãã³ãã®äžæã®èå¥å |
1513| `session_id` | `str` | ã»ãã·ã§ã³èå¥å |
1514| `event` | `dict[str, Any]` | çã® Claude API ã¹ããªãŒã ã€ãã³ãããŒã¿ |
1515| `parent_tool_use_id` | `str \| None` | ãã®ã€ãã³ãããµããšãŒãžã§ã³ãããã®å Žåã®èŠªããŒã«äœ¿çš ID |
1516
1517### `RateLimitEvent`
1518
1519ã¬ãŒãå¶éã¹ããŒã¿ã¹ãå€æŽããããšãã«çºè¡ãããŸãïŒäŸïŒ`"allowed"` ãã `"allowed_warning"` ãžïŒããŠãŒã¶ãŒã«ããŒãå¶éã«éããåã«èŠåããããã¹ããŒã¿ã¹ã `"rejected"` ã®å Žåã«ããã¯ãªãããããã«äœ¿çšããŸãã
1520
1521```python theme={null}
1522@dataclass
1523class RateLimitEvent:
1524 rate_limit_info: RateLimitInfo
1525 uuid: str
1526 session_id: str
1527```
1528
1529| ãã£ãŒã«ã | å | 説æ |
1530| :---------------- | :---------------------------------- | :--------- |
1531| `rate_limit_info` | [`RateLimitInfo`](#rate-limit-info) | çŸåšã®ã¬ãŒãå¶éç¶æ
|
1532| `uuid` | `str` | äžæã®ã€ãã³ãèå¥å |
1533| `session_id` | `str` | ã»ãã·ã§ã³èå¥å |
1534
1535### `RateLimitInfo`
1536
1537[`RateLimitEvent`](#rate-limit-event) ã«ãã£ãŠéã°ããã¬ãŒãå¶éç¶æ
ã
1538
1539```python theme={null}
1540RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]
1541RateLimitType = Literal[
1542 "five_hour", "seven_day", "seven_day_opus", "seven_day_sonnet", "overage"
1543]
1544
1545
1546@dataclass
1547class RateLimitInfo:
1548 status: RateLimitStatus
1549 resets_at: int | None = None
1550 rate_limit_type: RateLimitType | None = None
1551 utilization: float | None = None
1552 overage_status: RateLimitStatus | None = None
1553 overage_resets_at: int | None = None
1554 overage_disabled_reason: str | None = None
1555 raw: dict[str, Any] = field(default_factory=dict)
1556```
1557
1558| ãã£ãŒã«ã | å | 説æ |
1559| :------------------------ | :------------------------ | :--------------------------------------------------------------------------- |
1560| `status` | `RateLimitStatus` | çŸåšã®ã¹ããŒã¿ã¹ã`"allowed_warning"` ã¯å¶éã«è¿ã¥ããŠããããšãæå³ããŸãã`"rejected"` ã¯å¶éã«éããããšãæå³ããŸã |
1561| `resets_at` | `int \| None` | ã¬ãŒãå¶éãŠã£ã³ããŠããªã»ããããã Unix ã¿ã€ã ã¹ã¿ã³ã |
1562| `rate_limit_type` | `RateLimitType \| None` | ã©ã®ã¬ãŒãå¶éãŠã£ã³ããŠãé©çšãããã |
1563| `utilization` | `float \| None` | æ¶è²»ãããã¬ãŒãå¶éã®å²åïŒ0.0 ãã 1.0ïŒ |
1564| `overage_status` | `RateLimitStatus \| None` | 該åœããå Žåã®åŸé課éè¶
é䜿çšã®ã¹ããŒã¿ã¹ |
1565| `overage_resets_at` | `int \| None` | è¶
éãŠã£ã³ããŠããªã»ããããã Unix ã¿ã€ã ã¹ã¿ã³ã |
1566| `overage_disabled_reason` | `str \| None` | ã¹ããŒã¿ã¹ã `"rejected"` ã®å Žåãè¶
éãå©çšã§ããªãçç± |
1567| `raw` | `dict[str, Any]` | äžèšã§ã¢ãã«åãããŠããªããã£ãŒã«ããå«ããCLI ããã®å®å
šãªç dict |
1568
1569### `TaskStartedMessage`
1570
1571ããã¯ã°ã©ãŠã³ãã¿ã¹ã¯ãéå§ããããšãã«çºè¡ãããŸããããã¯ã°ã©ãŠã³ãã¿ã¹ã¯ã¯ãã¡ã€ã³ã¿ãŒã³ã®å€ã§è¿œè·¡ããããã®ïŒããã¯ã°ã©ãŠã³ã Bash ã³ãã³ãã[Monitor](#monitor) ãŠã©ãããAgent ããŒã«çµç±ã§çæããããµããšãŒãžã§ã³ãããŸãã¯ãªã¢ãŒããšãŒãžã§ã³ãã`task_type` ãã£ãŒã«ãã¯ã©ãã§ãããã瀺ããŸãããã®ããŒãã³ã°ã¯ `Task` ãã `Agent` ããŒã«ãžã®ååå€æŽãšã¯ç¡é¢ä¿ã§ãã
1572
1573```python theme={null}
1574@dataclass
1575class TaskStartedMessage(SystemMessage):
1576 task_id: str
1577 description: str
1578 uuid: str
1579 session_id: str
1580 tool_use_id: str | None = None
1581 task_type: str | None = None
1582```
1583
1584| ãã£ãŒã«ã | å | 説æ |
1585| :------------ | :------------ | :-------------------------------------------------------------------------------------------------- |
1586| `task_id` | `str` | ã¿ã¹ã¯ã®äžæã®èå¥å |
1587| `description` | `str` | ã¿ã¹ã¯ã®èª¬æ |
1588| `uuid` | `str` | äžæã®ã¡ãã»ãŒãžèå¥å |
1589| `session_id` | `str` | ã»ãã·ã§ã³èå¥å |
1590| `tool_use_id` | `str \| None` | é¢é£ããããŒã«äœ¿çš ID |
1591| `task_type` | `str \| None` | ããã¯ã°ã©ãŠã³ãã¿ã¹ã¯ã®çš®é¡ïŒããã¯ã°ã©ãŠã³ã Bash ãš Monitor ãŠã©ããã®å Žå㯠`"local_bash"`ã`"local_agent"`ããŸã㯠`"remote_agent"` |
1592
1593### `TaskUsage`
1594
1595ããã¯ã°ã©ãŠã³ãã¿ã¹ã¯ã®ããŒã¯ã³ãšã¿ã€ãã³ã°ããŒã¿ã
1596
1597```python theme={null}
1598class TaskUsage(TypedDict):
1599 total_tokens: int
1600 tool_uses: int
1601 duration_ms: int
1602```
1603
1604### `TaskProgressMessage`
1605
1606å®è¡äžã®ããã¯ã°ã©ãŠã³ãã¿ã¹ã¯ã®é²ææŽæ°ã§å®æçã«çºè¡ãããŸãã
1607
1608```python theme={null}
1609@dataclass
1610class TaskProgressMessage(SystemMessage):
1611 task_id: str
1612 description: str
1613 usage: TaskUsage
1614 uuid: str
1615 session_id: str
1616 tool_use_id: str | None = None
1617 last_tool_name: str | None = None
1618```
1619
1620| ãã£ãŒã«ã | å | 説æ |
1621| :--------------- | :------------ | :------------------ |
1622| `task_id` | `str` | ã¿ã¹ã¯ã®äžæã®èå¥å |
1623| `description` | `str` | çŸåšã®ã¹ããŒã¿ã¹èª¬æ |
1624| `usage` | `TaskUsage` | ãããŸã§ã®ãã®ã¿ã¹ã¯ã®ããŒã¯ã³äœ¿çšç¶æ³ |
1625| `uuid` | `str` | äžæã®ã¡ãã»ãŒãžèå¥å |
1626| `session_id` | `str` | ã»ãã·ã§ã³èå¥å |
1627| `tool_use_id` | `str \| None` | é¢é£ããããŒã«äœ¿çš ID |
1628| `last_tool_name` | `str \| None` | ã¿ã¹ã¯ãæåŸã«äœ¿çšããããŒã«ã®åå |
1629
1630### `TaskNotificationMessage`
1631
1632ããã¯ã°ã©ãŠã³ãã¿ã¹ã¯ãå®äºã倱æããŸãã¯åæ¢ããããšãã«çºè¡ãããŸããããã¯ã°ã©ãŠã³ãã¿ã¹ã¯ã«ã¯ã`run_in_background` Bash ã³ãã³ããMonitor ãŠã©ãããããã¯ã°ã©ãŠã³ããµããšãŒãžã§ã³ããå«ãŸããŸãã
1633
1634```python theme={null}
1635@dataclass
1636class TaskNotificationMessage(SystemMessage):
1637 task_id: str
1638 status: TaskNotificationStatus # "completed" | "failed" | "stopped"
1639 output_file: str
1640 summary: str
1641 uuid: str
1642 session_id: str
1643 tool_use_id: str | None = None
1644 usage: TaskUsage | None = None
1645```
1646
1647| ãã£ãŒã«ã | å | 説æ |
1648| :------------ | :----------------------- | :--------------------------------------------- |
1649| `task_id` | `str` | ã¿ã¹ã¯ã®äžæã®èå¥å |
1650| `status` | `TaskNotificationStatus` | `"completed"`ã`"failed"`ããŸã㯠`"stopped"` ã®ãããã |
1651| `output_file` | `str` | ã¿ã¹ã¯åºåãã¡ã€ã«ãžã®ãã¹ |
1652| `summary` | `str` | ã¿ã¹ã¯çµæã®ãµããªãŒ |
1653| `uuid` | `str` | äžæã®ã¡ãã»ãŒãžèå¥å |
1654| `session_id` | `str` | ã»ãã·ã§ã³èå¥å |
1655| `tool_use_id` | `str \| None` | é¢é£ããããŒã«äœ¿çš ID |
1656| `usage` | `TaskUsage \| None` | ã¿ã¹ã¯ã®æçµããŒã¯ã³äœ¿çšç¶æ³ |
1657
1658## ã³ã³ãã³ããããã¯å
1659
1660### `ContentBlock`
1661
1662ãã¹ãŠã®ã³ã³ãã³ããããã¯ã® Union åã
1663
1664```python theme={null}
1665ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock
1666```
1667
1668### `TextBlock`
1669
1670ããã¹ãã³ã³ãã³ããããã¯ã
1671
1672```python theme={null}
1673@dataclass
1674class TextBlock:
1675 text: str
1676```
1677
1678### `ThinkingBlock`
1679
1680æèã³ã³ãã³ããããã¯ïŒæèæ©èœãæã€ã¢ãã«çšïŒã
1681
1682```python theme={null}
1683@dataclass
1684class ThinkingBlock:
1685 thinking: str
1686 signature: str
1687```
1688
1689### `ToolUseBlock`
1690
1691ããŒã«äœ¿çšãªã¯ãšã¹ããããã¯ã
1692
1693```python theme={null}
1694@dataclass
1695class ToolUseBlock:
1696 id: str
1697 name: str
1698 input: dict[str, Any]
1699```
1700
1701### `ToolResultBlock`
1702
1703ããŒã«å®è¡çµæãããã¯ã
1704
1705```python theme={null}
1706@dataclass
1707class ToolResultBlock:
1708 tool_use_id: str
1709 content: str | list[dict[str, Any]] | None = None
1710 is_error: bool | None = None
1711```
1712
1713## ãšã©ãŒå
1714
1715### `ClaudeSDKError`
1716
1717ãã¹ãŠã® SDK ãšã©ãŒã®åºæ¬äŸå€ã¯ã©ã¹ã
1718
1719```python theme={null}
1720class ClaudeSDKError(Exception):
1721 """Base error for Claude SDK."""
1722```
1723
1724### `CLINotFoundError`
1725
1726Claude Code CLI ãã€ã³ã¹ããŒã«ãããŠããªããèŠã€ãããªãå Žåã«çºçããŸãã
1727
1728```python theme={null}
1729class CLINotFoundError(CLIConnectionError):
1730 def __init__(
1731 self, message: str = "Claude Code not found", cli_path: str | None = None
1732 ):
1733 """
1734 Args:
1735 message: Error message (default: "Claude Code not found")
1736 cli_path: Optional path to the CLI that was not found
1737 """
1738```
1739
1740### `CLIConnectionError`
1741
1742Claude Code ãžã®æ¥ç¶ã«å€±æããå Žåã«çºçããŸãã
1743
1744```python theme={null}
1745class CLIConnectionError(ClaudeSDKError):
1746 """Failed to connect to Claude Code."""
1747```
1748
1749### `ProcessError`
1750
1751Claude Code ããã»ã¹ã倱æããå Žåã«çºçããŸãã
1752
1753```python theme={null}
1754class ProcessError(ClaudeSDKError):
1755 def __init__(
1756 self, message: str, exit_code: int | None = None, stderr: str | None = None
1757 ):
1758 self.exit_code = exit_code
1759 self.stderr = stderr
1760```
1761
1762### `CLIJSONDecodeError`
1763
1764JSON 解æã«å€±æããå Žåã«çºçããŸãã
1765
1766```python theme={null}
1767class CLIJSONDecodeError(ClaudeSDKError):
1768 def __init__(self, line: str, original_error: Exception):
1769 """
1770 Args:
1771 line: The line that failed to parse
1772 original_error: The original JSON decode exception
1773 """
1774 self.line = line
1775 self.original_error = original_error
1776```
1777
1778## Hook å
1779
1780hooks ã®äœ¿çšã«é¢ããå
æ¬çãªã¬ã€ããäŸãäžè¬çãªãã¿ãŒã³ã«ã€ããŠã¯ã[Hooks ã¬ã€ã](/ja/agent-sdk/hooks) ãåç
§ããŠãã ããã
1781
1782### `HookEvent`
1783
1784ãµããŒããããŠãã hook ã€ãã³ãåã
1785
1786```python theme={null}
1787HookEvent = Literal[
1788 "PreToolUse", # Called before tool execution
1789 "PostToolUse", # Called after tool execution
1790 "PostToolUseFailure", # Called when a tool execution fails
1791 "UserPromptSubmit", # Called when user submits a prompt
1792 "Stop", # Called when stopping execution
1793 "SubagentStop", # Called when a subagent stops
1794 "PreCompact", # Called before message compaction
1795 "Notification", # Called for notification events
1796 "SubagentStart", # Called when a subagent starts
1797 "PermissionRequest", # Called when a permission decision is needed
1798]
1799```
1800
1801<Note>
1802 TypeScript SDK ã¯ãPython ã§ã¯ãŸã å©çšã§ããªãè¿œå ã® hook ã€ãã³ãããµããŒãããŠããŸãïŒ`SessionStart`ã`SessionEnd`ã`Setup`ã`TeammateIdle`ã`TaskCompleted`ã`ConfigChange`ã`WorktreeCreate`ã`WorktreeRemove`ã`PostToolBatch`ã
1803</Note>
1804
1805### `HookCallback`
1806
1807hook ã³ãŒã«ããã¯é¢æ°ã®åå®çŸ©ã
1808
1809```python theme={null}
1810HookCallback = Callable[[HookInput, str | None, HookContext], Awaitable[HookJSONOutput]]
1811```
1812
1813ãã©ã¡ãŒã¿ïŒ
1814
1815* `input`ïŒ`hook_event_name` ã«åºã¥ããå€å¥ Union ãæã€åŒ·ãåä»ãããã hook å
¥åïŒ[`HookInput`](#hook-input) ãåç
§ïŒ
1816* `tool_use_id`ïŒãªãã·ã§ã³ã®ããŒã«äœ¿çšèå¥åïŒããŒã«é¢é£ã® hook çšïŒ
1817* `context`ïŒè¿œå æ
å ±ãå«ã hook ã³ã³ããã¹ã
1818
1819以äžãå«ãå¯èœæ§ã®ãã [`HookJSONOutput`](#hook-json-output) ãè¿ããŸãïŒ
1820
1821* `decision`ïŒã¢ã¯ã·ã§ã³ããããã¯ããã«ã¯ `"block"`
1822* `systemMessage`ïŒãã©ã³ã¹ã¯ãªããã«è¿œå ããã·ã¹ãã ã¡ãã»ãŒãž
1823* `hookSpecificOutput`ïŒhook åºæã®åºåããŒã¿
1824
1825### `HookContext`
1826
1827hook ã³ãŒã«ããã¯ã«æž¡ãããã³ã³ããã¹ãæ
å ±ã
1828
1829```python theme={null}
1830class HookContext(TypedDict):
1831 signal: Any | None # Future: abort signal support
1832```
1833
1834### `HookMatcher`
1835
1836ç¹å®ã®ã€ãã³ããŸãã¯ããŒã«ã« hook ããããã³ã°ããããã®èšå®ã
1837
1838```python theme={null}
1839@dataclass
1840class HookMatcher:
1841 matcher: str | None = (
1842 None # Tool name or pattern to match (e.g., "Bash", "Write|Edit")
1843 )
1844 hooks: list[HookCallback] = field(
1845 default_factory=list
1846 ) # List of callbacks to execute
1847 timeout: float | None = (
1848 None # Timeout in seconds for all hooks in this matcher (default: 60)
1849 )
1850```
1851
1852### `HookInput`
1853
1854ãã¹ãŠã® hook å
¥ååã® Union åãå®éã®å㯠`hook_event_name` ãã£ãŒã«ãã«äŸåããŸãã
1855
1856```python theme={null}
1857HookInput = (
1858 PreToolUseHookInput
1859 | PostToolUseHookInput
1860 | PostToolUseFailureHookInput
1861 | UserPromptSubmitHookInput
1862 | StopHookInput
1863 | SubagentStopHookInput
1864 | PreCompactHookInput
1865 | NotificationHookInput
1866 | SubagentStartHookInput
1867 | PermissionRequestHookInput
1868)
1869```
1870
1871### `BaseHookInput`
1872
1873ãã¹ãŠã® hook å
¥ååã«ååšããåºæ¬ãã£ãŒã«ãã
1874
1875```python theme={null}
1876class BaseHookInput(TypedDict):
1877 session_id: str
1878 transcript_path: str
1879 cwd: str
1880 permission_mode: NotRequired[str]
1881```
1882
1883| ãã£ãŒã«ã | å | 説æ |
1884| :---------------- | :----------- | :-------------------- |
1885| `session_id` | `str` | çŸåšã®ã»ãã·ã§ã³èå¥å |
1886| `transcript_path` | `str` | ã»ãã·ã§ã³ãã©ã³ã¹ã¯ãªãããã¡ã€ã«ãžã®ãã¹ |
1887| `cwd` | `str` | çŸåšã®äœæ¥ãã£ã¬ã¯ã㪠|
1888| `permission_mode` | `str`ïŒãªãã·ã§ã³ïŒ | çŸåšã®ããŒããã·ã§ã³ã¢ãŒã |
1889
1890### `PreToolUseHookInput`
1891
1892`PreToolUse` hook ã€ãã³ãã®å
¥åããŒã¿ã
1893
1894```python theme={null}
1895class PreToolUseHookInput(BaseHookInput):
1896 hook_event_name: Literal["PreToolUse"]
1897 tool_name: str
1898 tool_input: dict[str, Any]
1899 tool_use_id: str
1900 agent_id: NotRequired[str]
1901 agent_type: NotRequired[str]
1902```
1903
1904| ãã£ãŒã«ã | å | 説æ |
1905| :---------------- | :---------------------- | :------------------------------------ |
1906| `hook_event_name` | `Literal["PreToolUse"]` | åžžã« "PreToolUse" |
1907| `tool_name` | `str` | å®è¡ããããšããŠããããŒã«ã®åå |
1908| `tool_input` | `dict[str, Any]` | ããŒã«ã®å
¥åãã©ã¡ãŒã¿ |
1909| `tool_use_id` | `str` | ãã®ããŒã«äœ¿çšã®äžæã®èå¥å |
1910| `agent_id` | `str`ïŒãªãã·ã§ã³ïŒ | ãµããšãŒãžã§ã³ãèå¥åãhook ããµããšãŒãžã§ã³ãå
ã§çºç«ããå Žåã«ååš |
1911| `agent_type` | `str`ïŒãªãã·ã§ã³ïŒ | ãµããšãŒãžã§ã³ãåãhook ããµããšãŒãžã§ã³ãå
ã§çºç«ããå Žåã«ååš |
1912
1913### `PostToolUseHookInput`
1914
1915`PostToolUse` hook ã€ãã³ãã®å
¥åããŒã¿ã
1916
1917```python theme={null}
1918class PostToolUseHookInput(BaseHookInput):
1919 hook_event_name: Literal["PostToolUse"]
1920 tool_name: str
1921 tool_input: dict[str, Any]
1922 tool_response: Any
1923 tool_use_id: str
1924 agent_id: NotRequired[str]
1925 agent_type: NotRequired[str]
1926```
1927
1928| ãã£ãŒã«ã | å | 説æ |
1929| :---------------- | :----------------------- | :------------------------------------ |
1930| `hook_event_name` | `Literal["PostToolUse"]` | åžžã« "PostToolUse" |
1931| `tool_name` | `str` | å®è¡ãããããŒã«ã®åå |
1932| `tool_input` | `dict[str, Any]` | 䜿çšãããå
¥åãã©ã¡ãŒã¿ |
1933| `tool_response` | `Any` | ããŒã«å®è¡ããã®å¿ç |
1934| `tool_use_id` | `str` | ãã®ããŒã«äœ¿çšã®äžæã®èå¥å |
1935| `agent_id` | `str`ïŒãªãã·ã§ã³ïŒ | ãµããšãŒãžã§ã³ãèå¥åãhook ããµããšãŒãžã§ã³ãå
ã§çºç«ããå Žåã«ååš |
1936| `agent_type` | `str`ïŒãªãã·ã§ã³ïŒ | ãµããšãŒãžã§ã³ãåãhook ããµããšãŒãžã§ã³ãå
ã§çºç«ããå Žåã«ååš |
1937
1938### `PostToolUseFailureHookInput`
1939
1940`PostToolUseFailure` hook ã€ãã³ãã®å
¥åããŒã¿ãããŒã«å®è¡ã倱æãããšãã«åŒã³åºãããŸãã
1941
1942```python theme={null}
1943class PostToolUseFailureHookInput(BaseHookInput):
1944 hook_event_name: Literal["PostToolUseFailure"]
1945 tool_name: str
1946 tool_input: dict[str, Any]
1947 tool_use_id: str
1948 error: str
1949 is_interrupt: NotRequired[bool]
1950 agent_id: NotRequired[str]
1951 agent_type: NotRequired[str]
1952```
1953
1954| ãã£ãŒã«ã | å | 説æ |
1955| :---------------- | :------------------------------ | :------------------------------------ |
1956| `hook_event_name` | `Literal["PostToolUseFailure"]` | åžžã« "PostToolUseFailure" |
1957| `tool_name` | `str` | 倱æããããŒã«ã®åå |
1958| `tool_input` | `dict[str, Any]` | 䜿çšãããå
¥åãã©ã¡ãŒã¿ |
1959| `tool_use_id` | `str` | ãã®ããŒã«äœ¿çšã®äžæã®èå¥å |
1960| `error` | `str` | 倱æããå®è¡ããã®ãšã©ãŒã¡ãã»ãŒãž |
1961| `is_interrupt` | `bool`ïŒãªãã·ã§ã³ïŒ | 倱æãå²ã蟌ã¿ã«ãã£ãŠåŒãèµ·ãããããã©ãã |
1962| `agent_id` | `str`ïŒãªãã·ã§ã³ïŒ | ãµããšãŒãžã§ã³ãèå¥åãhook ããµããšãŒãžã§ã³ãå
ã§çºç«ããå Žåã«ååš |
1963| `agent_type` | `str`ïŒãªãã·ã§ã³ïŒ | ãµããšãŒãžã§ã³ãåãhook ããµããšãŒãžã§ã³ãå
ã§çºç«ããå Žåã«ååš |
1964
1965### `UserPromptSubmitHookInput`
1966
1967`UserPromptSubmit` hook ã€ãã³ãã®å
¥åããŒã¿ã
1968
1969```python theme={null}
1970class UserPromptSubmitHookInput(BaseHookInput):
1971 hook_event_name: Literal["UserPromptSubmit"]
1972 prompt: str
1973```
1974
1975| ãã£ãŒã«ã | å | 説æ |
1976| :---------------- | :---------------------------- | :-------------------- |
1977| `hook_event_name` | `Literal["UserPromptSubmit"]` | åžžã« "UserPromptSubmit" |
1978| `prompt` | `str` | ãŠãŒã¶ãŒãéä¿¡ããããã³ãã |
1979
1980### `StopHookInput`
1981
1982`Stop` hook ã€ãã³ãã®å
¥åããŒã¿ã
1983
1984```python theme={null}
1985class StopHookInput(BaseHookInput):
1986 hook_event_name: Literal["Stop"]
1987 stop_hook_active: bool
1988```
1989
1990| ãã£ãŒã«ã | å | 説æ |
1991| :----------------- | :---------------- | :------------------- |
1992| `hook_event_name` | `Literal["Stop"]` | åžžã« "Stop" |
1993| `stop_hook_active` | `bool` | stop hook ãã¢ã¯ãã£ããã©ãã |
1994
1995### `SubagentStopHookInput`
1996
1997`SubagentStop` hook ã€ãã³ãã®å
¥åããŒã¿ã
1998
1999```python theme={null}
2000class SubagentStopHookInput(BaseHookInput):
2001 hook_event_name: Literal["SubagentStop"]
2002 stop_hook_active: bool
2003 agent_id: str
2004 agent_transcript_path: str
2005 agent_type: str
2006```
2007
2008| ãã£ãŒã«ã | å | 説æ |
2009| :---------------------- | :------------------------ | :------------------------ |
2010| `hook_event_name` | `Literal["SubagentStop"]` | åžžã« "SubagentStop" |
2011| `stop_hook_active` | `bool` | stop hook ãã¢ã¯ãã£ããã©ãã |
2012| `agent_id` | `str` | ãµããšãŒãžã§ã³ãã®äžæã®èå¥å |
2013| `agent_transcript_path` | `str` | ãµããšãŒãžã§ã³ãã®ãã©ã³ã¹ã¯ãªãããã¡ã€ã«ãžã®ãã¹ |
2014| `agent_type` | `str` | ãµããšãŒãžã§ã³ãã®å |
2015
2016### `PreCompactHookInput`
2017
2018`PreCompact` hook ã€ãã³ãã®å
¥åããŒã¿ã
2019
2020```python theme={null}
2021class PreCompactHookInput(BaseHookInput):
2022 hook_event_name: Literal["PreCompact"]
2023 trigger: Literal["manual", "auto"]
2024 custom_instructions: str | None
2025```
2026
2027| ãã£ãŒã«ã | å | 説æ |
2028| :-------------------- | :-------------------------- | :---------------- |
2029| `hook_event_name` | `Literal["PreCompact"]` | åžžã« "PreCompact" |
2030| `trigger` | `Literal["manual", "auto"]` | ã³ã³ãã¯ã·ã§ã³ ãããªã¬ãŒãããã® |
2031| `custom_instructions` | `str \| None` | ã³ã³ãã¯ã·ã§ã³çšã®ã«ã¹ã¿ã æ瀺 |
2032
2033### `NotificationHookInput`
2034
2035`Notification` hook ã€ãã³ãã®å
¥åããŒã¿ã
2036
2037```python theme={null}
2038class NotificationHookInput(BaseHookInput):
2039 hook_event_name: Literal["Notification"]
2040 message: str
2041 title: NotRequired[str]
2042 notification_type: str
2043```
2044
2045| ãã£ãŒã«ã | å | 説æ |
2046| :------------------ | :------------------------ | :---------------- |
2047| `hook_event_name` | `Literal["Notification"]` | åžžã« "Notification" |
2048| `message` | `str` | éç¥ã¡ãã»ãŒãžã³ã³ãã³ã |
2049| `title` | `str`ïŒãªãã·ã§ã³ïŒ | éç¥ã¿ã€ãã« |
2050| `notification_type` | `str` | éç¥ã®å |
2051
2052### `SubagentStartHookInput`
2053
2054`SubagentStart` hook ã€ãã³ãã®å
¥åããŒã¿ã
2055
2056```python theme={null}
2057class SubagentStartHookInput(BaseHookInput):
2058 hook_event_name: Literal["SubagentStart"]
2059 agent_id: str
2060 agent_type: str
2061```
2062
2063| ãã£ãŒã«ã | å | 説æ |
2064| :---------------- | :------------------------- | :----------------- |
2065| `hook_event_name` | `Literal["SubagentStart"]` | åžžã« "SubagentStart" |
2066| `agent_id` | `str` | ãµããšãŒãžã§ã³ãã®äžæã®èå¥å |
2067| `agent_type` | `str` | ãµããšãŒãžã§ã³ãã®å |
2068
2069### `PermissionRequestHookInput`
2070
2071`PermissionRequest` hook ã€ãã³ãã®å
¥åããŒã¿ãhooks ãããŒããã·ã§ã³æ±ºå®ãããã°ã©ã ã§åŠçã§ããããã«ããŸãã
2072
2073```python theme={null}
2074class PermissionRequestHookInput(BaseHookInput):
2075 hook_event_name: Literal["PermissionRequest"]
2076 tool_name: str
2077 tool_input: dict[str, Any]
2078 permission_suggestions: NotRequired[list[Any]]
2079```
2080
2081| ãã£ãŒã«ã | å | 説æ |
2082| :----------------------- | :----------------------------- | :--------------------- |
2083| `hook_event_name` | `Literal["PermissionRequest"]` | åžžã« "PermissionRequest" |
2084| `tool_name` | `str` | ããŒããã·ã§ã³ããªã¯ãšã¹ãããããŒã«ã®åå |
2085| `tool_input` | `dict[str, Any]` | ããŒã«ã®å
¥åãã©ã¡ãŒã¿ |
2086| `permission_suggestions` | `list[Any]`ïŒãªãã·ã§ã³ïŒ | CLI ããã®ææ¡ãããããŒããã·ã§ã³æŽæ° |
2087
2088### `HookJSONOutput`
2089
2090hook ã³ãŒã«ããã¯æ»ãå€ã® Union åã
2091
2092```python theme={null}
2093HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput
2094```
2095
2096#### `SyncHookJSONOutput`
2097
2098å¶åŸ¡ãã£ãŒã«ããšæ±ºå®ãã£ãŒã«ããæã€åæ hook åºåã
2099
2100```python theme={null}
2101class SyncHookJSONOutput(TypedDict):
2102 # Control fields
2103 continue_: NotRequired[bool] # Whether to proceed (default: True)
2104 suppressOutput: NotRequired[bool] # Hide stdout from transcript
2105 stopReason: NotRequired[str] # Message when continue is False
2106
2107 # Decision fields
2108 decision: NotRequired[Literal["block"]]
2109 systemMessage: NotRequired[str] # Warning message for user
2110 reason: NotRequired[str] # Feedback for Claude
2111
2112 # Hook-specific output
2113 hookSpecificOutput: NotRequired[HookSpecificOutput]
2114```
2115
2116<Note>
2117 Python ã³ãŒã㧠`continue_`ïŒã¢ã³ããŒã¹ã³ã¢ä»ãïŒã䜿çšããŠãã ãããCLI ã«éä¿¡ããããšãã«èªåçã« `continue` ã«å€æãããŸãã
2118</Note>
2119
2120#### `HookSpecificOutput`
2121
2122hook ã€ãã³ãåãšã€ãã³ãåºæã®ãã£ãŒã«ããå«ã `TypedDict`ã圢ç¶ã¯ `hookEventName` å€ã«äŸåããŸããhook ã€ãã³ãããšã«å©çšå¯èœãªãã£ãŒã«ãã®è©³çŽ°ã«ã€ããŠã¯ã[hooks ã§å®è¡ãå¶åŸ¡](/ja/agent-sdk/hooks#outputs) ãåç
§ããŠãã ããã
2123
2124ã€ãã³ãåºæã®åºååã®å€å¥ unionã`hookEventName` ãã£ãŒã«ãã¯ã©ã®ãã£ãŒã«ããæå¹ãã決å®ããŸãã
2125
2126```python theme={null}
2127class PreToolUseHookSpecificOutput(TypedDict):
2128 hookEventName: Literal["PreToolUse"]
2129 permissionDecision: NotRequired[Literal["allow", "deny", "ask"]]
2130 permissionDecisionReason: NotRequired[str]
2131 updatedInput: NotRequired[dict[str, Any]]
2132 additionalContext: NotRequired[str]
2133
2134
2135class PostToolUseHookSpecificOutput(TypedDict):
2136 hookEventName: Literal["PostToolUse"]
2137 additionalContext: NotRequired[str]
2138 updatedMCPToolOutput: NotRequired[Any]
2139
2140
2141class PostToolUseFailureHookSpecificOutput(TypedDict):
2142 hookEventName: Literal["PostToolUseFailure"]
2143 additionalContext: NotRequired[str]
2144
2145
2146class UserPromptSubmitHookSpecificOutput(TypedDict):
2147 hookEventName: Literal["UserPromptSubmit"]
2148 additionalContext: NotRequired[str]
2149
2150
2151class NotificationHookSpecificOutput(TypedDict):
2152 hookEventName: Literal["Notification"]
2153 additionalContext: NotRequired[str]
2154
2155
2156class SubagentStartHookSpecificOutput(TypedDict):
2157 hookEventName: Literal["SubagentStart"]
2158 additionalContext: NotRequired[str]
2159
2160
2161class PermissionRequestHookSpecificOutput(TypedDict):
2162 hookEventName: Literal["PermissionRequest"]
2163 decision: dict[str, Any]
2164
2165
2166HookSpecificOutput = (
2167 PreToolUseHookSpecificOutput
2168 | PostToolUseHookSpecificOutput
2169 | PostToolUseFailureHookSpecificOutput
2170 | UserPromptSubmitHookSpecificOutput
2171 | NotificationHookSpecificOutput
2172 | SubagentStartHookSpecificOutput
2173 | PermissionRequestHookSpecificOutput
2174)
2175```
2176
2177#### `AsyncHookJSONOutput`
2178
2179hook å®è¡ãé
延ãããéåæ hook åºåã
2180
2181```python theme={null}
2182class AsyncHookJSONOutput(TypedDict):
2183 async_: Literal[True] # Set to True to defer execution
2184 asyncTimeout: NotRequired[int] # Timeout in milliseconds
2185```
2186
2187<Note>
2188 Python ã³ãŒã㧠`async_`ïŒã¢ã³ããŒã¹ã³ã¢ä»ãïŒã䜿çšããŠãã ãããCLI ã«éä¿¡ããããšãã«èªåçã« `async` ã«å€æãããŸãã
2189</Note>
2190
2191### Hook 䜿çšäŸ
2192
2193ãã®äŸã¯ 2 ã€ã® hook ãç»é²ããŸãïŒ1 ã€ã¯ `rm -rf /` ã®ãããªå±éºãª bash ã³ãã³ãããããã¯ãããã 1 ã€ã¯ç£æ»ã®ããã«ãã¹ãŠã®ããŒã«äœ¿çšããã°ããŸããã»ãã¥ãªã㣠hook 㯠`matcher` ãä»ã㊠Bash ã³ãã³ãã§ã®ã¿å®è¡ããããã° hook ã¯ãã¹ãŠã®ããŒã«ã§å®è¡ãããŸãã
2194
2195```python theme={null}
2196from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, HookContext
2197from typing import Any
2198
2199
2200async def validate_bash_command(
2201 input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
2202) -> dict[str, Any]:
2203 """Validate and potentially block dangerous bash commands."""
2204 if input_data["tool_name"] == "Bash":
2205 command = input_data["tool_input"].get("command", "")
2206 if "rm -rf /" in command:
2207 return {
2208 "hookSpecificOutput": {
2209 "hookEventName": "PreToolUse",
2210 "permissionDecision": "deny",
2211 "permissionDecisionReason": "Dangerous command blocked",
2212 }
2213 }
2214 return {}
2215
2216
2217async def log_tool_use(
2218 input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
2219) -> dict[str, Any]:
2220 """Log all tool usage for auditing."""
2221 print(f"Tool used: {input_data.get('tool_name')}")
2222 return {}
2223
2224
2225options = ClaudeAgentOptions(
2226 hooks={
2227 "PreToolUse": [
2228 HookMatcher(
2229 matcher="Bash", hooks=[validate_bash_command], timeout=120
2230 ), # 2 min for validation
2231 HookMatcher(
2232 hooks=[log_tool_use]
2233 ), # Applies to all tools (default 60s timeout)
2234 ],
2235 "PostToolUse": [HookMatcher(hooks=[log_tool_use])],
2236 }
2237)
2238
2239async for message in query(prompt="Analyze this codebase", options=options):
2240 print(message)
2241```
2242
2243## ããŒã«å
¥åºåå
2244
2245ãã¹ãŠã®çµã¿èŸŒã¿ Claude Code ããŒã«ã®å
¥åºåã¹ããŒãã®ããã¥ã¡ã³ããPython SDK ã¯ããããåãšããŠãšã¯ã¹ããŒãããŸããããã¡ãã»ãŒãžå
ã®ããŒã«å
¥åºåã®æ§é ãè¡šããŸãã
2246
2247### Agent
2248
2249**ããŒã«åïŒ** `Agent`ïŒä»¥å㯠`Task`ãããã¯ãŸã ãšã€ãªã¢ã¹ãšããŠåãå
¥ããããŸãïŒ
2250
2251**å
¥åïŒ**
2252
2253```python theme={null}
2254{
2255 "description": str, # A short (3-5 word) description of the task
2256 "prompt": str, # The task for the agent to perform
2257 "subagent_type": str, # The type of specialized agent to use
2258}
2259```
2260
2261**åºåïŒ**
2262
2263```python theme={null}
2264{
2265 "result": str, # Final result from the subagent
2266 "usage": dict | None, # Token usage statistics
2267 "total_cost_usd": float | None, # Estimated total cost in USD
2268 "duration_ms": int | None, # Execution duration in milliseconds
2269}
2270```
2271
2272### AskUserQuestion
2273
2274**ããŒã«åïŒ** `AskUserQuestion`
2275
2276å®è¡äžã«ãŠãŒã¶ãŒã«æ確åã®è³ªåãããŸãã䜿çšã®è©³çŽ°ã«ã€ããŠã¯ [æ¿èªãšãŠãŒã¶ãŒå
¥åãåŠç](/ja/agent-sdk/user-input#handle-clarifying-questions) ãåç
§ããŠãã ããã
2277
2278**å
¥åïŒ**
2279
2280```python theme={null}
2281{
2282 "questions": [ # Questions to ask the user (1-4 questions)
2283 {
2284 "question": str, # The complete question to ask the user
2285 "header": str, # Very short label displayed as a chip/tag (max 12 chars)
2286 "options": [ # The available choices (2-4 options)
2287 {
2288 "label": str, # Display text for this option (1-5 words)
2289 "description": str, # Explanation of what this option means
2290 }
2291 ],
2292 "multiSelect": bool, # Set to true to allow multiple selections
2293 }
2294 ],
2295 "answers": dict | None, # User answers populated by the permission system
2296}
2297```
2298
2299**åºåïŒ**
2300
2301```python theme={null}
2302{
2303 "questions": [ # The questions that were asked
2304 {
2305 "question": str,
2306 "header": str,
2307 "options": [{"label": str, "description": str}],
2308 "multiSelect": bool,
2309 }
2310 ],
2311 "answers": dict[str, str], # Maps question text to answer string
2312 # Multi-select answers are comma-separated
2313}
2314```
2315
2316### Bash
2317
2318**ããŒã«åïŒ** `Bash`
2319
2320**å
¥åïŒ**
2321
2322```python theme={null}
2323{
2324 "command": str, # The command to execute
2325 "timeout": int | None, # Optional timeout in milliseconds (max 600000)
2326 "description": str | None, # Clear, concise description (5-10 words)
2327 "run_in_background": bool | None, # Set to true to run in background
2328}
2329```
2330
2331**åºåïŒ**
2332
2333```python theme={null}
2334{
2335 "output": str, # Combined stdout and stderr output
2336 "exitCode": int, # Exit code of the command
2337 "killed": bool | None, # Whether command was killed due to timeout
2338 "shellId": str | None, # Shell ID for background processes
2339}
2340```
2341
2342### Monitor
2343
2344**ããŒã«åïŒ** `Monitor`
2345
2346ããã¯ã°ã©ãŠã³ãã¹ã¯ãªãããå®è¡ããå stdout è¡ã Claude ã«ã€ãã³ããšããŠé
ä¿¡ããŠãããŒãªã³ã°ãªãã§åå¿ã§ããããã«ããŸããMonitor 㯠Bash ãšåãããŒããã·ã§ã³ã«ãŒã«ã«åŸããŸããåäœãšãããã€ããŒã®å¯çšæ§ã«ã€ããŠã¯ã[Monitor ããŒã«ãªãã¡ã¬ã³ã¹](/ja/tools-reference#monitor-tool) ãåç
§ããŠãã ããã
2347
2348**å
¥åïŒ**
2349
2350```python theme={null}
2351{
2352 "command": str, # Shell script; each stdout line is an event, exit ends the watch
2353 "description": str, # Short description shown in notifications
2354 "timeout_ms": int | None, # Kill after this deadline (default 300000, max 3600000)
2355 "persistent": bool | None, # Run for the lifetime of the session; stop with TaskStop
2356}
2357```
2358
2359**åºåïŒ**
2360
2361```python theme={null}
2362{
2363 "taskId": str, # ID of the background monitor task
2364 "timeoutMs": int, # Timeout deadline in milliseconds (0 when persistent)
2365 "persistent": bool | None, # True when running until TaskStop or session end
2366}
2367```
2368
2369### Edit
2370
2371**ããŒã«åïŒ** `Edit`
2372
2373**å
¥åïŒ**
2374
2375```python theme={null}
2376{
2377 "file_path": str, # The absolute path to the file to modify
2378 "old_string": str, # The text to replace
2379 "new_string": str, # The text to replace it with
2380 "replace_all": bool | None, # Replace all occurrences (default False)
2381}
2382```
2383
2384**åºåïŒ**
2385
2386```python theme={null}
2387{
2388 "message": str, # Confirmation message
2389 "replacements": int, # Number of replacements made
2390 "file_path": str, # File path that was edited
2391}
2392```
2393
2394### Read
2395
2396**ããŒã«åïŒ** `Read`
2397
2398**å
¥åïŒ**
2399
2400```python theme={null}
2401{
2402 "file_path": str, # The absolute path to the file to read
2403 "offset": int | None, # The line number to start reading from
2404 "limit": int | None, # The number of lines to read
2405}
2406```
2407
2408**åºåïŒããã¹ããã¡ã€ã«ïŒïŒ**
2409
2410```python theme={null}
2411{
2412 "content": str, # File contents with line numbers
2413 "total_lines": int, # Total number of lines in file
2414 "lines_returned": int, # Lines actually returned
2415}
2416```
2417
2418**åºåïŒç»åïŒïŒ**
2419
2420```python theme={null}
2421{
2422 "image": str, # Base64 encoded image data
2423 "mime_type": str, # Image MIME type
2424 "file_size": int, # File size in bytes
2425}
2426```
2427
2428### Write
2429
2430**ããŒã«åïŒ** `Write`
2431
2432**å
¥åïŒ**
2433
2434```python theme={null}
2435{
2436 "file_path": str, # The absolute path to the file to write
2437 "content": str, # The content to write to the file
2438}
2439```
2440
2441**åºåïŒ**
2442
2443```python theme={null}
2444{
2445 "message": str, # Success message
2446 "bytes_written": int, # Number of bytes written
2447 "file_path": str, # File path that was written
2448}
2449```
2450
2451### Glob
2452
2453**ããŒã«åïŒ** `Glob`
2454
2455**å
¥åïŒ**
2456
2457```python theme={null}
2458{
2459 "pattern": str, # The glob pattern to match files against
2460 "path": str | None, # The directory to search in (defaults to cwd)
2461}
2462```
2463
2464**åºåïŒ**
2465
2466```python theme={null}
2467{
2468 "matches": list[str], # Array of matching file paths
2469 "count": int, # Number of matches found
2470 "search_path": str, # Search directory used
2471}
2472```
2473
2474### Grep
2475
2476**ããŒã«åïŒ** `Grep`
2477
2478**å
¥åïŒ**
2479
2480```python theme={null}
2481{
2482 "pattern": str, # The regular expression pattern
2483 "path": str | None, # File or directory to search in
2484 "glob": str | None, # Glob pattern to filter files
2485 "type": str | None, # File type to search
2486 "output_mode": str | None, # "content", "files_with_matches", or "count"
2487 "-i": bool | None, # Case insensitive search
2488 "-n": bool | None, # Show line numbers
2489 "-B": int | None, # Lines to show before each match
2490 "-A": int | None, # Lines to show after each match
2491
2492 "-C": int | None, # Lines to show before and after
2493 "head_limit": int | None, # Limit output to first N lines/entries
2494 "multiline": bool | None, # Enable multiline mode
2495}
2496```
2497
2498**åºåïŒcontent ã¢ãŒãïŒïŒ**
2499
2500```python theme={null}
2501{
2502 "matches": [
2503 {
2504 "file": str,
2505 "line_number": int | None,
2506 "line": str,
2507 "before_context": list[str] | None,
2508 "after_context": list[str] | None,
2509 }
2510 ],
2511 "total_matches": int,
2512}
2513```
2514
2515**åºåïŒfiles\_with\_matches ã¢ãŒãïŒïŒ**
2516
2517```python theme={null}
2518{
2519 "files": list[str], # Files containing matches
2520 "count": int, # Number of files with matches
2521}
2522```
2523
2524### NotebookEdit
2525
2526**ããŒã«åïŒ** `NotebookEdit`
2527
2528**å
¥åïŒ**
2529
2530```python theme={null}
2531{
2532 "notebook_path": str, # Absolute path to the Jupyter notebook
2533 "cell_id": str | None, # The ID of the cell to edit
2534 "new_source": str, # The new source for the cell
2535 "cell_type": "code" | "markdown" | None, # The type of the cell
2536 "edit_mode": "replace" | "insert" | "delete" | None, # Edit operation type
2537}
2538```
2539
2540**åºåïŒ**
2541
2542```python theme={null}
2543{
2544 "message": str, # Success message
2545 "edit_type": "replaced" | "inserted" | "deleted", # Type of edit performed
2546 "cell_id": str | None, # Cell ID that was affected
2547 "total_cells": int, # Total cells in notebook after edit
2548}
2549```
2550
2551### WebFetch
2552
2553**ããŒã«åïŒ** `WebFetch`
2554
2555**å
¥åïŒ**
2556
2557```python theme={null}
2558{
2559 "url": str, # The URL to fetch content from
2560 "prompt": str, # The prompt to run on the fetched content
2561}
2562```
2563
2564**åºåïŒ**
2565
2566```python theme={null}
2567{
2568 "response": str, # AI model's response to the prompt
2569 "url": str, # URL that was fetched
2570 "final_url": str | None, # Final URL after redirects
2571 "status_code": int | None, # HTTP status code
2572}
2573```
2574
2575### WebSearch
2576
2577**ããŒã«åïŒ** `WebSearch`
2578
2579**å
¥åïŒ**
2580
2581```python theme={null}
2582{
2583 "query": str, # The search query to use
2584 "allowed_domains": list[str] | None, # Only include results from these domains
2585 "blocked_domains": list[str] | None, # Never include results from these domains
2586}
2587```
2588
2589**åºåïŒ**
2590
2591```python theme={null}
2592{
2593 "results": [{"title": str, "url": str, "snippet": str, "metadata": dict | None}],
2594 "total_results": int,
2595 "query": str,
2596}
2597```
2598
2599### TodoWrite
2600
2601**ããŒã«åïŒ** `TodoWrite`
2602
2603**å
¥åïŒ**
2604
2605```python theme={null}
2606{
2607 "todos": [
2608 {
2609 "content": str, # The task description
2610 "status": "pending" | "in_progress" | "completed", # Task status
2611 "activeForm": str, # Active form of the description
2612 }
2613 ]
2614}
2615```
2616
2617**åºåïŒ**
2618
2619```python theme={null}
2620{
2621 "message": str, # Success message
2622 "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},
2623}
2624```
2625
2626### BashOutput
2627
2628**ããŒã«åïŒ** `BashOutput`
2629
2630**å
¥åïŒ**
2631
2632```python theme={null}
2633{
2634 "bash_id": str, # The ID of the background shell
2635 "filter": str | None, # Optional regex to filter output lines
2636}
2637```
2638
2639**åºåïŒ**
2640
2641```python theme={null}
2642{
2643 "output": str, # New output since last check
2644 "status": "running" | "completed" | "failed", # Current shell status
2645 "exitCode": int | None, # Exit code when completed
2646}
2647```
2648
2649### KillBash
2650
2651**ããŒã«åïŒ** `KillBash`
2652
2653**å
¥åïŒ**
2654
2655```python theme={null}
2656{
2657 "shell_id": str # The ID of the background shell to kill
2658}
2659```
2660
2661**åºåïŒ**
2662
2663```python theme={null}
2664{
2665 "message": str, # Success message
2666 "shell_id": str, # ID of the killed shell
2667}
2668```
2669
2670### ExitPlanMode
2671
2672**ããŒã«åïŒ** `ExitPlanMode`
2673
2674**å
¥åïŒ**
2675
2676```python theme={null}
2677{
2678 "plan": str # The plan to run by the user for approval
2679}
2680```
2681
2682**åºåïŒ**
2683
2684```python theme={null}
2685{
2686 "message": str, # Confirmation message
2687 "approved": bool | None, # Whether user approved the plan
2688}
2689```
2690
2691### ListMcpResources
2692
2693**ããŒã«åïŒ** `ListMcpResources`
2694
2695**å
¥åïŒ**
2696
2697```python theme={null}
2698{
2699 "server": str | None # Optional server name to filter resources by
2700}
2701```
2702
2703**åºåïŒ**
2704
2705```python theme={null}
2706{
2707 "resources": [
2708 {
2709 "uri": str,
2710 "name": str,
2711 "description": str | None,
2712 "mimeType": str | None,
2713 "server": str,
2714 }
2715 ],
2716 "total": int,
2717}
2718```
2719
2720### ReadMcpResource
2721
2722**ããŒã«åïŒ** `ReadMcpResource`
2723
2724**å
¥åïŒ**
2725
2726```python theme={null}
2727{
2728 "server": str, # The MCP server name
2729 "uri": str, # The resource URI to read
2730}
2731```
2732
2733**åºåïŒ**
2734
2735```python theme={null}
2736{
2737 "contents": [
2738 {"uri": str, "mimeType": str | None, "text": str | None, "blob": str | None}
2739 ],
2740 "server": str,
2741}
2742```
2743
2744## ClaudeSDKClient ã䜿çšããé«åºŠãªæ©èœ
2745
2746### ç¶ç¶çãªäŒè©±ã€ã³ã¿ãŒãã§ãŒã¹ã®æ§ç¯
2747
2748```python theme={null}
2749from claude_agent_sdk import (
2750 ClaudeSDKClient,
2751 ClaudeAgentOptions,
2752 AssistantMessage,
2753 TextBlock,
2754)
2755import asyncio
2756
2757
2758class ConversationSession:
2759 """Maintains a single conversation session with Claude."""
2760
2761 def __init__(self, options: ClaudeAgentOptions | None = None):
2762 self.client = ClaudeSDKClient(options)
2763 self.turn_count = 0
2764
2765 async def start(self):
2766 await self.client.connect()
2767 print("Starting conversation session. Claude will remember context.")
2768 print(
2769 "Commands: 'exit' to quit, 'interrupt' to stop current task, 'new' for new session"
2770 )
2771
2772 while True:
2773 user_input = input(f"\n[Turn {self.turn_count + 1}] You: ")
2774
2775 if user_input.lower() == "exit":
2776 break
2777 elif user_input.lower() == "interrupt":
2778 await self.client.interrupt()
2779 print("Task interrupted!")
2780 continue
2781 elif user_input.lower() == "new":
2782 # Disconnect and reconnect for a fresh session
2783 await self.client.disconnect()
2784 await self.client.connect()
2785 self.turn_count = 0
2786 print("Started new conversation session (previous context cleared)")
2787 continue
2788
2789 # Send message - the session retains all previous messages
2790 await self.client.query(user_input)
2791 self.turn_count += 1
2792
2793 # Process response
2794 print(f"[Turn {self.turn_count}] Claude: ", end="")
2795 async for message in self.client.receive_response():
2796 if isinstance(message, AssistantMessage):
2797 for block in message.content:
2798 if isinstance(block, TextBlock):
2799 print(block.text, end="")
2800 print() # New line after response
2801
2802 await self.client.disconnect()
2803 print(f"Conversation ended after {self.turn_count} turns.")
2804
2805
2806async def main():
2807 options = ClaudeAgentOptions(
2808 allowed_tools=["Read", "Write", "Bash"], permission_mode="acceptEdits"
2809 )
2810 session = ConversationSession(options)
2811 await session.start()
2812
2813
2814# Example conversation:
2815# Turn 1 - You: "Create a file called hello.py"
2816# Turn 1 - Claude: "I'll create a hello.py file for you..."
2817# Turn 2 - You: "What's in that file?"
2818# Turn 2 - Claude: "The hello.py file I just created contains..." (remembers!)
2819# Turn 3 - You: "Add a main function to it"
2820# Turn 3 - Claude: "I'll add a main function to hello.py..." (knows which file!)
2821
2822asyncio.run(main())
2823```
2824
2825### åäœä¿®æ£ã®ããã® Hooks ã®äœ¿çš
2826
2827```python theme={null}
2828from claude_agent_sdk import (
2829 ClaudeSDKClient,
2830 ClaudeAgentOptions,
2831 HookMatcher,
2832 HookContext,
2833)
2834import asyncio
2835from typing import Any
2836
2837
2838async def pre_tool_logger(
2839 input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
2840) -> dict[str, Any]:
2841 """Log all tool usage before execution."""
2842 tool_name = input_data.get("tool_name", "unknown")
2843 print(f"[PRE-TOOL] About to use: {tool_name}")
2844
2845 # You can modify or block the tool execution here
2846 if tool_name == "Bash" and "rm -rf" in str(input_data.get("tool_input", {})):
2847 return {
2848 "hookSpecificOutput": {
2849 "hookEventName": "PreToolUse",
2850 "permissionDecision": "deny",
2851 "permissionDecisionReason": "Dangerous command blocked",
2852 }
2853 }
2854 return {}
2855
2856
2857async def post_tool_logger(
2858 input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
2859) -> dict[str, Any]:
2860 """Log results after tool execution."""
2861 tool_name = input_data.get("tool_name", "unknown")
2862 print(f"[POST-TOOL] Completed: {tool_name}")
2863 return {}
2864
2865
2866async def user_prompt_modifier(
2867 input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
2868) -> dict[str, Any]:
2869 """Add context to user prompts."""
2870 original_prompt = input_data.get("prompt", "")
2871
2872 # Add a timestamp as additional context for Claude to see
2873 from datetime import datetime
2874
2875 timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
2876
2877 return {
2878 "hookSpecificOutput": {
2879 "hookEventName": "UserPromptSubmit",
2880 "additionalContext": f"[Submitted at {timestamp}] Original prompt: {original_prompt}",
2881 }
2882 }
2883
2884
2885async def main():
2886 options = ClaudeAgentOptions(
2887 hooks={
2888 "PreToolUse": [
2889 HookMatcher(hooks=[pre_tool_logger]),
2890 HookMatcher(matcher="Bash", hooks=[pre_tool_logger]),
2891 ],
2892 "PostToolUse": [HookMatcher(hooks=[post_tool_logger])],
2893 "UserPromptSubmit": [HookMatcher(hooks=[user_prompt_modifier])],
2894 },
2895 allowed_tools=["Read", "Write", "Bash"],
2896 )
2897
2898 async with ClaudeSDKClient(options=options) as client:
2899 await client.query("List files in current directory")
2900
2901 async for message in client.receive_response():
2902 # Hooks will automatically log tool usage
2903 pass
2904
2905
2906asyncio.run(main())
2907```
2908
2909### ãªã¢ã«ã¿ã€ã é²æç£èŠ
2910
2911```python theme={null}
2912from claude_agent_sdk import (
2913 ClaudeSDKClient,
2914 ClaudeAgentOptions,
2915 AssistantMessage,
2916 ToolUseBlock,
2917 ToolResultBlock,
2918 TextBlock,
2919)
2920import asyncio
2921
2922
2923async def monitor_progress():
2924 options = ClaudeAgentOptions(
2925 allowed_tools=["Write", "Bash"], permission_mode="acceptEdits"
2926 )
2927
2928 async with ClaudeSDKClient(options=options) as client:
2929 await client.query("Create 5 Python files with different sorting algorithms")
2930
2931 # Monitor progress in real-time
2932 async for message in client.receive_response():
2933 if isinstance(message, AssistantMessage):
2934 for block in message.content:
2935 if isinstance(block, ToolUseBlock):
2936 if block.name == "Write":
2937 file_path = block.input.get("file_path", "")
2938 print(f"Creating: {file_path}")
2939 elif isinstance(block, ToolResultBlock):
2940 print("Completed tool execution")
2941 elif isinstance(block, TextBlock):
2942 print(f"Claude says: {block.text[:100]}...")
2943
2944 print("Task completed!")
2945
2946
2947asyncio.run(monitor_progress())
2948```
2949
2950## 䜿çšäŸ
2951
2952### åºæ¬çãªãã¡ã€ã«æäœïŒquery ã䜿çšïŒ
2953
2954```python theme={null}
2955from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock
2956import asyncio
2957
2958
2959async def create_project():
2960 options = ClaudeAgentOptions(
2961 allowed_tools=["Read", "Write", "Bash"],
2962 permission_mode="acceptEdits",
2963 cwd="/home/user/project",
2964 )
2965
2966 async for message in query(
2967 prompt="Create a Python project structure with setup.py", options=options
2968 ):
2969 if isinstance(message, AssistantMessage):
2970 for block in message.content:
2971 if isinstance(block, ToolUseBlock):
2972 print(f"Using tool: {block.name}")
2973
2974
2975asyncio.run(create_project())
2976```
2977
2978### ãšã©ãŒåŠç
2979
2980```python theme={null}
2981from claude_agent_sdk import query, CLINotFoundError, ProcessError, CLIJSONDecodeError
2982
2983try:
2984 async for message in query(prompt="Hello"):
2985 print(message)
2986except CLINotFoundError:
2987 print(
2988 "Claude Code CLI not found. Try reinstalling: pip install --force-reinstall claude-agent-sdk"
2989 )
2990except ProcessError as e:
2991 print(f"Process failed with exit code: {e.exit_code}")
2992except CLIJSONDecodeError as e:
2993 print(f"Failed to parse response: {e}")
2994```
2995
2996### ã¯ã©ã€ã¢ã³ãã§ã®ã¹ããªãŒãã³ã°ã¢ãŒã
2997
2998```python theme={null}
2999from claude_agent_sdk import ClaudeSDKClient
3000import asyncio
3001
3002
3003async def interactive_session():
3004 async with ClaudeSDKClient() as client:
3005 # Send initial message
3006 await client.query("What's the weather like?")
3007
3008 # Process responses
3009 async for msg in client.receive_response():
3010 print(msg)
3011
3012 # Send follow-up
3013 await client.query("Tell me more about that")
3014
3015 # Process follow-up response
3016 async for msg in client.receive_response():
3017 print(msg)
3018
3019
3020asyncio.run(interactive_session())
3021```
3022
3023### ClaudeSDKClient ã§ã«ã¹ã¿ã ããŒã«ã䜿çšãã
3024
3025```python theme={null}
3026from claude_agent_sdk import (
3027 ClaudeSDKClient,
3028 ClaudeAgentOptions,
3029 tool,
3030 create_sdk_mcp_server,
3031 AssistantMessage,
3032 TextBlock,
3033)
3034import asyncio
3035from typing import Any
3036
3037
3038# Define custom tools with @tool decorator
3039@tool("calculate", "Perform mathematical calculations", {"expression": str})
3040async def calculate(args: dict[str, Any]) -> dict[str, Any]:
3041 try:
3042 result = eval(args["expression"], {"__builtins__": {}})
3043 return {"content": [{"type": "text", "text": f"Result: {result}"}]}
3044 except Exception as e:
3045 return {
3046 "content": [{"type": "text", "text": f"Error: {str(e)}"}],
3047 "is_error": True,
3048 }
3049
3050
3051@tool("get_time", "Get current time", {})
3052async def get_time(args: dict[str, Any]) -> dict[str, Any]:
3053 from datetime import datetime
3054
3055 current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
3056 return {"content": [{"type": "text", "text": f"Current time: {current_time}"}]}
3057
3058
3059async def main():
3060 # Create SDK MCP server with custom tools
3061 my_server = create_sdk_mcp_server(
3062 name="utilities", version="1.0.0", tools=[calculate, get_time]
3063 )
3064
3065 # Configure options with the server
3066 options = ClaudeAgentOptions(
3067 mcp_servers={"utils": my_server},
3068 allowed_tools=["mcp__utils__calculate", "mcp__utils__get_time"],
3069 )
3070
3071 # Use ClaudeSDKClient for interactive tool usage
3072 async with ClaudeSDKClient(options=options) as client:
3073 await client.query("What's 123 * 456?")
3074
3075 # Process calculation response
3076 async for message in client.receive_response():
3077 if isinstance(message, AssistantMessage):
3078 for block in message.content:
3079 if isinstance(block, TextBlock):
3080 print(f"Calculation: {block.text}")
3081
3082 # Follow up with time query
3083 await client.query("What time is it now?")
3084
3085 async for message in client.receive_response():
3086 if isinstance(message, AssistantMessage):
3087 for block in message.content:
3088 if isinstance(block, TextBlock):
3089 print(f"Time: {block.text}")
3090
3091
3092asyncio.run(main())
3093```
3094
3095## ãµã³ãããã¯ã¹èšå®
3096
3097### `SandboxSettings`
3098
3099ãµã³ãããã¯ã¹åäœã®èšå®ãããã䜿çšããŠã³ãã³ããµã³ãããã¯ã¹ãæå¹ã«ãããããã¯ãŒã¯å¶éãããã°ã©ã ã§èšå®ããŸãã
3100
3101```python theme={null}
3102class SandboxSettings(TypedDict, total=False):
3103 enabled: bool
3104 autoAllowBashIfSandboxed: bool
3105 excludedCommands: list[str]
3106 allowUnsandboxedCommands: bool
3107 network: SandboxNetworkConfig
3108 ignoreViolations: SandboxIgnoreViolations
3109 enableWeakerNestedSandbox: bool
3110```
3111
3112| ãããã㣠| å | ããã©ã«ã | 説æ |
3113| :-------------------------- | :------------------------------------------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3114| `enabled` | `bool` | `False` | ã³ãã³ãå®è¡ã®ãµã³ãããã¯ã¹ã¢ãŒããæå¹ã«ããŸã |
3115| `autoAllowBashIfSandboxed` | `bool` | `True` | ãµã³ãããã¯ã¹ãæå¹ãªå Žåãbash ã³ãã³ããèªåæ¿èªããŸã |
3116| `excludedCommands` | `list[str]` | `[]` | åžžã«ãµã³ãããã¯ã¹å¶éããã€ãã¹ããã³ãã³ãïŒäŸïŒ`["docker"]`ïŒããããã¯ã¢ãã«ã®é¢äžãªãã«èªåçã«ãµã³ãããã¯ã¹ãªãã§å®è¡ãããŸã |
3117| `allowUnsandboxedCommands` | `bool` | `True` | ã¢ãã«ããµã³ãããã¯ã¹ã®å€ã§ã³ãã³ããå®è¡ããããã«ãªã¯ãšã¹ãããããšãèš±å¯ããŸãã`True` ã®å Žåãã¢ãã«ã¯ããŒã«å
¥å㧠`dangerouslyDisableSandbox` ãèšå®ã§ãã[ããŒããã·ã§ã³ã·ã¹ãã ](#permissions-fallback-for-unsandboxed-commands) ã«ãã©ãŒã«ããã¯ããŸã |
3118| `network` | [`SandboxNetworkConfig`](#sandbox-network-config) | `None` | ãããã¯ãŒã¯åºæã®ãµã³ãããã¯ã¹èšå® |
3119| `ignoreViolations` | [`SandboxIgnoreViolations`](#sandbox-ignore-violations) | `None` | ç¡èŠãããµã³ãããã¯ã¹éåãèšå®ããŸã |
3120| `enableWeakerNestedSandbox` | `bool` | `False` | äºææ§ã®ããã«ãã匱ããã¹ãããããµã³ãããã¯ã¹ãæå¹ã«ããŸã |
3121
3122#### 䜿çšäŸ
3123
3124```python theme={null}
3125from claude_agent_sdk import query, ClaudeAgentOptions, SandboxSettings
3126
3127sandbox_settings: SandboxSettings = {
3128 "enabled": True,
3129 "autoAllowBashIfSandboxed": True,
3130 "network": {"allowLocalBinding": True},
3131}
3132
3133async for message in query(
3134 prompt="Build and test my project",
3135 options=ClaudeAgentOptions(sandbox=sandbox_settings),
3136):
3137 print(message)
3138```
3139
3140<Warning>
3141 **Unix ãœã±ããã»ãã¥ãªãã£**ïŒ`allowUnixSockets` ãªãã·ã§ã³ã¯åŒ·åãªã·ã¹ãã ãµãŒãã¹ãžã®ã¢ã¯ã»ã¹ãèš±å¯ã§ããŸããäŸãã°ã`/var/run/docker.sock` ãèš±å¯ãããšãDocker API ãéããŠãã¹ãã·ã¹ãã ãžã®å®å
šãªã¢ã¯ã»ã¹ãå¹æçã«èš±å¯ããããµã³ãããã¯ã¹åé¢ããã€ãã¹ãããŸããå³å¯ã«å¿
èŠãª Unix ãœã±ããã®ã¿ãèš±å¯ããåãœã±ããã®ã»ãã¥ãªãã£ãžã®åœ±é¿ãç解ããŠãã ããã
3142</Warning>
3143
3144### `SandboxNetworkConfig`
3145
3146ãµã³ãããã¯ã¹ã¢ãŒãçšã®ãããã¯ãŒã¯åºæã®èšå®ã
3147
3148```python theme={null}
3149class SandboxNetworkConfig(TypedDict, total=False):
3150 allowedDomains: list[str]
3151 deniedDomains: list[str]
3152 allowManagedDomainsOnly: bool
3153 allowUnixSockets: list[str]
3154 allowAllUnixSockets: bool
3155 allowLocalBinding: bool
3156 allowMachLookup: list[str]
3157 httpProxyPort: int
3158 socksProxyPort: int
3159```
3160
3161| ãããã㣠| å | ããã©ã«ã | 説æ |
3162| :------------------------ | :---------- | :------ | :-------------------------------------------------------------------------------------------- |
3163| `allowedDomains` | `list[str]` | `[]` | ãµã³ãããã¯ã¹åãããããã»ã¹ãã¢ã¯ã»ã¹ã§ãããã¡ã€ã³å |
3164| `deniedDomains` | `list[str]` | `[]` | ãµã³ãããã¯ã¹åãããããã»ã¹ãã¢ã¯ã»ã¹ã§ããªããã¡ã€ã³åã`allowedDomains` ããåªå
ãããŸã |
3165| `allowManagedDomainsOnly` | `bool` | `False` | ãããŒãžãèšå®ã®ã¿ïŒãããŒãžãèšå®ã§èšå®ãããŠããå ŽåãéãããŒãžãèšå®ãœãŒã¹ããã® `allowedDomains` ãç¡èŠããŸããSDK ãªãã·ã§ã³ã§èšå®ãããå Žåã¯å¹æããããŸãã |
3166| `allowUnixSockets` | `list[str]` | `[]` | ããã»ã¹ãã¢ã¯ã»ã¹ã§ãã Unix ãœã±ãããã¹ïŒäŸïŒDocker ãœã±ããïŒ |
3167| `allowAllUnixSockets` | `bool` | `False` | ãã¹ãŠã® Unix ãœã±ãããžã®ã¢ã¯ã»ã¹ãèš±å¯ããŸã |
3168| `allowLocalBinding` | `bool` | `False` | ããã»ã¹ãããŒã«ã«ããŒãã«ãã€ã³ãããããšãèš±å¯ããŸãïŒäŸïŒdev ãµãŒããŒçšïŒ |
3169| `allowMachLookup` | `list[str]` | `[]` | macOS ã®ã¿ïŒèš±å¯ãã XPC/Mach ãµãŒãã¹åãæ«å°Ÿã®ã¯ã€ã«ãã«ãŒãããµããŒãããŸã |
3170| `httpProxyPort` | `int` | `None` | ãããã¯ãŒã¯ãªã¯ãšã¹ãçšã® HTTP ãããã·ããŒã |
3171| `socksProxyPort` | `int` | `None` | ãããã¯ãŒã¯ãªã¯ãšã¹ãçšã® SOCKS ãããã·ããŒã |
3172
3173<Note>
3174 çµã¿èŸŒã¿ãµã³ãããã¯ã¹ãããã·ã¯ããªã¯ãšã¹ãããããã¹ãåã«åºã¥ããŠãããã¯ãŒã¯èš±å¯ãªã¹ãã匷å¶ããTLS ãã©ãã£ãã¯ãçµäºãŸãã¯æ€æ»ããªãããã[ãã¡ã€ã³ããã³ãã£ã³ã°](https://en.wikipedia.org/wiki/Domain_fronting) ãªã©ã®æè¡ãããããã€ãã¹ããå¯èœæ§ããããŸãã詳现㯠[ãµã³ãããã¯ã¹ã»ãã¥ãªãã£ã®å¶éäºé
](/ja/sandboxing#security-limitations) ãåç
§ããTLS çµäºãããã·ã®èšå®ã«ã€ããŠã¯ [ã»ãã¥ã¢ãªãããã€](/ja/agent-sdk/secure-deployment#traffic-forwarding) ãåç
§ããŠãã ããã
3175</Note>
3176
3177### `SandboxIgnoreViolations`
3178
3179ç¹å®ã®ãµã³ãããã¯ã¹éåãç¡èŠããããã®èšå®ã
3180
3181```python theme={null}
3182class SandboxIgnoreViolations(TypedDict, total=False):
3183 file: list[str]
3184 network: list[str]
3185```
3186
3187| ãããã㣠| å | ããã©ã«ã | 説æ |
3188| :-------- | :---------- | :---- | :---------------- |
3189| `file` | `list[str]` | `[]` | éåãç¡èŠãããã¡ã€ã«ãã¹ãã¿ãŒã³ |
3190| `network` | `list[str]` | `[]` | éåãç¡èŠãããããã¯ãŒã¯ãã¿ãŒã³ |
3191
3192### ãµã³ãããã¯ã¹ãªãã³ãã³ãã®ããŒããã·ã§ã³ãã©ãŒã«ããã¯
3193
3194`allowUnsandboxedCommands` ãæå¹ãªå Žåãã¢ãã«ã¯ããŒã«å
¥å㧠`dangerouslyDisableSandbox: True` ãèšå®ããããšã§ãµã³ãããã¯ã¹ã®å€ã§ã³ãã³ããå®è¡ããããã«ãªã¯ãšã¹ãã§ããŸãããããã®ãªã¯ãšã¹ãã¯æ¢åã®ããŒããã·ã§ã³ã·ã¹ãã ã«ãã©ãŒã«ããã¯ããŸããã€ãŸãã`can_use_tool` ãã³ãã©ãŒãåŒã³åºãããã«ã¹ã¿ã èªå¯ããžãã¯ãå®è£
ã§ããŸãã
3195
3196<Note>
3197 **`excludedCommands` vs `allowUnsandboxedCommands`ïŒ**
3198
3199 * `excludedCommands`ïŒåžžã«ãµã³ãããã¯ã¹ãèªåçã«ãã€ãã¹ããã³ãã³ãã®éçãªã¹ãïŒäŸïŒ`["docker"]`ïŒãã¢ãã«ã¯ãããå¶åŸ¡ã§ããŸããã
3200 * `allowUnsandboxedCommands`ïŒã¢ãã«ãå®è¡æã«ããŒã«å
¥å㧠`dangerouslyDisableSandbox: True` ãèšå®ããããšã§ãµã³ãããã¯ã¹ãªãå®è¡ããªã¯ãšã¹ãããããšãèš±å¯ããŸãã
3201</Note>
3202
3203```python theme={null}
3204from claude_agent_sdk import (
3205 query,
3206 ClaudeAgentOptions,
3207 HookMatcher,
3208 PermissionResultAllow,
3209 PermissionResultDeny,
3210 ToolPermissionContext,
3211)
3212
3213
3214async def can_use_tool(
3215 tool: str, input: dict, context: ToolPermissionContext
3216) -> PermissionResultAllow | PermissionResultDeny:
3217 # Check if the model is requesting to bypass the sandbox
3218 if tool == "Bash" and input.get("dangerouslyDisableSandbox"):
3219 # The model is requesting to run this command outside the sandbox
3220 print(f"Unsandboxed command requested: {input.get('command')}")
3221
3222 if is_command_authorized(input.get("command")):
3223 return PermissionResultAllow()
3224 return PermissionResultDeny(
3225 message="Command not authorized for unsandboxed execution"
3226 )
3227 return PermissionResultAllow()
3228
3229
3230# Required: dummy hook keeps the stream open for can_use_tool
3231async def dummy_hook(input_data, tool_use_id, context):
3232 return {"continue_": True}
3233
3234
3235async def prompt_stream():
3236 yield {
3237 "type": "user",
3238 "message": {"role": "user", "content": "Deploy my application"},
3239 }
3240
3241
3242async def main():
3243 async for message in query(
3244 prompt=prompt_stream(),
3245 options=ClaudeAgentOptions(
3246 sandbox={
3247 "enabled": True,
3248 "allowUnsandboxedCommands": True, # Model can request unsandboxed execution
3249 },
3250 permission_mode="default",
3251 can_use_tool=can_use_tool,
3252 hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},
3253 ),
3254 ):
3255 print(message)
3256```
3257
3258ãã®ãã¿ãŒã³ã«ããã以äžãå¯èœã«ãªããŸãïŒ
3259
3260* **ã¢ãã«ãªã¯ãšã¹ããç£æ»ãã**ïŒã¢ãã«ããµã³ãããã¯ã¹ãªãå®è¡ããªã¯ãšã¹ããããšãããã°ããŸã
3261* **èš±å¯ãªã¹ããå®è£
ãã**ïŒç¹å®ã®ã³ãã³ãã®ã¿ããµã³ãããã¯ã¹ãªãã§å®è¡ãããããšãèš±å¯ããŸã
3262* **æ¿èªã¯ãŒã¯ãããŒãè¿œå ãã**ïŒç¹æš©æäœã«æ瀺çãªèªå¯ãèŠæ±ããŸã
3263
3264<Warning>
3265 `dangerouslyDisableSandbox: True` ã§å®è¡ãããã³ãã³ãã¯ã·ã¹ãã ãžã®å®å
šãªã¢ã¯ã»ã¹ãæã¡ãŸãã`can_use_tool` ãã³ãã©ãŒããããã®ãªã¯ãšã¹ããæ
éã«æ€èšŒããããšã確èªããŠãã ããã
3266
3267 `permission_mode` ã `bypassPermissions` ã«èšå®ããã`allow_unsandboxed_commands` ãæå¹ãªå Žåãã¢ãã«ã¯æ¿èªããã³ãããªãã«ãµã³ãããã¯ã¹ã®å€ã§ã³ãã³ããèªåŸçã«å®è¡ã§ããŸãããã®çµã¿åããã¯ãã¢ãã«ããµã³ãããã¯ã¹åé¢ããµã€ã¬ã³ãã«éããããšãå¹æçã«èš±å¯ããŸãã
3268</Warning>
3269
3270## é¢é£é
ç®
3271
3272* [SDK æŠèŠ](/ja/agent-sdk/overview) - äžè¬ç㪠SDK æŠå¿µ
3273* [TypeScript SDK ãªãã¡ã¬ã³ã¹](/ja/agent-sdk/typescript) - TypeScript SDK ããã¥ã¡ã³ã
3274* [CLI ãªãã¡ã¬ã³ã¹](/ja/cli-reference) - ã³ãã³ãã©ã€ã³ã€ã³ã¿ãŒãã§ãŒã¹
3275* [äžè¬çãªã¯ãŒã¯ãããŒ](/ja/common-workflows) - ã¹ããããã€ã¹ãããã¬ã€ã
