Skip to main content

TraceAI AutoGen Instrumentation

OpenTelemetry instrumentation for Microsoft AutoGen, providing comprehensive tracing for multi-agent conversations, tool executions, and LLM interactions.

Supports both AutoGen v0.2 (legacy) and v0.4 (AgentChat).

Installation

pip install traceAI-autogen

AutoGen Versions

This package supports both major AutoGen versions:

AutoGen v0.2 (legacy):

pip install "pyautogen>=0.2.0,<0.3"

AutoGen v0.4 (AgentChat):

pip install "autogen-agentchat>=0.4.0"
pip install "autogen-ext[openai]"

Quick Start

Set Environment Variables

import os

os.environ["FI_API_KEY"] = "your-api-key"
os.environ["FI_SECRET_KEY"] = "your-secret-key"
os.environ["OPENAI_API_KEY"] = "your-openai-key"

Register Tracer Provider

from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType

trace_provider = register(
    project_type=ProjectType.OBSERVE,
    project_name="autogen_app"
)

Instrument AutoGen

from traceai_autogen import AutogenInstrumentor

AutogenInstrumentor().instrument(tracer_provider=trace_provider)

Or use the convenience function:

from traceai_autogen import instrument_autogen

instrumentor = instrument_autogen(tracer_provider=trace_provider)

Examples

AutoGen v0.2 (Legacy)

import autogen
from traceai_autogen import instrument_autogen

# Instrument AutoGen
instrument_autogen()

# Configure LLM
llm_config = {
    "config_list": [{"model": "gpt-4", "api_key": os.environ["OPENAI_API_KEY"]}],
    "temperature": 0,
}

# Create agents
assistant = autogen.AssistantAgent(
    name="assistant",
    llm_config=llm_config,
    system_message="You are a helpful AI assistant."
)

user_proxy = autogen.UserProxyAgent(
    name="user_proxy",
    human_input_mode="NEVER",
    max_consecutive_auto_reply=3,
    code_execution_config={"work_dir": "coding", "use_docker": False},
)

# Start conversation - automatically traced
chat_result = user_proxy.initiate_chat(
    assistant,
    message="Write a Python function to calculate fibonacci numbers."
)

AutoGen v0.4 (AgentChat)

import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.conditions import MaxMessageTermination
from autogen_ext.models.openai import OpenAIChatCompletionClient
from traceai_autogen import instrument_autogen

# Instrument AutoGen
instrument_autogen()

async def main():
    # Create model client
    model_client = OpenAIChatCompletionClient(model="gpt-4o")

    # Create agents
    coder = AssistantAgent(
        name="coder",
        model_client=model_client,
        system_message="You are a Python expert. Write clean, efficient code.",
    )

    reviewer = AssistantAgent(
        name="reviewer",
        model_client=model_client,
        system_message="You review code and suggest improvements.",
    )

    # Create team
    team = RoundRobinGroupChat(
        participants=[coder, reviewer],
        termination_condition=MaxMessageTermination(max_messages=6),
    )

    # Run team task - automatically traced
    result = await team.run(task="Write a Python class for a binary search tree.")

    print(result.messages[-1].content)

asyncio.run(main())

AutoGen v0.4 with Tools

import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient
from traceai_autogen import instrument_autogen

instrument_autogen()

# Define tools
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"The weather in {city} is sunny and 72F."

def search_web(query: str) -> str:
    """Search the web for information."""
    return f"Search results for: {query}"

async def main():
    model_client = OpenAIChatCompletionClient(model="gpt-4o")

    agent = AssistantAgent(
        name="assistant",
        model_client=model_client,
        tools=[get_weather, search_web],
        system_message="You are a helpful assistant with access to tools.",
    )

    # Tool calls are automatically traced
    response = await agent.on_messages(
        [{"role": "user", "content": "What's the weather in San Francisco?"}],
        cancellation_token=None
    )

    print(response.chat_message.content)

asyncio.run(main())

AutoGen v0.4 with Streaming

import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_ext.models.openai import OpenAIChatCompletionClient
from traceai_autogen import instrument_autogen

instrument_autogen()

async def main():
    model_client = OpenAIChatCompletionClient(model="gpt-4o")

    agent = AssistantAgent(
        name="writer",
        model_client=model_client,
        system_message="You are a creative writer.",
    )

    team = RoundRobinGroupChat(participants=[agent])

    # Streaming is also traced
    async for message in team.run_stream(task="Write a haiku about coding"):
        print(message)

asyncio.run(main())

Multi-Agent Code Review Team

import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import SelectorGroupChat
from autogen_agentchat.conditions import MaxMessageTermination
from autogen_ext.models.openai import OpenAIChatCompletionClient
from traceai_autogen import instrument_autogen

instrument_autogen()

async def main():
    model = OpenAIChatCompletionClient(model="gpt-4o")

    # Create specialized agents
    architect = AssistantAgent(
        name="architect",
        model_client=model,
        system_message="You are a software architect. Design system architecture.",
    )

    developer = AssistantAgent(
        name="developer",
        model_client=model,
        system_message="You implement code based on architectural designs.",
    )

    tester = AssistantAgent(
        name="tester",
        model_client=model,
        system_message="You write tests and identify edge cases.",
    )

    # Selector-based team that picks the right agent
    team = SelectorGroupChat(
        participants=[architect, developer, tester],
        model_client=model,
        termination_condition=MaxMessageTermination(max_messages=10),
    )

    result = await team.run(
        task="Design and implement a REST API for a todo list application."
    )

    for msg in result.messages:
        print(f"{msg.source}: {msg.content[:100]}...")

asyncio.run(main())

Features

