anthropics / anthropics/claude-agent-sdk-python

query() documentation incorrectly promises send-all-then-receive streaming semantics

Aberta
#1,169 0 comentários 0 reações 0 responsáveis Ver no GitHub
Linguagem predominante
Python
Estrelas
8.1k
Forks
1.3k
Métricas de merge de PRs
Métricas de PR pendentes

Descrição

### Summary

The public documentation says that async-iterable `query()` sends every prompt before receiving any response, but the implementation streams input and output concurrently. The README also implies that custom tools and hooks are unavailable through `query()`, although its initialization path supports both.

### Affected code and docs

- `src/claude_agent_sdk/query.py:18-28`
- `src/claude_agent_sdk/query.py:90-99`
- `src/claude_agent_sdk/_internal/client.py:203-229`
- `README.md:85-96`

### Documented behavior

The docstring calls the API unidirectional and says:

- "Send all messages upfront, receive all responses"
- "All prompts are sent, then all responses received"

The README says that, unlike `query()`, `ClaudeSDKClient` additionally enables custom tools and hooks.

### Actual behavior

For an AsyncIterable prompt, `InternalClient` starts `query.stream_input(prompt)` as a background task and immediately enters `query.receive_messages()`. The CLI can therefore produce responses while the input iterable is still running.

The same InternalClient also extracts SDK MCP servers and hooks and sends them during initialization, so they are usable through `query()` when streaming mode requirements are met.

### Why this matters

Users may:

- write producers that assume no response processing occurs until input exhaustion;
- choose the more stateful client solely to access hooks or custom tools;
- misunderstand backpressure and exception timing;
- incorrectly describe the API in downstream libraries.

### Expected behavior

Documentation should describe async-iterable `query()` as a single-call streaming lifecycle where input and output may interleave, while clarifying that callers cannot send new messages in response through the same iterator after their producer design has committed its flow.

### Possible fix

Update the comparison and example, document supported hooks/tools and their streaming requirements, and add an ordering test demonstrating that a response may arrive before the prompt iterable completes.

### Environment

- Repository revision: current `main` audit at SDK version 0.2.128
- Bundled CLI version: 2.1.220
- Python test suite: 1,291 passed, 5 skipped
- Ruff and mypy: clean

I searched the existing issues and pull requests using the affected symbols and behavior before filing this.

Guia de contribuição

Nenhum guia de contribuição indexado para este repositório

Avaliação

Esta issue ainda não foi avaliada.

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.