agents_create
Create a new AI agent in the workspace.
Execution modes:
ai_assisted (default): Two-phase AI — fast pre-classifier (Haiku) for keyword filtering and simple replies, then full AI with tools for complex messages.
agentic: Autonomous multi-step agent with planning and tool execution.
rule_based: Simple pattern matching without AI.
Keyword filtering is available in ai_assisted mode via keywords in trigger conditions (free, deterministic) and/or auto_reply_rules (LLM-based) set through agents.update.
Pass prompt_text for the agent's instructions (stored inline on the agent) or prompt_id to link an existing prompt row, not both.
Tools: a new agent starts with the standard tool set (knowledge base lookup, replying, lead capture, reading files, handoff, plus the default voice-call tools). Pass allowed_tools to replace that set.
From a template: pass template (e.g. 'dm-auto-reply') to create the agent AND its built-in trigger in one call — deterministic, no need to add a trigger separately. When template is set, name/text_engine/send_mode come from the template.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the AI agent (1-100 characters) | |
| model | No | LLM the agent runs on. OMIT to use the platform default (deepseek-v4-flash-nothink). Applied right after creation so you don't need a follow-up agents_update. | |
| template | No | Optional template slug to instantiate the agent + its built-in trigger from (deterministic). Use 'dm-auto-reply' for the customer DM auto-reply agent (incoming DM trigger, draft mode). When set, the trigger comes from the template — you don't need agents.trigger_create. OMIT to create a plain agent (no template). | |
| prompt_id | No | ID of the prompt to assign to this agent | |
| send_mode | No | Default send mode: 'auto' or 'draft'. OMIT to use 'draft' (the default). | |
| description | No | Optional description of what this agent does | |
| prompt_text | No | The agent's instructions, stored inline on the agent (this is what drives how it replies). Works with or without `template`; no separate prompts tool needed. Write it from the business to its customers. | |
| remote_tool | No | Only for text_engine='external_agent': the workspace integration tool that starts the remote agent, e.g. 'ext42_run_routine' (list them with integrations.search_tools). On each trigger DialogBrain calls it once with the event, the agent's instructions and the ids to answer with; the remote agent replies through the DialogBrain MCP tools (messages.send, tasks.comment, agents.task_complete). The endpoint and its secret belong to the integration, not to the agent. | |
| text_engine | No | Text-execution engine: 'rule_based', 'ai_assisted', 'agentic' (default), 'claude_channels', or 'external_agent' (the run is handed to an agent outside DialogBrain; needs remote_tool). Voice is derived from triggers, not engine. OMIT to use the default ('agentic'). | |
| in_workspace | No | Run this one call in this workspace id instead of the session's. Nothing is stored; other sessions are not affected. | |
| allowed_tools | No | Explicit allow-list of tool IDs the agent may call on triggered runs (e.g. ['knowledge.query', 'messages.send']). OMIT to give the agent the standard set: knowledge.query, messages.send, contacts.capture_lead, files.read, agent.handoff (plus the default voice-call tools). When passed, the list REPLACES the standard set entirely — include 'knowledge.query' for an agent that must answer from its knowledge base, or the model has no such tool and tends to imitate the call in its reply text. An empty list leaves the agent with no tools. | |
| max_iterations | No | Hard cap on agentic-loop turns per run (1-50). OMIT for the default (10). |