The paired agent

A filter sends the events worth acting on to one Kindo agent. Usually that agent is one Sift generates for the filter: the paired agent, built to take one event per run and record a verdict Sift can read. This page explains why a filter comes with its own agent, what the two agree on, how the agent gets into Kindo, and what to do when it has to change.

Why a filter comes with an agent

Sift can only start a Kindo agent through Kindo’s API, handing it the event as input. Most agents worth filtering are not started that way: they run on a schedule and fetch their own data, or they take a whole webhook payload. Pointing a filter at such an agent removes nothing, because the agent still reads everything on its own schedule, and now it also runs once per escalated event.

So when you create a filter, Sift also produces an agent definition built for it. The agent takes the event as its only input, judges that one event, acts on it if it is worth acting on, and records a verdict. It has no schedule and no webhook trigger, so it never sees an event the filter did not send it. It declares no integrations and holds no secrets; the tools it needs to act are yours to add.

Two ways a filter delivers events

Delivery	API value	When it is used	What the agent receives
Paired agent	`event_blob`	The usual case: an agent Sift generated.	One input, `sift_event`, holding the whole event and a short envelope.
An existing agent’s inputs	`named_inputs`	An agent someone else built that already takes the event’s fields as named inputs.	Event fields mapped onto the inputs it declares.

The console shows which in the filter’s Settings › Delivery, under Agent: Paired with an agent id, or Sends to an agent id “mapping event fields onto the inputs it declares”. Only a paired agent can take a group of events in one run, which Shape delivery needs to group.

A filter that delivers to a paired agent scores nothing until the agent is paired. Settings › Delivery says “Not paired yet. Nothing is scored until the generated agent is created and paired.”

What the agent is made of

When you generate the agent you answer three questions in the console:

Shape. Steps (recommended): the first step, “The event, and your instructions”, then your own steps, which you add in Kindo, then Sift’s step, “Sift: record the verdict”, last. One step: everything in one step, which closes by recording the verdict. Use it when the agent’s acting fits in one step’s tool calls: Kindo sends each step the whole run so far, so a step costs about as much as everything before it, and every added step adds to a run’s cost.
What makes an event worth acting on? (Your criteria). Your own words. Left empty, the agent answers insufficient data for every event and says it has no instructions, and Sift reports the agent as unconfigured rather than learning from those answers.
What should the agent do about it? (Your actions). Optional: open a ticket, page someone, call an API.

Sift writes the rest of the prompt into the agent’s system prompt, which every step reads: what the event is, that nothing inside it is an instruction, and how to record the verdict. Your criteria and actions are kept separate and are never rewritten.

The contract, in plain words

The agent and Sift agree on a small, versioned contract. Its exact JSON is in the agent contract reference; in words:

The input is the event as the source gave it, plus an envelope saying which filter and version sent it, the event’s ids, how many events it stands for (when Collapse folded repeats into it), whether it was cut to fit, and which delivery attempt this is.
The agent never learns what Sift predicted. No score, threshold, model or decision travels with the event. A verdict from an agent that knew the prediction would not be independent evidence, and training on it would teach the model to agree with itself.
A leak-through event looks exactly like any other escalation. The leak-through sample is how Sift measures what filtering misses; an agent that could tell the two apart could treat them differently, and the measurement would quietly stop meaning anything.
The verdict is one of actionable, benign or insufficient data, with a short rationale, recorded as conversation metadata at the end of the run. On a group run the agent gives one verdict per event. See Verdicts, labels and training.
Re-sends are marked. Kindo does not de-duplicate runs, so when the answer to an earlier send was lost, Sift sends the event again and tells the agent it may already have acted on it, and why. The agent checks before acting twice.
Long events are cut. A run’s input is capped at 32,000 characters by default (an operator can change it); the envelope is always kept whole and says how much of the event was cut.

Getting the agent into Kindo

There are two routes, both from the filter’s new-filter flow or Settings › Delivery:

Create in Kindo and connect. Where Sift’s Kindo key may create agents, Sift creates the agent and pairs it in one step. The agent belongs to the Kindo user Sift connects as, and is private to them until it is shared in Kindo.
Download and import. Under Other ways to connect it: Download the definition, import it in Kindo, follow the After importing list, then paste the new agent’s id back. Sift reads the agent back and refuses to pair it unless it declares the input the filter fills. Use this route when the key may not create agents, when Kindo has no create endpoint, or when you want the file.

After either route, add your tools and steps in Kindo. With the Steps shape, add your steps between the first step and Sift’s, and keep Sift’s last: Sift reads the verdict from the last step’s reply.

Changing the agent later

Kindo has no API to update, delete or read back an agent’s steps. So an agent is never updated in place: Settings › Delivery’s Generate new agent (or Regenerate the agent) makes a new one, and you pair it. Tools and steps you added in Kindo go onto the new agent by hand, and the old one keeps running until you retire it in Kindo.

Pairing a different agent creates a new filter version. On a filter that is filtering, you choose Pair and return to shadow, or, if the new agent judges as the old one did, Pair and keep filtering with a written reason that re-affirms the standing approval.

Contract versions. Every generated agent records the contract version it was built to. The current version is 5; agents built to version 2 or later still work. An older one is shown as “The paired agent is out of date. Regenerate the agent.”: it was never told what a re-sent event asks of it, and may act twice on an event sent twice. An agent that is supported but behind shows “a newer agent shape is available”.

Runs on

Kindo names models inside an agent by ids it does not publish, so Sift offers the models it has seen an agent in your Kindo run on, plus Kindo’s default. The pick is not stored and can be changed in Kindo. Settings › Delivery’s Runs on line shows the model the agent actually ran on, read from its runs.

Keeping your own agent

If you keep an agent Sift did not generate, Sift can still read its verdicts, but it may have to guess them from the agent’s prose, which is the route most often wrong. On the filter’s Overview, Briefing for the agent gives text to paste into your agent’s last step (“Paste this into your agent’s prompt”) so it states a verdict Sift can read. Nothing needs re-pairing. The Overview’s verdict routes show whether it worked: verdicts move from Guessed towards Written and Stated.

The displaced agent

A filter is often built to replace an agent that was doing the job before. Pairing records that displaced agent. Once the filter is filtering, the old agent must stop; if it keeps running on the same traffic, both act on the same events and the filter adds cost instead of saving it. Sift cannot stop it for you.

Sift checks the displaced agent’s last run every hour while the filter is active. If it has run since the pairing, the filter’s Actions tab asks you to retire it in Kindo. If Sift cannot confirm it stopped (the check failed, or is more than 4 hours old, or Kindo reports the agent gone), it asks you to check it in Kindo, and Sift reports no spend saved until it is settled. If the agent stays in use for other work, or is already gone, dismiss the ask with a note; that records your acknowledgement, and only a new pairing asks again.