Complete specification for an AI agent, defining its identity, LLM backend, tools, and routing.

Each agent has a unique ID, a display name, an LLM configuration (ModelConfig), and a system prompt that can be static or dynamic (receiving AgentContext). Agents declare their available tools and can optionally access MCP servers and hand off to other agents.

The canHandoffTo field enables the multi-agent swarm pattern: the runtime auto-generates handoff_to_<agentId> tools for each target agent, allowing the LLM to route conversations. The maxIterations field provides a safety limit on tool-call loops per turn.

Related: RuntimeConfig collects agents, AgentRuntime orchestrates them, ModelConfig configures the LLM, ToolDefinition defines available tools.

interface AgentDefinition {
    id: string;
    name: string;
    description: string;
    model: ModelConfig;
    systemPrompt: string | ((context: AgentContext) => string);
    tools: ToolDefinition[];
    allowedMcpServers?: string[];
    canHandoffTo?: string[];
    maxIterations?: number;
}