AGENT CONTROL PLANE
A control-plane instrumentation framework for AI agents. ACP provides deterministic recording, replay, and debugging of agent execution—making AI behavior observable, testable, and reproducible.
What is a Control Plane?
In distributed systems, the control plane manages how things work, not what they do. ACP applies this concept to AI agents: it observes and records agent behavior without modifying the agent's logic, enabling forensic debugging and deterministic replay.
Instrument
Decorator-based instrumentation that captures every LLM call, tool invocation, and state change.
Debug
Timeline visualization, state inspection, and diff comparison for forensic debugging.
Analyze
Command-line utilities for inspection, replay, testing, and automated analysis.
CORE CONCEPTS
Run
A single execution session of an agent. Each run generates a unique run_<uuid> directory containing all recorded artifacts. Runs are immutable once stopped.
Step
An atomic unit of execution within a run. Each step captures a specific phase:
[REASON]LLM thought processes
[TOOL]Tool executions
[OBSERVE]Environment inputs
[MEMORY]State updates
[RETRY]Retry attempts
[TERMINATE]Run completion
Snapshot
A point-in-time capture of the agent's complete memory state. Snapshots are immutable and referenced by step IDs, enabling exact state reconstruction during replay.
Trace
The complete record of a run, consisting of metadata, steps, and snapshots. Traces are the single source of truth for agent behavior and enable deterministic replay.
QUICK START
1 Install the SDK
pip install acp-sdk2 Instrument Your Agent
import acp
# Initialize a recording session
acp.init(
agent_version="v1.0.0",
llm="gpt-4",
seed=42,
tools=["search", "calculator"]
)
# Instrument tools with automatic capture
@acp.tool(retry_policy=2)
def search(query: str) -> str:
"""Search results are automatically recorded."""
return external_search_api(query)
# Wrap LLM calls
@acp.llm_wrapper
def call_llm(prompt: str) -> str:
"""Prompts and responses are captured."""
return openai.chat(prompt)
# Run your agent logic
try:
with acp.step("reason") as ctx:
thought = call_llm("What should I do?")
ctx.set_output("thought", thought)
result = search("latest news")
with acp.step("observe"):
acp.update_memory([{"role": "tool", "content": result}])
finally:
# Flush and close the trace
acp.stop(reason="success")3 View the Trace
acp listacp inspect traces/run_abc123/4 Replay Deterministically
acp replay traces/run_abc123/Replay reads from recorded artifacts—no API calls are made.
5 Debug in VS Code
Open the trace folder in VS Code and run:
ACP: Open Agent Runvia Command Palette (Ctrl+Shift+P)EXPLICIT NON-GOALS
ACP is a control plane, not an agent framework. It explicitly does NOT:
- ✕Execute agents or manage their runtime
- ✕Modify code or rewrite prompts
- ✕Auto-fix logic or retry loops
- ✕Hallucinate explanations for behavior
- ✕Apply changes to agent source code
- ✕Inject system instructions or modify behavior
- ✕Simulate counterfactuals during normal operation