--- title: "Getting started with Wajo" url: https://wajo.ai/docs/getting-started.md summary: "Wajo is a platform for building and running AI agents. An agent is a persisted configuration — instructions, a persona, an LLM provider and model, and a set of attached capabilities (tools, connectors, MCP servers, skills) — that you can talk to over chat, email, Slack, voice, or an API." related: [building-agents, connectors, mcp-server, mcp-tools, sessions, webhooks] --- # Getting started with Wajo Wajo is a platform for building and running AI agents. An agent is a persisted configuration — instructions, a persona, an LLM provider and model, and a set of attached capabilities (tools, connectors, MCP servers, skills) — that you can talk to over chat, email, Slack, voice, or an API. You build and drive agents through the Wajo MCP server, which connects your AI client (Claude, Cursor, ChatGPT, and other MCP-capable tools) directly to the Wajo platform. ## The lifecycle Every agent follows the same three-step lifecycle: 1. **Create** — describe the agent you want in one brief, and the Agent Builder designs and persists it for you. See "Building agents". 2. **Refine** — inspect the agent and adjust its instructions, persona, model, and attached capabilities until it behaves the way you want. 3. **Chat** — talk to the finished agent. Chat happens through a session, a server-minted handle bound to exactly one agent. See "Sessions". ## Connecting Point your MCP client at the Wajo MCP server and authenticate. See "The Wajo MCP server" for the endpoint, transport, and authentication options. ## Where to next - **The Wajo MCP server** — connect and authenticate. - **MCP tools** — the full tool surface. - **Building agents** — the Agent Builder. - **Sessions** — how chat is addressed. - **Connectors** — call external HTTP APIs from an agent. --- title: "Building agents" url: https://wajo.ai/docs/building-agents.md summary: "An agent on Wajo is a persisted specification:" related: [getting-started, connectors, mcp-server, mcp-tools, sessions, webhooks] --- # Building agents An agent on Wajo is a persisted specification: - a **name** and a one-line **description**, - an **instruction** body (what the agent does and how), - a typed **soul** (its persona / voice), - an LLM **provider and model**, - attached **capabilities** — system tools, connectors, MCP servers, skills, and sub-agents. ## Create with the Agent Builder The Agent Builder is itself an agent, reached through the `build_agent` tool: 1. Call `generate_session_id` with the Agent Builder's id (`b4409947-a46d-497e-94bb-fbba525185b7`). You get back a `sessionId`. 2. Call `build_agent` with that `sessionId` and a one-paragraph brief of the agent you want — e.g. "A support-triage agent that reads inbound email, tags urgency, and drafts replies." The Builder designs, persists, and returns the new agent's name and id in a single turn. 3. Keep chatting on the same `sessionId` to refine it. ## Refine Use `get_agent` to read the full record, then `update_agent` to patch its instructions, model, or attached capabilities. Or keep refining conversationally through `build_agent`. ## Attach capabilities - **System tools** — platform capabilities the agent can use (web search, calendar, email, and more). - **Connectors** — external HTTP APIs. See "Connectors". - **MCP servers** — third-party MCP tool servers, registered with `build_mcp_server`. - **Skills** — reusable instruction fragments curated by the platform. --- title: "Connectors" url: https://wajo.ai/docs/connectors.md summary: "A connector lets an agent call an external HTTP API. Connectors are data, not code — you add a new one by pointing Wajo at the API's public docs, with no deploy." related: [getting-started, building-agents, mcp-server, mcp-tools, sessions, webhooks] --- # Connectors A connector lets an agent call an external HTTP API. Connectors are data, not code — you add a new one by pointing Wajo at the API's public docs, with no deploy. ## Build a connector Use `build_connector` with the service's documentation URL and a `format`: - `openapi` (default) — an OpenAPI 3.x document. - `postman` — a Postman v2.1 collection. - `html` — an HTML API-reference page; Wajo discovers the OpenAPI or Postman spec linked from it. Wajo distills the docs into a typed endpoint catalog the agent can call. ## Typed vs free-form - **Typed** — the agent picks a catalog endpoint and supplies inputs, validated against the endpoint's schema. Deterministic; the default. - **Free-form** — the agent supplies a method and path directly, for endpoints the catalog missed. A connector can be marked typed-only to disable this. ## Scope and credentials - **SYSTEM** connectors are platform-curated and available to everyone. - **USER** connectors are the ones you author with `build_connector`, scoped to you. Credentials are per-user and stored encrypted; you provide them through the credential form. The agent never sees a secret — Wajo attaches auth after the agent produces its request, so credentials stay server-side. ## OAuth-backed services Connectors you author support API-key, Bearer, and Basic auth. OAuth-backed services are platform-curated — connect to those from the Wajo Integrations UI rather than building a connector. --- title: "The Wajo MCP server" url: https://wajo.ai/docs/mcp-server.md summary: "Wajo exposes its platform to AI clients through a hosted MCP (Model Context Protocol) server. Any MCP-capable client — Claude Code, Claude.ai and Claude Desktop, Cursor, ChatGPT, VS Code, and others — can connect and drive the Wajo runtime end-to-end." related: [getting-started, building-agents, connectors, mcp-tools, sessions, webhooks] --- # The Wajo MCP server Wajo exposes its platform to AI clients through a hosted MCP (Model Context Protocol) server. Any MCP-capable client — Claude Code, Claude.ai and Claude Desktop, Cursor, ChatGPT, VS Code, and others — can connect and drive the Wajo runtime end-to-end. ## Endpoint and transport - **Endpoint:** `https://mcp.api.wajo.ai/mcp` - **Transport:** Streamable HTTP. The server is stateless across connections, so it scales horizontally — you do not need sticky sessions. ## Authentication Two ways to authenticate, depending on your client: - **API key.** Developer tools (Claude Code, Cursor, VS Code) send a Wajo API key (prefixed `wak_`), either as an `X-API-Key` header or as a standard `Authorization: Bearer `. For example, in Claude Code: ```shell claude mcp add --transport http wajo https://mcp.api.wajo.ai/mcp \ --header "X-API-Key: wak_..." ``` - **OAuth.** Consumer apps that cannot paste a key — Claude.ai custom connectors and ChatGPT developer-mode apps — use the MCP authorization (OAuth) flow. Add `https://mcp.api.wajo.ai/mcp` as a custom connector and complete the sign-in prompt. Every request is scoped to the authenticated user: you only ever see and touch your own agents, connectors, and sessions. ## Searching the docs without an account This documentation is itself searchable over MCP with no account and no authentication: connect to `https://mcp.api.wajo.ai/mcp` and call `search_documentation`. It is the one tool you can use before you authenticate — everything else on the endpoint is scoped to your account and prompts you to sign in the first time you call it. --- title: "MCP tools" url: https://wajo.ai/docs/mcp-tools.md summary: "The Wajo MCP server (`mcp.api.wajo.ai/mcp`) exposes the tools below. Every call is owner-scoped to the authenticated user — except `search_documentation`, which is public and needs no account (see \"The Wajo MCP server\"). All of them, public and authenticated, live on the same `/mcp` endpoint." related: [getting-started, building-agents, connectors, mcp-server, sessions, webhooks] --- # MCP tools The Wajo MCP server (`mcp.api.wajo.ai/mcp`) exposes the tools below. Every call is owner-scoped to the authenticated user — except `search_documentation`, which is public and needs no account (see "The Wajo MCP server"). All of them, public and authenticated, live on the same `/mcp` endpoint. ## Sessions - `generate_session_id` — mint a server-controlled session id bound to a specific agent. Required before any chat-shaped call. - `list_sessions` — list your existing sessions. - `delete_session` — delete a session. ## Build and chat - `build_agent` — chat with the built-in Agent Builder to design and persist a new agent, or keep refining one you are building. - `chat_agent` — chat with any persisted agent. - `get_agent_reply` — poll a `chat_agent` turn that came back `status="working"`. Pass the same session id; it reports that session's latest turn, so do not send another message on the session until polling settles. ## Agent discovery and management - `list_agents` — list the agents you can access (your own plus those shared through your organizations' projects). - `find_agents` — fuzzy-search agents by a query, including the public agent directory, so you can discover agents you do not own. This is how you find Fo, the platform's general-purpose assistant. - `get_agent` — fetch an agent's full record. - `update_agent` — patch an existing agent. - `copy_agent` — duplicate an agent. - `delete_agent` — delete an agent you own. ## Capabilities - `build_connector` — turn a public API's docs into a connector an agent can call. Point it at an OpenAPI 3.x document or a Postman v2.1 collection. See "Connectors". - `build_mcp_server` — register a third-party MCP server so an agent can call its tools. - `list_connectors` — list connectors you can use. - `delete_connector` — delete one of your connectors. Destructive; confirm the connector id with the user first. ## Webhooks - `register_webhook` — register an https URL that receives a signed POST when a conversation turn closes, a scheduled action fires or the assistant sends a proactive message. Returns the signing secret once. See "Webhooks". - `list_webhooks` — your endpoints with their status and delivery state. - `delete_webhook` — remove an endpoint. Destructive; confirm the id with the user first. - `test_webhook` — send a `webhook.test` event now and report the answer. ## The Fo profile at `/fo` `mcp.api.wajo.ai/fo` is a second, separate profile carrying one agent — Fo — for consumer apps that host a single assistant (a ChatGPT app, for instance). It does not expose the tools above; the only ids on its wire are ones the server handed out. - `ask_fo` — send the user's request to Fo, which acts in the real world from their own Wajo account. Continues their current conversation by default. - `get_fo_reply` — wait for Fo's reply after `ask_fo` returned `status="working"`. Each call waits up to 40 seconds; keep calling it and relay progress rather than asking the user to check back. - `list_fo_conversations` — the user's previous Fo conversations across every channel (chat, email, texting, Slack, voice, and this app), newest first. - `get_fo_conversation` — read the recent transcript of one of them. ## There is no create_agent tool New agents are created by chatting with the Agent Builder through `build_agent`. `update_agent` only patches an agent that already exists. See "Building agents". --- title: "Sessions" url: https://wajo.ai/docs/sessions.md summary: "Chat-shaped calls (`build_agent`, `chat_agent`) go through a **session** — a server-minted handle bound to exactly one agent." related: [getting-started, building-agents, connectors, mcp-server, mcp-tools, webhooks] --- # Sessions Chat-shaped calls (`build_agent`, `chat_agent`) go through a **session** — a server-minted handle bound to exactly one agent. ## Lifecycle 1. `generate_session_id` — pass the `agent_id` you want to talk to (and an optional `session_name`). The server mints a session id and binds it to that agent, scoped to you. 2. `chat_agent` — pass the `session_id` and your message. The server resolves the bound agent and runs the turn. You never pass the agent id on the chat call; the session carries it. ## Session ids are server-minted You cannot invent a session id — the server mints it and owns the binding from session to agent. This keeps the agent's identity server-authoritative and prevents a client from re-pointing a session at a different agent by editing a request field. The binding is scoped to the owner, so a session id is only ever usable by the account that created it. --- title: "Webhooks" url: https://wajo.ai/docs/webhooks.md summary: "The MCP endpoint is pull-only: every tool is a request you make, and nothing on it can call you back. A device, a bot or an integration that must react the moment the assistant answers registers a **webhook**: an https URL that receives a signed POST for each event it subscribed to." related: [getting-started, building-agents, connectors, mcp-server, mcp-tools, sessions] --- # Webhooks The MCP endpoint is pull-only: every tool is a request you make, and nothing on it can call you back. A device, a bot or an integration that must react the moment the assistant answers registers a **webhook**: an https URL that receives a signed POST for each event it subscribed to. ## Registering an endpoint Call `register_webhook` with the `url`, a `name`, and optionally the `eventKinds` to receive (omit for all). The reply carries the endpoint and its signing secret **once**; the server keeps the secret encrypted and can never show it again. Delete and re-register an endpoint to get a new one. - Up to 5 webhooks per account. - The URL must be https and publicly reachable. Private addresses, loopback and cloud metadata hosts are refused at registration and again at dial. - Endpoints can also be managed on the Apps page of the Wajo settings. ## Events Each delivery is a JSON body with `id`, `type`, `occurredAt`, `webhookId` and one data object named after the type: - `conversation.reply` → `reply`: a turn in one of your conversations closed. Carries `conversationId` (the same id the conversation tools use), `channel` (`chat`, `email`, `sms`, `slack`, `voice`), `status` (`completed`, `failed`, `stopped`), `trigger` (`user`, `inbound_email`, `inbound_text`, `voice_postcall`, `system`), `agentId`, `text` (the assistant's final message, capped at 2,000 characters), `awaitingUser` (true when the assistant asked you something) and `closure` (`message`, `delivered`, `acknowledged`, `silent`). - `schedule.fired` → `reply`: a scheduled action or one-shot reminder fired and finished. Same shape as above with `trigger: "schedule"` and the `scheduleId`. - `message.proactive` → `message`: the assistant sent you a message on its own initiative. Carries `conversationId` (when known), `channel`, `text` and `agentId`. - `webhook.test` → `test`: what `test_webhook` sends. Every endpoint receives it. ## Verifying a delivery Deliveries follow the Standard Webhooks specification. Each request carries `webhook-id`, `webhook-timestamp` (unix seconds) and `webhook-signature` (`v1,` over `".."` keyed with your secret). Verify with any Standard Webhooks library, reject timestamps older than five minutes, and deduplicate on `webhook-id`: a retried delivery keeps the same id. ## Delivery and retries Answer `2xx` within 10 seconds to acknowledge; do the work after responding. A `5xx`, a timeout or a connection failure is retried with backoff for up to an hour; a `4xx` is not retried; `410 Gone` disables the endpoint. An endpoint whose every attempt fails for three days is disabled too. A successful `test_webhook` re-enables a disabled endpoint, and `list_webhooks` shows each endpoint's status, last delivery, last error and failure streak.