Getting Started

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.

Fundamentals

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.

5-Minute Guide

QUICK START

1 Install the SDK

pip install acp-sdk

2 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

# List generated traces
acp list
# Inspect a specific trace
acp 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