ace-framework 0.5.1

Build self-improving AI agents that learn from experience

Agentic Context Engine (ACE)

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!

---

🤖 LLM Quickstart

1. Direct your favorite coding agent (Cursor, Claude Code, Codex, etc) to Quick Start Guide
2. Prompt away!

---

✋ Quick Start

1. Install

pip install ace-framework

2. Set API Key

export OPENAI_API_KEY="your-api-key"

3. Run

from ace import ACELiteLLM

agent = ACELiteLLM(model="gpt-4o-mini")

answer = agent.ask("What does Kayba's ACE framework do?")
print(answer)  # "ACE allows AI agents to remember and learn from experience!"

🎉 Done! Your agent learns automatically from each interaction.

---

🎯 Integrations

ACE provides three ready-to-use integrations:

ACELiteLLM - Simplest Start 🚀

Perfect for Q&A, classification, reasoning:

from ace import ACELiteLLM

# Create self-improving agent
agent = ACELiteLLM(model="gpt-4o-mini")

# Ask related questions - agent learns patterns
answer1 = agent.ask("If all cats are animals, is Felix (a cat) an animal?")
answer2 = agent.ask("If all birds fly, can penguins (birds) fly?")  # Learns to check assumptions!
answer3 = agent.ask("If all metals conduct electricity, does copper conduct electricity?")

# View learned strategies
print(f"✅ Learned {len(agent.playbook.bullets())} reasoning strategies")

# Save for reuse
agent.save_playbook("my_agent.json")

# Load and continue
agent2 = ACELiteLLM.from_playbook("my_agent.json", model="gpt-4o-mini")

ACEAgent (browser-use) - Browser Automation 🌐

Self-improving browser agents with browser-use:

pip install ace-framework[browser-use]

from ace import ACEAgent
from browser_use import ChatBrowserUse

# Two LLMs: ChatBrowserUse for browser, gpt-4o-mini for ACE learning
agent = ACEAgent(
    llm=ChatBrowserUse(),      # Browser execution
    ace_model="gpt-4o-mini"    # ACE learning
)

await agent.run(task="Find top Hacker News post")
agent.save_playbook("hn_expert.json")

# Reuse learned knowledge
agent = ACEAgent(llm=ChatBrowserUse(), playbook_path="hn_expert.json")
await agent.run(task="New task")  # Starts smart!

Features: Drop-in replacement for browser_use.Agent, automatic learning, reusable playbooks → Browser Use Guide

ACELangChain - Complex Workflows ⛓️

Wrap any LangChain chain/agent with learning:

from ace import ACELangChain

ace_chain = ACELangChain(runnable=your_langchain_chain)
result = ace_chain.invoke({"question": "Your task"})  # Learns automatically

Best for: Multi-step workflows, tool-using agents

→ Integration Guide | → Examples

---

Why Agentic Context Engine (ACE)?

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.

Clear Benefits

• 📈 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
• 📊 Production Observability: Built-in Opik integration for enterprise monitoring

---

Demos

🌊 The Seahorse Emoji Challenge

A challenge where LLMs often hallucinate that a seahorse emoji exists (it doesn't).

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:

uv run python examples/kayba_ace_test.py

🌐 Browser Automation

Online Shopping Demo: ACE vs baseline agent shopping for 5 grocery items.

ACE Performance:

• 29.8% fewer steps (57.2 vs 81.5)
• 49.0% token reduction (595k vs 1,166k)
• 42.6% cost reduction (including ACE overhead)

→ Try it yourself & see all demos

---

How does Agentic Context Engine (ACE) work?

Based on the ACE research framework from Stanford & SambaNova.

ACE uses three specialized roles that work together:

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

Important: The three ACE roles are different specialized prompts using the same language model, not separate models.

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

---

Installation

# Basic
pip install ace-framework

# With extras
pip install ace-framework[browser-use]      # Browser automation
pip install ace-framework[langchain]        # LangChain
pip install ace-framework[observability]    # Opik monitoring
pip install ace-framework[all]              # All features

Configuration

ACE works with any LLM provider through LiteLLM:

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

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

Production Monitoring

ACE includes built-in Opik integration for tracing and cost tracking:

pip install ace-framework[observability]
export OPIK_API_KEY="your-api-key"

Automatically tracks: LLM calls, costs, playbook evolution. View at comet.com/opik

---

Documentation

• Quick Start Guide - Get running in 5 minutes
• API Reference - Complete API documentation
• Examples - Ready-to-run code examples
  • Browser Automation - Self-improving browser agents
  • LangChain Integration - Wrap chains/agents with learning
  • Custom Integration - Pattern for any agent
• Integration Guide - Add ACE to existing agents
• ACE Framework Guide - Deep dive into Agentic Context Engineering
• Prompt Engineering - Advanced prompt techniques
• Benchmarks - Evaluate ACE performance with scientific rigor across multiple datasets
• Changelog - See recent changes

---

Contributing

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

---

Acknowledgment

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}}

⭐ Star this repo if you find it useful!
Built with ❤️ by Kayba and the open-source community.