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

Open
#423 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
25/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
aws, python
Domain
api, backend, cloud

Research direction

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.

Written by the indexing model from the issue text.

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 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.
Dominant language
Python
Stars
764
Forks
149
Avg merge
1d 19h
Merged PRs (30d)
7

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from aws/bedrock-agentcore-sdk-python

All issues in aws/bedrock-agentcore-sdk-python

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.