Prompt Engineering
ACE uses specialized prompt templates for each role. The framework includes multiple prompt versions with different trade-offs.
Default Prompts
ace ships with v2.1 prompts built in. All three roles (Agent, Reflector, SkillManager) use them by default — no extra imports needed.
Recommendation
The built-in v2.1 prompts work well out of the box. Only provide custom prompts when you need domain-specific instructions.
Overriding Prompts
Pass a prompt_template string to any role constructor:
from ace import Agent, Reflector, SkillManager
agent = Agent("gpt-4o-mini", prompt_template="Your custom agent prompt ...")
reflector = Reflector("gpt-4o-mini", prompt_template="Your custom reflector prompt ...")
skill_manager = SkillManager("gpt-4o-mini", prompt_template="Your custom skill manager prompt ...")
Template Variables
Agent Prompt
| Variable | Description |
|---|---|
{skillbook} | Current skillbook in TOON format |
{question} | The input question |
{context} | Additional context |
{reflection} | Optional reflection from a previous attempt |
Reflector Prompt
| Variable | Description |
|---|---|
{skillbook} | Current skillbook in TOON format |
{question} | The original question |
{agent_output} | The agent's response |
{ground_truth} | Expected answer |
{feedback} | Environment feedback |
SkillManager Prompt
| Variable | Description |
|---|---|
{skillbook} | Current skillbook in TOON format |
{reflection} | Reflector's analysis |
{question_context} | Description of the task domain |
{progress} | Current training progress |
Custom Prompts
You can provide your own prompt templates. They must include the required template variables:
custom_agent_prompt = """
Skillbook: {skillbook}
Question: {question}
Context: {context}
Generate a JSON response with:
- reasoning: Your step-by-step thought process
- skill_ids: List of skillbook IDs you used
- final_answer: Your answer
"""
agent = Agent(llm, prompt_template=custom_agent_prompt)
Formatting Skillbook for External Agents
Integration runners inject the skillbook into external agent prompts using a wrapper function:
from ace import wrap_skillbook_context
context = wrap_skillbook_context(skillbook)
# Returns formatted strategies with usage instructions
Troubleshooting
| Problem | Solution |
|---|---|
| JSON parse failures | Increase max_tokens, use Instructor, or try v2.1 prompts |
| Empty skill_ids | Agent not citing skills — check skillbook has content |
| Poor answer quality | Switch to v2.1 prompts or try a larger model |
What to Read Next
- Full Pipeline Guide — use prompts in a complete pipeline
- The Skillbook — what goes into
{skillbook}