Registry / aws / bedrock-agentcore-starter-toolkit

bedrock-agentcore-starter-toolkit

JSON →
library0.3.12pypypi✓ verified 23d ago

The Bedrock AgentCore Starter Toolkit is a Python CLI toolkit designed to simplify the deployment of AI agents to Amazon Bedrock AgentCore Runtime. It enables developers to take Python-based agent logic (e.g., built with Strands Agents or LangGraph) and deploy it to AWS with minimal infrastructure management. The library is currently at version 0.3.5 and undergoes rapid development with frequent patch releases. While still active for existing Python workflows, AWS now recommends using the `@aws/agentcore-cli` (an npm-based CLI) for new projects due to its broader framework support and features.

pip install bedrock-agentcore-starter-toolkit==0.3.5
INSTALL
IMPORT
SIG · BEDROCK-AGENTCORE-
B
bedrock-agentcore-starter-toolkit
awspythonv0.3.12
Install
12.3s avg
Import
1477ms
Disk
140MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.3.5 · 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
musl
glibc
py 3.10
✓ —
✓ 14.7s
py 3.11
✓ —
✓ 13.1s
py 3.12
✓ —
✓ 10.8s
py 3.13
✓ —
✓ 10.8s
py 3.9
✕ build_error
✕ build_error
140MB installed
● package 140MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

BedrockAgentCoreApp
from bedrock_agentcore.runtime import BedrockAgentCoreApp
This class is used to wrap your agent's Python logic, making it deployable to the Bedrock AgentCore Runtime. The starter toolkit CLI then interacts with this wrapped application.

This quickstart demonstrates how to define a simple AI agent using `bedrock_agentcore.runtime.BedrockAgentCoreApp` and then deploy it using the `agentcore` command-line interface provided by the `bedrock-agentcore-starter-toolkit`. The Python code defines the agent's logic, which the CLI toolkit then containerizes and deploys to the AWS Bedrock AgentCore Runtime. Ensure your AWS credentials are configured (e.g., using `aws configure`) and you have the necessary IAM permissions to create roles, Lambda functions, and use Bedrock AgentCore services.

