Spaces:
Sleeping
Sleeping
File size: 5,548 Bytes
116524e | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 | # 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](full-pipeline.md) 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:
```python
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:
```python
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:
```python
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:
```python
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).
```python
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](../pipeline/custom-steps.md) for the Step protocol.
## What to Read Next
- [LiteLLM Integration](../integrations/litellm.md) — simplest self-improving agent
- [Browser-Use Integration](../integrations/browser-use.md) — browser automation details
- [LangChain Integration](../integrations/langchain.md) — chain/agent wrapping
- [Claude Code Integration](../integrations/claude-code.md) — coding tasks
- [Claude SDK Integration](../integrations/claude-sdk.md) — direct Anthropic API steps
|