AutoGen / AG2

Available for: Python and TypeScript.

Python
TypeScript

Installation

pip install zespan autogen-agentchat

Usage

Wrap any ConversableAgent (or subclass) with wrap_autogen_agent. The wrapper patches generate_reply to trace every agent response.

import zespan
from zespan.integrations.autogen_handler import wrap_autogen_agent
from autogen import AssistantAgent, UserProxyAgent

zespan.init(api_key="zsp_your_api_key_here")

assistant = AssistantAgent(
    name="assistant",
    llm_config={"model": "gpt-4o", "api_key": "your_openai_key"},
)
assistant = wrap_autogen_agent(assistant)

user_proxy = UserProxyAgent(
    name="user_proxy",
    human_input_mode="NEVER",
    max_consecutive_auto_reply=3,
)

user_proxy.initiate_chat(assistant, message="Explain gradient descent.")

With guardrails

Pass guardrails=True to run pre/post content checks on each agent reply.

from zespan.integrations.autogen_handler import wrap_autogen_agent
from zespan import GuardrailBlockedError

assistant = wrap_autogen_agent(assistant, guardrails=True)

For fine-grained control:

assistant = wrap_autogen_agent(assistant, guardrails={
    "pre": True,
    "post": True,
    "fail_closed": False,
})

Wrap each agent individually. wrap_autogen_agent patches only the agent it receives — other agents in the conversation are not automatically traced.

Agent steps

Each agent span records zespan.agent.step (the number of replies that agent has generated so far), zespan.agent.max_steps (its max_consecutive_auto_reply, when it is a positive integer) and a stop reason: max_steps when the reply count reaches that limit, error when generating the reply failed. With the zespan-autogen middleware, the conversation span records the message count as the step and maps the team’s own stop text to done, max_steps, timeout, handoff or interrupted (no text, only that fixed value), and a handoff span records the target agent as its route. See Agent steps.

For Node.js services that receive HTTP calls from an AutoGen agent, use context helpers to propagate the trace across the HTTP boundary.Sending side — attach trace context to an outgoing message:

import { attachTraceToAutoGenMessage, zespan } from "@zespan/sdk";

zespan.init({ apiKey: process.env.ZESPAN_API_KEY! });

const message = { role: "user", content: "Process this request" };
const tracedMessage = attachTraceToAutoGenMessage(message, "delegating to Node service");

// Send tracedMessage to the downstream AutoGen agent over HTTP
await fetch("http://agent-service/reply", {
  method: "POST",
  body: JSON.stringify(tracedMessage),
});

Receiving side — extract trace context from an incoming message:

import { extractTraceFromAutoGenMessage, zespan } from "@zespan/sdk";

export async function POST(req: Request) {
  const message = await req.json();
  extractTraceFromAutoGenMessage(message);

  // All LLM calls made here now link back to the upstream AutoGen trace
  const result = await processMessage(message);
  return Response.json(result);
}

Overview

CLI

TypeScript SDK

Python SDK

Advanced SDK Configuration

Integrations

LLM Providers

Agent Frameworks

RAG Frameworks

Gateways

Vector Databases

Custom / Other

Guides

Installation

Usage

With guardrails

Agent steps

​Installation

​Usage

​With guardrails

​Agent steps

Installation

Usage

With guardrails

Agent steps