anthropics / anthropics/claude-agent-sdk-typescript

Feature: Include Anthropic API citations in ACP agent_message_chunk events via _meta

Aperta
#254 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
enhancement
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.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.