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
requirements.txt. The starter toolkit installs these into the AgentCore container at deploy time:
Setup
Set your Phoenix and AWS credentials as environment variables: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:
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: aninvoke_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. Passdisable_otel=Truetoconfigure(...)and setDISABLE_ADOT_OBSERVABILITY=trueinenv_varsatlaunch(...)soregister()can install the Phoenix tracer provider.- No spans from the deployed agent. Confirm
PHOENIX_COLLECTOR_ENDPOINTpoints at a Phoenix instance reachable from AWS (notlocalhost) and thatPHOENIX_API_KEYis passed inenv_vars. AccessDeniedExceptionfrom Bedrock at invocation time. The auto-created execution role has minimal permissions. Attachbedrock:InvokeModelandbedrock:InvokeModelWithResponseStreamto it. The role ARN is in theconfigure(...)return value.- Spans for an invocation arrive late.
BatchSpanProcessorexports on a timer. To export at the end of each invocation, calltracer_provider.force_flush()before your@app.entrypointfunction returns. - Region mismatch. The
BedrockModel(region_name=...)region and the AgentCore Runtime region must agree, or the model call fails withValidationException.

