Skip to content

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.

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:

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")

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")

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.