docs/guides/integration.md

Integration Pattern

Use the integration pattern when you have an existing agent (browser-use, LangChain, Claude Code, the Anthropic SDK, or a custom framework) and want to add ACE learning on top.

!!! note "Full Pipeline vs Integration" The Full Pipeline uses all three ACE roles. The integration pattern skips the ACE Agent — your external agent handles execution, and ACE only learns from the results.

Three Steps

Every integration follows the same pattern:

1. INJECT   — Add skillbook strategies to the agent's context
2. EXECUTE  — Run the external agent normally
3. LEARN    — Reflector + SkillManager update the skillbook

Using Built-In Runners

ACE provides runners for popular frameworks. Each uses from_model() for quick setup or from_roles() for full control:

=== "Browser-Use"

```python
from ace import BrowserUse
from langchain_openai import ChatOpenAI

runner = BrowserUse.from_model(
    browser_llm=ChatOpenAI(model="gpt-4o"),
    ace_model="gpt-4o-mini",
)
results = runner.run(["Find top HN post", "Check weather in NYC"])
runner.save("browser_expert.json")
```

=== "LangChain"

```python
from ace import LangChain

runner = LangChain.from_model(your_chain, ace_model="gpt-4o-mini")
results = runner.run([{"input": "Summarize this document"}])
runner.save("chain_expert.json")
```

=== "Claude Code"

```python
from ace import ClaudeCode

runner = ClaudeCode.from_model(working_dir="./my_project")
results = runner.run(["Add tests for utils.py", "Fix the login bug"])
runner.save("code_expert.json")
```

Direct SDK Steps

The Anthropic SDK integration is step-based rather than runner-based. Use it when you want direct Messages API access, tool use, validated result models, and Logfire observability inside your own pipeline:

from ace import Pipeline, Reflector, SkillManager, Skillbook, learning_tail
from ace.integrations import ClaudeSDKExecuteStep, ClaudeSDKToTrace

skillbook = Skillbook()
pipe = Pipeline([
    ClaudeSDKExecuteStep(model="claude-sonnet-4-20250514"),
    ClaudeSDKToTrace(),
    *learning_tail(Reflector("gpt-4o-mini"), SkillManager("gpt-4o-mini"), skillbook),
])

Construction Patterns

All integration runners offer two construction paths:

from_model() — Quick Setup

Builds ACE roles automatically from a model string:

runner = BrowserUse.from_model(
    browser_llm=ChatOpenAI(model="gpt-4o"),
    ace_model="gpt-4o-mini",       # Model for Reflector + SkillManager
    skillbook_path="saved.json",   # Optional: resume from saved skillbook
)

from_roles() — Full Control

Provide pre-built role instances:

from ace import Reflector, SkillManager

runner = BrowserUse.from_roles(
    browser_llm=ChatOpenAI(model="gpt-4o"),
    reflector=Reflector("gpt-4o-mini"),
    skill_manager=SkillManager("gpt-4o-mini"),
    skillbook_path="saved.json",
    dedup_config=my_dedup_config,
    checkpoint_dir="./checkpoints",
)

Common Options

All integration runners share these parameters:

Parameter	Description	Default
skillbook	Existing Skillbook instance	None (creates empty)
skillbook_path	Path to load skillbook from	None
dedup_config	Deduplication configuration	None
dedup_interval	Samples between dedup runs	10
checkpoint_dir	Directory for checkpoint files	None
checkpoint_interval	Samples between checkpoints	10

Lifecycle Methods

All runners expose:

runner.save("path.json")              # Save skillbook
runner.wait_for_background()          # Wait for async learning
runner.learning_stats                 # Background progress dict
runner.skillbook                      # Current Skillbook instance
runner.get_strategies()               # Formatted strategies string

Building a Custom Integration

For frameworks not covered by the built-in runners, you can compose a custom pipeline using steps.

The pattern: Execute Step (runs your agent) + ToTrace Step (extracts learning signal) + learning_tail() (standard learning pipeline).

from pipeline import Pipeline
from ace import Skillbook, Reflector, SkillManager
from ace.steps import learning_tail
from ace.runners import ACERunner

# Your custom execute step would implement the Step protocol
# See the Pipeline Engine docs for details on building custom steps

skillbook = Skillbook()

steps = [
    MyCustomExecuteStep(...),
    MyCustomToTraceStep(),
    *learning_tail(
        Reflector("gpt-4o-mini"),
        SkillManager("gpt-4o-mini"),
        skillbook,
    ),
]

runner = ACERunner(pipeline=Pipeline(steps), skillbook=skillbook)

See Pipeline Engine: Building Custom Steps for the Step protocol.

What to Read Next

• LiteLLM Integration — simplest self-improving agent
• Browser-Use Integration — browser automation details
• LangChain Integration — chain/agent wrapping
• Claude Code Integration — coding tasks
• Claude SDK Integration — direct Anthropic API steps