/aws-agentic-ai

Runtime Service

The Runtime service provides a secure, serverless hosting environment for deploying and running AI agents or tools. It handles scaling, session management, security isolation, and infrastructure management.

Key Features

Quick Start

Prerequisites

• AWS CLI configured with appropriate permissions
• Docker installed for container builds (ARM64)
• Python 3.12+ for SDK usage

Deploy an Agent

Step 1: Install AgentCore SDK

pip install bedrock-agentcore strands-agents strands-agents-tools

Step 2: Create agent code

from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands import Agent

app = BedrockAgentCoreApp()
agent = Agent(system_prompt="You are a helpful assistant.")

@app.entrypoint
async def main(payload):
    async for event in agent.stream_async(payload.get("prompt", "")):
        if "data" in event:
            yield event["data"]

if __name__ == "__main__":
    app.run()  # Auto-listens on port 8080, auto-generates /ping and /invocations

See scripts/runtime-fastapi-template.py for a FastAPI-based alternative with MCPClient integration.

Step 3: Create AgentCore Runtime

aws bedrock-agentcore-control create-agent-runtime \
  --agent-runtime-name my-agent \
  --runtime-artifact '{"containerConfiguration": {"containerUri": "<ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/my-agent:latest"}}' \
  --role-arn arn:aws:iam::<ACCOUNT_ID>:role/AgentRuntimeExecutionRole \
  --network-configuration '{"networkMode": "PUBLIC"}' \
  --protocol-configuration HTTP \
  --region us-west-2

Step 4: Invoke agent

aws bedrock-agentcore-runtime invoke-agent-runtime \
  --agent-runtime-endpoint-arn arn:aws:bedrock-agentcore:us-west-2:<ACCOUNT_ID>:runtime/my-agent/endpoint/DEFAULT \
  --payload '{"prompt": "Hello, agent!"}' \
  --region us-west-2

Transforming an Existing Agent

To deploy an existing agent (built with Strands, LangGraph, or another framework) to AgentCore Runtime, wrap it with the BedrockAgentCoreApp:

Transformation Checklist

1. Add runtime dependency to requirements.txt:

   bedrock-agentcore
   strands-agents       # or your framework

2. Add runtime import:

   from bedrock_agentcore.runtime import BedrockAgentCoreApp

3. Initialize the application:

   app = BedrockAgentCoreApp()

4. Decorate the main entrypoint with @app.entrypoint:

   @app.entrypoint
   def handler(event, context):
       # Your existing agent logic here
       return agent.invoke(event)

5. Add the application runner:

   if __name__ == "__main__":
       app.run()

Complete Transformation Example

Before (standalone Strands agent):

from strands import Agent

agent = Agent(system_prompt="You are a helpful assistant.")
response = agent("Hello!")

After (Runtime-compatible):

from strands import Agent
from bedrock_agentcore.runtime import BedrockAgentCoreApp

app = BedrockAgentCoreApp()
agent = Agent(system_prompt="You are a helpful assistant.")

@app.entrypoint
def handler(event, context):
    user_input = event.get("input", "")
    return agent(user_input)

if __name__ == "__main__":
    app.run()

@app.entrypoint vs @app.handler()

Both decorators register the main request handler. Use @app.entrypoint for simple synchronous handlers and @app.handler() for async handlers with streaming support:

Alternative: AgentCore CLI Deployment

The AgentCore CLI provides a streamlined deployment experience:

# Install the CLI
npm install -g @aws/agentcore

# Deploy (builds container, pushes to ECR, creates runtime)
agentcore deploy

The CLI automates containerization, ECR push, and runtime creation. For manual control, use the AWS CLI workflow below.

Core Concepts

Runtime → Version → Endpoint

• Runtime: Containerized application hosting your AI agent. Has a unique identity and is versioned for controlled updates.
• Version: Immutable configuration snapshot. V1 created automatically; each update creates a new version with rollback capability.
• Endpoint: Addressable access point. DEFAULT endpoint auto-created pointing to latest version. States: CREATING → READY → UPDATING → READY.

Container Contract

See scripts/Dockerfile.runtime-template for a production-ready Dockerfile.

MicroVM Sessions

Each session gets a dedicated microVM with isolated CPU, memory, and filesystem. Same session ID always routes to the same microVM.

States: Active (processing) → Idle (waiting) → Terminated (destroyed)

Common Operations

List Agent Runtimes

aws bedrock-agentcore-control list-agent-runtimes --region us-west-2

Get Runtime Details

aws bedrock-agentcore-control get-agent-runtime \
  --agent-runtime-id <RUNTIME_ID> --region us-west-2

Update Runtime

aws bedrock-agentcore-control update-agent-runtime \
  --agent-runtime-id <RUNTIME_ID> \
  --runtime-artifact '{"containerConfiguration": {"containerUri": "<NEW_IMAGE_URI>"}}' \
  --region us-west-2

Delete Runtime

aws bedrock-agentcore-control delete-agent-runtime \
  --agent-runtime-id <RUNTIME_ID> --region us-west-2

Supported Frameworks

Troubleshooting

Deep-Dive References

For production deployment architecture, detailed internals, and advanced patterns, see the reference documentation:

Related Services

• Gateway Service: Expose APIs as MCP tools for agents with transparent OAuth credential injection
• Memory Service: Short-term (multi-turn) + long-term (cross-session) conversation memory
• Identity Service: Credential providers, Token Vault, OAuth lifecycle management
• Observability Service: OpenTelemetry tracing, CloudWatch metrics, X-Ray integration
• Agent Registry: Catalog, discover, and govern deployed agents and tools

References

• AWS Runtime Documentation
• How Runtime Works
• Runtime Troubleshooting
• Runtime API Reference