Skip to content

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.

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.

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.

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.

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:

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:

agent = Agent("gpt-4o")
reflector = Reflector("gpt-4o-mini")
skill_manager = SkillManager("gpt-4o-mini")