Custom Agents & Self-Hosted Harnesses
The Custom platform lets a background agent run on your own runtime instead of a Willow-managed one. Your harness authenticates with the agent's client credentials and calls the agent's assigned tools back through the Willow gateway — over MCP or a plain REST API. You can also let Willow push work to your harness: triggers and messages are POSTed to the endpoints you register with Add custom type.
Open the agent from Build > Background Agents (see the list page), choose a Custom agent, and use the Connect button on the Overview tab (or the Connection panel in Settings → Platform Configuration) to find its endpoints and credentials.
This page documents every payload involved, in both directions:
| Direction | What it covers |
|---|---|
| Your harness → Willow | Authenticate, call tools over MCP, call tools over REST, fire API triggers. |
| Willow → your harness | Sync and message payloads delivered to your configured endpoints. |
Authentication
Every request to the gateway is authenticated with the agent's client credentials:
| Credential | Where it comes from |
|---|---|
| Client ID | The agent's access_key. |
| Client Secret | A manual token's secret, shown once when you create or recreate it. |
Copy the access key from the agent's connection details and create a manual token under Settings > Tokens. Send them together as a bearer token:
Authorization: Bearer <client_id>:<client_secret>
The client secret is only shown at creation and when you create or recreate a token. Store it in a secrets manager; it cannot be retrieved later. Recreating a token immediately invalidates its previous secret. Deploying does not affect manual tokens. See Agent credentials.
Connecting to your harness
The Connect dialog exposes two base URLs:
| Endpoint | URL shape | Use it for |
|---|---|---|
| MCP endpoint | https://<your-gateway>/agent/<slug> | Speak the Model Context Protocol from any MCP-compatible host. |
| API endpoint | https://<your-gateway>/agent-api/<slug> | Call a single tool with a plain HTTP POST. |
<your-gateway> is your gateway’s Run URL, shown on the gateway card under Settings > Gateway Settings, for example https://acme.withwillow.ai/mcp. The Connect dialog shows both URLs with it already filled in.
The agent only ever exposes the tools, skills, and rules assigned to it — its capabilities are its permission boundary.
MCP configuration
Copy this from Connect → MCP config (or download the ZIP bundle). Drop it into any MCP host:
{
"mcpServers": {
"<slug>": {
"type": "http",
"url": "https://<your-gateway>/agent/<slug>",
"headers": {
"Authorization": "Bearer <client_id>:<client_secret>"
}
}
}
}
Calling tools
Option A: MCP
Connect to the MCP endpoint with the Authorization header above and call tools using standard MCP tools/list and tools/call requests. Every call flows through the gateway and is subject to the same guards, policies, and logging as any other traffic.
Option B: REST API
Prefer plain HTTP? Each enabled tool is also a POST endpoint.
Discover the tools the agent exposes:
curl https://<your-gateway>/agent-api/<slug> \
-H "Authorization: Bearer <client_id>:<client_secret>"
{
"data": {
"agent": "<slug>",
"description": "Call any of this agent's tools with a direct POST request. The JSON request body is passed through as the tool arguments.",
"tools": [
{
"name": "slack__send_message",
"description": "Send a message to a Slack channel",
"input_schema": { "type": "object", "properties": { "channel": { "type": "string" }, "text": { "type": "string" } } }
}
]
}
}
Call a tool. The path is <integration_slug>__<tool_slug> and the JSON body is passed straight through as the tool arguments:
curl -X POST https://<your-gateway>/agent-api/<slug>/slack__send_message \
-H "Authorization: Bearer <client_id>:<client_secret>" \
-H "Content-Type: application/json" \
-d '{ "channel": "#alerts", "text": "Deploy finished" }'
The response mirrors an MCP tool result:
{
"isError": false,
"content": [
{ "type": "text", "text": "Message sent to #alerts" }
]
}
A 4xx status with "isError": true means the tool wasn't found, isn't enabled for this agent, or the call failed — the reason is in content[].text.
Firing an API trigger
An API trigger starts an agent conversation on demand. Create one on the agent's Triggers tab; it has a stored prompt (message) and an optional Session ID (JSONata) expression. Call it at:
POST https://<your-gateway>/agent-api/<slug>/trigger/<triggerId>
Authorization: Bearer <client_id>:<client_secret>
Content-Type: application/json
Instead of the trigger id you can use the trigger's Label: POST https://<your-gateway>/agent-api/<slug>/trigger/<label>. The first API trigger you add is labelled default, so callers can use /trigger/default without storing the id. A label is optional, uses lowercase letters, numbers, and hyphens, and must be unique on the agent.
Copy the exact URL from the trigger’s row on the Triggers tab. It already includes the gateway’s Run URL path, for example https://acme.withwillow.ai/mcp/agent-api/<slug>/trigger/<triggerId>.
The request body is optional:
{
"message": "Optional prompt that overrides the trigger's stored message",
"session_key": "Optional id that correlates this call into a conversation",
"mode": "Optional mode name or id (beta)"
}
| Field | Type | Behavior |
|---|---|---|
message | string | Overrides the trigger's saved prompt for this call. Omit it to use the saved prompt. |
session_key | string | Correlates the call to a conversation. If it matches an existing session that conversation is resumed; otherwise a new one starts. |
mode | string | Beta. A mode's name or id, to run under it instead of the trigger's own mode. An unknown mode returns a 400 that lists the agent's modes. |
How the session is chosen
The session id is resolved in this order:
session_keyin the body, if present.- The trigger's Session ID (JSONata) expression, evaluated against the request body. For example, with the expression
payload.thread_idand a body of{ "payload": { "thread_id": "T-123" } }, the session id isT-123. Use this to correlate runs by an id that already lives in your webhook payload. - A fresh conversation on each call, when neither is provided.
The response reports where the message landed:
{
"isError": false,
"content": [{ "type": "text", "text": "Trigger fired" }],
"session_id": "T-123",
"session_key": "T-123",
"created": true
}
created is true when a new conversation was started and false when an existing one was resumed.
Receiving work on your harness
Instead of only pulling tools, you can have Willow push conversations to your own harness. Configure the delivery endpoints in the agent's Connection panel:
| Setting | Meaning |
|---|---|
| Single endpoint (default on) | One URL handles both new sessions and every follow-up message. |
| New session endpoint | Called to start a new session (only when Single endpoint is off). |
| New message endpoint | Called to deliver messages to your harness. |
| Request body (under each URL) | Optional. Willow default sends the standard harness body; Custom opens a JSON template where {{message}}, {{session_key}}, {{agent_slug}}, {{agent_id}} and {{event}} are filled in per request. Select Build with AI to write it from a description of what your endpoint expects. See Custom request bodies. |
Willow POSTs JSON to these URLs with Content-Type: application/json. Calls to a Custom agent's own harness endpoints carry no credentials; auth tokens apply to Custom Managed types, which send the token on a configurable header (defaults to Authorization: Bearer <token>).
For the full delivery contract — the agent.session payload sent on the first turn, timeouts, retries, and how session_key is built by each trigger source — see Harness API: New Sessions and Messages.
1. agent.sync (agent snapshot)
Sent when the agent is synced, so your harness has the current definition. The agent_token is the agent's client_id:client_secret bearer token, so your harness can call the gateway:
{
"event": "agent.sync",
"agent": {
"id": "agent_abc123",
"name": "Release Notes Writer",
"slug": "release-notes-writer",
"description": "Drafts release notes from merged PRs",
"status": "active",
"capabilities": {
"tools": [],
"skills": [],
"rules": []
},
"platform_config": {},
"mcp_url": "https://<your-gateway>/agent/release-notes-writer"
},
"agent_token": "<client_id>:<client_secret>"
}
Respond 2xx to acknowledge. You may echo metadata that Willow stores on the sync state:
{ "external_agent_id": "your-side-id", "external_agent_version": 3 }
2. agent.message (a conversation turn)
Sent when a trigger, schedule, or webhook delivers a message. Correlation is delegated to your harness via session_key:
{
"event": "agent.message",
"agent_id": "agent_abc123",
"agent_slug": "release-notes-writer",
"external_agent_id": "your-side-id",
"session_key": "T-123",
"message": "Summarize the PRs merged today."
}
| Field | Meaning |
|---|---|
session_key | Conversation id. Resume the matching session, or start one on first use. |
external_agent_id | The id you returned from agent.sync, when set. |
message | The prompt to deliver to the agent. |
Return any 2xx status to acknowledge receipt. A non-2xx response is surfaced in Willow as a delivery error.
Sync webhook and manual sync
To sync an individual Custom agent, open its Connection panel and select Sync to harness. After the first sync, the button reads Re-sync (rotate token).
A successful sync replaces the agent's platform token. Manual tokens remain valid. Willow shows the Authorization header, MCP URL, and agent.sync payload once. Copy these values into your harness, or configure a Sync webhook to receive them automatically:
| Field | Meaning |
|---|---|
| Webhook URL | Optional. Willow POSTs the agent.sync event here on every sync. It must be a public https URL with no credentials or {placeholders} in it. Willow does not follow redirects and refuses private addresses. |
| Signing secret | Optional. When set, each request carries X-Willow-Signature: t=<timestamp>,v1=<signature>, the HMAC-SHA256 of <timestamp>.<body>. Verify it before trusting the token in the body, as described in Send results to a webhook. The secret is stored encrypted and never shown again. Select Remove stored secret to clear it. |
If the agent uses an external (self-hosted) run gateway and has a sync webhook, the button reads Sync via browser (Re-sync via browser after the first sync). It opens a page on your run gateway, which sends the webhook from inside your network, so the Webhook URL can then point at a private or internal https host. Your browser must allow the popup it opens.
The body has the same shape as agent.sync above, plus platform: "custom" and an authorization field with the full Bearer <client_id>:<client_secret> header. Your endpoint must return 2xx within 15 seconds. Otherwise, sync fails and the previous platform token remains valid.
Testing an agent
Use Test on the agent's Overview tab to trigger a run without wiring anything up. Edit the JSON payload — it defaults to a session_key and a message — and select Run test:
{
"session_key": "test-a1b2c3",
"message": "Hi, this is a test run. Give a short summary of what you can do."
}
Willow starts (or resumes) a conversation on the agent's platform and returns the resulting session_id and whether it was newly created.
What to do next
- Back to Background Agents
- Harness API: New Sessions and Messages for the exact payloads Willow delivers
- Add a custom agent type to register your sync and message endpoints
- Assign tools from your MCP servers
- Set up guards to constrain what the agent can do
- Gateway API reference