Agent Architecture

What is an Agent?

An agent is a deployable unit of AI behavior defined by an CAFF flow. Each agent has:

• A flow definition — Directed graph of nodes and edges
• A trigger — How the agent is activated (manual, schedule, webhook, platform events)
• Model configuration — Which LLM(s) to use and how
• Optional tools — MCP servers providing external capabilities
• Optional guardrails — Safety checks on input/output

Execution Lifecycle

1. Trigger fires — User message, cron schedule, webhook, or platform event
2. Flow starts — The start node receives input and initializes variables
3. Nodes execute — Each node runs in topological order following edges
4. Tools called — Agent nodes can invoke MCP tools in a loop (up to maxToolIterations)
5. Flow ends — The end node captures output and returns the response
6. Usage recorded — Token usage and cost are tracked against the user’s credit balance

Agent States

State	Description
DRAFT	Being edited, not executable
ACTIVE	Deployed and accepting triggers
PAUSED	Temporarily disabled
ARCHIVED	Soft-deleted, not visible

Session Management

For chat-based agents, sessions track conversation state per user per platform. Sessions maintain:

• Chat history (configurable via chatHistoryLimit)
• Flow variable state
• Platform-specific context (user ID, channel, thread)

Cost Management

Every agent execution costs credits based on model usage. Control costs with:

• Daily budget — Maximum spend per day (auto-resets at midnight UTC)
• Monthly budget — Maximum spend per month
• Chat history limit — Reduce context window size to lower token usage
• Model routing — Use cheaper models for simple tasks