aws / aws/bedrock-agentcore-sdk-python

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

Abierto
#423 2 comentarios 0 reacciones 0 asignados Ver en GitHub
Lenguaje dominante
Python
Estrellas
761
Forks
147
Merge medio
1 d 23 h
PR fusionados (30 d)
7

Descripción

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

Guía de contribución

Abrir la guía de contribución

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
aws, python
Área
api, backend, cloud
Tipo de issue
Nueva funcionalidad
Dificultad
4/5
Tiempo estimado
3-5 días
Estado de actividad
Estancado
Claridad
Bastante claro
Aptitud para principiantes
25/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.