<div align="center">
<a href="https://strandsagents.com">
<img src="https://strandsagents.com/latest/assets/logo-github.svg" alt="Strands Agents" width="55px" height="105px">
</a>
<span style="font-size: 48px; margin: 0 20px;">×</span>
<a href="https://aws.amazon.com/bedrock/agentcore/">
<img width="150" height="150" alt="Bedrock AgentCore" src="https://github.com/user-attachments/assets/b8b9456d-c9e2-45e1-ac5b-760f21f1ac18" />
</a>
<h1>Strands AgentCore Tools</h1>
<p><strong>Agentic tools that enable AI agents to autonomously deploy, manage, and monitor themselves on AWS Bedrock AgentCore</strong></p>
<p>
<a href="https://pypi.org/project/strands-agentcore-tools"><img src="https://img.shields.io/pypi/v/strands-agentcore-tools" alt="PyPI version"></a>
<a href="https://github.com/cagataycali/strands-agentcore-tools/blob/main/LICENSE"><img src="https://img.shields.io/github/license/cagataycali/strands-agentcore-tools" alt="License"></a>
</p>
</div>
---
## What This Is
**9 Python functions that wrap AWS Bedrock AgentCore boto3 APIs** for deployment, invocation, monitoring, and lifecycle management. Use these tools to:
- ✅ Deploy agents to AgentCore from code
- ✅ Invoke deployed agents programmatically
- ✅ Monitor CloudWatch logs and metrics
- ✅ Manage memory, sessions, and OAuth
- ✅ Integrate with Strands agents for autonomous deployment
**Lightweight by design:** Import only the tools you need for your use case.
---
## Agent Example
**Copy-paste ready agent with all execution modes:**
```python
# agent.py - Minimalist AgentCore agent with Strands
import asyncio
from bedrock_agentcore import BedrockAgentCoreApp
from strands import Agent
app = BedrockAgentCoreApp()
@app.async_task
async def run_agent_background(agent, prompt):
"""Background task wrapper for fire-and-forget execution"""
async for event in agent.stream_async(prompt):
print(event) # Log events in background
@app.entrypoint
async def invoke(payload, context):
agent = Agent()
prompt = payload.get("prompt", "")
mode = payload.get("mode", "streaming") # streaming | sync | fire_and_forget
if mode == "fire_and_forget":
# Start background task with @app.async_task wrapper, return immediately
asyncio.create_task(run_agent_background(agent, prompt))
return {"status": "started", "content": [{"text": "Agent running in background"}]}
elif mode == "sync":
# Single blocking response (wait for completion)
result = agent(prompt)
return {"status": "success", "content": [{"text": str(result)}]}
else:
# Streaming response (default, recommended for UX)
async for event in agent.stream_async(prompt):
yield event
app.run()
```
**Deploy this agent:**
```python
from strands_agentcore_tools import configure, launch, invoke
configure(action="configure", entrypoint="agent.py", agent_name="my-agent")
launch(action="launch", agent_name="my-agent")
invoke(agent_arn="arn:...", payload='{"prompt": "Hello!", "mode": "streaming"}')
```
<details>
<summary><b>📝 Advanced: Agent with Memory (STM + LTM)</b></summary>
```python
# agent.py - Agent with persistent memory
import os
from bedrock_agentcore import BedrockAgentCoreApp
from strands import Agent
from bedrock_agentcore.memory.integrations.strands.config import (
AgentCoreMemoryConfig, RetrievalConfig
)
from bedrock_agentcore.memory.integrations.strands.session_manager import (
AgentCoreMemorySessionManager
)
from strands_tools.agent_core_memory import AgentCoreMemoryToolProvider
app = BedrockAgentCoreApp()
MEMORY_ID = os.getenv("BEDROCK_AGENTCORE_MEMORY_ID")
REGION = os.getenv("AWS_REGION", "us-west-2")
@app.entrypoint
async def invoke(payload, context):
session_id = context.session_id
actor_id = context.headers.get(
"X-Amzn-Bedrock-AgentCore-Runtime-Custom-Actor-Id",
"user"
)
# Configure memory with semantic search
memory_config = AgentCoreMemoryConfig(
memory_id=MEMORY_ID,
session_id=session_id,
actor_id=actor_id,
retrieval_config={
f"/users/{actor_id}/facts": RetrievalConfig(
top_k=3,
relevance_score=0.5
)
}
)
# Memory tools provider
memory_provider = AgentCoreMemoryToolProvider(
memory_id=MEMORY_ID,
session_id=session_id,
actor_id=actor_id,
namespace="default",
region=REGION
)
# Create agent with memory
agent = Agent(
tools=memory_provider.tools,
session_manager=AgentCoreMemorySessionManager(memory_config, REGION),
system_prompt="You have persistent memory across conversations."
)
# Stream responses
async for event in agent.stream_async(payload.get("prompt")):
yield event
app.run()
```
**Deploy with memory:**
```python
from strands_agentcore_tools import memory, configure, launch
# 1. Create memory
memory(
action="create",
name="my-memory",
strategies=[{
"semanticMemoryStrategy": {
"name": "Facts",
"namespaces": ["/users/{actorId}/facts"]
}
}],
wait_for_active=True
)
# 2. Configure with memory
configure(
action="configure",
entrypoint="agent.py",
agent_name="my-agent",
memory_mode="STM_AND_LTM"
)
# 3. Launch
launch(action="launch", agent_name="my-agent")
```
</details>
---
## Installation
```bash
pip install strands-agentcore-tools
```
**Requirements:**
- Python 3.10+
- AWS credentials configured
- IAM permissions for `bedrock-agentcore:*`, `ecr:*`, `codebuild:*`, `iam:*`, `logs:*`
---
## The 9 Tools
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| **`configure`** | Generate Dockerfile, IAM roles, config YAML | `entrypoint`, `agent_name`, `memory_mode` |
| **`launch`** | Build & deploy to AgentCore via CodeBuild | `agent_name`, `mode`, `env_vars` |
| **`invoke`** | Execute deployed agent with payload | `agent_arn`, `payload`, `session_id` |
| **`agents`** | List/get agent runtimes | `action` ("list", "get", "find_by_name") |
| **`status`** | Check agent health & endpoint status | `agent_id` or `agent_name` |
| **`logs`** | Query CloudWatch logs | `agent_name`, `action`, `filter_pattern` |
| **`memory`** | Manage AgentCore memories (STM/LTM) | `action`, `memory_id`, `strategies` |
| **`identity`** | OAuth provider management | `action`, `provider_type`, `vendor` |
| **`session`** | Stop active runtime sessions | `agent_arn`, `session_id` |
---
## Quick Reference
### 1. Configure
**Generates deployment files:** Dockerfile, `.bedrock_agentcore.yaml`, IAM roles
```python
from strands_agentcore_tools import configure
configure(
action="configure",
entrypoint="agent.py",
agent_name="my-agent",
memory_mode="STM_AND_LTM", # or "STM_ONLY", "NO_MEMORY"
enable_observability=True,
idle_timeout=1800, # seconds
max_lifetime=7200, # seconds
region="us-west-2"
)
```
**Actions:**
- `configure` - Generate deployment files
- `status` - Check configuration status
- `list` - List all configured agents
**Output:**
- `.bedrock_agentcore/<agent_name>/Dockerfile`
- `.bedrock_agentcore/<agent_name>/.dockerignore`
- `.bedrock_agentcore.yaml`
---
### 2. Launch
**Builds ARM64 container on CodeBuild, pushes to ECR, deploys to AgentCore**
```python
from strands_agentcore_tools import launch
result = launch(
action="launch",
agent_name="my-agent",
mode="codebuild", # or "local" (requires Docker/Finch/Podman)
auto_update_on_conflict=True,
env_vars={
"MODEL_ID": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
"LOG_LEVEL": "DEBUG"
},
region="us-west-2"
)
print(result["agent_arn"]) # arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-agent-abc
```
**Actions:**
- `launch` - Deploy agent
- `status` - Check deployment status
- `stop` - Stop active deployment
**Returns:**
```python
{
"agent_id": "my-agent-abc123",
"agent_arn": "arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-agent-abc123",
"status": "READY"
}
```
---
### 3. Invoke
**Execute deployed agent, supports streaming responses**
```python
from strands_agentcore_tools import invoke
# Streaming invocation (default)
invoke(
agent_arn="arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-agent-abc",
payload='{"prompt": "Analyze this dataset"}',
session_id="session-123", # Optional: for conversation continuity
user_id="user-abc", # Optional: for OAuth flows
headers={ # Optional: custom headers
"X-Custom-Header": "value"
},
region="us-west-2"
)
```
**Parameters:**
- `agent_arn` (required) - Full ARN of deployed agent
- `payload` (required) - JSON string payload
- `session_id` (optional) - Min 33 chars for session tracking
- `user_id` (optional) - Triggers OAuth if configured
- `headers` (optional) - Custom HTTP headers
- `region` (optional) - AWS region
**Returns:** SSE streaming events from agent
---
### 4. Agents
**List, get, and search agent runtimes**
```python
from strands_agentcore_tools import agents
# List all agents
agents(action="list", region="us-west-2")
# Get specific agent
agents(action="get", agent_id="my-agent-abc123", region="us-west-2")
# Find by name
result = agents(action="find_by_name", agent_name="my-agent", region="us-west-2")
print(result["agent_arn"])
```
**Actions:**
- `list` - List all agent runtimes
- `get` - Get agent by ID
- `find_by_name` - Find agent by name (returns first match)
**Returns:**
```python
{
"agent_id": "my-agent-abc123",
"agent_arn": "arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-agent-abc123",
"status": "READY",
"created": "2024-10-24T14:20:00Z"
}
```
---
### 5. Status
**Check agent health and endpoint status**
```python
from strands_agentcore_tools import status
status(
agent_id="my-agent-abc123", # Can use agent_id
agent_name="my-agent", # Or agent_name (auto-lookup)
endpoint="DEFAULT", # Optional: specific endpoint
region="us-west-2"
)
```
**Returns:**
```python
{
"agent_id": "my-agent-abc123",
"status": "READY", # READY, CREATING, UPDATING, DELETING, FAILED
"endpoint": "DEFAULT",
"created": "2024-10-24T14:20:00Z",
"updated": "2024-10-24T15:30:00Z"
}
```
---
### 6. Logs
**Query CloudWatch logs for deployed agents**
```python
from strands_agentcore_tools import logs
# Recent logs
logs(
agent_name="my-agent",
action="recent",
limit=50,
region="us-west-2"
)
# Search for errors
logs(
agent_name="my-agent",
action="search",
filter_pattern="ERROR",
limit=100,
region="us-west-2"
)
# Tail logs (real-time)
logs(
agent_name="my-agent",
action="tail",
region="us-west-2"
)
# List log streams
logs(
agent_name="my-agent",
action="streams",
region="us-west-2"
)
```
**Actions:**
- `recent` - Get recent log events
- `search` - Filter logs by pattern
- `tail` - Stream logs in real-time
- `streams` - List available log streams
**Parameters:**
- `agent_name` - Agent name (auto-lookups runtime ID)
- `agent_id` - Or use runtime ID directly
- `endpoint` - Default: "DEFAULT"
- `limit` - Max events to return
- `filter_pattern` - CloudWatch filter pattern
---
### 7. Memory
**Manage AgentCore memories (STM/LTM)**
```python
from strands_agentcore_tools import memory
# Create memory
memory(
action="create",
name="research-memory",
strategies=[{
"semanticMemoryStrategy": {
"name": "Facts",
"namespaces": ["/users/{actorId}/facts"]
}
}],
wait_for_active=True, # Block until ACTIVE
region="us-west-2"
)
# Get memory status
memory(
action="get_status",
memory_id="memory-abc123",
region="us-west-2"
)
# Retrieve from memory
memory(
action="retrieve",
memory_id="memory-abc123",
namespace="/users/user-abc/facts",
search_query="What is the capital of France?",
top_k=5,
min_score=0.5,
region="us-west-2"
)
# Create memory event
memory(
action="create_event",
memory_id="memory-abc123",
session_id="session-123",
actor_id="user-abc",
namespace="/users/user-abc/facts",
content="Paris is the capital of France",
region="us-west-2"
)
# List all memories
memory(action="list", region="us-west-2")
```
**Actions:**
- `create` - Create new memory
- `get_status` - Check memory status
- `retrieve` - Semantic search
- `create_event` - Add memory event
- `list` - List all memories
---
### 8. Identity
**OAuth provider management**
```python
from strands_agentcore_tools import identity
# Create OAuth provider
identity(
action="create",
provider_type="oauth2",
name="slack-oauth",
vendor="SlackOauth2", # SlackOauth2, GitHubOAuth2, GoogleOAuth2
client_id="your-client-id",
client_secret="your-client-secret",
region="us-west-2"
)
# Get provider
identity(
action="get",
provider_id="provider-abc123",
region="us-west-2"
)
# List providers
identity(action="list", region="us-west-2")
# Delete provider
identity(
action="delete",
provider_id="provider-abc123",
region="us-west-2"
)
```
**Actions:**
- `create` - Create OAuth provider
- `get` - Get provider details
- `list` - List all providers
- `delete` - Delete provider
**Supported Vendors:**
- `SlackOauth2`
- `GitHubOAuth2`
- `GoogleOAuth2`
---
### 9. Session
**Stop active runtime sessions**
```python
from strands_agentcore_tools import session
session(
action="stop",
agent_arn="arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-agent-abc",
session_id="session-123",
region="us-west-2"
)
```
**Actions:**
- `stop` - Terminate active session
---
## Complete Workflow Example
```python
from strands_agentcore_tools import (
configure, launch, invoke, status, logs, memory
)
# 1. Configure deployment
configure(
action="configure",
entrypoint="agent.py",
agent_name="research-agent",
memory_mode="STM_AND_LTM"
)
# 2. Create memory
memory(
action="create",
name="research-memory",
strategies=[{
"semanticMemoryStrategy": {
"name": "Facts",
"namespaces": ["/users/{actorId}/facts"]
}
}],
wait_for_active=True
)
# 3. Deploy to AWS
result = launch(
action="launch",
agent_name="research-agent",
mode="codebuild"
)
agent_arn = result["agent_arn"]
# 4. Check deployment status
status(agent_name="research-agent")
# 5. Invoke agent
invoke(
agent_arn=agent_arn,
payload='{"prompt": "Analyze this data"}',
session_id="session-abc-123-very-long-session-id-here"
)
# 6. Check logs
logs(agent_name="research-agent", action="recent", limit=50)
```
---
## Use with Strands Agents
**Enable autonomous deployment by giving agents these tools:**
```python
from strands import Agent
from strands_agentcore_tools import (
configure, launch, invoke, status, logs
)
agent = Agent(
tools=[configure, launch, invoke, status, logs],
system_prompt="You can deploy yourself to AWS AgentCore."
)
# Agent deploys itself
response = agent("""
Deploy yourself to AWS:
1. Configure deployment
2. Launch to production
3. Check status
4. Show logs
""")
```
**Agent will autonomously:**
- ✅ Generate Dockerfile and config
- ✅ Trigger CodeBuild deployment
- ✅ Monitor deployment status
- ✅ Validate with logs
- ✅ Report results
---
## Configuration File
**`.bedrock_agentcore.yaml`** (auto-generated by `configure`):
```yaml
agents:
my-agent:
name: my-agent
entrypoint: agent.py
platform: linux/arm64
aws:
execution_role: arn:aws:iam::123:role/AgentCoreRuntime-us-west-2-abc
region: us-west-2
ecr_repository: 123.dkr.ecr.us-west-2.amazonaws.com/bedrock-agentcore-my-agent
memory:
mode: STM_AND_LTM
memory_id: memory-abc123
bedrock_agentcore:
agent_id: my-agent-abc123
agent_arn: arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-agent-abc123
```
---
## IAM Permissions
**Runtime Execution Role** (auto-created by `configure`):
```json
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"bedrock:InvokeModel",
"bedrock:InvokeModelWithResponseStream",
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"bedrock-agentcore:CreateMemoryEvent",
"bedrock-agentcore:RetrieveMemoryRecords",
"ecr:GetAuthorizationToken",
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer",
"xray:PutTraceSegments",
"xray:PutTelemetryRecords"
],
"Resource": "*"
}]
}
```
**Your IAM User/Role** (attach manually):
```json
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"bedrock-agentcore-control:*",
"bedrock-agentcore:*",
"ecr:*",
"codebuild:*",
"iam:CreateRole",
"iam:GetRole",
"iam:PassRole",
"iam:PutRolePolicy",
"logs:*",
"s3:PutObject",
"s3:GetObject"
],
"Resource": "*"
}]
}
```
---
## Error Handling
All tools return structured responses:
```python
# Success
{
"status": "success",
"agent_arn": "arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-agent-abc",
"message": "Agent deployed successfully"
}
# Error
{
"status": "error",
"error": "ConflictException",
"message": "Agent already exists. Use auto_update_on_conflict=True"
}
```
**Common Errors:**
- `ConflictException` - Agent exists, use `auto_update_on_conflict=True` in `launch()`
- `ValidationException` - Invalid parameters (check agent_name format)
- `AccessDeniedException` - IAM permissions missing
- `ResourceNotFoundException` - Agent/memory not found
---
## Observability
**View logs programmatically:**
```python
from strands_agentcore_tools import logs
# Recent logs
logs(agent_name="my-agent", action="recent", limit=50)
# Search for errors
logs(agent_name="my-agent", action="search", filter_pattern="ERROR")
# Tail in real-time
logs(agent_name="my-agent", action="tail")
```
**Add ADOT instrumentation for tracing:**
```dockerfile
# In Dockerfile (auto-generated by configure)
RUN pip install aws-opentelemetry-distro>=0.10.1
CMD ["opentelemetry-instrument", "python", "agent.py"]
```
**CloudWatch Logs Location:**
```
/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint>
```
---
## Development
**Local Testing:**
```bash
# Install package locally
pip install -e .
# Run tests
pytest tests/
# Format code
black strands_agentcore_tools/
```
**Project Structure:**
```
strands-agentcore-tools/
├── strands_agentcore_tools/
│ ├── __init__.py
│ ├── configure.py # Deployment configuration
│ ├── launch.py # CodeBuild deployment
│ ├── invoke.py # Agent invocation
│ ├── agents.py # Agent discovery
│ ├── status.py # Health checks
│ ├── logs.py # CloudWatch logs
│ ├── memory.py # Memory management
│ ├── identity.py # OAuth providers
│ └── session.py # Session control
├── setup.py
├── pyproject.toml
└── README.md
```
---
## Resources
**Documentation:**
- [Strands Agents Docs](https://strandsagents.com/)
- [AWS Bedrock AgentCore Docs](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/)
- [AgentCore API Reference](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore-control.html)
**Related Projects:**
- [bedrock-agentcore-starter-toolkit](https://github.com/aws/bedrock-agentcore-starter-toolkit) - Official AWS toolkit
- [strands-agents](https://github.com/strands-agents/sdk-python) - Strands SDK
---
## License
Apache2 License - see [LICENSE](LICENSE) file for details.
---
## Contributing
Issues and PRs welcome at [github.com/cagataycali/strands-agentcore-tools](https://github.com/cagataycali/strands-agentcore-tools)
Raw data
{
"_id": null,
"home_page": "https://github.com/cagataycali/strands-agentcore-tools",
"name": "strands-agentcore-tools",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "aws, bedrock, agentcore, strands, ai, agents, tools",
"author": "Cagatay Cali",
"author_email": "Cagatay Cali <cagataycali@icloud.com>",
"download_url": "https://files.pythonhosted.org/packages/35/29/e48fa8b49dadb7ab4504f6982a775045047dd09d68380ec9402dae0e3dd5/strands_agentcore_tools-0.1.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <a href=\"https://strandsagents.com\">\n <img src=\"https://strandsagents.com/latest/assets/logo-github.svg\" alt=\"Strands Agents\" width=\"55px\" height=\"105px\">\n </a>\n <span style=\"font-size: 48px; margin: 0 20px;\">\u00d7</span>\n <a href=\"https://aws.amazon.com/bedrock/agentcore/\">\n <img width=\"150\" height=\"150\" alt=\"Bedrock AgentCore\" src=\"https://github.com/user-attachments/assets/b8b9456d-c9e2-45e1-ac5b-760f21f1ac18\" />\n </a>\n\n <h1>Strands AgentCore Tools</h1>\n <p><strong>Agentic tools that enable AI agents to autonomously deploy, manage, and monitor themselves on AWS Bedrock AgentCore</strong></p>\n\n <p>\n <a href=\"https://pypi.org/project/strands-agentcore-tools\"><img src=\"https://img.shields.io/pypi/v/strands-agentcore-tools\" alt=\"PyPI version\"></a>\n <a href=\"https://github.com/cagataycali/strands-agentcore-tools/blob/main/LICENSE\"><img src=\"https://img.shields.io/github/license/cagataycali/strands-agentcore-tools\" alt=\"License\"></a>\n </p>\n</div>\n\n---\n\n## What This Is\n\n**9 Python functions that wrap AWS Bedrock AgentCore boto3 APIs** for deployment, invocation, monitoring, and lifecycle management. Use these tools to:\n\n- \u2705 Deploy agents to AgentCore from code\n- \u2705 Invoke deployed agents programmatically\n- \u2705 Monitor CloudWatch logs and metrics\n- \u2705 Manage memory, sessions, and OAuth\n- \u2705 Integrate with Strands agents for autonomous deployment\n\n**Lightweight by design:** Import only the tools you need for your use case.\n\n---\n\n## Agent Example\n\n**Copy-paste ready agent with all execution modes:**\n\n```python\n# agent.py - Minimalist AgentCore agent with Strands\nimport asyncio\nfrom bedrock_agentcore import BedrockAgentCoreApp\nfrom strands import Agent\n\napp = BedrockAgentCoreApp()\n\n@app.async_task\nasync def run_agent_background(agent, prompt):\n \"\"\"Background task wrapper for fire-and-forget execution\"\"\"\n async for event in agent.stream_async(prompt):\n print(event) # Log events in background\n\n@app.entrypoint\nasync def invoke(payload, context):\n agent = Agent()\n prompt = payload.get(\"prompt\", \"\")\n mode = payload.get(\"mode\", \"streaming\") # streaming | sync | fire_and_forget\n \n if mode == \"fire_and_forget\":\n # Start background task with @app.async_task wrapper, return immediately\n asyncio.create_task(run_agent_background(agent, prompt))\n return {\"status\": \"started\", \"content\": [{\"text\": \"Agent running in background\"}]}\n \n elif mode == \"sync\":\n # Single blocking response (wait for completion)\n result = agent(prompt)\n return {\"status\": \"success\", \"content\": [{\"text\": str(result)}]}\n \n else:\n # Streaming response (default, recommended for UX)\n async for event in agent.stream_async(prompt):\n yield event\n\napp.run()\n```\n\n**Deploy this agent:**\n```python\nfrom strands_agentcore_tools import configure, launch, invoke\n\nconfigure(action=\"configure\", entrypoint=\"agent.py\", agent_name=\"my-agent\")\nlaunch(action=\"launch\", agent_name=\"my-agent\")\ninvoke(agent_arn=\"arn:...\", payload='{\"prompt\": \"Hello!\", \"mode\": \"streaming\"}')\n```\n\n<details>\n<summary><b>\ud83d\udcdd Advanced: Agent with Memory (STM + LTM)</b></summary>\n\n```python\n# agent.py - Agent with persistent memory\nimport os\nfrom bedrock_agentcore import BedrockAgentCoreApp\nfrom strands import Agent\nfrom bedrock_agentcore.memory.integrations.strands.config import (\n AgentCoreMemoryConfig, RetrievalConfig\n)\nfrom bedrock_agentcore.memory.integrations.strands.session_manager import (\n AgentCoreMemorySessionManager\n)\nfrom strands_tools.agent_core_memory import AgentCoreMemoryToolProvider\n\napp = BedrockAgentCoreApp()\n\nMEMORY_ID = os.getenv(\"BEDROCK_AGENTCORE_MEMORY_ID\")\nREGION = os.getenv(\"AWS_REGION\", \"us-west-2\")\n\n@app.entrypoint\nasync def invoke(payload, context):\n session_id = context.session_id\n actor_id = context.headers.get(\n \"X-Amzn-Bedrock-AgentCore-Runtime-Custom-Actor-Id\", \n \"user\"\n )\n \n # Configure memory with semantic search\n memory_config = AgentCoreMemoryConfig(\n memory_id=MEMORY_ID,\n session_id=session_id,\n actor_id=actor_id,\n retrieval_config={\n f\"/users/{actor_id}/facts\": RetrievalConfig(\n top_k=3, \n relevance_score=0.5\n )\n }\n )\n \n # Memory tools provider\n memory_provider = AgentCoreMemoryToolProvider(\n memory_id=MEMORY_ID,\n session_id=session_id,\n actor_id=actor_id,\n namespace=\"default\",\n region=REGION\n )\n \n # Create agent with memory\n agent = Agent(\n tools=memory_provider.tools,\n session_manager=AgentCoreMemorySessionManager(memory_config, REGION),\n system_prompt=\"You have persistent memory across conversations.\"\n )\n \n # Stream responses\n async for event in agent.stream_async(payload.get(\"prompt\")):\n yield event\n\napp.run()\n```\n\n**Deploy with memory:**\n```python\nfrom strands_agentcore_tools import memory, configure, launch\n\n# 1. Create memory\nmemory(\n action=\"create\",\n name=\"my-memory\",\n strategies=[{\n \"semanticMemoryStrategy\": {\n \"name\": \"Facts\",\n \"namespaces\": [\"/users/{actorId}/facts\"]\n }\n }],\n wait_for_active=True\n)\n\n# 2. Configure with memory\nconfigure(\n action=\"configure\",\n entrypoint=\"agent.py\",\n agent_name=\"my-agent\",\n memory_mode=\"STM_AND_LTM\"\n)\n\n# 3. Launch\nlaunch(action=\"launch\", agent_name=\"my-agent\")\n```\n\n</details>\n\n---\n\n## Installation\n\n```bash\npip install strands-agentcore-tools\n```\n\n**Requirements:**\n- Python 3.10+\n- AWS credentials configured\n- IAM permissions for `bedrock-agentcore:*`, `ecr:*`, `codebuild:*`, `iam:*`, `logs:*`\n\n---\n\n## The 9 Tools\n\n| Tool | Purpose | Key Parameters |\n|------|---------|----------------|\n| **`configure`** | Generate Dockerfile, IAM roles, config YAML | `entrypoint`, `agent_name`, `memory_mode` |\n| **`launch`** | Build & deploy to AgentCore via CodeBuild | `agent_name`, `mode`, `env_vars` |\n| **`invoke`** | Execute deployed agent with payload | `agent_arn`, `payload`, `session_id` |\n| **`agents`** | List/get agent runtimes | `action` (\"list\", \"get\", \"find_by_name\") |\n| **`status`** | Check agent health & endpoint status | `agent_id` or `agent_name` |\n| **`logs`** | Query CloudWatch logs | `agent_name`, `action`, `filter_pattern` |\n| **`memory`** | Manage AgentCore memories (STM/LTM) | `action`, `memory_id`, `strategies` |\n| **`identity`** | OAuth provider management | `action`, `provider_type`, `vendor` |\n| **`session`** | Stop active runtime sessions | `agent_arn`, `session_id` |\n\n---\n\n## Quick Reference\n\n### 1. Configure\n\n**Generates deployment files:** Dockerfile, `.bedrock_agentcore.yaml`, IAM roles\n\n```python\nfrom strands_agentcore_tools import configure\n\nconfigure(\n action=\"configure\",\n entrypoint=\"agent.py\",\n agent_name=\"my-agent\",\n memory_mode=\"STM_AND_LTM\", # or \"STM_ONLY\", \"NO_MEMORY\"\n enable_observability=True,\n idle_timeout=1800, # seconds\n max_lifetime=7200, # seconds\n region=\"us-west-2\"\n)\n```\n\n**Actions:**\n- `configure` - Generate deployment files\n- `status` - Check configuration status\n- `list` - List all configured agents\n\n**Output:**\n- `.bedrock_agentcore/<agent_name>/Dockerfile`\n- `.bedrock_agentcore/<agent_name>/.dockerignore`\n- `.bedrock_agentcore.yaml`\n\n---\n\n### 2. Launch\n\n**Builds ARM64 container on CodeBuild, pushes to ECR, deploys to AgentCore**\n\n```python\nfrom strands_agentcore_tools import launch\n\nresult = launch(\n action=\"launch\",\n agent_name=\"my-agent\",\n mode=\"codebuild\", # or \"local\" (requires Docker/Finch/Podman)\n auto_update_on_conflict=True,\n env_vars={\n \"MODEL_ID\": \"us.anthropic.claude-sonnet-4-5-20250929-v1:0\",\n \"LOG_LEVEL\": \"DEBUG\"\n },\n region=\"us-west-2\"\n)\n\nprint(result[\"agent_arn\"]) # arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-agent-abc\n```\n\n**Actions:**\n- `launch` - Deploy agent\n- `status` - Check deployment status\n- `stop` - Stop active deployment\n\n**Returns:**\n```python\n{\n \"agent_id\": \"my-agent-abc123\",\n \"agent_arn\": \"arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-agent-abc123\",\n \"status\": \"READY\"\n}\n```\n\n---\n\n### 3. Invoke\n\n**Execute deployed agent, supports streaming responses**\n\n```python\nfrom strands_agentcore_tools import invoke\n\n# Streaming invocation (default)\ninvoke(\n agent_arn=\"arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-agent-abc\",\n payload='{\"prompt\": \"Analyze this dataset\"}',\n session_id=\"session-123\", # Optional: for conversation continuity\n user_id=\"user-abc\", # Optional: for OAuth flows\n headers={ # Optional: custom headers\n \"X-Custom-Header\": \"value\"\n },\n region=\"us-west-2\"\n)\n```\n\n**Parameters:**\n- `agent_arn` (required) - Full ARN of deployed agent\n- `payload` (required) - JSON string payload\n- `session_id` (optional) - Min 33 chars for session tracking\n- `user_id` (optional) - Triggers OAuth if configured\n- `headers` (optional) - Custom HTTP headers\n- `region` (optional) - AWS region\n\n**Returns:** SSE streaming events from agent\n\n---\n\n### 4. Agents\n\n**List, get, and search agent runtimes**\n\n```python\nfrom strands_agentcore_tools import agents\n\n# List all agents\nagents(action=\"list\", region=\"us-west-2\")\n\n# Get specific agent\nagents(action=\"get\", agent_id=\"my-agent-abc123\", region=\"us-west-2\")\n\n# Find by name\nresult = agents(action=\"find_by_name\", agent_name=\"my-agent\", region=\"us-west-2\")\nprint(result[\"agent_arn\"])\n```\n\n**Actions:**\n- `list` - List all agent runtimes\n- `get` - Get agent by ID\n- `find_by_name` - Find agent by name (returns first match)\n\n**Returns:**\n```python\n{\n \"agent_id\": \"my-agent-abc123\",\n \"agent_arn\": \"arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-agent-abc123\",\n \"status\": \"READY\",\n \"created\": \"2024-10-24T14:20:00Z\"\n}\n```\n\n---\n\n### 5. Status\n\n**Check agent health and endpoint status**\n\n```python\nfrom strands_agentcore_tools import status\n\nstatus(\n agent_id=\"my-agent-abc123\", # Can use agent_id\n agent_name=\"my-agent\", # Or agent_name (auto-lookup)\n endpoint=\"DEFAULT\", # Optional: specific endpoint\n region=\"us-west-2\"\n)\n```\n\n**Returns:**\n```python\n{\n \"agent_id\": \"my-agent-abc123\",\n \"status\": \"READY\", # READY, CREATING, UPDATING, DELETING, FAILED\n \"endpoint\": \"DEFAULT\",\n \"created\": \"2024-10-24T14:20:00Z\",\n \"updated\": \"2024-10-24T15:30:00Z\"\n}\n```\n\n---\n\n### 6. Logs\n\n**Query CloudWatch logs for deployed agents**\n\n```python\nfrom strands_agentcore_tools import logs\n\n# Recent logs\nlogs(\n agent_name=\"my-agent\",\n action=\"recent\",\n limit=50,\n region=\"us-west-2\"\n)\n\n# Search for errors\nlogs(\n agent_name=\"my-agent\",\n action=\"search\",\n filter_pattern=\"ERROR\",\n limit=100,\n region=\"us-west-2\"\n)\n\n# Tail logs (real-time)\nlogs(\n agent_name=\"my-agent\",\n action=\"tail\",\n region=\"us-west-2\"\n)\n\n# List log streams\nlogs(\n agent_name=\"my-agent\",\n action=\"streams\",\n region=\"us-west-2\"\n)\n```\n\n**Actions:**\n- `recent` - Get recent log events\n- `search` - Filter logs by pattern\n- `tail` - Stream logs in real-time\n- `streams` - List available log streams\n\n**Parameters:**\n- `agent_name` - Agent name (auto-lookups runtime ID)\n- `agent_id` - Or use runtime ID directly\n- `endpoint` - Default: \"DEFAULT\"\n- `limit` - Max events to return\n- `filter_pattern` - CloudWatch filter pattern\n\n---\n\n### 7. Memory\n\n**Manage AgentCore memories (STM/LTM)**\n\n```python\nfrom strands_agentcore_tools import memory\n\n# Create memory\nmemory(\n action=\"create\",\n name=\"research-memory\",\n strategies=[{\n \"semanticMemoryStrategy\": {\n \"name\": \"Facts\",\n \"namespaces\": [\"/users/{actorId}/facts\"]\n }\n }],\n wait_for_active=True, # Block until ACTIVE\n region=\"us-west-2\"\n)\n\n# Get memory status\nmemory(\n action=\"get_status\",\n memory_id=\"memory-abc123\",\n region=\"us-west-2\"\n)\n\n# Retrieve from memory\nmemory(\n action=\"retrieve\",\n memory_id=\"memory-abc123\",\n namespace=\"/users/user-abc/facts\",\n search_query=\"What is the capital of France?\",\n top_k=5,\n min_score=0.5,\n region=\"us-west-2\"\n)\n\n# Create memory event\nmemory(\n action=\"create_event\",\n memory_id=\"memory-abc123\",\n session_id=\"session-123\",\n actor_id=\"user-abc\",\n namespace=\"/users/user-abc/facts\",\n content=\"Paris is the capital of France\",\n region=\"us-west-2\"\n)\n\n# List all memories\nmemory(action=\"list\", region=\"us-west-2\")\n```\n\n**Actions:**\n- `create` - Create new memory\n- `get_status` - Check memory status\n- `retrieve` - Semantic search\n- `create_event` - Add memory event\n- `list` - List all memories\n\n---\n\n### 8. Identity\n\n**OAuth provider management**\n\n```python\nfrom strands_agentcore_tools import identity\n\n# Create OAuth provider\nidentity(\n action=\"create\",\n provider_type=\"oauth2\",\n name=\"slack-oauth\",\n vendor=\"SlackOauth2\", # SlackOauth2, GitHubOAuth2, GoogleOAuth2\n client_id=\"your-client-id\",\n client_secret=\"your-client-secret\",\n region=\"us-west-2\"\n)\n\n# Get provider\nidentity(\n action=\"get\",\n provider_id=\"provider-abc123\",\n region=\"us-west-2\"\n)\n\n# List providers\nidentity(action=\"list\", region=\"us-west-2\")\n\n# Delete provider\nidentity(\n action=\"delete\",\n provider_id=\"provider-abc123\",\n region=\"us-west-2\"\n)\n```\n\n**Actions:**\n- `create` - Create OAuth provider\n- `get` - Get provider details\n- `list` - List all providers\n- `delete` - Delete provider\n\n**Supported Vendors:**\n- `SlackOauth2`\n- `GitHubOAuth2`\n- `GoogleOAuth2`\n\n---\n\n### 9. Session\n\n**Stop active runtime sessions**\n\n```python\nfrom strands_agentcore_tools import session\n\nsession(\n action=\"stop\",\n agent_arn=\"arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-agent-abc\",\n session_id=\"session-123\",\n region=\"us-west-2\"\n)\n```\n\n**Actions:**\n- `stop` - Terminate active session\n\n---\n\n## Complete Workflow Example\n\n```python\nfrom strands_agentcore_tools import (\n configure, launch, invoke, status, logs, memory\n)\n\n# 1. Configure deployment\nconfigure(\n action=\"configure\",\n entrypoint=\"agent.py\",\n agent_name=\"research-agent\",\n memory_mode=\"STM_AND_LTM\"\n)\n\n# 2. Create memory\nmemory(\n action=\"create\",\n name=\"research-memory\",\n strategies=[{\n \"semanticMemoryStrategy\": {\n \"name\": \"Facts\",\n \"namespaces\": [\"/users/{actorId}/facts\"]\n }\n }],\n wait_for_active=True\n)\n\n# 3. Deploy to AWS\nresult = launch(\n action=\"launch\",\n agent_name=\"research-agent\",\n mode=\"codebuild\"\n)\n\nagent_arn = result[\"agent_arn\"]\n\n# 4. Check deployment status\nstatus(agent_name=\"research-agent\")\n\n# 5. Invoke agent\ninvoke(\n agent_arn=agent_arn,\n payload='{\"prompt\": \"Analyze this data\"}',\n session_id=\"session-abc-123-very-long-session-id-here\"\n)\n\n# 6. Check logs\nlogs(agent_name=\"research-agent\", action=\"recent\", limit=50)\n```\n\n---\n\n## Use with Strands Agents\n\n**Enable autonomous deployment by giving agents these tools:**\n\n```python\nfrom strands import Agent\nfrom strands_agentcore_tools import (\n configure, launch, invoke, status, logs\n)\n\nagent = Agent(\n tools=[configure, launch, invoke, status, logs],\n system_prompt=\"You can deploy yourself to AWS AgentCore.\"\n)\n\n# Agent deploys itself\nresponse = agent(\"\"\"\nDeploy yourself to AWS:\n1. Configure deployment\n2. Launch to production\n3. Check status\n4. Show logs\n\"\"\")\n```\n\n**Agent will autonomously:**\n- \u2705 Generate Dockerfile and config\n- \u2705 Trigger CodeBuild deployment\n- \u2705 Monitor deployment status\n- \u2705 Validate with logs\n- \u2705 Report results\n\n---\n\n## Configuration File\n\n**`.bedrock_agentcore.yaml`** (auto-generated by `configure`):\n\n```yaml\nagents:\n my-agent:\n name: my-agent\n entrypoint: agent.py\n platform: linux/arm64\n aws:\n execution_role: arn:aws:iam::123:role/AgentCoreRuntime-us-west-2-abc\n region: us-west-2\n ecr_repository: 123.dkr.ecr.us-west-2.amazonaws.com/bedrock-agentcore-my-agent\n memory:\n mode: STM_AND_LTM\n memory_id: memory-abc123\n bedrock_agentcore:\n agent_id: my-agent-abc123\n agent_arn: arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-agent-abc123\n```\n\n---\n\n## IAM Permissions\n\n**Runtime Execution Role** (auto-created by `configure`):\n\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [{\n \"Effect\": \"Allow\",\n \"Action\": [\n \"bedrock:InvokeModel\",\n \"bedrock:InvokeModelWithResponseStream\",\n \"logs:CreateLogGroup\",\n \"logs:CreateLogStream\",\n \"logs:PutLogEvents\",\n \"bedrock-agentcore:CreateMemoryEvent\",\n \"bedrock-agentcore:RetrieveMemoryRecords\",\n \"ecr:GetAuthorizationToken\",\n \"ecr:BatchGetImage\",\n \"ecr:GetDownloadUrlForLayer\",\n \"xray:PutTraceSegments\",\n \"xray:PutTelemetryRecords\"\n ],\n \"Resource\": \"*\"\n }]\n}\n```\n\n**Your IAM User/Role** (attach manually):\n\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [{\n \"Effect\": \"Allow\",\n \"Action\": [\n \"bedrock-agentcore-control:*\",\n \"bedrock-agentcore:*\",\n \"ecr:*\",\n \"codebuild:*\",\n \"iam:CreateRole\",\n \"iam:GetRole\",\n \"iam:PassRole\",\n \"iam:PutRolePolicy\",\n \"logs:*\",\n \"s3:PutObject\",\n \"s3:GetObject\"\n ],\n \"Resource\": \"*\"\n }]\n}\n```\n\n---\n\n## Error Handling\n\nAll tools return structured responses:\n\n```python\n# Success\n{\n \"status\": \"success\",\n \"agent_arn\": \"arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-agent-abc\",\n \"message\": \"Agent deployed successfully\"\n}\n\n# Error\n{\n \"status\": \"error\",\n \"error\": \"ConflictException\",\n \"message\": \"Agent already exists. Use auto_update_on_conflict=True\"\n}\n```\n\n**Common Errors:**\n- `ConflictException` - Agent exists, use `auto_update_on_conflict=True` in `launch()`\n- `ValidationException` - Invalid parameters (check agent_name format)\n- `AccessDeniedException` - IAM permissions missing\n- `ResourceNotFoundException` - Agent/memory not found\n\n---\n\n## Observability\n\n**View logs programmatically:**\n\n```python\nfrom strands_agentcore_tools import logs\n\n# Recent logs\nlogs(agent_name=\"my-agent\", action=\"recent\", limit=50)\n\n# Search for errors\nlogs(agent_name=\"my-agent\", action=\"search\", filter_pattern=\"ERROR\")\n\n# Tail in real-time\nlogs(agent_name=\"my-agent\", action=\"tail\")\n```\n\n**Add ADOT instrumentation for tracing:**\n\n```dockerfile\n# In Dockerfile (auto-generated by configure)\nRUN pip install aws-opentelemetry-distro>=0.10.1\nCMD [\"opentelemetry-instrument\", \"python\", \"agent.py\"]\n```\n\n**CloudWatch Logs Location:**\n```\n/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint>\n```\n\n---\n\n## Development\n\n**Local Testing:**\n\n```bash\n# Install package locally\npip install -e .\n\n# Run tests\npytest tests/\n\n# Format code\nblack strands_agentcore_tools/\n```\n\n**Project Structure:**\n\n```\nstrands-agentcore-tools/\n\u251c\u2500\u2500 strands_agentcore_tools/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 configure.py # Deployment configuration\n\u2502 \u251c\u2500\u2500 launch.py # CodeBuild deployment\n\u2502 \u251c\u2500\u2500 invoke.py # Agent invocation\n\u2502 \u251c\u2500\u2500 agents.py # Agent discovery\n\u2502 \u251c\u2500\u2500 status.py # Health checks\n\u2502 \u251c\u2500\u2500 logs.py # CloudWatch logs\n\u2502 \u251c\u2500\u2500 memory.py # Memory management\n\u2502 \u251c\u2500\u2500 identity.py # OAuth providers\n\u2502 \u2514\u2500\u2500 session.py # Session control\n\u251c\u2500\u2500 setup.py\n\u251c\u2500\u2500 pyproject.toml\n\u2514\u2500\u2500 README.md\n```\n\n---\n\n## Resources\n\n**Documentation:**\n- [Strands Agents Docs](https://strandsagents.com/)\n- [AWS Bedrock AgentCore Docs](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/)\n- [AgentCore API Reference](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore-control.html)\n\n**Related Projects:**\n- [bedrock-agentcore-starter-toolkit](https://github.com/aws/bedrock-agentcore-starter-toolkit) - Official AWS toolkit\n- [strands-agents](https://github.com/strands-agents/sdk-python) - Strands SDK\n\n---\n\n## License\n\nApache2 License - see [LICENSE](LICENSE) file for details.\n\n---\n\n## Contributing\n\nIssues and PRs welcome at [github.com/cagataycali/strands-agentcore-tools](https://github.com/cagataycali/strands-agentcore-tools)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Strands tools for AWS Bedrock AgentCore lifecycle management",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/cagataycali/strands-agentcore-tools/issues",
"Documentation": "https://github.com/cagataycali/strands-agentcore-tools",
"Homepage": "https://github.com/cagataycali/strands-agentcore-tools",
"Repository": "https://github.com/cagataycali/strands-agentcore-tools"
},
"split_keywords": [
"aws",
" bedrock",
" agentcore",
" strands",
" ai",
" agents",
" tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8b227e7e139d9bee6f4aac07288a577e16222044a83162a0e6ccd1befc37c08a",
"md5": "d59d2b3d1e103eae1fc5d0d696a0be39",
"sha256": "e82c04b3db946a7f688718a703b5a4cd9f576503a4411a5e6c58aab54a0e4b79"
},
"downloads": -1,
"filename": "strands_agentcore_tools-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d59d2b3d1e103eae1fc5d0d696a0be39",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 67696,
"upload_time": "2025-10-26T15:41:56",
"upload_time_iso_8601": "2025-10-26T15:41:56.734847Z",
"url": "https://files.pythonhosted.org/packages/8b/22/7e7e139d9bee6f4aac07288a577e16222044a83162a0e6ccd1befc37c08a/strands_agentcore_tools-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3529e48fa8b49dadb7ab4504f6982a775045047dd09d68380ec9402dae0e3dd5",
"md5": "11576f13043bdb428e58da4bc968415e",
"sha256": "2252c3d3a9b3f82c91694a1555438dfec381dc1dc90c22543a95fe47a09c1148"
},
"downloads": -1,
"filename": "strands_agentcore_tools-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "11576f13043bdb428e58da4bc968415e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 67764,
"upload_time": "2025-10-26T15:41:58",
"upload_time_iso_8601": "2025-10-26T15:41:58.102062Z",
"url": "https://files.pythonhosted.org/packages/35/29/e48fa8b49dadb7ab4504f6982a775045047dd09d68380ec9402dae0e3dd5/strands_agentcore_tools-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 15:41:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cagataycali",
"github_project": "strands-agentcore-tools",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "bedrock-agentcore",
"specs": []
},
{
"name": "strands-agents",
"specs": []
},
{
"name": "strands-agents-tools",
"specs": []
},
{
"name": "pyyaml",
"specs": []
}
],
"lcname": "strands-agentcore-tools"
}
JSON
