# Custom agent harness setup

Connect your own agent backend to Watchline with hosted watch tools, source filtering, and matched-event delivery.

Published: 2026-05-26
Updated: 2026-05-26
Canonical: https://watch.qordinate.ai/docs/custom-agent
Markdown: https://watch.qordinate.ai/docs/custom-agent.md


Image: https://watch.qordinate.ai/images/docs/watchline-custom-agent.png

Tags:
- custom agents
- API
- webhooks
- MCP

Use this path when your agent runs in your own product, worker, queue, or orchestration layer. Watchline sits before the expensive agent turn: your product creates a future condition, Watchline filters source-app events, and your backend receives only matched events.

## Integration shape

A custom harness usually needs four pieces:

1. A Watchline project and API key.
2. A delivery channel for matched events.
3. A way for the agent or product UI to create and manage watches.
4. A handler that routes matched events into your agent workflow.

For hosted agent backends, use webhook delivery. For private or local harnesses, use pull delivery so the harness makes outbound requests instead of exposing a public URL.

## Create a delivery channel

Open the Watchline dashboard and create a channel for the agent runtime that should receive matched events.

Use a webhook channel when your backend has a public HTTPS endpoint. Store the webhook secret and verify incoming deliveries before enqueueing work.

Use a pull channel when the harness runs somewhere private. The harness should poll for pending matched events, hand them to the agent, and acknowledge only after the handoff succeeds.

## Let the agent create watches

The easiest control-plane integration is the hosted Watchline MCP server:

```text
https://api.watch.qordinate.ai/v1/mcp
```

Expose the Watchline tools to your agent when it needs to remember a future condition. The core tools are:

- `start_watch`
- `continue_watch`
- `list_watches`
- `pause_watch`
- `resume_watch`
- `delete_watch`

`start_watch` begins setup from a user request such as "tell me when a customer mentions downtime." If Watchline needs a missing detail or an app authorization, it returns the next setup step. Your product should show that step to the user and call `continue_watch` after the user answers or completes the connection.

## Deliver matched events to your backend

Your delivery handler should treat a matched event as a scoped reason to start work, not as a raw source webhook. The useful payload is the match: the source event, the watch condition, the reason it matched, and the routing identity for the receiving agent.

In a hosted backend, the handler usually looks like this:

```ts
export async function handleWatchlineDelivery(request: Request) {
  const payload = await verifyWatchlineWebhook(request);

  await agentQueue.enqueue({
    kind: "watchline.match",
    watchId: payload.watch.id,
    deliveryId: payload.delivery.id,
    condition: payload.watch.intent,
    event: payload.event,
    reason: payload.match.reason,
  });

  return new Response("ok");
}
```

For pull delivery, keep the same internal envelope. The only difference is transport: your harness asks Watchline for pending deliveries, accepts the work it can handle, and acknowledges after the agent run is safely queued or started.

## Recommended runtime behavior

Keep the agent's authority scoped to the matched event. A delivery from a billing email should not carry the same permission envelope as a direct user command.

Log the source event, watch id, match reason, delivery id, and agent run id together. That makes false wakeups, missed wakeups, and retries easier to debug.

Separate setup from delivery. MCP and API tools are best for creating and managing watches; webhook or pull delivery is better for waking the runtime with matched work.

## When to use the runtime-specific guides

Use this custom harness guide for your own backend, hosted worker, or product-specific agent runtime.

Use the OpenClaw or Hermes guides only when you specifically want Watchline to deliver matched events into those local runtimes.