agent-kernel: Skill for Claude Code

Adding a New Tracing Provider

This guide walks through adding a new observability/tracing provider to Agent Kernel. Use the Langfuse implementation (ak-py/src/agentkernel/trace/langfuse/) as the canonical reference. For a backend reached through plain OpenTelemetry (no vendor SDK), see the CloudWatch provider (ak-py/src/agentkernel/trace/cloudwatch/): it installs its own SDK TracerProvider and OTLP exporter once (or reuses one already installed, since OpenTelemetry honours only the first), wraps each run through a span(name, session) context manager on the provider class that its runners receive, and adds a provider-specific helper module (sigv4.py) beside the runners.

Architecture Overview

Agent Kernel's tracing system:

1. BaseTrace (trace/base.py) defines the interface — one method per supported framework that returns a traced Runner (or None)
2. Trace (trace/trace.py) is a factory that creates the appropriate trace instance based on AKConfig.trace.type
3. Each framework Module checks for a trace runner at initialization — if tracing is enabled, it uses the traced runner instead of the default
4. Traced runners extend the base framework runner and wrap execution with spans/traces
5. BaseTrace.fetch_spans(query) (optional, not abstract) reads spans back from the provider's cloud as provider-neutral FetchedSpans; Trace.fetch_spans is the facade users call (Trace.get().fetch_spans(last=..., session_id=...)), and Trace.fetch_traces groups the same spans into FetchedTraces on top of it, so a provider implements only fetch_spans. A provider that only sends traces skips it and raises NotImplementedError (step 6)

Step-by-Step

1. Create the Trace Provider Directory

ak-py/src/agentkernel/trace/<provider>/
├── __init__.py
├── <provider>.py        # Main trace class
├── openai.py            # Traced OpenAI runner
├── langgraph.py         # Traced LangGraph runner
├── crewai.py            # Traced CrewAI runner
├── adk.py               # Traced Google ADK runner
├── smolagents.py        # Traced Smolagents runner
├── pydanticai.py        # Traced Pydantic AI runner
├── maf.py               # Traced Microsoft Agent Framework runner
├── claude.py            # Traced Claude Agent SDK runner
└── fetch.py             # Optional: <Provider>TraceFetcher, reads spans back (step 6)