anthropics / anthropics/claude-agent-sdk-python
query() documentation incorrectly promises send-all-then-receive streaming semantics
- 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.