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.

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

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

2. Implement the Main Trace Class

In the main trace class, there should be a method each agentic framework. Each method should return a traced Runner if the framework is supported, or None if not. The traced Runner should extend the base Runner for that framework and wrap execution with tracing spans.

# ak-py/src/agentkernel/trace/<provider>/<provider>.py
import logging
from agentkernel.core.base import Runner
from agentkernel.trace.base import BaseTrace

logger = logging.getLogger("ak.trace.<provider>")


class <Provider>(BaseTrace):
    """<Provider> tracing implementation for Agent Kernel."""

    def __init__(self):
        logger.info("Initializing <Provider> tracing")
        # Initialize the tracing client/SDK
        # e.g., self._client = ProviderClient()

    def init(self):
        """Initialize the tracing backend. Called once at startup."""
        # Set up any global instrumentation
        # e.g., self._client.configure(api_key=os.getenv("PROVIDER_API_KEY"))
        pass

    def openai(self) -> Runner | None:
        """Return a traced runner for OpenAI framework, or None if not supported."""
        try:
            from .openai import <Provider>OpenAIRunner
            return <Provider>OpenAIRunner(self._client)
        except ImportError:
            logger.warning("OpenAI tracing dependencies not available")
            return None

    def langgraph(self) -> Runner | None:
        try:
            from .langgraph import <Provider>LangGraphRunner
            return <Provider>LangGraphRunner(self._client)
        except ImportError:
            return None

    def crewai(self) -> Runner | None:
        try:
            from .crewai import <Provider>CrewAIRunner
            return <Provider>CrewAIRunner(self._client)
        except ImportError:
            return None

    def adk(self) -> Runner | None:
        try:
            from .adk import <Provider>ADKRunner
            return <Provider>ADKRunner(self._client)
        except ImportError:
            return None

    def smolagents(self) -> Runner:
        from .smolagents import <Provider>SmolagentsRunner

        return <Provider>SmolagentsRunner(self._client)