How ACE Works

Agentic Context Engineering (ACE) enables AI agents to learn from their own execution feedback. Instead of updating model weights (expensive, slow, opaque), ACE evolves a skillbook of strategies based on what actually works.

Research

ACE was introduced in Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models by researchers at Stanford University and SambaNova Systems.

The Learning Loop

Three collaborative roles share the same base LLM:

The Agent executes a task using strategies from the skillbook
The Environment evaluates the result (correct/incorrect, feedback)
The Reflector analyzes what worked and what failed
The SkillManager updates the skillbook with new strategies

The Skillbook accumulates strategies across runs, making every subsequent agent call smarter.

Three Roles

Role	Responsibility	Key Class
Agent	Executes tasks using skillbook strategies	`Agent`
Reflector	Analyzes execution results (what worked, what failed)	`Reflector`
SkillManager	Transforms reflections into skillbook updates	`SkillManager`

All three roles use the same LLM — the intelligence comes from the specialized prompts each role receives.

See Three Roles for details on each role's inputs and outputs.

Two Architecture Patterns

Full ACE Pipeline

Use when building a new agent from scratch.

All three roles participate. The Agent produces answers, the Environment evaluates them, and the learning pipeline updates the skillbook.

from ace import ACE, Agent, Reflector, SkillManager, SimpleEnvironment

runner = ACE.from_roles(
    agent=Agent("gpt-4o-mini"),
    reflector=Reflector("gpt-4o-mini"),
    skill_manager=SkillManager("gpt-4o-mini"),
    environment=SimpleEnvironment(),
)
results = runner.run(samples, epochs=3)

Integration Pattern

Use when wrapping an existing agent (browser-use, LangChain, Claude Code).

No ACE Agent — the external framework handles execution. ACE only learns from the results.

Three steps: INJECT skillbook context, EXECUTE with external agent, LEARN from results.

from ace import BrowserUse

runner = BrowserUse.from_model(
    browser_llm=ChatOpenAI(model="gpt-4o"),
    ace_model="gpt-4o-mini",
)
results = runner.run("Find the top post on Hacker News")

See Integration Pattern for building custom integrations.

How It Compares

Approach	Updates	Speed	Interpretability
Fine-tuning	Model weights	Slow (hours)	Low (opaque)
RAG	External documents	Medium	Medium
ACE	Skillbook context	Fast (real-time)	High (readable strategies)

ACE strategies are human-readable, auditable, and transferable between models.

Performance

Benchmark	Improvement	Notes
AppWorld Agent	+17.1 pp	Complex multi-step tasks with tool use
FiNER (Finance)	+8.6 pp	Financial reasoning tasks
Adaptation Latency	-86.9%	vs. existing context-adaptation methods