Skip to main content
AWS Bedrock AgentCore is a managed runtime for deploying agentic applications. Your agent code runs as a containerized service that AWS provisions and operates. AgentCore is framework-agnostic and works with Strands Agents, CrewAI, LangGraph, LlamaIndex, Google ADK, and the OpenAI Agents SDK. Phoenix captures every invocation by configuring the AgentCore-deployed agent to export OpenTelemetry traces to Phoenix through the same openinference-instrumentation-strands-agents span processor used in the Strands Agents tracing guide.
This is a deployment workflow. The AgentCore starter toolkit ships your agent file to AWS: it provisions an ECR repository, builds and pushes the agent container, creates an IAM execution role, and launches the runtime. The deployed container sends spans over the network, so it needs a Phoenix instance it can reach, such as Phoenix Cloud or a self-hosted Phoenix with a public endpoint. A localhost Phoenix only works when you run the agent locally.

Prerequisites

  • Python 3.10+
  • A Phoenix instance reachable from AWS, plus a Phoenix API key if your instance requires authentication
  • An AWS account with:
    • Bedrock model access enabled for the foundation model your agent uses
    • Bedrock AgentCore available in your AWS region. Check the Bedrock AgentCore docs for the current list of regions.
    • IAM permissions to create ECR repositories, execution roles, and AgentCore runtimes
  • Docker running locally, because the starter toolkit builds the agent container image on your machine before pushing it to ECR

Install

Add the runtime dependencies to your project’s requirements.txt. The starter toolkit installs these into the AgentCore container at deploy time:

Setup

Set your Phoenix and AWS credentials as environment variables:
Create the agent’s runtime file. This is the file AgentCore packages into the deployable container. The tracing setup matches the Strands Agents tracing guide, with one runtime-specific step: AgentCore registers its own tracer provider by default, so you disable AgentCore’s built-in OpenTelemetry at deploy time (see Run Bedrock AgentCore) and let register() install the Phoenix tracer provider globally.
strands_claude.py
Processor ordering matters. register() installs a default exporter-backed processor. Adding StrandsAgentsToOpenInferenceProcessor() replaces that default, and the BatchSpanProcessor you add after it exports the converted OpenInference spans to Phoenix.

Test the agent locally

Before you deploy, you can run the same file locally. app.run() serves the agent on port 8080, the same /invocations contract AgentCore uses:
In another terminal, send a request:
The trace appears in your Phoenix project. Locally you can point PHOENIX_COLLECTOR_ENDPOINT at http://localhost:6006.

Run Bedrock AgentCore

Configure and launch the AgentCore deployment. The starter toolkit creates the ECR repository and the execution role on the first run.
deploy.py

Observe

Each invocation appears in your Phoenix project as one trace, with the same shape as the Strands Agents tracing guide: an invoke_agent OceanAssistant agent span wrapping an execute_event_loop_cycle chain span and a chat LLM span for the us.anthropic.claude-sonnet-4-6 call, with the prompt, response, and token usage attached. The first invocation after launch can take a minute or two while the container provisions.

Troubleshooting

  • Overriding of current TracerProvider is not allowed. AgentCore registers its own tracer provider on startup. Pass disable_otel=True to configure(...) and set DISABLE_ADOT_OBSERVABILITY=true in env_vars at launch(...) so register() can install the Phoenix tracer provider.
  • No spans from the deployed agent. Confirm PHOENIX_COLLECTOR_ENDPOINT points at a Phoenix instance reachable from AWS (not localhost) and that PHOENIX_API_KEY is passed in env_vars.
  • AccessDeniedException from Bedrock at invocation time. The auto-created execution role has minimal permissions. Attach bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream to it. The role ARN is in the configure(...) return value.
  • Spans for an invocation arrive late. BatchSpanProcessor exports on a timer. To export at the end of each invocation, call tracer_provider.force_flush() before your @app.entrypoint function returns.
  • Region mismatch. The BedrockModel(region_name=...) region and the AgentCore Runtime region must agree, or the model call fails with ValidationException.

Resources