aws / aws/bedrock-agentcore-sdk-python
[Feature Request] Bearer-token HTTP client for runtime invocation and InvokeAgentRuntimeCommand
- Ngôn ngữ chính
- Python
- Star
- 764
- Fork
- 148
- Merge trung bình
- 1 ngày 23 giờ
- Pull request đã merge (30 ngày)
- 7
Mô tả
## Problem
The SDK currently ships `bedrock_agentcore.runtime.AgentCoreRuntimeClient`, which generates **WebSocket URLs and headers** (SigV4, SigV4 presigned, and OAuth bearer variants) but does not itself invoke the runtime over HTTP. There is no first-class client in the SDK for:
1. Calling `POST /runtimes/{arn}/invocations` with a bearer token (JWT/OAuth) and handling both JSON and SSE (`text/event-stream`) responses.
2. Calling `POST /runtimes/{arn}/commands` — the [`InvokeAgentRuntimeCommand`](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-execute-command.html) API — and parsing its AWS EventStream (`application/vnd.amazon.eventstream`) response.
3. Calling `POST /runtimes/{arn}/stopruntimesession`.
Today, callers authenticating via Cognito / OAuth client credentials have to hand-roll `urllib3` / `requests` and a `botocore.eventstream.EventStreamBuffer` loop, duplicating logic across teams.
## Use cases
- Python apps that authenticate end users via Cognito and need to invoke a deployed agent runtime without passing IAM credentials around.
- Automated tests that want to exec shell commands inside an AgentCore container via `InvokeAgentRuntimeCommand`.
- FastAPI / MCP servers that need to stream tokens from a runtime to a browser (async-for over SSE chunks).
## Proposed solution
Extend the existing `AgentCoreRuntimeClient` with HTTP invocation methods, keeping everything on a single client:
- `invoke` (blocking, JSON or SSE)
- `invoke_streaming` (sync generator over SSE chunks)
- `invoke_streaming_async` (async generator; thread-pumped for use in async frameworks)
- `execute_command` (blocking, accumulates `stdout` / `stderr` / `exitCode` / `status`)
- `execute_command_streaming` (yields parsed EventStream events)
- `stop_runtime_session`
- `AgentRuntimeError` exception type
Design constraints:
- **Per-call bearer auth**, matching the shape of the existing `generate_ws_connection_oauth`. Each method takes `(runtime_arn, bearer_token, ...)` so the same client can be reused across rotating credentials.
- **Lazy `urllib3.PoolManager`.** The pool is constructed on first HTTP call via a `@property`, so callers that only use the existing SigV4 URL-generation methods pay zero cost.
- **Reuse existing helpers.** URL construction uses `_parse_runtime_arn` (already on the class) and `get_data_plane_endpoint` from `bedrock_agentcore._utils.endpoints`.
- **urllib3** (already an SDK dep) and **`botocore.eventstream.EventStreamBuffer`** (transitive through `boto3`) — no new top-level dependencies.
## Proof of concept
Implementation in #422 with 72 new unit tests, 96% branch coverage on the modified class, and the full upstream suite still passing (1505 / 0 failed).
## Alternatives considered
- **Users write their own** — works today, but the EventStream framing is tricky enough that most implementations I've seen have subtle bugs around chunk boundaries and the `chunk` envelope.
- **Sibling class `AgentCoreRuntimeHttpClient`** — initial approach in an earlier revision of #422. Kept responsibilities cleaner (URL generator vs. network client) but required a second import and discovery point. Reviewer feedback preferred a single-client shape, which the current PR delivers.
Hướng dẫn đóng góp
Hướng nghiên cứu
Start with bedrock_agentcore.runtime.AgentCoreRuntimeClient and its existing _parse_runtime_arn and get_data_plane_endpoint helpers. Review implementation in pull request #422, including its 72 unit tests, then verify the proposed invocation, streaming, command, and session-stop behavior against the stated JSON, SSE, and AWS EventStream responses and the full suite.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- aws, python
- Lĩnh vực
- api, backend, cloud
- Loại issue
- Tính năng
- Độ khó
- 4/5
- Thời gian dự kiến
- 3-5 ngày
- Mức độ hoạt động
- Đình trệ
- Độ rõ ràng
- Khá rõ ràng
- Mức phù hợp với người mới
- 25/100