Maple agent tracing: Strands Agents

Goal: every conversation = one Maple Agent Session. Each agent(...) / invoke_async / stream_async call = one turn (one trace) with transcript, chat spans with tokens, execute_tool spans with args/results, failed tools marked failed, sub-agents in their own lanes.

Mechanism: Strands' native OTel tracer (scope strands.telemetry.tracer, gen_ai.provider.name=strands-agents). No extra instrumentation package. Maple reads session.id (then gen_ai.conversation.id) as the session key, and reads span ATTRIBUTES only (never span events).

Step 0: Detect

1. Language and version.
   • Python: python -c "from importlib.metadata import version; print(version('strands-agents'))" or read pyproject.toml / uv.lock / requirements*.txt. Need >= 1.51 (tested 1.57.1): span-attribute content needs 1.48, tool args/results 1.51. Older → upgrade; do not work around it.
   • TypeScript: @strands-agents/sdk in package.json (tested 1.19.0). Follow Step 2 TS.
2. Existing OTel setup. Search for StrandsTelemetry(, TracerProvider(, set_tracer_provider, opentelemetry-instrument, aws-opentelemetry-distro, logfire.configure, sentry_sdk.init, setupTracer(, NodeSDK(, NodeTracerProvider(.
   • StrandsTelemetry().setup_otlp_exporter() already present → reuse it; only change env vars.
   • Another global provider exists (web framework, opentelemetry-instrument, ADOT on AgentCore) → do NOT call StrandsTelemetry(). Add BatchSpanProcessor(OTLPSpanExporter(endpoint=".../v1/traces", headers={...})) to that provider. Strands uses the global provider automatically.
   • Nothing → Step 2.
3. Find: every Agent( construction (and whether it is module-level/shared), every place the agent is invoked, where the chat/thread/conversation id lives in the request, every session_manager=, every .as_tool(, Swarm(, GraphBuilder( / Graph(.
4. Other instrumentors on the same model calls (OpenLIT, OpenLLMetry Traceloop.init, OpenInference, opentelemetry-instrumentation-openai*, botocore/Bedrock GenAI instrumentation) → they double-trace model calls. Keep Strands' spans; ask before removing the others if they serve something else.

Step 1: Key and region