Architecture
Agent System
How BaseAgent and its 5 specialized agents work with personas, prompts, and LLM settings.
All pipeline stages are powered by agents that inherit from BaseAgent in src/autoflow/agents/base.py.
BaseAgent
Every agent follows the same pattern:
- Load persona — Reads
personas/{name}.txtas the LLM system prompt - Load prompt template — Reads
prompts/{name}.txtas the user message template - Fill template — Substitutes variables into the prompt template
- Call LLM — Sends system prompt + filled template to the configured provider
- Parse JSON — Extracts and validates JSON from the response
Each agent has its own temperature and max_tokens settings tuned for its task.
Specialized Agents
NavigatorAgent
- Persona:
personas/navigator.txt - Prompt:
prompts/navigate.txt - Purpose: Decides which Ask Sage tool fits the user's request
- Output: Tool recommendation with reasoning
Uses 7 decision rules to route to: In A Box, Agent Builder, Workbook, Dataset, Persona, Standard Chat, or Persona + Dataset.
NormalizerAgent
- Persona:
personas/normalizer.txt - Prompt:
prompts/normalize.txt - Purpose: Converts messy free-form input into a structured task contract
- Output: Objective, deliverable type, constraints, and requirements
GeneratorAgent
- Persona:
personas/generator.txt - Prompt:
prompts/generate_workflow.txt - Purpose: Produces Ask Sage Agent Builder workflow JSON
- Enrichments: Automatically adds
RECOMMENDED PATTERN:andMODEL RECOMMENDATION:hints to the prompt based on pattern matching and model recommendations
EvaluatorAgent
- Persona:
personas/evaluator.txt - Prompt:
prompts/evaluate.txt - Purpose: Scores workflow output on 5 quality dimensions
- Output: Scores (1-5 each), verdict (PASS/FAIL), estimated edit minutes
CritiqueAgent
- Persona:
personas/critique.txt - Prompt:
prompts/critique.txt - Purpose: Identifies specific issues in failed evaluations and suggests improvements
- Output: List of issues with suggested fixes
Additional Stage Agents
The synthesize pipeline uses BaseAgent directly (no subclass) with different persona/prompt pairs:
| Stage | Persona | Prompt |
|---|---|---|
| Parse | parser.txt | parse.txt |
| Extract | extractor.txt | extract_events.txt |
| Synthesize | synthesizer.txt | synthesize.txt |
Persona Files
Personas define the agent's identity and expertise in the system prompt. Example structure:
You are [role description].
Your expertise includes:
- [domain knowledge]
- [specific skills]
You always:
- [behavioral constraint]
- [output format requirement]Prompt Templates
Prompt templates use {variable} placeholders that get filled at runtime:
Given the following task contract:
{task_contract}
USER INPUT:
{user_input}
Generate a workflow that...