AutoGen v0.4+ Integration

AutoGenEventHandler subclasses logging.Handler and attaches to AutoGen's EVENT_LOGGER_NAME and TRACE_LOGGER_NAME loggers to capture agent messages, tool calls, and control events without modifying agent code.

Installation

pip install briefcase-ai
pip install autogen-agentchat>=0.4.0
# or
pip install briefcase-ai[autogen]

Quick Setup with `auto()`

The simplest way to instrument AutoGen is one line:

import briefcase_ai

briefcase_ai.auto("autogen")
# That's it — all AutoGen agent events are now traced.

Setup with `install()`

Use install() to attach the handler globally. It is idempotent — calling it multiple times returns the same handler instance.

from briefcase_ai.integrations.frameworks import autogen_hook

handler = autogen_hook.install()

Or import directly:

from briefcase_ai.integrations.frameworks.autogen_handler import install

handler = install(context_version="v2.1", async_capture=True)

Constructor

AutoGenEventHandler(
    context_version: Optional[str] = None,
    async_capture: bool = True,
    capture_events: bool = True,
    capture_traces: bool = True,
    max_input_chars: int = 10000,
    max_output_chars: int = 10000,
    exporter: Optional[BaseExporter] = None,
)

Parameter	Default	Description
`context_version`	`None`	Version tag added to all decision records
`async_capture`	`True`	Export in a background daemon thread
`capture_events`	`True`	Capture records from `EVENT_LOGGER_NAME`
`capture_traces`	`True`	Capture records from `TRACE_LOGGER_NAME`
`max_input_chars`	`10000`	Maximum length of captured input strings
`max_output_chars`	`10000`	Maximum length of captured output strings
`exporter`	`None`	Per-instance BaseExporter override

`attach()`

Attach this handler to both AutoGen loggers and set their level to DEBUG.

`detach()`

Remove this handler from all attached loggers.

Basic Usage

import asyncio
from autogen_agentchat.agents import AssistantAgent, UserProxyAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.conditions import MaxMessageTermination
from autogen_ext.models import OpenAIChatCompletionClient
from briefcase_ai.integrations.frameworks import autogen_hook

handler = autogen_hook.install(context_version="v2.1")

model_client = OpenAIChatCompletionClient(model="gpt-4o")

assistant = AssistantAgent("assistant", model_client=model_client)
user_proxy = UserProxyAgent("user_proxy")

team = RoundRobinGroupChat(
    [assistant, user_proxy],
    termination_condition=MaxMessageTermination(3),
)

async def run():
    await team.run(task="Summarize recent AI safety research.")

asyncio.run(run())

for record in handler.get_records():
    print(f"{record['decision_type']}: {record['captured_at']}")

Record Format

Each record is a Dict[str, Any]:

{
    "decision_id": "uuid-string",
    "decision_type": "text_message",
    "captured_at": "2026-02-26T10:00:00Z",
    "logger": "autogen_agentchat.event",
    "inputs": {
        "source": "assistant",
        "content": "Here is a summary of AI safety research..."
    },
    "outputs": {},
    "context_version": "v2.1"
}

Event Types

`decision_type`	AutoGen event	Key fields
`text_message`	`TextMessage`	`source`, `content`
`tool_call_request`	`ToolCallRequestEvent`	`source`, `tool_calls`
`tool_call_execution`	`ToolCallExecutionEvent`	`source`, `results`
`tool_call_summary`	`ToolCallSummaryMessage`	`source`, `content`
`control_message`	`StopMessage` / `HandoffMessage`	`source`, `content`, `subtype`
`autogen_event`	Unknown / raw	`type`, `raw`

Export

from briefcase_ai.config import setup
from briefcase_ai.exporters import SentinelConnector

setup(
    exporter=SentinelConnector(
        workspace_id="your-workspace-id",
        shared_key="your-shared-key",
    )
)

handler = autogen_hook.install(async_capture=True)

Public API

Method	Returns	Description
`get_records()`	`List[Dict[str, Any]]`	All captured decision records
`clear()`	`None`	Reset all records
`decision_count`	`int`	Number of captured records (property)
`attach()`	`None`	Attach to AutoGen event and trace loggers
`detach()`	`None`	Remove from all attached loggers

Module-level function

from briefcase_ai.integrations.frameworks.autogen_handler import install

install(
    context_version: Optional[str] = None,
    async_capture: bool = True,
) -> AutoGenEventHandler

Advanced: Per-Instance Exporter

Override the global exporter for this handler instance:

from briefcase_ai.exporters import SplunkHECExporter

handler = AutoGenEventHandler(
    exporter=SplunkHECExporter(url="https://splunk.example.com:8088", token="your-hec-token"),
)

Troubleshooting

ImportError: autogen-agentchat is required: Install with pip install autogen-agentchat>=0.4.0. The handler raises at instantiation time if the package is absent.

No records captured: Call attach() or install() before your agent team runs. The handler only observes log records emitted after it is attached.

Double installation: install() is idempotent — it returns the existing handler without re-attaching. Use install() rather than manually calling attach() more than once.

Handler not detached after tests: Call handler.detach() in test teardown to avoid handler leaks across tests.

Installation​

Quick Setup with auto()​

Setup with install()​

Constructor​

attach()​

detach()​

Basic Usage​

Record Format​

Event Types​

Export​

Public API​

Module-level function​

Advanced: Per-Instance Exporter​

Troubleshooting​

See Also​