AI agents that get smarter with every task 🧠

Agentic Context Engine learns from your agent's successes and failures. Just plug in and watch your agents improve.

Star ⭐️ this repo if you find it useful!

pip install ace-framework

export OPENAI_API_KEY="your-api-key"
# Or use Claude, Gemini, or 100+ other providers

from ace import LiteLLMClient, Generator, Reflector, Curator, Playbook

# Initialize with any LLM
client = LiteLLMClient(model="gpt-4o-mini")
generator = Generator(client)
reflector = Reflector(client)
curator = Curator(client)
playbook = Playbook()

# Teach your agent through examples
# (See examples/ folder for complete training patterns)

# Now it can solve new problems with learned strategies
result = generator.generate(
    question="Give me the seahorse emoji",
    context="",
    playbook=playbook
)
print(result.final_answer)  # Agent applies learned strategies

That's it! Your agent is now learning and improving. 🎉

AI agents make the same mistakes repeatedly.

ACE enables agents to learn from execution feedback: what works, what doesn't, and continuously improve.
No training data, no fine-tuning, just automatic improvement.

• 📈 20-35% Better Performance: Proven improvements on complex tasks
• 🧠 Self-Improving: Agents get smarter with each task
• 🔄 No Context Collapse: Preserves valuable knowledge over time
• 🚀 100+ LLM Providers: Works with OpenAI, Anthropic, Google, and more

A challenge where LLMs often hallucinate that a seahorse emoji exists (it doesn't). Watch ACE learn from its own mistakes in real-time. This demo shows how ACE handles the infamous challenge!

In this example:

• Round 1: The agent incorrectly outputs 🐴 (horse emoji)
• Self-Reflection: ACE reflects without any external feedback
• Round 2: With learned strategies from ACE, the agent successfully realizes there is no seahorse emoji

Try it yourself:

python examples/kayba_ace_test.py

Based on the ACE research framework from Stanford & SambaNova.

ACE uses three specialized roles that work together:

1. 🎯 Generator - Executes tasks using learned strategies from the playbook
2. 🔍 Reflector - Analyzes what worked and what didn't after each execution
3. 📝 Curator - Updates the playbook with new strategies based on reflection

ACE teaches your agent and internalises:

• ✅ Successes → Extract patterns that work
• ❌ Failures → Learn what to avoid
• 🔧 Tool usage → Discover which tools work best for which tasks
• 🎯 Edge cases → Remember rare scenarios and how to handle them

The magic happens in the Playbook—a living document of strategies that evolves with experience.
Key innovation: All learning happens in context through incremental updates—no fine-tuning, no training data, and complete transparency into what your agent learned.

---
config:
  look: neo
  theme: neutral
---
flowchart LR
    Playbook[("`**📚 Playbook**<br>(Evolving Context)<br><br>•Strategy Bullets<br> ✓ Helpful strategies <br>✗ Harmful patterns <br>○ Neutral observations`")]
    Start(["**📝Query** <br>User prompt or question"]) --> Generator["**⚙️Generator** <br>Executes task using playbook"]
    Generator --> Reflector
    Playbook -. Provides Context .-> Generator
    Environment["**🌍 Task Environment**<br>Evaluates answer<br>Provides feedback"] -- Feedback+ <br>Optional Ground Truth --> Reflector
    Reflector["**🔍 Reflector**<br>Analyzes and provides feedback what was helpful/harmful"]
    Reflector --> Curator["**📝 Curator**<br>Produces improvement deltas"]
    Curator --> DeltaOps["**🔀Merger** <br>Updates the playbook with deltas"]
    DeltaOps -- Incremental<br>Updates --> Playbook
    Generator <--> Environment

# Basic installation
pip install ace-framework

# With LangChain support
pip install ace-framework[langchain]

# With all features
pip install ace-framework[all]

# Development
pip install ace-framework[dev]

# Development from source (contributors)
git clone https://github.com/kayba-ai/agentic-context-engine
cd agentic-context-engine
pip install -r requirements.txt
pip install -e .

ACE works with any LLM provider through LiteLLM:

# OpenAI
client = LiteLLMClient(model="gpt-4o")

# Anthropic Claude
client = LiteLLMClient(model="claude-3-5-sonnet-20241022")

# Google Gemini
client = LiteLLMClient(model="gemini-pro")

# Ollama (local)
client = LiteLLMClient(model="ollama/llama2")

# With fallbacks for reliability
client = LiteLLMClient(
    model="gpt-4",
    fallbacks=["claude-3-haiku", "gpt-3.5-turbo"]
)

• Quick Start Guide - Get running in 5 minutes
• API Reference - Complete API documentation
• Examples - Ready-to-run code examples
• Prompt Engineering - Advanced prompt techniques

We love contributions! Check out our Contributing Guide to get started.

Based on the ACE paper and inspired by Dynamic Cheatsheet.

If you use ACE in your research, please cite:

@article{zhang2024ace,title={Agentic Context Engineering},author={Zhang et al.},journal={arXiv:2510.04618},year={2024}}