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

# Monitor AutoGen Multi-Agent Systems with Agent Therapy

> Connect AutoGen multi-agent workflows to Agent Therapy to analyze conversations, detect coordination failures, and score each agent independently.

Multi-agent systems built with Microsoft AutoGen introduce failure modes that single-agent monitoring tools aren't designed to catch. When an `AssistantAgent` and a `UserProxyAgent` enter a reasoning loop, or two specialized agents repeatedly miscommunicate on task handoffs, you need visibility at the conversation level — not just per-model. Agent Therapy is purpose-built to detect inter-agent miscommunication, coordination loops, role confusion, and termination failures in AutoGen workflows, and to score each participating agent's behavior independently within the same session.

## Prerequisites

Before you begin, make sure you have the following:

* **AutoGen** installed in your Python environment (`pip install pyautogen`)
* An **Agent Therapy account** with an active API key — find yours in the [Agent Therapy dashboard](https://app.agenttherapy.ai/settings/api-keys)
* The `requests` library installed (`pip install requests`)

## Registering Each Agent

In multi-agent setups, register each participant agent separately in Agent Therapy so that the health dashboard can attribute behavioral findings to the correct agent. For example, if your workflow uses an `AssistantAgent` and a `UserProxyAgent`, create two Agent Therapy agent records and capture the `agent_id` for each.

```python theme={null}
import requests

AT_API_KEY = "at_..."
BASE_URL = "https://api.agenttherapy.ai/v1"


def register_agent(name: str, role_description: str) -> str:
    """Register an AutoGen agent in Agent Therapy and return its agent_id."""
    resp = requests.post(
        f"{BASE_URL}/agents",
        headers={
            "Authorization": f"Bearer {AT_API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "framework": "autogen",
            "model": "gpt-4o",
            "description": role_description,
        },
    )
    resp.raise_for_status()
    agent_id = resp.json()["id"]
    print(f"Registered '{name}' as {agent_id}")
    return agent_id


assistant_agent_id = register_agent(
    name="AutoGen AssistantAgent",
    role_description="Primary reasoning and task-planning agent",
)
proxy_agent_id = register_agent(
    name="AutoGen UserProxyAgent",
    role_description="Executes code and acts as the human proxy",
)
```

You only need to register each agent once. Save the returned `agent_id` values — you'll reference them every time you submit a session for this workflow.

## Capturing AutoGen Chat History

After a conversation ends, extract the message history from your `GroupChat` object or from a direct two-agent conversation. AutoGen stores each message as a dictionary with at minimum a `role` and `content` key.

```python theme={null}
import autogen

config_list = [{"model": "gpt-4o", "api_key": "sk-..."}]

assistant = autogen.AssistantAgent(
    name="assistant",
    llm_config={"config_list": config_list},
)
user_proxy = autogen.UserProxyAgent(
    name="user_proxy",
    human_input_mode="NEVER",
    max_consecutive_auto_reply=5,
)

groupchat = autogen.GroupChat(
    agents=[assistant, user_proxy],
    messages=[],
    max_round=12,
)
manager = autogen.GroupChatManager(groupchat=groupchat, llm_config={"config_list": config_list})

# Initiate the conversation
user_proxy.initiate_chat(manager, message="Write a Python function to compute Fibonacci numbers.")

# After the conversation ends, extract the chat history:
chat_history = groupchat.messages  # list of message dicts

logs = [
    {
        "role": msg["role"],
        "content": msg["content"],
        "timestamp": msg.get("timestamp", None),
    }
    for msg in chat_history
]
```

For direct two-agent conversations (without a `GroupChat`), use `user_proxy.chat_messages[assistant]` to retrieve the message list in the same dictionary format.

## Submitting Multi-Agent Sessions

When submitting a session that involves multiple agents, include the `participants` field in your request body. This tells Agent Therapy which registered agents were active in the conversation so it can score each one separately.

```python theme={null}
def submit_multi_agent_session(
    behavior_log: list,
    agent_ids: list,
    context: str = "",
) -> str:
    """Submit a multi-agent behavior log to Agent Therapy."""
    resp = requests.post(
        f"{BASE_URL}/sessions",
        headers={
            "Authorization": f"Bearer {AT_API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "agent_id": agent_ids[0],        # Primary agent for the session record
            "participants": agent_ids,        # All agents in the conversation
            "behavior_log": behavior_log,
            "context": context,
            "source": "autogen",
        },
    )
    resp.raise_for_status()
    session = resp.json()
    print(f"Session submitted: {session['id']} — status: {session['status']}")
    return session["id"]


session_id = submit_multi_agent_session(
    behavior_log=logs,
    agent_ids=[assistant_agent_id, proxy_agent_id],
    context="Fibonacci function generation — GroupChat round",
)
```

The `participants` list accepts any number of `agent_id` strings. Agent Therapy uses the `name` field in each agent's registry entry to attribute turns in the log — make sure the AutoGen agent `name` values match or are noted in the `context` field if they differ.

## Retrieving Session Results

After submitting a session, poll `GET /sessions/{id}` until the `status` field shows `"completed"`. The response includes the full transcript, behavioral findings, and individual health scores for each participant.

```python theme={null}
import time

def wait_for_session(session_id: str, poll_interval: int = 5) -> dict:
    """Poll Agent Therapy until the session analysis is complete."""
    while True:
        resp = requests.get(
            f"{BASE_URL}/sessions/{session_id}",
            headers={"Authorization": f"Bearer {AT_API_KEY}"},
        )
        resp.raise_for_status()
        session = resp.json()

        if session["status"] == "completed":
            return session

        print(f"Session {session_id} status: {session['status']} — waiting...")
        time.sleep(poll_interval)


result = wait_for_session(session_id)
print(f"Health score: {result['health_score']}")
for finding in result.get("findings", []):
    print(f"  [{finding['severity']}] {finding['title']}: {finding['description']}")
```

## Multi-Agent Health Dashboard

Once sessions are submitted with multiple `participants`, the Agent Therapy dashboard displays a **Workflow View** for that agent group. In this view:

* Each participating agent gets its own **health score trend** graph plotted over time
* Behavioral findings are tagged to the specific agent whose turns triggered them
* **Coordination metrics** appear at the workflow level, measuring things like turn balance, escalation frequency, and loop detection across the full conversation
* You can filter the session list by any individual participant to drill into one agent's behavior in isolation

Health scores update automatically as new sessions arrive, giving you a rolling view of how each agent in your workflow is performing over time.

> [!NOTE]
>
> **UserProxyAgent turns are treated as user input:** Because `UserProxyAgent` represents a human operator in AutoGen's design, Agent Therapy treats its turns as `user` role messages rather than `assistant` role messages. This means `UserProxyAgent` turns are not included in the assistant-side behavioral scoring. If your `UserProxyAgent` is making autonomous LLM-backed decisions (i.e., `human_input_mode="NEVER"` with an LLM config), set `"user_proxy_is_autonomous": true` in your session metadata so Agent Therapy scores those turns as agent output instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.