Skip to content

autogen.md

Latest commit

 

History

History
328 lines (244 loc) · 8.15 KB

autogen.md

File metadata and controls

328 lines (244 loc) · 8.15 KB

AutoGen Integration Guide

Automatic observability for AutoGen multi-agent conversations

Overview

The AutoGen adapter provides automatic tracing for:

  • ✅ Agent message passing
  • ✅ Multi-agent conversations
  • ✅ Group chats
  • ✅ State changes
  • ✅ Tool usage

Integration time: <5 minutes (just import and go!)

Quick Start

Installation

pip install agent-observability-kit pyautogen

Basic Usage (Auto-Detection)

from agent_observability import init_tracer
from autogen import AssistantAgent, UserProxyAgent

# 1. Initialize tracer (auto-detects AutoGen)
tracer = init_tracer(agent_id="my-autogen-system")

# 2. Create AutoGen agents
assistant = AssistantAgent(
    name="assistant",
    llm_config={"model": "gpt-4"},
)

user = UserProxyAgent(
    name="user",
    human_input_mode="NEVER",
)

# 3. Use AutoGen normally - automatically traced!
user.initiate_chat(
    assistant,
    message="What are the benefits of AI observability?"
)  # ← Every message is automatically traced!

# 4. View traces
# python server/app.py
# open http://localhost:5000

That's it! Every agent message, handoff, and conversation is automatically captured.

What Gets Captured

Message Sending

Every agent.send() creates a span capturing:

{
  "span_type": "multi_agent_handoff",
  "framework": "autogen",
  "inputs": {
    "sender": "user",
    "recipient": "assistant",
    "message": "What are the benefits of AI observability?"
  },
  "outputs": {
    "sent": true
  },
  "duration_ms": 120
}

Message Receiving

Every agent.receive() creates a span capturing:

{
  "span_type": "agent_decision",
  "framework": "autogen",
  "inputs": {
    "receiver": "assistant",
    "sender": "user",
    "message": "What are the benefits..."
  },
  "outputs": {
    "processed": true
  },
  "duration_ms": 450
}

Group Chat

Every GroupChat.run() creates a root trace capturing:

{
  "trace_id": "tr_abc123",
  "framework": "autogen",
  "metadata": {
    "agents": ["user", "assistant", "critic"],
    "max_round": 10
  },
  "spans": [...]
}

Advanced Usage

Manual Adapter Installation

Control when adapters are installed:

from agent_observability import init_tracer
from agent_observability.adapters.autogen import AutoGenAdapter

# Initialize without auto-detection
tracer = init_tracer(agent_id="my-system", auto_detect_frameworks=False)

# Manually install AutoGen adapter
adapter = AutoGenAdapter(tracer=tracer)
adapter.install()

Custom Metadata

Add context to conversations:

from agent_observability import trace

with trace("customer_support_conversation"):
    tracer.start_span(
        name="Handle support ticket",
        metadata={
            "ticket_id": "TKT-456",
            "customer": "jane@example.com",
            "priority": "high"
        }
    )
    
    user.initiate_chat(assistant, message="...")

Tracing Specific Conversations

Only trace important conversations:

from agent_observability import init_tracer

# Production conversations
prod_tracer = init_tracer(agent_id="production-agents")

# Development/testing - no traces
# (Don't initialize tracer)

Visualization

Execution Graph

AutoGen traces show conversation flow:

┌─────────────────────────────────────────────────────┐
│ GroupChat: 3 agents, 5 rounds                      │
├─────────────────────────────────────────────────────┤
│                                                     │
│   [Start]                                           │
│      ↓                                              │
│   ┌─────────────┐                                  │
│   │ 🟧 AutoGen  │ user → assistant                │
│   │ Message     │ 450ms                           │
│   └─────────────┘                                  │
│      ↓                                              │
│   ┌─────────────┐                                  │
│   │ 🟧 AutoGen  │ assistant → user                │
│   │ Response    │ 1.2s                            │
│   └─────────────┘                                  │
│      ↓                                              │
│   ┌─────────────┐                                  │
│   │ 🟧 AutoGen  │ user → critic                   │
│   │ Handoff     │ 200ms                           │
│   └─────────────┘                                  │
│      ↓                                              │
│   [Complete]                                        │
│                                                     │
│ Legend: 🟧 AutoGen                                 │
└─────────────────────────────────────────────────────┘

AutoGen-Specific Details

Click any span to see:

  • Sender: "user"
  • Recipient: "assistant"
  • Message Type: "text"
  • Auto-reply: Yes (3 remaining)
  • Conversation History: 12 messages

Performance

Overhead: <1% latency impact

# Benchmark (100 conversations, 5 messages each)
# Without tracing: 45.2s
# With tracing:    45.6s
# Overhead:        0.9%

Troubleshooting

"AutoGen is not installed" Error

Solution:

pip install pyautogen

Messages Not Appearing in Traces

Problem: Only some messages captured

Solution: Ensure both send() and receive() are called:

# ✅ Good - full conversation captured
user.initiate_chat(assistant, message="...")

# ⚠️ Partial - only send captured, not receive
agent.send(message, recipient)

Group Chat Not Creating Root Trace

Problem: Group chat spans scattered, no root trace

Solution: Use GroupChat.run() method (not manual message passing):

from autogen import GroupChat, GroupChatManager

# ✅ Good - creates root trace
group_chat = GroupChat(agents=[user, assistant, critic])
manager = GroupChatManager(groupchat=group_chat)
user.initiate_chat(manager, message="...")

# ❌ Bad - no root trace
for msg in messages:
    agent.send(msg, recipient)

Migration from Custom Logging

Before (Manual logging):

import json

def log_message(sender, recipient, message):
    with open("conversation.jsonl", "a") as f:
        json.dump({
            "sender": sender,
            "recipient": recipient,
            "message": message
        }, f)
        f.write("\n")

# Manual logging everywhere ❌
agent.send(message, recipient)
log_message(agent.name, recipient.name, message)

After (Agent Observability Kit):

from agent_observability import init_tracer

tracer = init_tracer(agent_id="my-system")

# Automatic tracing! ✅
agent.send(message, recipient)  # Logged automatically

Benefits:

  • ✅ No boilerplate
  • ✅ Visual UI (not just JSONL)
  • ✅ LLM call tracking
  • ✅ Error capture
  • ✅ Multi-framework support

Examples

See examples/autogen_example.py for a complete working example.

Multi-Framework Usage

AutoGen works great with other frameworks:

from agent_observability import init_tracer

# Auto-detects AutoGen + LangChain + CrewAI
tracer = init_tracer(agent_id="hybrid-system")

# LangChain classifies intent
intent = langchain_chain.run(query)

# AutoGen refines the response
assistant.generate_reply([{"content": intent, "role": "user"}])

# Single trace shows BOTH frameworks! 🎉

See examples/multi_framework_example.py for details.

Support

Issues? github.com/reflectt/agent-observability-kit/issues

Questions? discord.gg/openclaw