deepagents-contrib-aws 0.2.1

AWS contributions for Deep Agents

deepagents-contrib-aws

AWS backend implementations for the deepagents framework.

Installation

pip install deepagents-contrib-aws

This installs both backends (S3Backend and AgentCoreCodeInterpreterSandbox) and all dependencies.

Backends

Backend	Protocol	Description	Docs
S3Backend	BackendProtocol	Persists agent workspace files in Amazon S3. Supports ls, read, write, edit, grep, glob, upload_files, download_files.	docs/s3-backend.md
AgentCoreCodeInterpreterSandbox	SandboxBackendProtocol	Executes Python and shell commands in a managed cloud sandbox via Amazon Bedrock AgentCore Code Interpreter. Native file upload/download.	docs/agentcore-sandbox.md

Quick Examples

S3Backend

from deepagents_contrib_aws import S3Backend

backend = S3Backend(bucket="my-bucket", prefix="agent/workspace/")
backend.write("/hello.py", "print('hello')")
content = backend.read("/hello.py")

Or configure from environment variables:

export S3_BACKEND_BUCKET=my-bucket

backend = S3Backend.from_env()

See docs/s3-backend.md for full usage, configuration reference, and all operations.

AgentCore Code Interpreter Sandbox

from deepagents_contrib_aws import AgentCoreCodeInterpreterSandbox

with AgentCoreCodeInterpreterSandbox(region_name="us-west-2") as sandbox:
    # Python execution (variable state preserved across calls)
    sandbox.execute('python3 -c "x = 42"')
    result = sandbox.execute('python3 -c "print(x)"')
    print(result.output)  # "42"

    # Shell commands
    result = sandbox.execute("echo hello")
    print(result.output)  # "hello"

Or configure from environment variables:

export AGENTCORE_REGION=us-west-2

sandbox = AgentCoreCodeInterpreterSandbox.from_env()

See docs/agentcore-sandbox.md for full usage, file operations, session lifecycle, and configuration reference.

With deepagents

from deepagents import create_deep_agent
from deepagents_contrib_aws import S3Backend, AgentCoreCodeInterpreterSandbox

# File storage backend
backend = S3Backend.from_env()
agent = create_deep_agent(backend=backend)

# Code execution sandbox
sandbox = AgentCoreCodeInterpreterSandbox.from_env()
agent = create_deep_agent(backend=sandbox)

AWS Credentials

Both backends resolve credentials via the standard boto3 credential chain:

1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
2. Shared credentials file (~/.aws/credentials)
3. AWS SSO (aws sso login)
4. IAM role (EC2, ECS, Lambda)

Examples

Example	Description
Product Support Agent	A deep agent with 3 skills (electronics, healthcare, finance) using CompositeBackend — AgentCore for execution, S3 for storage. Fully self-contained with its own pyproject.toml.

Each example is an independent project — cd into it, run uv sync, configure .env, and go. See the example's own README for setup instructions.

Development

See docs/development.md for setup, testing, linting, building, and contributing guidelines.

# Quick start
uv sync              # install dependencies
uv run pytest        # run unit tests (102 tests, no AWS credentials needed)
uv run ruff check .  # lint
uv build             # build package

License

MIT