Skip to main content

Connect kagent

kagent runs agents as SandboxAgent custom resources in your Kubernetes cluster. Configure Willow with the namespace and name of your existing SandboxAgent.

Sync provides the MCP gateway URL, a gateway token, and a system message containing your prompt and enabled skills. Apply these values to your SandboxAgent, RemoteMCPServer, and Kubernetes Secret, or deliver them to your automation through a sync webhook.

How it fits together​

PieceWhere it runsWho owns it
SandboxAgent CRDYour clusterYou
RemoteMCPServer + SecretYour clusterYou (from the values sync reveals)
kagent controllerYour clusterYou
Willow MCP gatewayReachable from your clusterWillow

At run time, Willow's in-cluster component invokes your agent over the kagent A2A protocol; the agent calls back through the RemoteMCPServer to Willow's gateway for its tools. Willow's control plane is never in the run path.

Prerequisites​

  • A Kubernetes cluster with the kagent controller installed and a SandboxAgent you control.
  • Network egress from the cluster to Willow's MCP gateway URL.
  • The kagent controller base URL (for example http://kagent-controller.kagent:8083).

Step 1: Connect the platform in Willow​

  1. Go to Build > Background Agents, open Settings (gear icon), and find kagent under Agent Types.
  2. Select Set credentials and enter the org-level kagent controller base URL (and an auth token if your controller requires one). These live on the platform connection, not on each agent.
  3. Select Connect.

Once connected, kagent appears as a selectable platform when creating an agent.

Step 2: Reference your SandboxAgent​

When you create the agent, set its platform configuration to point at the CRD you own:

FieldMeaning
NamespaceKubernetes namespace of the SandboxAgent (defaults to kagent).
Agent nameThe SandboxAgent CRD name Willow invokes. Required before you can sync.
Controller URLOptional per-agent override of the org connection's base URL.
System promptThe recommended systemMessage. Enabled skills are appended to it when revealed (kagent has no separate skills API).

Step 3: Deploy to reveal the wiring values​

Select Deploy in the detail-page header. On a kagent agent this does not touch your cluster — it rotates the agent's gateway secret and shows the values once:

Revealed valueWhat it is
MCP gateway URLThe url your RemoteMCPServer points at.
Authorization headerBearer <access_key>:<secret> — the rotated gateway token. Shown once.
A2A URL…/api/a2a-sandboxes/{namespace}/{agent}/, where Willow invokes the agent.
Secret + RemoteMCPServer manifestA ready-to-apply YAML block (see below).
Recommended system messageYour prompt with enabled skills appended.
The token is shown only once

Deploying rotates the gateway secret, which invalidates any header revealed by a previous deploy. Copy the Authorization value now and paste it straight into your Secret — if you lose it, deploy again to mint a new one.

Step 4: Apply to your cluster​

Apply the revealed Secret + RemoteMCPServer with kubectl apply -f -. The manifest looks like this (with the values from Step 3 filled in):

apiVersion: v1
kind: Secret
metadata:
name: willow-<agent-slug>-mcp
namespace: kagent
type: Opaque
stringData:
authorization: "Bearer <access_key>:<secret>"
---
apiVersion: kagent.dev/v1alpha2
kind: RemoteMCPServer
metadata:
name: willow-<agent-slug>
namespace: kagent
spec:
description: Willow MCP gateway
protocol: STREAMABLE_HTTP
url: https://<your-willow-gateway>/agent/<agent-slug>
headersFrom:
- name: Authorization
valueFrom:
type: Secret
name: willow-<agent-slug>-mcp
key: authorization

Then reference the RemoteMCPServer from your SandboxAgent so the agent gains Willow's tools:

# Add under spec.declarative.tools of your SandboxAgent:
- type: McpServer
mcpServer:
kind: RemoteMCPServer
apiGroup: kagent.dev
name: willow-<agent-slug>

Finally, set the revealed system message as spec.declarative.systemMessage on your SandboxAgent (your prompt plus enabled skills).

Optional: have Willow send the values to a webhook​

To apply the values through your own automation, configure a Sync webhook on the agent's kagent configuration card. Enter a Webhook URL and, optionally, a Signing secret. On every sync, Willow POSTs an agent.sync event to that URL with the kagent kind, namespace, and agent name, the MCP gateway URL, the rotated Authorization header, the system message, and the ready-to-apply manifest. The panel also shows the values and the last successful webhook delivery.

The URL must be a public https URL, and Willow does not follow redirects. Requests are signed with X-Willow-Signature when you set a secret; see Send results to a webhook for how to verify it. Your endpoint must return 2xx within 15 seconds. Otherwise, sync fails and the previous platform token remains valid.

Message flow​

  1. A message (for example a Slack mention) is delivered to Willow's in-cluster component.
  2. That component checks the sender against the agent's Access, then invokes your SandboxAgent over the A2A URL. Access needs a current version of the in-cluster component: update it before Access is turned on for your organization.
  3. The agent calls Willow's MCP gateway through the RemoteMCPServer, authenticating with the header Secret.
  4. The agent replies through the reply_to_slack_thread tool, which returns the answer to the original thread.

Troubleshooting​

The agent cannot call any Willow tools​

Check the RemoteMCPServer and its header Secret. Confirm both were applied in the same namespace as the SandboxAgent, that the Secret's authorization key holds the full Bearer <access_key>:<secret> value, and that the RemoteMCPServer is referenced under spec.declarative.tools.

Tool calls started failing after a deploy​

Deploying rotates the gateway secret. Re-apply the Secret with the newly revealed Authorization header — the old one no longer authenticates.

Sync says the agent name is not set​

Set the Agent name (the SandboxAgent CRD name) in the agent's platform configuration before deploying. See Step 2.

Replies never reach Slack​

The agent needs the reply_to_slack_thread tool, which comes from the Willow RemoteMCPServer. Apply the resources in Step 4 to make that tool available.

What to do next​