Composio integrations

Composio is a managed catalog of third-party SaaS tools (Reddit, Gmail, Slack, GitHub, …). When an agent should act against one of those apps, you enable the Composio toolkit at the deployment level and connect each actor (end user or service identity) to it. The agent's runtime then surfaces the toolkit's tools automatically — there's no per-tool createAiTool step.

Use Composio when the action lives in someone else's product. For an HTTP endpoint you own, use an Api tool; for code execution, CodeRunner; for your own MCP server, Mcp.

API flow

Configure the Composio API key on the deployment first (one-time, via deployment settings). Then:

# Enable the toolkit on the deployment
wacht api call enableComposioApp --body @enable.json

# Confirm it's available
wacht api call listComposioTools --param toolkits=<toolkit_slug>

enable.json (managed auth — Composio handles OAuth):

{
  "slug": "<toolkit_slug>",
  "auth": { "type": "managed", "auth_scheme": "OAUTH2" }
}

That's it on the agent side — the toolkit's tools become available to any agent in this deployment as soon as the calling actor is authorized.

createAiTool rejects tool_type: "Virtual" with "Virtual tools cannot be created directly — they are discovered at runtime". Don't try to persist Composio tools as AI-tool records.

Authorization (per actor)

Each actor that the agent acts on behalf of needs an authorized connection for the toolkit. The first time the agent calls a tool the actor isn't connected to, the runtime returns an error pointing at the OAuth handshake URL.

Connection endpoints under /ai/composio/toolkits/{slug}/auth-configs and /ai/composio/toolkits/{slug}/auth-details drive the flow. The console exposes a one-click "Connect" button for the agent's current actor; service actors typically connect once via the same flow seeded from a session.

Tool surface

wacht api call listComposioTools --param toolkits=<slug> returns the toolkit's tools with their remote_tool_slug, display_name, description, and input_schema. The agent sees the same set at runtime once the actor is authorized.