create_agent
Create a specialized AI assistant with a defined role, persona, and behavioral instructions to handle specific tasks. Attach it to a workflow for immediate use.
Instructions
Create a new agent in the workspace.
WHAT IS AN AGENT: An agent is a specialised AI assistant with a defined role, persona, and behavioural instructions. Agents are where you put "You are a..." system prompts, persona definitions, tone of voice rules, and task-specific instructions. Agents can have skills attached to them to give them access to reference knowledge.
EXAMPLES of correct agent content:
"You are a senior customer support agent for Acme Corp. You handle billing and account queries..."
"You are a code reviewer specialising in Python. You check for security vulnerabilities..."
DO NOT use create_agent to store reference material, policies, or documentation — use create_skill for that.
IMPORTANT: You MUST always provide both a clear name AND a meaningful description — never leave description blank. The description should explain the agent's role, specialisation, and how it behaves.
WORKFLOW ATTACHMENT: Always provide workflowId when creating an agent for a specific project or feature — this ensures the agent is immediately attached to the right workflow and won't be orphaned.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | A clear, descriptive name for the agent (e.g., "Customer Support Agent", "Code Reviewer", "Marketing Copywriter") | |
| personaId | No | Optional persona ID to base this agent on a built-in persona. Use list_agents or get the persona list to find valid IDs. If provided, systemPrompt is derived from the persona. | |
| workflowId | No | Optional workflow ID to attach this agent to immediately after creation. Recommended — avoids orphaned agents. | |
| description | Yes | REQUIRED — A meaningful description of the agent's purpose, role, and behaviour. Explain what this agent specialises in, what tasks it handles, and how it should approach its work. Do NOT leave this blank. Example: "A customer support agent specialised in handling billing queries and account issues. Responds empathetically, escalates complex issues, and follows company refund policies." | |
| workspaceId | No | Workspace ID. If not provided, uses your default workspace. | |
| systemPrompt | No | The system prompt defining this agent's behaviour and instructions. Required for custom agents (when no personaId is given). Example: "You are a senior customer support agent. You handle billing queries empathetically and escalate complex issues." |