wajo.ai

# Wajo agentmcp — agent orchestration guide This MCP server lets you build, configure, and talk to agents on the Wajo platform end-to-end. Every call is owner-scoped to your API key: you only ever see and touch your own agents, connectors, and sessions. ## Mental model An **agent** is a persisted spec (`AgentSpec`): a name, a one-line description, an instruction body, a typed "soul" (persona), an LLM provider + model, and attached capabilities (system tools, connectors, MCP servers, skills, sub-agents). The lifecycle is: **create → inspect/refine → chat**. Chat-shaped calls go through a **session** — a server-minted handle bound to exactly one agent. ## Tools at a glance - Sessions: `generate_session_id`, `list_sessions`, `delete_session` - Build & chat: `build_agent`, `chat_agent`, `get_agent_reply` - Agent CRUD & discovery: `list_agents`, `find_agents`, `get_agent`, `update_agent`, `copy_agent`, `delete_agent` - Capabilities: `build_connector`, `build_mcp_server`, `list_connectors`, `delete_connector` - Docs (public — no account or auth needed): `search_documentation` `search_documentation` is the one tool you can call before authenticating — use it to search Wajo's docs (how to connect, build agents, use connectors) on this same endpoint; every other tool is scoped to your account and needs a credential. **There is no `create_agent` tool.** New agents are created by chatting with the built-in Agent Builder through `build_agent` (below). `update_agent` only patches an agent that already exists. (The Agent Builder itself uses a `create_agent` tool internally when you chat via `build_agent` — that name exists only inside the Builder's toolset and is not callable on this MCP surface.) ## Create an agent (via the Agent Builder) The Agent Builder is itself an agent, reached through `build_agent`: 1. Call `generate_session_id` with `agentId = "b4409947-a46d-497e-94bb-fbba525185b7"` (the Agent Builder's well-known id). You get back a `sessionId`. 2. Call `build_agent` with that `sessionId` and a `message` describing, in one brief, the agent you want — e.g. *"A support-triage agent that reads inbound email, tags urgency, and drafts replies."* The Builder creates **and persists** the new AgentSpec in that single turn and replies with its name and id. 3. Keep passing the same `sessionId` to `build_agent` to refine conversationally, or switch to the CRUD tools below for precise edits. The first message is treated as a complete brief: the Builder makes best-effort choices for anything you leave unspecified (name, model, tools, soul) instead of interrogating you. Open the returned id with `get_agent` to see what it chose. ## Inspect and refine an existing agent - `list_agents` — slim summary of every agent you can access: your own plus agents shared through your orgs' projects (id, name, description, provider, model, updated_at). Start here to find an id. - `get_agent` — the full spec for one id (instructions, soul, system_tools, connector_ids, skills, sub-agents, …). Resolves any agent `list_agents` returns. Always read this before `update_agent`. - `update_agent` — patch one agent. Singular fields use proto presence: **omit a field to leave it unchanged.** To change the tool or connector lists, set `replaceSystemTools: true` / `replaceConnectorIds: true` and supply the full replacement array (an empty array clears the list). - `delete_agent` — remove an agent. Destructive; confirm the id with the user first. ## Talk to an agent 1. Call `generate_session_id` with `agentId = "<the agent's real UUID>"` → a `sessionId`. 2. Call `chat_agent` with that `sessionId` and your `message`. Reuse the same `sessionId` across turns to continue the conversation. Long turns may return `status: "working"` instead of the final reply. The run continues server-side; call `get_agent_reply` with the same `sessionId` every ~15s until it returns `status: "complete"` or `status: "failed"`. ## The session-id contract - Session ids are **server-minted** by `generate_session_id` and bound to one agent. You cannot invent or guess one — the server rejects unbound ids. - A session is either a **builder** session (bound to the Agent Builder id) or a **chat** session (bound to a real agent). `build_agent` requires the former; `chat_agent` requires the latter. Calling the wrong one returns an error that names the call you should have used. - `chat_agent` takes no `agentId` — the session binding is the only routing key. - `list_sessions` / `delete_session` manage your sessions; `list_sessions` takes an optional `agentId` to scope the result to one agent. ## Give an agent external capabilities Add a capability whenever the agent's instructions describe an action it can't yet take. - **System tools** — platform-built capabilities (web search, send SMS, Google Workspace, …). Set them on `system_tools` via the Builder or `update_agent`. - **Connectors** — any REST API distilled from its docs. `build_connector` takes a docs URL (`format` picks the distiller: `openapi` / `postman` / `html`) and persists a ConnectorSpec; attach it by adding its id to `connector_ids` via `update_agent`. `list_connectors` / `delete_connector` manage them. (OAuth-backed services aren't supported through this path yet.) - **MCP servers** — `build_mcp_server` registers a remote MCP server (auth: bearer / oauth / none), caches its tool catalog, and lets the agent call those tools. ## Wire format Request JSON uses protojson lowerCamelCase across every tool: `agentId`, `sessionId`, `sessionName`, `replaceSystemTools`, `connectorIds`. Most tools return a structured proto in the result (a stable lowerCamelCase schema in `structuredContent`), but `build_mcp_server` returns a plain text result instead (a JSON summary rendered as text). Read each tool's own result rather than assuming one uniform response envelope.