AutoGen v0.2 (Legacy) Features

  • Agent Conversations: Traces initiate_chat calls between agents
  • Reply Generation: Traces generate_reply for each agent response
  • Function Execution: Traces tool/function calls via execute_function
  • Full Context: Captures messages, responses, and metadata

AutoGen v0.4 (AgentChat) Features

  • Agent Runs: Traces on_messages for all agent types
  • Team Orchestration: Traces run and run_stream for teams
  • Tool Execution: Automatic tracing of tool function calls
  • Streaming Support: Full tracing for streaming responses
  • Handoffs: Traces agent handoffs in Swarm teams
  • Token Usage: Captures token metrics from responses

Traced Attributes

Agent Spans

Attribute Description
autogen.span_kind Type of span (agent_run, team_run, tool_call)
autogen.agent.name Agent name
autogen.agent.type Agent class name
autogen.agent.tool_count Number of tools available
autogen.agent.has_memory Whether agent has memory
gen_ai.request.model Model name

Team Spans

Attribute Description
autogen.team.type Team class name
autogen.team.participant_count Number of participants
autogen.team.participants JSON list of agent names
autogen.team.max_turns Maximum turns configured
autogen.team.termination_condition Termination condition type

Task/Run Spans

Attribute Description
autogen.run.id Unique run identifier
autogen.run.method Method name (run, run_stream)
autogen.task.content Task/prompt content
autogen.task.message_count Number of messages
autogen.task.stop_reason Why the task stopped

Tool Spans

Attribute Description
autogen.tool.name Tool function name
autogen.tool.description Tool description
autogen.tool.args Tool arguments (JSON)
autogen.tool.result Tool return value
autogen.tool.is_error Whether tool failed
autogen.tool.duration_ms Execution time

Usage Metrics (GenAI Conventions)

Attribute Description
gen_ai.usage.input_tokens Input/prompt tokens
gen_ai.usage.output_tokens Output/completion tokens
gen_ai.usage.total_tokens Total tokens used

Error Attributes

Attribute Description
autogen.is_error Whether an error occurred
autogen.error.type Exception type
autogen.error.message Error message

Model Provider Detection

The instrumentor automatically detects model providers:

Pattern Provider
gpt-*, o1-*, o3-* openai
claude-* anthropic
gemini* google
mistral* mistral
deepseek* deepseek
groq* groq
ollama* ollama

Uninstrumenting

from traceai_autogen import AutogenInstrumentor

instrumentor = AutogenInstrumentor()
instrumentor.instrument()

# ... use AutoGen ...

# Remove instrumentation
instrumentor.uninstrument()

Integration with FutureAGI

from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType
from traceai_autogen import AutogenInstrumentor

# Register with FutureAGI
trace_provider = register(
    api_key="your-api-key",
    project_type=ProjectType.OBSERVE,
    project_name="my-autogen-app",
)

# Instrument AutoGen
AutogenInstrumentor().instrument(tracer_provider=trace_provider)

Running Tests

Install development dependencies with poetry install, then run the commands below with poetry run. The suite uses real OpenTelemetry and offline SDK contracts; no provider key is required. Legacy contracts use pyautogen==0.2.35 on Python 3.10–3.12; AgentChat supports Python 3.13 as well. The legacy test file is not collected on 3.13 because that upstream distribution excludes it.

The compatibility repair restores the advertised legacy hooks, including their async counterparts, rather than removing legacy tests or changing the support policy. Real-SDK coverage includes keyword-only/task-less team calls, streaming and early close, concrete AssistantAgent hooks, cancellation, span parentage and usage, uninstrument/reinstrument, and legacy conversations/function execution.

# Run all tests
pytest tests/

# Run with verbose output
pytest tests/ -v

# Run specific test file
pytest tests/test_v04_wrapper.py -v

Requirements

  • Python >= 3.10, < 3.14 (legacy pyautogen requires < 3.13)
  • opentelemetry-api >= 1.0.0
  • opentelemetry-sdk >= 1.0.0
  • fi-instrumentation-otel >= 0.1.11

For v0.2: pyautogen >= 0.2.0, < 0.3 (import name: autogen) For v0.4: autogen-agentchat >= 0.4.0

License

MIT License - see LICENSE file for details.

Metadata

Release files for traceAI-autogen 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for traceAI-autogen 0.2.2
File Size Uploaded Provenance Actions
traceai_autogen-0.2.2.tar.gz 18.7 kB With provenance Details for traceai_autogen-0.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for traceAI-autogen 0.2.2
File Interpreter ABI Platform Actions
traceai_autogen-0.2.2-py3-none-any.whl Python 3 none any Details for traceai_autogen-0.2.2-py3-none-any.whl

Total release size: 36.6 kB

Release files / traceai_autogen-0.2.2.tar.gz

Download URL traceai_autogen-0.2.2.tar.gz
Size 18.7 kB
Tags Source
SHA-256 checksum
How to use checksums
2f5ad4d4d11364dce738b290ff102b2f88961a9639ffcfdc3708714f602ecab3
BLAKE2b-256 checksum
How to use checksums
9a0962b815a57fee0877438f71bcaf888dbf49550727bfba2b34c84cac522785
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / traceai_autogen-0.2.2-py3-none-any.whl

Download URL traceai_autogen-0.2.2-py3-none-any.whl
Size 17.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0a98078999caacf3a8941a197d7d2b2f612aa57f0f720a56d6e5b0a90347e6c3
BLAKE2b-256 checksum
How to use checksums
9cffd694ec40e29bde8b69695eb128afdb8db2fb6eaac0244060d5d53c0554ce
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for traceAI-autogen 0.2.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for traceai_autogen-0.2.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page