anthropics / anthropics/claude-agent-sdk-typescript
Feature: Include Anthropic API citations in ACP agent_message_chunk events via _meta
- Lingua principale
- Shell
- Stelle
- 1.8k
- Fork
- 226
- Metriche di merge delle PR
- Nessuna PR unita negli ultimi 30g
Descrizione
## Problem
When Claude uses the `web_search` tool, the Anthropic Messages API returns per-claim citation metadata on text blocks:
```json
{
"type": "text",
"text": "Global temperatures rose 1.2°C since pre-industrial levels",
"citations": [
{
"type": "web_search_result_location",
"url": "https://nasa.gov/climate-data",
"title": "NASA Climate Report",
"cited_text": "global mean temperatures have increased by 1.2 degrees Celsius..."
}
]
}
```
However, when the Claude Code binary emits ACP `session/update` notifications with `sessionUpdate: "agent_message_chunk"`, the `citations` array is dropped. The ACP `TextContent` only contains `{ type: "text", text: "..." }`.
This means any application consuming agent events through the Agent SDK or sandbox-agent **cannot access per-claim source attribution** from web search, even though the underlying API provides it.
## Impact
This is a significant limitation for RAG and research applications. Without structured citations, applications must rely on prompt engineering to get the agent to manually attribute sources — which has significant misattribution rates in practice (agent cites the wrong URL for a claim because it loses track after multiple web searches).
## Proposed Solution
The ACP `TextContent` type already has a `_meta` field (`Record`) designed for arbitrary metadata. When the Claude Code binary converts Anthropic API text blocks to ACP content blocks, include citations in `_meta`:
```json
{
"sessionUpdate": "agent_message_chunk",
"content": {
"type": "text",
"text": "Global temperatures rose 1.2°C since pre-industrial levels",
"_meta": {
"citations": [
{
"type": "web_search_result_location",
"url": "https://nasa.gov/climate-data",
"title": "NASA Climate Report",
"cited_text": "global mean temperatures have increased by 1.2 degrees Celsius..."
}
]
}
}
}
```
This is fully backwards compatible — consumers that don't check `_meta` are unaffected.
## Alternatives Considered
- **MCP wrapper tool**: We built an MCP server that calls the Claude API internally with `web_search`, extracts citations from the response, and returns structured `{claim, url}` tuples. This works but adds latency and cost (extra API call per search).
- **Prompt engineering**: Instructing agents to manually cite sources. Unreliable (significant error rate) because WebSearch returns blended summaries from multiple sources without per-source attribution.
Both are workarounds for metadata that the API already provides but the ACP layer drops.
## Environment
- Agent SDK: `@anthropic-ai/claude-agent-sdk`
- Also affects sandbox-agent consumers (sandbox-agent is a passthrough — it relays ACP events as-is from Claude Code's stdout)
- The `StreamEvent` in the Agent SDK wraps raw Claude API events which **do** include citations when using `includePartialMessages: true`, but the `AssistantMessage` (complete message) does not expose them
Guida per i contributori
Nessuna guida per i contributori indicizzata per questo repository
Valutazione
Questa issue non è ancora stata valutata.