# AI agents ## List AI Agents `TOOL discourse_ai_list_agents` List concise Discourse AI agent summaries and slim tool/model metadata. Defaults to slim; use discourse_ai_get_agent to load one full configuration, or view=full only when the complete index is explicitly needed. Requires admin credentials. Authentication: no security requirement declared for this operation. Parameters: - `view` (argument, string, optional) Type: string default: "slim" enum: ["slim","full"] ## Examples ### JSON-RPC ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "discourse_ai_list_agents", "arguments": { "view": "slim" } } } ``` ### TypeScript ```typescript const result = await client.callTool({ "name": "discourse_ai_list_agents", "arguments": { "view": "slim" } }); ``` ### Python ```python result = await session.call_tool("discourse_ai_list_agents", arguments={ "view": "slim" }) ``` ## Get AI Agent `TOOL discourse_ai_get_agent` Get the full editable configuration of one Discourse AI agent. Custom tools use custom-; native tools use native- in tool tuples. Authentication: no security requirement declared for this operation. Request body: application/json (required) Type: object - `id` (required) Type: integer | string anyOf: Type: integer Type: string pattern: "^-?[1-9]\\d*$" Additional properties: false ## Examples ### JSON-RPC ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "discourse_ai_get_agent", "arguments": { "id": 0 } } } ``` ### TypeScript ```typescript const result = await client.callTool({ "name": "discourse_ai_get_agent", "arguments": { "id": 0 } }); ``` ### Python ```python result = await session.call_tool("discourse_ai_get_agent", arguments={ "id": 0 }) ``` ## Create AI Agent `TOOL discourse_ai_create_agent` Create a typed Discourse AI agent, including an optional subagent delegation allowlist of up to 20 existing agent IDs. Requires admin credentials and write mode. Tool entries may be names or [name, options, force] tuples. Authentication: no security requirement declared for this operation. Request body: application/json (required) Type: object - `name` (required) Type: string minLength: 1 maxLength: 100 - `description` (required) Type: string minLength: 1 maxLength: 2000 - `system_prompt` (required) Type: string minLength: 1 maxLength: 10000000 - `enabled` (optional) Type: boolean - `priority` (optional) Type: boolean - `default_llm_id` (optional) Type: integer | null anyOf: Type: integer exclusiveMinimum: 0 Type: null - `top_p` (optional) Type: number | null anyOf: Type: number minimum: 0 maximum: 1 Type: null - `temperature` (optional) Type: number | null anyOf: Type: number minimum: 0 Type: null - `thinking_effort` (optional) Type: string | null anyOf: Type: string enum: ["default","none","minimal","low","medium","high","xhigh","max"] Type: null - `force_default_llm` (optional) Type: boolean - `allowed_group_ids` (optional) Type: Array Items: Type: integer minimum: 0 - `user_id` (optional) Type: integer | null anyOf: Type: integer exclusiveMinimum: 0 Type: null - `allow_chat_channel_mentions` (optional) Type: boolean - `allow_chat_direct_messages` (optional) Type: boolean - `allow_topic_mentions` (optional) Type: boolean - `allow_personal_messages` (optional) Type: boolean - `tools` (optional) Type: Array> Items: Type: string | Array anyOf: Type: string minLength: 1 Type: Array minItems: 3 maxItems: 3 Items: Type: string | never | object | null | never | boolean oneOf: Type: string minLength: 1 Type: never | object | null anyOf: Type: never Must not match: Type: any Type: object | null anyOf: Type: object Additional properties: Type: any Type: null Type: never | boolean anyOf: Type: never Must not match: Type: any Type: boolean - `mcp_server_ids` (optional) Type: Array Items: Type: integer exclusiveMinimum: 0 - `mcp_server_tool_names` (optional) Type: object Additional properties: Type: Array Items: Type: string minLength: 1 - `subagent_ids` (optional) Type: Array Up to 20 existing AI agent IDs this agent may delegate to; IDs may include negative system-agent IDs Items: Type: integer | string anyOf: Type: integer Type: string pattern: "^-?[1-9]\\d*$" - `forced_tool_count` (optional) Type: integer minimum: -1 maximum: 100000 - `require_approval` (optional) Type: boolean - `response_format` (optional) Type: Array | null anyOf: Type: Array Items: Type: object Additional properties: Type: any Type: null - `examples` (optional) Type: Array> Items: Type: Array minItems: 2 maxItems: 2 Items: Type: string oneOf: Type: string Type: string - `show_thinking` (optional) Type: boolean - `vision_enabled` (optional) Type: boolean - `vision_max_pixels` (optional) Type: integer maximum: 4000000 exclusiveMinimum: 0 - `rag_chunk_tokens` (optional) Type: integer minimum: 1 maximum: 50000 - `rag_chunk_overlap_tokens` (optional) Type: integer minimum: 0 maximum: 200 - `rag_conversation_chunks` (optional) Type: integer minimum: 1 maximum: 1000 - `rag_llm_model_id` (optional) Type: integer | null anyOf: Type: integer exclusiveMinimum: 0 Type: null - `rag_uploads` (optional) Type: Array Items: Type: object - `id` (required) Type: integer exclusiveMinimum: 0 Additional properties: false - `max_turn_tokens` (optional) Type: integer | null anyOf: Type: integer maximum: 10000000 exclusiveMinimum: 0 Type: null - `compression_threshold` (optional) Type: integer minimum: 20 maximum: 99 Additional properties: false ## Examples ### JSON-RPC ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "discourse_ai_create_agent", "arguments": { "name": "string", "description": "string", "system_prompt": "string", "enabled": true, "priority": true, "default_llm_id": 0, "top_p": 0, "temperature": 0, "thinking_effort": "default", "force_default_llm": true, "allowed_group_ids": [ 0 ], "user_id": 0, "allow_chat_channel_mentions": true, "allow_chat_direct_messages": true, "allow_topic_mentions": true, "allow_personal_messages": true, "tools": [ "string" ], "mcp_server_ids": [ 0 ], "mcp_server_tool_names": {}, "subagent_ids": [ 0 ], "forced_tool_count": -1, "require_approval": true, "response_format": [ {} ], "examples": [ [ "string" ] ], "show_thinking": true, "vision_enabled": true, "vision_max_pixels": 0, "rag_chunk_tokens": 1, "rag_chunk_overlap_tokens": 0, "rag_conversation_chunks": 1, "rag_llm_model_id": 0, "rag_uploads": [ { "id": 0 } ], "max_turn_tokens": 0, "compression_threshold": 20 } } } ``` ### TypeScript ```typescript const result = await client.callTool({ "name": "discourse_ai_create_agent", "arguments": { "name": "string", "description": "string", "system_prompt": "string", "enabled": true, "priority": true, "default_llm_id": 0, "top_p": 0, "temperature": 0, "thinking_effort": "default", "force_default_llm": true, "allowed_group_ids": [ 0 ], "user_id": 0, "allow_chat_channel_mentions": true, "allow_chat_direct_messages": true, "allow_topic_mentions": true, "allow_personal_messages": true, "tools": [ "string" ], "mcp_server_ids": [ 0 ], "mcp_server_tool_names": {}, "subagent_ids": [ 0 ], "forced_tool_count": -1, "require_approval": true, "response_format": [ {} ], "examples": [ [ "string" ] ], "show_thinking": true, "vision_enabled": true, "vision_max_pixels": 0, "rag_chunk_tokens": 1, "rag_chunk_overlap_tokens": 0, "rag_conversation_chunks": 1, "rag_llm_model_id": 0, "rag_uploads": [ { "id": 0 } ], "max_turn_tokens": 0, "compression_threshold": 20 } }); ``` ### Python ```python result = await session.call_tool("discourse_ai_create_agent", arguments={ "name": "string", "description": "string", "system_prompt": "string", "enabled": true, "priority": true, "default_llm_id": 0, "top_p": 0, "temperature": 0, "thinking_effort": "default", "force_default_llm": true, "allowed_group_ids": [ 0 ], "user_id": 0, "allow_chat_channel_mentions": true, "allow_chat_direct_messages": true, "allow_topic_mentions": true, "allow_personal_messages": true, "tools": [ "string" ], "mcp_server_ids": [ 0 ], "mcp_server_tool_names": {}, "subagent_ids": [ 0 ], "forced_tool_count": -1, "require_approval": true, "response_format": [ {} ], "examples": [ [ "string" ] ], "show_thinking": true, "vision_enabled": true, "vision_max_pixels": 0, "rag_chunk_tokens": 1, "rag_chunk_overlap_tokens": 0, "rag_conversation_chunks": 1, "rag_llm_model_id": 0, "rag_uploads": [ { "id": 0 } ], "max_turn_tokens": 0, "compression_threshold": 20 }) ``` ## Update AI Agent `TOOL discourse_ai_update_agent` Partially update one AI agent, including enabled state, permissions, model, prompt, tools, subagent delegation, and RAG configuration. Only supplied fields are sent. Requires admin credentials and write mode. Authentication: no security requirement declared for this operation. Request body: application/json (required) Type: object - `id` (required) Type: integer | string anyOf: Type: integer Type: string pattern: "^-?[1-9]\\d*$" - `name` (optional) Type: string minLength: 1 maxLength: 100 - `description` (optional) Type: string minLength: 1 maxLength: 2000 - `system_prompt` (optional) Type: string minLength: 1 maxLength: 10000000 - `enabled` (optional) Type: boolean - `priority` (optional) Type: boolean - `default_llm_id` (optional) Type: integer | null anyOf: Type: integer exclusiveMinimum: 0 Type: null - `top_p` (optional) Type: number | null anyOf: Type: number minimum: 0 maximum: 1 Type: null - `temperature` (optional) Type: number | null anyOf: Type: number minimum: 0 Type: null - `thinking_effort` (optional) Type: string | null anyOf: Type: string enum: ["default","none","minimal","low","medium","high","xhigh","max"] Type: null - `force_default_llm` (optional) Type: boolean - `allowed_group_ids` (optional) Type: Array Items: Type: integer minimum: 0 - `user_id` (optional) Type: integer | null anyOf: Type: integer exclusiveMinimum: 0 Type: null - `allow_chat_channel_mentions` (optional) Type: boolean - `allow_chat_direct_messages` (optional) Type: boolean - `allow_topic_mentions` (optional) Type: boolean - `allow_personal_messages` (optional) Type: boolean - `tools` (optional) Type: Array> Items: Type: string | Array anyOf: Type: string minLength: 1 Type: Array minItems: 3 maxItems: 3 Items: Type: string | never | object | null | never | boolean oneOf: Type: string minLength: 1 Type: never | object | null anyOf: Type: never Must not match: Type: any Type: object | null anyOf: Type: object Additional properties: Type: any Type: null Type: never | boolean anyOf: Type: never Must not match: Type: any Type: boolean - `mcp_server_ids` (optional) Type: Array Items: Type: integer exclusiveMinimum: 0 - `mcp_server_tool_names` (optional) Type: object Additional properties: Type: Array Items: Type: string minLength: 1 - `subagent_ids` (optional) Type: Array Up to 20 existing AI agent IDs this agent may delegate to; IDs may include negative system-agent IDs Items: Type: integer | string anyOf: Type: integer Type: string pattern: "^-?[1-9]\\d*$" - `forced_tool_count` (optional) Type: integer minimum: -1 maximum: 100000 - `require_approval` (optional) Type: boolean - `response_format` (optional) Type: Array | null anyOf: Type: Array Items: Type: object Additional properties: Type: any Type: null - `examples` (optional) Type: Array> Items: Type: Array minItems: 2 maxItems: 2 Items: Type: string oneOf: Type: string Type: string - `show_thinking` (optional) Type: boolean - `vision_enabled` (optional) Type: boolean - `vision_max_pixels` (optional) Type: integer maximum: 4000000 exclusiveMinimum: 0 - `rag_chunk_tokens` (optional) Type: integer minimum: 1 maximum: 50000 - `rag_chunk_overlap_tokens` (optional) Type: integer minimum: 0 maximum: 200 - `rag_conversation_chunks` (optional) Type: integer minimum: 1 maximum: 1000 - `rag_llm_model_id` (optional) Type: integer | null anyOf: Type: integer exclusiveMinimum: 0 Type: null - `rag_uploads` (optional) Type: Array Items: Type: object - `id` (required) Type: integer exclusiveMinimum: 0 Additional properties: false - `max_turn_tokens` (optional) Type: integer | null anyOf: Type: integer maximum: 10000000 exclusiveMinimum: 0 Type: null - `compression_threshold` (optional) Type: integer minimum: 20 maximum: 99 Additional properties: false ## Examples ### JSON-RPC ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "discourse_ai_update_agent", "arguments": { "id": 0, "name": "string", "description": "string", "system_prompt": "string", "enabled": true, "priority": true, "default_llm_id": 0, "top_p": 0, "temperature": 0, "thinking_effort": "default", "force_default_llm": true, "allowed_group_ids": [ 0 ], "user_id": 0, "allow_chat_channel_mentions": true, "allow_chat_direct_messages": true, "allow_topic_mentions": true, "allow_personal_messages": true, "tools": [ "string" ], "mcp_server_ids": [ 0 ], "mcp_server_tool_names": {}, "subagent_ids": [ 0 ], "forced_tool_count": -1, "require_approval": true, "response_format": [ {} ], "examples": [ [ "string" ] ], "show_thinking": true, "vision_enabled": true, "vision_max_pixels": 0, "rag_chunk_tokens": 1, "rag_chunk_overlap_tokens": 0, "rag_conversation_chunks": 1, "rag_llm_model_id": 0, "rag_uploads": [ { "id": 0 } ], "max_turn_tokens": 0, "compression_threshold": 20 } } } ``` ### TypeScript ```typescript const result = await client.callTool({ "name": "discourse_ai_update_agent", "arguments": { "id": 0, "name": "string", "description": "string", "system_prompt": "string", "enabled": true, "priority": true, "default_llm_id": 0, "top_p": 0, "temperature": 0, "thinking_effort": "default", "force_default_llm": true, "allowed_group_ids": [ 0 ], "user_id": 0, "allow_chat_channel_mentions": true, "allow_chat_direct_messages": true, "allow_topic_mentions": true, "allow_personal_messages": true, "tools": [ "string" ], "mcp_server_ids": [ 0 ], "mcp_server_tool_names": {}, "subagent_ids": [ 0 ], "forced_tool_count": -1, "require_approval": true, "response_format": [ {} ], "examples": [ [ "string" ] ], "show_thinking": true, "vision_enabled": true, "vision_max_pixels": 0, "rag_chunk_tokens": 1, "rag_chunk_overlap_tokens": 0, "rag_conversation_chunks": 1, "rag_llm_model_id": 0, "rag_uploads": [ { "id": 0 } ], "max_turn_tokens": 0, "compression_threshold": 20 } }); ``` ### Python ```python result = await session.call_tool("discourse_ai_update_agent", arguments={ "id": 0, "name": "string", "description": "string", "system_prompt": "string", "enabled": true, "priority": true, "default_llm_id": 0, "top_p": 0, "temperature": 0, "thinking_effort": "default", "force_default_llm": true, "allowed_group_ids": [ 0 ], "user_id": 0, "allow_chat_channel_mentions": true, "allow_chat_direct_messages": true, "allow_topic_mentions": true, "allow_personal_messages": true, "tools": [ "string" ], "mcp_server_ids": [ 0 ], "mcp_server_tool_names": {}, "subagent_ids": [ 0 ], "forced_tool_count": -1, "require_approval": true, "response_format": [ {} ], "examples": [ [ "string" ] ], "show_thinking": true, "vision_enabled": true, "vision_max_pixels": 0, "rag_chunk_tokens": 1, "rag_chunk_overlap_tokens": 0, "rag_conversation_chunks": 1, "rag_llm_model_id": 0, "rag_uploads": [ { "id": 0 } ], "max_turn_tokens": 0, "compression_threshold": 20 }) ``` ## Delete AI Agent `TOOL discourse_ai_delete_agent` Delete a non-system AI agent. Requires admin credentials and write mode. Authentication: no security requirement declared for this operation. Request body: application/json (required) Type: object - `id` (required) Type: integer | string anyOf: Type: integer Type: string pattern: "^-?[1-9]\\d*$" Additional properties: false Declared MCP annotations: ```json { "destructiveHint": true } ``` ## Examples ### JSON-RPC ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "discourse_ai_delete_agent", "arguments": { "id": 0 } } } ``` ### TypeScript ```typescript const result = await client.callTool({ "name": "discourse_ai_delete_agent", "arguments": { "id": 0 } }); ``` ### Python ```python result = await session.call_tool("discourse_ai_delete_agent", arguments={ "id": 0 }) ``` ## Create AI Agent User `TOOL discourse_ai_create_agent_user` Explicitly create the bot user used by an AI agent for mention/chat entry points. Requires admin credentials and write mode. Authentication: no security requirement declared for this operation. Request body: application/json (required) Type: object - `id` (required) Type: integer | string anyOf: Type: integer Type: string pattern: "^-?[1-9]\\d*$" Additional properties: false ## Examples ### JSON-RPC ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "discourse_ai_create_agent_user", "arguments": { "id": 0 } } } ``` ### TypeScript ```typescript const result = await client.callTool({ "name": "discourse_ai_create_agent_user", "arguments": { "id": 0 } }); ``` ### Python ```python result = await session.call_tool("discourse_ai_create_agent_user", arguments={ "id": 0 }) ``` ## Export AI Agent `TOOL discourse_ai_export_agent` Export a portable AI agent bundle. It may include referenced custom-tool definitions but excludes secret bindings. Treat prompts and scripts as sensitive. Authentication: no security requirement declared for this operation. Request body: application/json (required) Type: object - `id` (required) Type: integer | string anyOf: Type: integer Type: string pattern: "^-?[1-9]\\d*$" Additional properties: false ## Examples ### JSON-RPC ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "discourse_ai_export_agent", "arguments": { "id": 0 } } } ``` ### TypeScript ```typescript const result = await client.callTool({ "name": "discourse_ai_export_agent", "arguments": { "id": 0 } }); ``` ### Python ```python result = await session.call_tool("discourse_ai_export_agent", arguments={ "id": 0 }) ``` ## Import AI Agent `TOOL discourse_ai_import_agent` Import a portable AI agent bundle. The bundle may create or overwrite embedded custom tools. force requires confirm_force=true. Requires admin credentials and write mode. Authentication: no security requirement declared for this operation. Parameters: - `bundle` (argument, object, required) Type: object Additional properties: Type: any - `force` (argument, boolean, optional) Type: boolean default: false - `confirm_force` (argument, boolean, optional) Type: boolean default: false Declared MCP annotations: ```json { "destructiveHint": true } ``` ## Examples ### JSON-RPC ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "discourse_ai_import_agent", "arguments": { "bundle": {}, "force": false, "confirm_force": false } } } ``` ### TypeScript ```typescript const result = await client.callTool({ "name": "discourse_ai_import_agent", "arguments": { "bundle": {}, "force": false, "confirm_force": false } }); ``` ### Python ```python result = await session.call_tool("discourse_ai_import_agent", arguments={ "bundle": {}, "force": false, "confirm_force": false }) ```