Agents
AI-in-a-Box runs one adaptive main agent per chat session. The main agent can call tools, load skills, use MCP servers, access memory/knowledge, request approvals, execute code, and launch focused subagents through Delegate.
Top-Level Agents
GET /v1/agents lists top-level global and DB-backed custom agents. It does not list subagent types.
Global YAML agents can be loaded and shown in the registry, but current chat request handling applies DB-backed custom-agent config or falls back to the default adaptive agent. Do not promise that every YAML registry entry is directly selectable through agent_id until that behavior is wired end-to-end.
Subagents
Subagents are Markdown files under deploy/config/subagents/. They are launched only by the main agent through the Delegate tool.
---
name: researcher
description: Searches the web and retrieves knowledge
tools: [web_search, scrape_url, knowledge_search]
model: openai/gpt-5.4
color: green
skills: []
mcpServers: []
---
You are a focused research subagent...
The child run receives a self-contained prompt, runs with its configured tool set, returns one final_output, and exits. It does not become a separate user-visible chat session.
Chat Contract
Use the current messages request shape:
{
"messages": [{"role": "user", "content": "Analyze this CSV"}],
"tenant_id": "default",
"user_id": "alice",
"session_id": "s1",
"agent_id": "default"
}
Specialist IDs such as coder, researcher, and analyst are legacy inputs and are mapped back to default. Use Delegate for specialist work.
Tool Categories
The actual tool set is assembled at runtime from config, policy, user secrets, and MCP availability.
| Category | Examples |
|---|---|
| Memory | Store, search, list, update, delete typed memories. |
| Knowledge | Document search, wiki read/write, visibility-aware retrieval. |
| Web | Search and scrape through Firecrawl/SearXNG. |
| Sandbox | Python, bash, file read/write, grep/glob, artifacts. |
| Database | Conditional SQL/database tools when configured. |
| MCP | User/admin MCP servers attached at runtime. |
| Governance | Approval-gated tools and policy summaries. |
| Skills | load_skill, including forkable skills. |
| Delegation | Delegate(subagent_type=..., prompt=...). |
Memory Behavior
Memory is not only a visible memory_recall tool call. The chat handler prefetches relevant memories before agent construction and injects them into the prompt as recent relevant notes. The agent can still call memory tools when it needs explicit lookup or storage.
Turn Events and Receipts
Agent-runtime emits turn events such as:
prompt_generatedtool_calledtool_returnedturn_failed
These events join gateway, model, memory, knowledge, and guardrail events in the audit turn envelope. Chat responses include receipt metadata with URLs under /v1/receipts/{turn_id}.