Add comprehensive documentation for Claude Code hooks and streaming input modes
- Introduced a detailed reference for implementing hooks in Claude Code, covering configuration, project-specific scripts, plugin hooks, and various hook events. - Explained the input modes available in the Claude Agent SDK, emphasizing the benefits of streaming input mode and providing implementation examples for both streaming and single message input. - Highlighted security considerations and best practices for writing hooks, along with debugging tips and execution details.
This commit is contained in:
Alex Newman
@@ -0,0 +1,295 @@
|
||||
# Streaming Input
|
||||
|
||||
> Understanding the two input modes for Claude Agent SDK and when to use each
|
||||
|
||||
## Overview
|
||||
|
||||
The Claude Agent SDK supports two distinct input modes for interacting with agents:
|
||||
|
||||
* **Streaming Input Mode** (Default & Recommended) - A persistent, interactive session
|
||||
* **Single Message Input** - One-shot queries that use session state and resuming
|
||||
|
||||
This guide explains the differences, benefits, and use cases for each mode to help you choose the right approach for your application.
|
||||
|
||||
## Streaming Input Mode (Recommended)
|
||||
|
||||
Streaming input mode is the **preferred** way to use the Claude Agent SDK. It provides full access to the agent's capabilities and enables rich, interactive experiences.
|
||||
|
||||
It allows the agent to operate as a long lived process that takes in user input, handles interruptions, surfaces permission requests, and handles session management.
|
||||
|
||||
### How It Works
|
||||
|
||||
```mermaid theme={null}
|
||||
%%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D", "primaryColor": "#F0F0EB", "primaryTextColor": "#191919", "primaryBorderColor": "#D9D8D5", "secondaryColor": "#F5E6D8", "tertiaryColor": "#CC785C", "noteBkgColor": "#FAF0E6", "noteBorderColor": "#91918D"}, "sequence": {"actorMargin": 50, "width": 150, "height": 65, "boxMargin": 10, "boxTextMargin": 5, "noteMargin": 10, "messageMargin": 35}}}%%
|
||||
sequenceDiagram
|
||||
participant App as Your Application
|
||||
participant Agent as Claude Agent
|
||||
participant Tools as Tools/Hooks
|
||||
participant FS as Environment/<br/>File System
|
||||
|
||||
App->>Agent: Initialize with AsyncGenerator
|
||||
activate Agent
|
||||
|
||||
App->>Agent: Yield Message 1
|
||||
Agent->>Tools: Execute tools
|
||||
Tools->>FS: Read files
|
||||
FS-->>Tools: File contents
|
||||
Tools->>FS: Write/Edit files
|
||||
FS-->>Tools: Success/Error
|
||||
Agent-->>App: Stream partial response
|
||||
Agent-->>App: Stream more content...
|
||||
Agent->>App: Complete Message 1
|
||||
|
||||
App->>Agent: Yield Message 2 + Image
|
||||
Agent->>Tools: Process image & execute
|
||||
Tools->>FS: Access filesystem
|
||||
FS-->>Tools: Operation results
|
||||
Agent-->>App: Stream response 2
|
||||
|
||||
App->>Agent: Queue Message 3
|
||||
App->>Agent: Interrupt/Cancel
|
||||
Agent->>App: Handle interruption
|
||||
|
||||
Note over App,Agent: Session stays alive
|
||||
Note over Tools,FS: Persistent file system<br/>state maintained
|
||||
|
||||
deactivate Agent
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Image Uploads" icon="image">
|
||||
Attach images directly to messages for visual analysis and understanding
|
||||
</Card>
|
||||
|
||||
<Card title="Queued Messages" icon="layer-group">
|
||||
Send multiple messages that process sequentially, with ability to interrupt
|
||||
</Card>
|
||||
|
||||
<Card title="Tool Integration" icon="wrench">
|
||||
Full access to all tools and custom MCP servers during the session
|
||||
</Card>
|
||||
|
||||
<Card title="Hooks Support" icon="link">
|
||||
Use lifecycle hooks to customize behavior at various points
|
||||
</Card>
|
||||
|
||||
<Card title="Real-time Feedback" icon="bolt">
|
||||
See responses as they're generated, not just final results
|
||||
</Card>
|
||||
|
||||
<Card title="Context Persistence" icon="database">
|
||||
Maintain conversation context across multiple turns naturally
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### Implementation Example
|
||||
|
||||
<CodeGroup>
|
||||
```typescript TypeScript theme={null}
|
||||
import { query } from "@anthropic-ai/claude-agent-sdk";
|
||||
import { readFileSync } from "fs";
|
||||
|
||||
async function* generateMessages() {
|
||||
// First message
|
||||
yield {
|
||||
type: "user" as const,
|
||||
message: {
|
||||
role: "user" as const,
|
||||
content: "Analyze this codebase for security issues"
|
||||
}
|
||||
};
|
||||
|
||||
// Wait for conditions or user input
|
||||
await new Promise(resolve => setTimeout(resolve, 2000));
|
||||
|
||||
// Follow-up with image
|
||||
yield {
|
||||
type: "user" as const,
|
||||
message: {
|
||||
role: "user" as const,
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: "Review this architecture diagram"
|
||||
},
|
||||
{
|
||||
type: "image",
|
||||
source: {
|
||||
type: "base64",
|
||||
media_type: "image/png",
|
||||
data: readFileSync("diagram.png", "base64")
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
// Process streaming responses
|
||||
for await (const message of query({
|
||||
prompt: generateMessages(),
|
||||
options: {
|
||||
maxTurns: 10,
|
||||
allowedTools: ["Read", "Grep"]
|
||||
}
|
||||
})) {
|
||||
if (message.type === "result") {
|
||||
console.log(message.result);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```python Python theme={null}
|
||||
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock
|
||||
import asyncio
|
||||
import base64
|
||||
|
||||
async def streaming_analysis():
|
||||
async def message_generator():
|
||||
# First message
|
||||
yield {
|
||||
"type": "user",
|
||||
"message": {
|
||||
"role": "user",
|
||||
"content": "Analyze this codebase for security issues"
|
||||
}
|
||||
}
|
||||
|
||||
# Wait for conditions
|
||||
await asyncio.sleep(2)
|
||||
|
||||
# Follow-up with image
|
||||
with open("diagram.png", "rb") as f:
|
||||
image_data = base64.b64encode(f.read()).decode()
|
||||
|
||||
yield {
|
||||
"type": "user",
|
||||
"message": {
|
||||
"role": "user",
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Review this architecture diagram"
|
||||
},
|
||||
{
|
||||
"type": "image",
|
||||
"source": {
|
||||
"type": "base64",
|
||||
"media_type": "image/png",
|
||||
"data": image_data
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
# Use ClaudeSDKClient for streaming input
|
||||
options = ClaudeAgentOptions(
|
||||
max_turns=10,
|
||||
allowed_tools=["Read", "Grep"]
|
||||
)
|
||||
|
||||
async with ClaudeSDKClient(options) as client:
|
||||
# Send streaming input
|
||||
await client.query(message_generator())
|
||||
|
||||
# Process responses
|
||||
async for message in client.receive_response():
|
||||
if isinstance(message, AssistantMessage):
|
||||
for block in message.content:
|
||||
if isinstance(block, TextBlock):
|
||||
print(block.text)
|
||||
|
||||
asyncio.run(streaming_analysis())
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## Single Message Input
|
||||
|
||||
Single message input is simpler but more limited.
|
||||
|
||||
### When to Use Single Message Input
|
||||
|
||||
Use single message input when:
|
||||
|
||||
* You need a one-shot response
|
||||
* You do not need image attachments, hooks, etc.
|
||||
* You need to operate in a stateless environment, such as a lambda function
|
||||
|
||||
### Limitations
|
||||
|
||||
<Warning>
|
||||
Single message input mode does **not** support:
|
||||
|
||||
* Direct image attachments in messages
|
||||
* Dynamic message queueing
|
||||
* Real-time interruption
|
||||
* Hook integration
|
||||
* Natural multi-turn conversations
|
||||
</Warning>
|
||||
|
||||
### Implementation Example
|
||||
|
||||
<CodeGroup>
|
||||
```typescript TypeScript theme={null}
|
||||
import { query } from "@anthropic-ai/claude-agent-sdk";
|
||||
|
||||
// Simple one-shot query
|
||||
for await (const message of query({
|
||||
prompt: "Explain the authentication flow",
|
||||
options: {
|
||||
maxTurns: 1,
|
||||
allowedTools: ["Read", "Grep"]
|
||||
}
|
||||
})) {
|
||||
if (message.type === "result") {
|
||||
console.log(message.result);
|
||||
}
|
||||
}
|
||||
|
||||
// Continue conversation with session management
|
||||
for await (const message of query({
|
||||
prompt: "Now explain the authorization process",
|
||||
options: {
|
||||
continue: true,
|
||||
maxTurns: 1
|
||||
}
|
||||
})) {
|
||||
if (message.type === "result") {
|
||||
console.log(message.result);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```python Python theme={null}
|
||||
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
|
||||
import asyncio
|
||||
|
||||
async def single_message_example():
|
||||
# Simple one-shot query using query() function
|
||||
async for message in query(
|
||||
prompt="Explain the authentication flow",
|
||||
options=ClaudeAgentOptions(
|
||||
max_turns=1,
|
||||
allowed_tools=["Read", "Grep"]
|
||||
)
|
||||
):
|
||||
if isinstance(message, ResultMessage):
|
||||
print(message.result)
|
||||
|
||||
# Continue conversation with session management
|
||||
async for message in query(
|
||||
prompt="Now explain the authorization process",
|
||||
options=ClaudeAgentOptions(
|
||||
continue_conversation=True,
|
||||
max_turns=1
|
||||
)
|
||||
):
|
||||
if isinstance(message, ResultMessage):
|
||||
print(message.result)
|
||||
|
||||
asyncio.run(single_message_example())
|
||||
```
|
||||
</CodeGroup>
|
||||
Reference in New Issue
Block a user