> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AutoGen / AG2

> Trace AutoGen agent conversations with Zespan. Wrap individual agents to capture replies, latency, and guardrail checks.

<Note>
  Available for: **Python** and **TypeScript**.
</Note>

<Tabs>
  <Tab title="Python">
    ## Installation

    ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
    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.

    ```python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
    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.

    ```python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
    from zespan.integrations.autogen_handler import wrap_autogen_agent
    from zespan import GuardrailBlockedError

    assistant = wrap_autogen_agent(assistant, guardrails=True)
    ```

    For fine-grained control:

    ```python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
    assistant = wrap_autogen_agent(assistant, guardrails={
        "pre": True,
        "post": True,
        "fail_closed": False,
    })
    ```

    <Note>
      Wrap each agent individually. `wrap_autogen_agent` patches only the agent it receives — other agents in the conversation are not automatically traced.
    </Note>
  </Tab>

  <Tab title="TypeScript">
    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:

    ```typescript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
    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:

    ```typescript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
    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);
    }
    ```
  </Tab>
</Tabs>