bedrock-agentcore-sdk-python: deploy a local AI agent with the AgentCore Runtime SDK

The gap between a working local agent and a deployed one

A local agent loop is short: build the prompt, call the model, dispatch tool calls, repeat. Everything around that loop is not short. You need a process that stays up, a request handler that survives concurrency, session isolation so two users do not share state, tracing that reaches your observability backend, and an identity path for the tools the agent calls. Teams usually rebuild that layer once per agent, in whatever framework they happened to pick.

bedrock-agentcore-sdk-python targets that layer. The README frames it as a way to "Deploy your local AI agent to Bedrock AgentCore with zero infrastructure", and the primitives it ships are runtime, memory, authentication and tools. The intended reader is a Python developer who already has agent logic and does not want to write the serving and hosting code around it. The framework is deliberately not part of the deal: the README lists Strands, LangGraph, CrewAI, Autogen and custom frameworks as supported, and the sample handler imports Strands only as an illustration.

The trade-off is visible immediately. You keep your agent code and hand over the deployment substrate to AWS. That is a reasonable exchange for a team already inside an AWS account, and a poor one for a team that wants the same agent to run on a laptop and on someone else's cloud without a rewrite.

How the entrypoint decorator and app.run() fit together

The mechanism is a small wrapper around an ASGI server. You construct a BedrockAgentCoreApp, decorate one async function with @app.entrypoint, and call app.run(). The decorator registers that function as the handler for incoming invocations, and app.run() starts the server. The dependencies in pyproject.toml confirm the shape: starlette and uvicorn for the HTTP layer, websockets for the WebSocket path, boto3 and botocore for the AWS calls underneath.

The handler is an async generator. In the README example it yields each event from agent.stream_async(prompt), which means the runtime streams partial output rather than buffering a full response. The README also carries an explicit input contract: validate that the incoming prompt is a string and raise ValueError otherwise, and "pass only prompt text to the agent". That is a deliberate boundary. The SDK does not sanitise or type-check your payload for you, so the handler is where untrusted input meets your agent framework.

AG-UI support reuses the same decorator idea. According to the README, a single entrypoint handler is served over both SSE at POST /invocations and WebSocket at /ws, so one handler covers two transports. The AGUIApp class takes an entrypoint that receives a RunAgentInput and yields AG-UI events such as RunStartedEvent and RunFinishedEvent. There is also a one-line form, serve_ag_ui(agui_agent), for a framework agent that already exposes a .run() method.

The A2A path is described more briefly: it serves an agent over the A2A protocol on AgentCore Runtime and works with any framework that provides an a2a-sdk AgentExecutor. The README names Strands, LangGraph and Google ADK as examples. What the README does not document is rollback behaviour, retry semantics or what happens to in-flight sessions when a deployment is replaced. Those questions belong to the AWS devguide, not to this repository.

Installing the SDK and serving a first agent

The package is published as bedrock-agentcore on PyPI, and pyproject.toml sets requires-python to >=3.10, so confirm your interpreter before anything else. The base install pulls in boto3, botocore, pydantic, starlette, uvicorn and websockets. Install it with pip:

pip install bedrock-agentcore

The AG-UI transport lives behind an extra, which the README gives as:

pip install "bedrock-agentcore[ag-ui]"

With the package installed, a minimal application is the README's own example. It creates the app, registers an async handler that validates the prompt and streams events from a Strands agent, then starts the server:

from bedrock_agentcore import BedrockAgentCoreApp
app = BedrockAgentCoreApp()

from strands import Agent

@app.entrypoint
async def handler(request):
    prompt = request.get("prompt")
    if not isinstance(prompt, str):
        raise ValueError("prompt must be a string")

    agent = Agent()

    async for event in agent.stream_async(prompt):
        yield (event)

app.run()

Run that file and you have a local server exposing your agent. What you should see is the process staying up and streaming events per request rather than returning one buffered payload.

Deployment is a separate tool. The README recommends the AgentCore CLI, installed through npm rather than pip:

npm i -g @aws/agentcore
agentcore create --name MyAgent --defaults
cd MyAgent
agentcore deploy

The README states that the CLI handles packaging, infrastructure provisioning and deployment. It also states that the CLI generates AWS CDK under the hood, which matters if you intend to customise the stack later.

The pydantic ceiling and the AWS-shaped footprint