# Wajo agentmcp — agent orchestration guide This MCP server lets you build, configure, and talk to agents on the Wajo platform end-to-end. Every call is owner-scoped to your API key: you only ever see and touch your own agents, connectors, and sessions. ## Mental model An **agent** is a persisted spec (`AgentSpec`): a name, a one-line description, an instruction body, a typed "soul" (persona), an LLM provider + model, and attached capabilities (system tools, connectors, MCP servers, skills, sub-agents). The lifecycle is: **create → inspect/refine → chat**. Chat-shaped calls go through a **session** — a server-minted handle bound to exactly one agent. ## Tools at a glance - Sessions: `generate_session_id`, `list_sessions`, `delete_session` - Build & chat: `build_agent`, `chat_agent`, `get_agent_reply` - Agent CRUD & discovery: `list_agents`, `find_agents`, `get_agent`, `update_agent`, `copy_agent`, `delete_agent` - Capabilities: `build_connector`, `build_mcp_server`, `list_connectors`, `delete_connector` - Docs (public — no account or auth needed): `search_documentation` `search_documentation` is the one tool you can call before authenticating — use it to search Wajo's docs (how to connect, build agents, use connectors) on this same endpoint; every other tool is scoped to your account and needs a credential. **There is no `create_agent` tool.** New agents are created by chatting with the built-in Agent Builder through `build_agent` (below). `update_agent` only patches an agent that already exists. (The Agent Builder itself uses a `create_agent` tool internally when you chat via `build_agent` — that name exists only inside the Builder's toolset and is not callable on this MCP surface.) ## Create an agent (via the Agent Builder) The Agent Builder is itself an agent, reached through `build_agent`: 1. Call `generate_session_id` with `agentId = "b4409947-a46d-497e-94bb-fbba525185b7"` (the Agent Builder's well-known id). You get back a `sessionId`. 2. Call `build_agent` with that `sessionId` and a `message` describing, in one brief, the agent you want — e.g. *"A support-triage agent that reads inbound email, tags urgency, and drafts replies."* The Builder creates **and persists** the new AgentSpec in that single turn and replies with its name and id. 3. Keep passing the same `sessionId` to `build_agent` to refine conversationally, or switch to the CRUD tools below for precise edits. The first message is treated as a complete brief: the Builder makes best-effort choices for anything you leave unspecified (name, model, tools, soul) instead of interrogating you. Open the returned id with `get_agent` to see what it chose. ## Inspect and refine an existing agent - `list_agents` — slim summary of every agent you can access: your own plus agents shared through your orgs' projects (id, name, description, provider, model, updated_at). Start here to find an id. - `get_agent` — the full spec for one id (instructions, soul, system_tools, connector_ids, skills, sub-agents, …). Resolves any agent `list_agents` returns. Always read this before `update_agent`. - `update_agent` — patch one agent. Singular fields use proto presence: **omit a field to leave it unchanged.** To change the tool or connector lists, set `replaceSystemTools: true` / `replaceConnectorIds: true` and supply the full replacement array (an empty array clears the list). - `delete_agent` — remove an agent. Destructive; confirm the id with the user first. ## Talk to an agent 1. Call `generate_session_id` with `agentId = "<the agent's real UUID>"` → a `sessionId`. 2. Call `chat_agent` with that `sessionId` and your `message`. Reuse the same `sessionId` across turns to continue the conversation. Long turns may return `status: "working"` instead of the final reply. The run continues server-side; call `get_agent_reply` with the same `sessionId` every ~15s until it returns `status: "complete"` or `status: "failed"`. ## The session-id contract - Session ids are **server-minted** by `generate_session_id` and bound to one agent. You cannot invent or guess one — the server rejects unbound ids. - A session is either a **builder** session (bound to the Agent Builder id) or a **chat** session (bound to a real agent). `build_agent` requires the former; `chat_agent` requires the latter. Calling the wrong one returns an error that names the call you should have used. - `chat_agent` takes no `agentId` — the session binding is the only routing key. - `list_sessions` / `delete_session` manage your sessions; `list_sessions` takes an optional `agentId` to scope the result to one agent. ## Give an agent external capabilities Add a capability whenever the agent's instructions describe an action it can't yet take. - **System tools** — platform-built capabilities (web search, send SMS, Google Workspace, …). Set them on `system_tools` via the Builder or `update_agent`. - **Connectors** — any REST API distilled from its docs. `build_connector` takes a docs URL (`format` picks the distiller: `openapi` / `postman` / `html`) and persists a ConnectorSpec; attach it by adding its id to `connector_ids` via `update_agent`. `list_connectors` / `delete_connector` manage them. (OAuth-backed services aren't supported through this path yet.) - **MCP servers** — `build_mcp_server` registers a remote MCP server (auth: bearer / oauth / none), caches its tool catalog, and lets the agent call those tools. ## Wire format Request JSON uses protojson lowerCamelCase across every tool: `agentId`, `sessionId`, `sessionName`, `replaceSystemTools`, `connectorIds`. Most tools return a structured proto in the result (a stable lowerCamelCase schema in `structuredContent`), but `build_mcp_server` returns a plain text result instead (a JSON summary rendered as text). Read each tool's own result rather than assuming one uniform response envelope.