Spaces:
Sleeping
Sleeping
File size: 3,918 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 | # Three Roles
ACE uses three collaborative roles that share the same base LLM. Each role has a specialized prompt that focuses it on a specific part of the learning loop.
```mermaid
graph LR
A[Agent] -->|execute| E[Environment]
E -->|evaluate| R[Reflector]
R -->|analyze| SM[SkillManager]
SM -->|update| SK[Skillbook]
```
## Agent
**Produces answers** using the current skillbook.
The Agent receives a question, context, and the skillbook's strategies, then generates a reasoned answer citing which skills it used.
```python
from ace import Agent
agent = Agent("gpt-4o-mini")
output = agent.generate(
question="What is 2+2?",
context="Show your work",
skillbook=skillbook,
reflection=None, # Optional: reflection from a previous attempt
)
```
### AgentOutput
| Field | Type | Description |
|-------|------|-------------|
| `final_answer` | `str` | The generated answer |
| `reasoning` | `str` | Step-by-step reasoning |
| `skill_ids` | `List[str]` | Skillbook strategies cited |
| `raw` | `Dict` | Raw LLM response |
## Reflector
**Analyzes execution outcomes** — what worked, what failed, and why.
The Reflector receives the agent's output, the environment's feedback, and the skillbook. It produces an analysis of the outcome and tags each cited skill as helpful, harmful, or neutral.
```python
from ace import Reflector
reflector = Reflector(llm)
reflection = reflector.reflect(
question="What is 2+2?",
agent_output=output,
skillbook=skillbook,
ground_truth="4",
feedback="Correct!",
)
```
### ReflectorOutput
| Field | Type | Description |
|-------|------|-------------|
| `reasoning` | `str` | Analysis of the outcome |
| `error_identification` | `str` | What went wrong (if anything) |
| `root_cause_analysis` | `str` | Why it went wrong |
| `correct_approach` | `str` | What should have been done |
| `key_insight` | `str` | Main lesson learned |
| `skill_tags` | `List[SkillTag]` | `(skill_id, tag)` pairs |
### Reflector Modes
| Mode | Description |
|------|-------------|
| `SIMPLE` | Single-pass analysis (default) |
| `RECURSIVE` | Multi-pass with code execution in a REPL loop |
## SkillManager
**Transforms reflections into skillbook updates.**
The SkillManager takes the Reflector's analysis and decides which operations to apply to the skillbook — adding new strategies, updating existing ones, or removing harmful ones.
```python
from ace import SkillManager
skill_manager = SkillManager(llm)
sm_output = skill_manager.update_skills(
reflections=(reflection,),
skillbook=skillbook,
question_context="Math problems",
progress="3/5 correct",
)
# Apply the updates
skillbook.apply_update(sm_output.update)
```
### SkillManagerOutput
| Field | Type | Description |
|-------|------|-------------|
| `update` | `UpdateBatch` | Batch of update operations to apply |
| `consolidation_ops` | `List` | Deduplication operations (if enabled) |
## Shared LLM
All three roles use the same model string. The intelligence comes from the specialized prompts, not from using different models:
```python
from ace import Agent, Reflector, SkillManager
agent = Agent("gpt-4o-mini")
reflector = Reflector("gpt-4o-mini")
skill_manager = SkillManager("gpt-4o-mini")
```
You can optionally use a cheaper model for the learning roles (Reflector + SkillManager) while keeping a stronger model for the Agent:
```python
agent = Agent("gpt-4o")
reflector = Reflector("gpt-4o-mini")
skill_manager = SkillManager("gpt-4o-mini")
```
## What to Read Next
- [Insight Levels](insight-levels.md) — micro, meso, and macro analysis scopes
- [Update Operations](updates.md) — the operations the SkillManager emits
- [Full Pipeline Guide](../guides/full-pipeline.md) — wire the roles together
|