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"

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.1

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.1
File Size Uploaded Provenance Actions
traceai_autogen-0.2.1.tar.gz 18.1 kB With provenance Details for traceai_autogen-0.2.1.tar.gz

Built distribution (wheel)

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

Total release size: 35.5 kB

Release files / traceai_autogen-0.2.1.tar.gz

Download URL traceai_autogen-0.2.1.tar.gz
Size 18.1 kB
Tags Source
SHA-256 checksum
How to use checksums
52c8abccc888cc35b07918cd4add7dcfec6b9cbaecfaee98f733d0b7333e614e
BLAKE2b-256 checksum
How to use checksums
452c2fa2adb9212e148226c01da0b396a14e15ff532ed0094187b5cb311d8754
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 Oct 31, 2026.

Transparency log

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

Download URL traceai_autogen-0.2.1-py3-none-any.whl
Size 17.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b94932ab7f12ad56307ad6899f03d7d766e9e1feb7b243a7c65f8a812097b14e
BLAKE2b-256 checksum
How to use checksums
ffa289a2e0694ac9875a8f21e6eebeea27d03978ea16be3f006048d70dceeecf
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 Oct 31, 2026.

Transparency log

Security for traceAI-autogen 0.2.1

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.1.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 Oct 31, 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