The most concrete constraint is in pyproject.toml: pydantic is pinned to >=2.0.0,<2.41.3. If another library in your agent stack requires a newer pydantic, pip will either refuse to resolve or silently pick an older version of something else. This is a normal consequence of a library that sits close to the request boundary, but it is the kind of pin that surfaces late, during a dependency upgrade, rather than during evaluation.

The second constraint is architectural. The README describes AgentCore as AWS-managed infrastructure and lists Runtime, Memory, Gateway, Code Interpreter, Browser, Observability and Identity as the services involved. Nothing in the README describes a local emulator for those services, so the deployed form of your agent depends on an AWS account and on the AgentCore control plane. The SDK itself is Apache-2.0 and the code is on GitHub, but the platform it targets is not something you can run on your own hardware.

A third point is worth stating plainly: the project classifies itself as "Development Status :: 3 - Alpha" in pyproject.toml. The release cadence is brisk, with v1.20.0, v1.21.0 and v1.22.0 all appearing in August 2026 and the repository receiving its most recent push on 2026-09-09. Fast releases are not the same as instability, but they do mean the API surface you read about today may shift, and the CHANGELOG.md at the repository root is the place to check before upgrading a deployed agent.

Where this is the wrong tool: if your agent must run on-premises, in a non-AWS cloud, or inside a build pipeline with no AWS credentials, the runtime half of the SDK has nothing to offer you. You could still use the framework-agnostic primitives, but you would be adopting a dependency whose main value is the part you cannot use.

AgentCore Runtime versus a self-hosted agent server

The obvious alternative is to skip the SDK and serve the agent yourself. FastAPI or plain Starlette plus uvicorn gives you the same HTTP surface, and you keep control of session storage, scaling and tracing. The difference in approach is where the hard parts live. With a self-hosted server, session isolation, autoscaling, identity for tool calls and OpenTelemetry export are your code and your operational burden. With AgentCore, the README positions them as platform services you configure rather than build.

The second alternative is a managed agent platform from a different vendor. Those typically require you to adopt their agent abstraction, which is the opposite of what this SDK does: the README's first bullet is "Keep your agent logic", and the handler example imports Strands only to show that any framework can sit behind the decorator. If your agent is written against a specific vendor's runtime objects, porting it to AgentCore is the smaller problem; porting it away from AgentCore later is the larger one.

The third comparison is within AWS. The README lists a Boto3 Python SDK for bedrock-agentcore-control alongside this Runtime SDK. The control-plane client is for provisioning and managing AgentCore resources; this package is for writing the agent that runs on them. Teams that only need to create and configure resources do not need this SDK, and teams that only need to serve an agent may find the CLI plus the runtime decorator sufficient without touching the control-plane client directly.

Licence, maintenance and what an upgrade costs

The project is licensed Apache-2.0, and the repository carries both LICENSE.txt and NOTICE.txt. Apache-2.0 permits commercial use and modification and includes a patent grant, but it also requires that you preserve the licence and notice files and state significant changes. That is a packaging obligation rather than a legal opinion, and if you redistribute the SDK inside a product, the NOTICE file is the artifact to check with whoever handles your compliance review.

Maintenance signals are mixed but readable. The repository is not archived, and the last push was on 2026-09-09, which is recent. Releases arrive in small increments: v1.20.0 on 2026-08-04, v1.21.0 on 2026-08-06, v1.22.0 on 2026-08-18. The pyproject.toml version is 1.23.0, ahead of the most recent tagged release, which is normal for a main branch between releases.

The upgrade cost is dominated by two things. First, the dependency pins: a pydantic ceiling of <2.41.3 means an upgrade of this SDK can force a downgrade elsewhere, so read the diff of pyproject.toml between tags rather than only the changelog prose. Second, the alpha classifier means the maintainers have not promised API stability. The repository ships TESTING.md, tests/ and tests_integ/ directories, and a .pre-commit-config.yaml, so there is a testing story, but the README does not describe a deprecation policy for the entrypoint decorator or the AGUIApp class.

Editorial conclusion

Adopt bedrock-agentcore-sdk-python if your agent already runs on AWS and you want AgentCore Runtime, Memory and Gateway without writing your own serving layer. Do not adopt it if you need a vendor-neutral runtime or cannot accept a Python 3.10 floor and a pinned pydantic ceiling. Before you commit, confirm that the AgentCore CLI generates a CDK stack you are willing to own, and check the AG-UI and A2A extras against the protocol contracts in the AWS devguide, because the README shows the entrypoint shape but not the failure behaviour.

Frequently asked questions

Official sources

1. aws/bedrock-agentcore-sdk-python on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases