AG2 Integration

AG2HookTracer registers read-only hooks on ConversableAgent instances to capture message sends, message context snapshots, state updates, and LLM/tool safeguard events. All hooks return their argument unmodified — purely observational.

Installation

pip install briefcase-ai
pip install ag2>=0.6.0
# or
pip install briefcase-ai[ag2]

Quick Setup with `auto()`

The simplest way to instrument AG2 agents is one line:

import briefcase_ai

briefcase_ai.auto("ag2")
# That's it — all AG2 agent activity is now traced.

Setup with `instrument_agent`

Use the instrument_agent convenience function to create a tracer and register hooks in one step:

from briefcase_ai.integrations.frameworks import ag2_hook

tracer = ag2_hook.instrument_agent(agent, context_version="v2.1")

Constructor

AG2HookTracer(
    context_version: Optional[str] = None,
    async_capture: bool = True,
    capture_messages: bool = True,
    capture_llm: bool = True,
    capture_tools: bool = True,
    capture_state: 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_messages`	`True`	Capture message send and context hooks
`capture_llm`	`True`	Capture LLM input/output safeguard hooks
`capture_tools`	`True`	Capture tool input/output safeguard hooks
`capture_state`	`True`	Capture agent state update hooks
`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

`instrument(agent)`

`instrument_many(agents)`

Basic Usage

from autogen import ConversableAgent
from briefcase_ai.integrations.frameworks import AG2HookTracer

tracer = AG2HookTracer(context_version="v2.1")

assistant = ConversableAgent(
    name="assistant",
    system_message="You are a helpful assistant.",
    llm_config={"model": "gpt-4o"},
)
user_proxy = ConversableAgent(
    name="user_proxy",
    human_input_mode="NEVER",
)

# Register hooks on both agents
tracer.instrument(assistant)
tracer.instrument(user_proxy)

user_proxy.initiate_chat(assistant, message="What is the capital of France?")

for record in tracer.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": "message_send",
    "captured_at": "2026-02-26T10:00:00Z",
    "inputs": {
        "content": "What is the capital of France?",
        "recipient": "assistant",
        "silent": false
    },
    "outputs": {},
    "context_version": "v2.1"
}

Hook Types

`decision_type`	Hook	Description
`message_send`	`process_message_before_send`	Outgoing message with recipient
`message_context`	`process_all_messages_before_reply`	Full message list before reply
`state_update`	`update_agent_state`	Agent state change
`llm_input`	`safeguard_llm_inputs`	Messages entering LLM
`llm_output`	`safeguard_llm_outputs`	Response from LLM
`tool_input`	`safeguard_tool_inputs`	Tool call arguments
`tool_output`	`safeguard_tool_outputs`	Tool call result

Multi-Agent Setup

tracer = AG2HookTracer()

agents = [coordinator, analyst, writer]
tracer.instrument_many(agents)

# Initiate multi-agent conversation
coordinator.initiate_chat(analyst, message="Start analysis.")

Export

from briefcase_ai.config import setup
from briefcase_ai.exporters import SplunkHECExporter

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

tracer = AG2HookTracer(async_capture=True)
tracer.instrument(agent)

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)
`instrument(agent)`	`None`	Register hooks on one agent
`instrument_many(agents)`	`None`	Register hooks on multiple agents

Module-level convenience function

from briefcase_ai.integrations.frameworks.ag2_handler import instrument_agent

tracer = instrument_agent(
    agent,
    context_version: Optional[str] = None,
    async_capture: bool = True,
) -> AG2HookTracer

Advanced: Per-Instance Exporter

Override the global exporter for this tracer instance:

from briefcase_ai.exporters import SplunkHECExporter

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

Troubleshooting

ImportError: ag2 is required: Install with pip install ag2>=0.6.0. The tracer raises at instantiation time if ag2/autogen is absent.

No records captured: Ensure instrument() is called before the agents start communicating. Hooks only observe messages sent after registration.

Hooks return original value: AG2 hooks must return their argument unmodified. AG2HookTracer always returns the original value — it never modifies messages or tool calls.

Installation​

Quick Setup with auto()​

Setup with instrument_agent​

Constructor​

instrument(agent)​

instrument_many(agents)​

Basic Usage​

Record Format​

Hook Types​

Multi-Agent Setup​

Export​

Public API​

Module-level convenience function​

Advanced: Per-Instance Exporter​

Troubleshooting​

See Also​