AutoGen / AG2 - Zespan

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.

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);
}

​Installation

​Usage

​With guardrails

Installation

Usage

With guardrails