Install & Compatibility
Where this runs
tested against v1.22.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.156s · 70.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.2s · import 1.046s · 70MB
59MB installed
● package 59MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BedrockAgentCoreApp
✓ from bedrock_agentcore import BedrockAgentCoreApp
✗ from bedrock_agentcore.agent import BedrockAgentCoreApp
BedrockAgentCoreContext
✓ from bedrock_agentcore import BedrockAgentCoreContext
config_bundle
✓ from bedrock_agentcore import config_bundle
This quickstart demonstrates how to define a simple AI agent using the `bedrock-agentcore` SDK. It initializes a `BedrockAgentCoreApp` and registers a handler function with the `@entrypoint` decorator. The agent echoes back the received prompt. The `app.run()` method allows for local testing by starting an HTTP server. Remember to set your AWS region and configure AWS credentials for local execution.
import os
from bedrock_agentcore.agent import BedrockAgentCoreApp, entrypoint
# Initialize the AgentCore application
app = BedrockAgentCoreApp(
region_name=os.environ.get('AWS_REGION', 'us-east-1')
)
# Define your agent's entrypoint
@app.entrypoint()
def handler(event):
"""Handles incoming agent invocations."""
prompt = event.prompt
# In a real agent, you would process the prompt, use tools, or interact with memory.
response_content = f"Hello from your AgentCore agent! You said: {prompt}"
# The response must be a dictionary with a 'response' key for simple text responses
return {"response": response_content}
# To run the agent locally (for development and testing)
# Make sure to set AWS_REGION and have AWS credentials configured.
# The `app.run()` method starts a local HTTP server on port 8080.
# You can test it with `curl -X POST http://localhost:8080/invocations -H "Content-Type: application/json" -d '{"prompt": "What's up?"}'`
if __name__ == "__main__":
print("Starting Bedrock AgentCore agent locally. Access at http://localhost:8080/invocations")
print("Ensure AWS_REGION environment variable is set and AWS credentials are configured.")
app.run()
Debug
Known issues
breakingVersion 1.5.1 reverted the feature to emit OTEL (OpenTelemetry) attributes for AgentCore Evaluation support. If your application relies on these specific OTEL attributes for observability, this change will break that integration.fixReview your observability setup if you were leveraging OTEL attributes from AgentCore Evaluation. You may need to adjust your tracing configuration or find alternative metrics.
affects: 1.5.1
gotchaAccessDeniedException is a common issue due to insufficient IAM permissions for the caller or the agent's execution role. This can occur during agent creation or runtime invocation.fixEnsure your AWS identity has `bedrock-agentcore:CreateAgentRuntime` and other necessary permissions. Verify the agent's execution role grants required permissions to interact with Bedrock services and any tools it uses. Consult AWS IAM documentation for Bedrock AgentCore specific policies.
affects: All versions
gotchaUsing outdated `boto3` or `botocore` libraries can lead to `Unknown service: 'bedrock-agent-core-runtime'` errors when attempting to interact with Bedrock AgentCore APIs.fixRegularly update `boto3` and `botocore` to their latest versions: `pip install --upgrade boto3 botocore`. Ensure both are at or above the minimum required versions (boto3 1.39.8+, botocore 1.33.8+).
affects: <1.39.8 (boto3) or <1.33.8 (botocore)
gotchaThe AWS region resolution order can be complex. If not explicitly passed as a parameter to SDK clients, the region is determined by `boto3_session`, `AWS_REGION` environment variable, `AWS_DEFAULT_REGION`, or falls back to `us-west-2`. Inconsistent region configuration can lead to resources not found or `AccessDeniedException` if the agent attempts to operate in an unintended region.fixAlways explicitly specify the `region_name` when initializing SDK clients, or consistently set the `AWS_REGION` environment variable in your deployment environment to avoid ambiguity.
affects: All versions
Upgrade
Version history
1.22.0latest on PyPI · released Aug 18, 2026
Audit
Dependencies
pythonrequiredRequired Python version.
boto3requiredUnderlying AWS SDK for interacting with Bedrock AgentCore APIs.
botocorerequiredUnderlying AWS SDK dependency, often needs to be updated with boto3.