aws / aws/bedrock-agentcore-sdk-python

[Feature Request] Bearer-token HTTP client for runtime invocation and InvokeAgentRuntimeCommand

オープン
#423 コメント 2 件 リアクション 0 件 担当者 0 名 GitHub で見る
主要言語
Python
スター
761
フォーク
147
平均マージ
1日 23時間
マージ済み PR(30日)
7

説明

## 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.

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

評価

技術スタック
aws, python
領域
api, backend, cloud
issue の種類
機能追加
難易度
4/5
見積もり時間
3〜5日
活発さ
停滞
明瞭さ
おおむね明確
初心者へのやさしさ
25/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。