Maple agent tracing: OpenAI, Anthropic and Gemini SDKs

Goal: every conversation = one Maple Agent Session. Each user message = one turn = one trace rooted at an invoke_agent <agent> span, containing a chat <model> / generate_content <model> span per model call (transcript + tokens) and an execute_tool <tool> span per tool call (args, result, failures).

Mechanism:

• Python: OpenTelemetry GenAI instrumentations (opentelemetry-instrumentation-genai-openai, -genai-anthropic, opentelemetry-instrumentation-google-genai, all >= 1.2b0) write chat spans with GenAI semconv on span attributes.
• TypeScript: no usable instrumentation (@opentelemetry/instrumentation-openai only patches openai < 7 and puts messages in log events; nothing official for @anthropic-ai/sdk / @google/genai). Record the model call with the helper in references/typescript.md.
• Both: YOU add the invoke_agent span (with gen_ai.conversation.id) and execute_tool spans.

Step 0: Detect

1. Confirm there is NO agent framework: openai-agents/@openai/agents, langchain*, langgraph, pydantic-ai*, crewai, llama-index*, ai (Vercel), @mastra/core, google-adk, strands-agents, smolagents, agno, dspy, haystack-ai, agent-framework, litellm. If one is present, stop and use that framework's skill (npx skills add MapleTechLabs/maple/skills --skill maple-agent-tracing -y routes). Instrumenting the provider SDK under a framework double-records every call.
2. Language and SDK versions:
   • Python >= 3.10. openai < 4 (tested 3.20.0), anthropic < 2 (tested 1.8.0), google-genai < 3 (tested 2.25.0). Outside these ranges the instrumentation won't patch: tell the user.
   • TypeScript: openai 7.x (tested 7.23.0). Anthropic / Gemini: adapt the helper (see reference).
3. Existing OTel setup. Search for TracerProvider(, set_tracer_provider, NodeSDK(, NodeTracerProvider, registerOTel, opentelemetry-instrument, logfire.configure, sentry_sdk.init / Sentry.init, Traceloop.init.
   • A provider exists → add a BatchSpanProcessor(OTLPSpanExporter()) to it; do NOT create a second provider.
4. Other instrumentations of the same SDK → duplicate model-call spans. Look for: opentelemetry-instrumentation-openai / -anthropic (OpenLLMetry, NOT the official ones), opentelemetry-instrumentation-openai-v2 (deprecated), openinference-instrumentation-*, @arizeai/openinference-*, @traceloop/*, logfire.instrument_openai/anthropic, Sentry OpenAI/Anthropic integrations, langfuse.openai. Keep exactly one; ask before removing one that serves something else.
5. Find: every model call site, the agent loop(s), the tool dispatch, where the conversation/thread id lives per request, any agent that calls another agent (sub-agent), any streaming call.