aws / aws/bedrock-agentcore-sdk-python

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

Open
#423 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
761
Forks
147
Avg merge
1d 23h
Merged PRs (30d)
7

Description

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.