> ## Documentation Index > Fetch the complete documentation index at: https://docs.xpressbot.org/llms.txt > Use this file to discover all available pages before exploring further. # AI Agent Tools > Build, configure, test, and publish AI agents from a description. ## What is this? These tools let the assistant create and manage AI agents: build a whole agent in one step, change its instructions, knowledge, skills, settings and capabilities, add your own HTTP and MCP tools, test it with real messages, check it is ready, and publish it. New agents are always created inactive, and publishing only happens when you ask. These tools belong to the [Workspace MCP](https://docs.xpressbot.org/api-reference/mcp/workspace/overview.md). Each tool below shows its **Mode** (**Read** runs immediately; **Write** asks your MCP client to confirm first) and the **Permission needed** for it to appear for your key — "None" means every connected key sees it. ## What can I do here? * List and read AI agents, their knowledge, skills and activity * Build an agent from a description, or change an existing one * Add your own HTTP and MCP tools to an agent * Test an agent with messages, check readiness, and publish ## Tools ### `list_ai_agents` List the AI agents of the user's current channel: name, type, description, status and tone. **Mode:** Read · **Permission needed:** `ai:view` ### `get_ai_agent` Details of one AI agent (from list\_ai\_agents): description, status, tone, model provider, its instructions and which capabilities are turned on for it. **Mode:** Read · **Permission needed:** `ai:view` ### `list_ai_settings` The AI models this channel can use (provider, model, text or voice, which one is active). Pick an id for `update_agent_settings`; an agent without one follows the channel's active text setting. Never returns API keys. **Mode:** Read · **Permission needed:** `ai:view` ### `create_ai_agent` Create a new AI Agent (draft) in the user's current channel with a name, optional description, instructions and tone. The agent is created INACTIVE: it does not answer customers until it is published, and it has no knowledge, skills or tools yet. Check list\_ai\_agents first so you do not duplicate one. Write the instructions from what the user told you about their business; do not invent facts (prices, hours, policies). If the user has not said what the agent should do, ask before proposing. **Mode:** Write · **Permission needed:** `ai:create` ### `build_ai_agent` Build a NEW AI Agent from the user's description in ONE step (one approval): the agent (created INACTIVE, a draft), its instructions and tone, knowledge (pasted text or web addresses), skills and which capabilities are on. Prefer this over create\_ai\_agent plus several add\_\* calls when the user describes a whole agent. Use only what the user told you: if you lack something that matters (what the business does, what the agent may or may not do, where its knowledge lives, who takes over), ask first; never invent prices, hours, policies or web addresses. Handoff recipients are NOT part of this (channel-wide: set\_handoff\_assignment). It does not publish: afterwards tell the user to test it, then offer check\_agent\_readiness and publish\_ai\_agent. **Mode:** Write · **Permission needed:** `ai:create` ### `update_ai_agent` Change an existing AI Agent's name, description, instructions or tone (agentId from list\_ai\_agents). Only the fields you give are changed, and `systemInstructions` REPLACES the whole instructions text: read the current ones with get\_ai\_agent first (long ones are shown truncated; if so, tell the user and ask before replacing) and send the complete new text. It does not turn the agent on or off, and does not touch its knowledge, skills or tools. **Mode:** Write · **Permission needed:** `ai:edit` ### `add_agent_knowledge` Give an existing AI Agent knowledge to answer from: pasted text the user provided, one web page, a sitemap or an llms.txt. It starts reading in the background (it is NOT ready instantly: say it is processing and that check\_agent\_readiness shows when it is done). Only use content or addresses the user gave you. Uploaded files cannot be added from here. **Mode:** Write · **Permission needed:** `ai:create` ### `add_agent_skill` Add a skill to an existing AI Agent: a named procedure it looks up when a matching situation comes up (e.g. refund-policy, book-appointment) instead of cramming everything into its main instructions. Base it on what the user told you; do not invent policies. **Mode:** Write · **Permission needed:** `ai:create` ### `set_agent_capability` Turn one of an AI Agent's capabilities (the actions it may take in a conversation, e.g. handoff\_to\_human, add\_contact\_label, close\_conversation) on or off, optionally with a guideline for when to use it. Read the agent's current capabilities with get\_ai\_agent first and use the exact `key` shown. Only for that agent; it does not change other agents. **Mode:** Write · **Permission needed:** `ai:edit` ### `set_handoff_assignment` Choose who receives conversations an AI Agent hands over to a human: nobody in particular (shared unassigned queue), one team member, or a group taking turns (round\_robin) or the least busy (least\_busy). IMPORTANT: this is a setting of the whole channel, shared by every AI Agent on it. Get team members with list\_team\_members and pass their userIds. Turning handoff on or off for one agent is set\_agent\_capability with handoff\_to\_human. **Mode:** Write · **Permission needed:** `ai:edit` ### `check_agent_readiness` Check whether an AI Agent is ready to go live: instructions, knowledge (ready / still processing / failed), skills, enabled capabilities, human handoff and the channel's AI model setting, plus whether the channel's AI Agent switch is on. Use it after building or changing an agent and before publish\_ai\_agent. Report what is missing in plain words. **Mode:** Read · **Permission needed:** `ai:view` ### `list_agent_knowledge` What an AI agent has been taught: each knowledge source with its type, title or address, status (pending, processing, processed, failed), the error if it failed and how much text was read. Use it after add\_agent\_knowledge to see whether it finished. Never returns the stored text. **Mode:** Read · **Permission needed:** `ai:view` ### `retry_agent_knowledge` Run a knowledge source that failed again (from list\_agent\_knowledge; only status failed). It processes in the background. **Mode:** Write · **Permission needed:** `ai:edit` ### `list_agent_skills` The skills of an AI agent in full (name, when to use it, the procedure, enabled or not), so you can review or improve them. **Mode:** Read · **Permission needed:** `ai:view` ### `update_agent_skill` Change one skill of an AI agent: rename it, rewrite when to use it or the procedure, or switch it on or off. Only the fields you give change; the procedure text is replaced as a whole. Switching a skill off is how it is retired over MCP; deleting stays in the dashboard. **Mode:** Write · **Permission needed:** `ai:edit` ### `update_agent_settings` Change an AI agent's settings: its type, which AI model it uses, which channel types it answers on, reply modes, response language, priority, image understanding and guardrails. Only the fields you give change; instructions, knowledge, skills and capabilities are untouched and nothing is published. Over MCP guardrails can be turned on but never off — that is a dashboard action. **Mode:** Write · **Permission needed:** `ai:edit` ### `list_external_capabilities` The channel's own HTTP and MCP tools ([External Capabilities](https://docs.xpressbot.org/workspace/ai-agents/tabs/external-capabilities.md)): name, type, server or endpoint, how it signs in and its status (`needs_credentials` means it was saved without a working login and is off until someone adds it in the dashboard). Give an agent id to see whether that agent has each one on. Credentials are never returned. **Mode:** Read · **Permission needed:** `ai:view` ### `add_external_capability` Give an AI agent one of your own tools: the tools of an MCP server (by URL and tool names) or one call to an HTTP API (method, body, a description for the agent and its inputs), signed in with no auth, a bearer token or OAuth client credentials. The tool is shared by every agent on the channel and switched on for this one. If the MCP server refuses the login, the tools are saved switched off as `needs_credentials` and you add the login in the dashboard. Credentials are stored encrypted and never shown again. **Mode:** Write · **Permission needed:** `ai:create` ### `get_agent_activity` How an AI agent (or all agents of the channel) has been used lately: tool and skill calls, failures, conversations, and which capabilities and skills were used most. Counts only — no customer text. **Mode:** Read · **Permission needed:** `ai:view` ### `test_ai_agent` Try an AI agent the way a customer would before it goes live: send one message and get its reply, the tools it used and a session to continue the conversation. It runs the real agent against a labelled throwaway test contact, so its tools can act on that contact only, and it uses your AI credits. Works on drafts. **Mode:** Write · **Permission needed:** `ai:edit` ### `publish_ai_agent` Put an AI Agent live so it starts answering real customers. Only when the user explicitly asks to publish or activate, after check\_agent\_readiness, and never in the same reply that builds the agent: the user should test it first (the dashboard's Playground). Set enableChannelAgenticMode true only if the user wants the channel's AI Agent switch turned on too (check\_agent\_readiness shows it); without that switch on, no agent answers customers. **Mode:** Write · **Permission needed:** `ai:edit` ## Troubleshooting / Technical Notes * **A tool I expect isn't offered.** The MCP server only offers tools whose required permission your API key's owner holds, re-checked on every call. Grant the permission shown on the tool — see [Team](https://docs.xpressbot.org/workspace/team.md). * **A Write tool never seems to run.** Your MCP client asks you to approve every Write tool call. Check for a pending approval prompt. * **A call returns an error.** See [MCP errors](https://docs.xpressbot.org/api-reference/mcp/errors.md). ## Related docs * [Workspace MCP tool catalog](https://docs.xpressbot.org/api-reference/mcp/workspace/tools/overview.md) * [Workspace MCP](https://docs.xpressbot.org/api-reference/mcp/workspace/overview.md) * [Overview](https://docs.xpressbot.org/workspace/ai-agents/overview.md) * [Capabilities](https://docs.xpressbot.org/workspace/ai-agents/tabs/capabilities.md) * [External Capabilities](https://docs.xpressbot.org/workspace/ai-agents/tabs/external-capabilities.md) * [Ai Assistant](https://docs.xpressbot.org/workspace/ai-assistant.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.