import os from bedrock_agentcore.runtime import BedrockAgentCoreApp def my_agent_logic(request): """ Processes an incoming request for the AI agent. """ prompt = request.get("prompt", "Hello from AgentCore!") # Simulate agent processing or integrate with an LLM response_content = f"The agent received your prompt: '{prompt}'." return {"response": response_content} app = BedrockAgentCoreApp() @app.entrypoint def production_agent(request): """ The entrypoint function for the Bedrock AgentCore Runtime. This function wraps your core agent logic. """ return my_agent_logic(request) if __name__ == "__main__": # This block allows local testing of the agent logic. # For deployment, the `agentcore` CLI interacts with this file. print("Starting local AgentCore development server...") print("Access at http://localhost:8080/invocations") app.run() # To deploy and invoke via the CLI, run these commands in your terminal: # 1. Save the above Python code to a file, e.g., `my_agent.py`. # 2. Configure your agent: `agentcore configure --entrypoint my_agent.py --name my-bedrock-agent --region us-east-1` # (Ensure AWS credentials are configured, e.g., via `aws configure`) # 3. Launch the agent: `agentcore launch` # 4. Invoke the deployed agent: `agentcore invoke '{"prompt": "Tell me a fun fact about Python."}'`
bedrock-agentcore-starter-toolkit --version
Debug
Known issues
gotchaFor all new Bedrock AgentCore projects, AWS now officially recommends using the `@aws/agentcore-cli` (an npm-based CLI) instead of this Python toolkit. This Python starter toolkit is primarily intended for existing Python-based workflows. The `@aws/agentcore-cli` offers broader framework support and features for local development.
fix
For new projects, consider installing and using the `@aws/agentcore-cli` via `npm i @aws/agentcore-cli`. Refer to the official AgentCore CLI documentation for migration guides if you need to move an existing project.
affects: >=0.3.4
gotchaThe Bedrock AgentCore Starter Toolkit is currently in 'public preview' status. This means that APIs and functionalities may change as the SDK is refined, potentially leading to breaking changes in future minor or patch releases.
fix
Review the `CHANGELOG.md` or release notes before updating to new versions, and thoroughly test your deployments after any updates.
affects: All versions
gotchaSuccessful deployment and invocation of agents require correctly configured AWS credentials and appropriate IAM permissions for creating roles, ECR repositories, and Bedrock AgentCore runtimes. Common issues arise from insufficient permissions or incorrectly set AWS regions.
fix
Ensure your AWS CLI is configured (`aws configure`) and the IAM role used for deployment has policies allowing `bedrock:*`, `iam:*`, `ecr:*`, and `lambda:*` actions, especially `bedrock-agentcore:*` for runtime operations. Specify the `--region` argument during `agentcore configure` if not using your default AWS region.
affects: All versions
Errors
Common errors & fixes
CLI hangs forever
The `agentcore configure` or `agentcore launch` command freezes indefinitely, often occurring on Windows systems due to conflicts with Python 3.13 or environment misconfigurations.
fix
Explicitly activate a supported Python version (e.g., Python 3.11), uninstall Python 3.13 if present, and ensure Python 3.11 paths are prioritized in environment variables, or use WSL (Windows Subsystem for Linux) for a more stable environment.
ResourceNotFoundException: Agent not found
This error occurs during agent deployment when the local configuration (`.bedrock_agentcore.yaml`) contains a stale agent ID that no longer exists in the Bedrock AgentCore service, leading the toolkit to attempt an update instead of a new creation.
fix
Manually delete the stale `bedrock_agentcore` section or the entire `.bedrock_agentcore.yaml` configuration file to force the toolkit to create a new agent and corresponding ID.
ModuleNotFoundError at runtime (direct_code_deploy) (uv workspace)
The `agentcore launch` command with `direct_code_deploy` fails to resolve workspace dependencies defined in `pyproject.toml` (specifically `[tool.uv.sources]`), causing Python packages in the same repository to be unavailable at runtime.
fix
Ensure that workspace members containing agent code are correctly configured, and that the build context for `agentcore launch` includes the necessary package directories for `uv pip compile` to properly install local workspace packages.
Unknown parameter in input: 'ExpectedBucketOwner'
This error typically arises during `agentcore launch` when the underlying `boto3` library is outdated, or the AWS IAM role lacks necessary S3 permissions, as `ExpectedBucketOwner` is an S3 API parameter.
fix
Upgrade your `boto3` library to the latest version (`pip install --upgrade boto3`) and verify that your AWS IAM role has the required S3 permissions for bucket operations, or consider using the `--local-build` flag if S3 direct access is not intended for builds.
AccessDeniedException when creating Bedrock AgentCore Runtime
The AWS IAM user or role attempting to create or interact with the AgentCore Runtime lacks the necessary permissions, specifically `bedrock-agentcore:CreateAgentRuntime`, or the agent's execution role cannot be assumed by Bedrock AgentCore.
fix
Attach the required IAM policies (e.g., `AmazonBedrockFullAccess`, `AmazonEC2ContainerRegistryFullAccess`) to your user/role, or explicitly grant `bedrock-agentcore:CreateAgentRuntime` permission, and ensure the agent's execution role has a trust policy allowing `bedrock-agentcore.amazonaws.com` to assume it.
Upgrade
Version history
0.3.12latest on PyPI · released Aug 19, 2026
Audit
Dependencies
pythonrequiredRequired Python version.
boto3requiredAWS SDK for Python, essential for interacting with AWS services including Bedrock AgentCore.
bedrock-agentcorerequiredThe core Python SDK for building Bedrock AgentCore applications, used to define agents.
strands-agentsoptionalCommonly used agent framework in quickstart examples, though other frameworks (LangGraph, etc.) are supported.
Agent activity
29 hits · last 30 days
node
22
OpenAI (training)
2
Amazon
1
Resources
bedrock-agentcore-starter-toolkit — pip install bedrock-agentcore-starter-toolkit · libregistry