Hand-off contracts
Hand-off contracts power "Hand-offs carry the facts": typed fields per receiving agent, dates compared as dates, leave types through code lists, with worked claims-intake examples, edge cases and the full field reference.
A claims hand-off that drops the onset date, rewords the leave type into another one or changes the amount is caught at the hop where it happened.
What it is and what it powers
When agent A hands work to agent B, the message can drop a field, change one, or invent one, and every later check passes on the corrupted request. A hand-off contract says, for one receiving agent, which fields a hand-off to it must carry and of what type. It powers Hand-offs carry the facts (a session check): "Every hand-off carries the fields its contract requires, each a valid value the sender had, unchanged between agents."
Each field is decided on the hop A → B, at its path (claimant.dob, diagnoses[1]):
| Finding | Meaning | Verdict |
|---|---|---|
| dropped | a required field missing or empty | fail |
| invalid | not a value of its type (format, unit, currency, code) | fail |
| changed | A had values of the type, none the same fact | fail |
| changed between hops | the same field arrived at A with another value | fail |
| untraced | nothing A had can decide it | N/A for that field |
"What A had" is A's input, its sources and tool results (free text, and JSON read by key) and the fields it received in earlier hops.
When it's not set. A session whose hand-offs carried fields or a message to an agent with no contract, with nothing else about them checked, shows Not configured: "A hand-off was sent to <agent>, but no hand-off contract is set for it in this project. Add one in Evaluation policy › Data definitions › Hand-off contracts." With no hand-off sent, the check is N/A: "Declare handoff_contracts (and code_lists) in the evaluation config, and send hand-offs (handoff=, or an agent called as a tool)." Neither is ever a pass.

Use cases
Insurance: claims intake → adjudication
The intake agent reads the claim form and hands the case to the adjudication agent. The contract (Insert example in the app gives this one):
{
"to": "adjudication",
"description": "What the intake agent must pass to the adjudication agent.",
"fields": [
{ "name": "claim_id", "type": "identifier", "required": true, "pattern": "^CLM-[0-9]{6}$", "description": "The claim number, for example CLM-004211." },
{ "name": "onset_date", "type": "date", "required": true, "date_order": "MDY", "description": "When the loss happened. 04/03/2026 reads as April 3." },
{ "name": "claimed_amount", "type": "money", "required": true, "currency": "USD", "tolerance": { "absolute": "0.01" }, "description": "The amount claimed; a difference of one cent or less counts as the same." },
{ "name": "coinsurance", "type": "percent", "scale": "percent", "description": "The member's share, written as 20 for 20%." },
{ "name": "adjuster_notes", "type": "text", "description": "Free text; checked only for being passed on." }
]
}
Add the leave type, checked through the code list:
{ "name": "leave_type", "type": "code", "code_list": "leave_type", "required": true }
From the intake step, send what it handed over:
client.log(
prompt=claim_form_text, response=intake_summary,
session_id=claim_session, agent_name="intake",
handoff={"to": "adjudication",
"fields": {"claim_id": "CLM-004211", "onset_date": "2026-04-03",
"leave_type": "STD", "claimed_amount": {"amount": "1840.00", "currency": "USD"}},
"message": "Claim CLM-004211: STD from April 3, 2026, $1,840.00 claimed."},
)
| The intake agent sent | It had | Result |
|---|---|---|
no onset_date | "Date of onset: 04/03/2026" | dropped: "intake sent adjudication no onset_date (required)." |
onset_date: "2026-03-04" | "04/03/2026" with date_order: MDY (April 3) | changed: dates compared as dates, 4 March is not 3 April |
onset_date: "April 3, 2026" | "04/03/2026", MDY | pass: the same date written another way |
leave_type: "short-term disability" | "STD" | pass: one code after the list |
leave_type: "LTD" | "short-term disability" | changed |
claimed_amount: 1840 | "$1,840.00" | pass (tolerance one cent) |
claimed_amount: {"amount": 1840, "currency": "CAD"} | — | invalid: "which is not an amount in USD" |
Taken from the wrong policy version
A contract proves the value came from what the sender had. If the intake agent read last year's policy and passed its 7-day waiting period faithfully, the hand-off passes: the agent had that value. Catch the wrong version on the intake step itself: send its sources with metadata and its question_scope, and Right version of the source fails that step (Document scope). Use both checks together.
Nested records and lists
{"to": "payment", "fields": [
{"name": "claimant", "type": "object", "required": true, "fields": [
{"name": "member_id", "type": "identifier", "pattern": "M-[0-9]{5}"},
{"name": "dob", "type": "date"}]},
{"name": "diagnoses", "type": "code", "code_list": "icd10", "list": true},
{"name": "weekly_benefit", "type": "money", "default_currency": "USD"},
{"name": "waiting_period", "type": "duration"}]}
list: true takes several values; their order does not matter.
Other domains
- Finance: an invoice-extraction agent → an approval agent:
invoice_number(identifier with a pattern),total(money,currency: EUR),vat_rate(percent,scale: percent),due_date(date). - Logistics:
weight(quantity,units: ["kg", "lb"]): 20 kg and 44.09 lb are the same fact withintolerance: {"relative": "0.001"}. - Customer support: a triage agent → a refund agent with
order_id,refund_amountandreason(code list), plus requirements the message must address.
Edge cases
| Situation | What happens |
|---|---|
| Field missing vs empty | Both are dropped when required: true; when not required, the field is skipped. An empty value inside a list is invalid. |
| Field present but changed | changed, with both values: "intake had onset_date as 2026-04-03; sent adjudication 2026-03-04." |
| Dates in different formats | Read as dates: 2026-04-03, April 3, 2026 and 04/03/2026 (with date_order: MDY) are one date. |
| An all-numeric date with no date order | 04/03/2026 could be two days, so it is untraced, never guessed: "declare the field's date_order (DMY or MDY) to check it". 13/03/2026 is decided, since 13 cannot be a month. The policy's date_order applies to every date field that has none. |
| A relative date ("next Thursday") | untraced: it needs the day it was written. |
| Rounding | Numbers, money, quantities, percentages and durations compare within tolerance (absolute and/or relative); without it, exactly. |
| Percent written two ways | scale: percent reads 20 as 20%; scale: fraction reads 0.2 as 20%. Without a scale, a bare number matches on either reading. "20%" is always 20%. |
| Amounts in different currencies | Never the same fact: no currency conversion. With currency, an amount in another currency is invalid. default_currency says what $ or ¥ means. |
| A value the sender never had | changed when the sender had other values of that type; untraced when it had none. |
| The sender had several values of the type and nothing ties one to the field | Shown as "only mentioned among other values of their type", never counted as verified. Send the sender's state keyed by field name. |
Key names differ in tool results (DOB vs dob) | Add aliases: ["DOB", "date_of_birth"] to the field. |
How to add it
In the app
- Create the code lists the contract's
codefields use (Code lists). - Open Evaluation policy › Advanced settings ▸ › Data definitions › Hand-off contracts and click Add contract.
- Click Insert example, replace
adjudicationwith your receiving agent'sagent_nameand the fields with yours. The JSON, key by key explains every key. - Click Add. The contract appears as a card with each field, its type, Required and its Rule (for example "must arrive unchanged; dates compared as dates (MDY)").
- Publish: Publish vN… › Publish. To edit or remove a contract, change it in the YAML.
In YAML
evaluation_config:
code_lists:
leave_type: {STD: ["short-term disability"], LTD: ["long-term disability"]}
handoff_contracts:
- to: adjudication
fields:
- {name: claim_id, type: identifier, required: true, pattern: "^CLM-[0-9]{6}$"}
- {name: onset_date, type: date, required: true, date_order: MDY}
- {name: leave_type, type: code, code_list: leave_type, required: true}
From the SDK
client.set_code_lists(pid, "settings/code_lists.json") # lists first
client.set_handoff_contracts(pid, "settings/handoff_contracts.json", note="add leave_type")
The call replaces all contracts; [] removes them.
Paste this into your coding agent
Paste this into Claude Code, Cursor, or whichever agent has your repository open. It writes the contracts from the hand-off payloads in your agent code.
Write variA/Bly hand-off contracts for this project from the agent code in this repository.
A contract says, for one receiving agent, which typed fields a hand-off to it must carry, so a
field dropped, changed or invented between agents is caught.
Look first:
1. Find every place one agent passes work to another: the payload, message, state update or
tool arguments it sends, and the agent that receives it. For each, list the sender, the
receiver (as the agent_name the app sends to variA/Bly), every field and its type, with
file paths and line numbers. Show me the list before you write anything.
Then write one contract per receiving agent under evaluation_config.handoff_contracts:
evaluation_config:
handoff_contracts:
- to: adjudication
fields:
- {name: claim_id, type: identifier, required: true, pattern: "^CLM-[0-9]{6}$"}
- {name: onset_date, type: date, required: true}
- {name: leave_type, type: code, code_list: leave_type, required: true}
- {name: claimed_amount, type: money, required: true, currency: USD}
- Field types: date, time, datetime, date_range, number, money, quantity, percent, duration,
boolean, identifier, code, string, text or object. Take each type from the code's own type
(a Pydantic model, dataclass, TypedDict or schema), not from a guess.
- required: true only for fields the receiver cannot work without.
- A code field names a code list that must exist in the policy (code_lists); write it too if
the vocabulary is in the code.
- The format is described at https://www.variably.dev/docs/data-handoff-contracts.
How to write it, as policy YAML:
1. The variably command comes with the SDK (pip install variably-sdk). It reads
VARIABLY_API_KEY and VARIABLY_BASE_URL from the environment; never hard-code the key or write it into a file.
2. If variably-policy.yaml is not in the repository yet, run `variably policy pull`: it writes
the version in force to variably-policy.yaml. Change only evaluation_config.handoff_contracts in that
file and leave every other key exactly as it is.
3. Verify: run `variably policy validate variably-policy.yaml`. It checks the file as the server would
and saves nothing; each problem is printed as "line N: path: message". Fix every problem and
run it again until it exits 0. Do not guess a key the error does not name: unknown keys are
refused.
4. Run `variably policy diff variably-policy.yaml` and show me what would change.
5. Do not push or publish. Tell me the two ways to save it as a draft: paste the file into
Evaluation policy › YAML and click Apply as draft, or run
`variably policy push variably-policy.yaml --note "<why>"` with a key allowed to change the
evaluation policy. A draft scores nothing until it is published.
6. Check that the app sends each hand-off to variA/Bly: the sending step's observe() or
client.log() call passes handoff={"to": "<receiving agent_name>", "fields": {...},
"message": "..."}. If it does not, add it there, with the same field names as the
contract. With the LangGraph or Google ADK integration, hand-offs are sent for you.
When you are done, tell me each contract, which code each field came from, and any hand-off you
found that you did not cover.Common mistakes
| Mistake | What happens | Fix |
|---|---|---|
The contract's to doesn't match the receiving step's agent_name | The contract is never used; the hand-off may show Not configured | Use the exact agent name your app sends |
Sending handoff= without the sender's own evidence (tool results or documents) | Fields are untraced: there is nothing to compare the sent value with | Send the sender's references or tool results on the same step |
A code field naming a list that doesn't exist | Refused when you save | Add the code list first |
| Dates like 04/03/2026 without a date order | The field is untraced, never guessed | Set the field's date_order, or the policy's |
Format reference
handoff_contracts is a list of contracts, one per receiving agent.
| Contract field | Type | Required | Allowed values | Meaning |
|---|---|---|---|---|
to | text | yes | the receiving agent's agent_name; one contract per agent | Who receives |
fields | list of fields | yes, unless the contract has only requirements | up to 100 per record, 500 in all | What the hand-off must carry |
requirements | list | no | as in requirement templates, content only | What the message must address in plain words |
requirements_ref | text | no | name or name@vN of a template; not with requirements | The same, from a template |
description | text | no | any | Your note |
| Field key | Type | Applies to | Allowed values | Default | Meaning |
|---|---|---|---|---|---|
name | text | all | non-empty, unique in its record | none | The key in handoff.fields |
type | text | all | date, time, datetime, date_range, number, money, quantity, percent, duration, boolean, identifier, code, string, text, object | none | How the value is read and compared |
required | true / false | all | false | Missing or empty is dropped | |
list | true / false | all | false | Several values, order aside | |
aliases | list of text | all | up to 10 | none | Other key names in tool results |
description | text | all | none | Your note | |
date_order | text | date | DMY, MDY | the policy's date_order | How 04/03/2026 is read |
timezone | text | datetime | an IANA zone (America/New_York) | none | The zone of a time written without one |
tolerance | object | number, money, quantity, percent, duration | {"absolute": n} and/or {"relative": r}, n ≥ 0, 0 ≤ r ≤ 1 | exact | How far two values may differ and be the same |
currency | text | money | ISO 4217 (USD, EUR, INR) | none | Every amount is in this currency |
default_currency | text | money | ISO 4217; not with currency | none | What $ or ¥ means |
units | list of text | quantity | 1–50 unit names, up to 32 characters | none | The units allowed |
scale | text | percent | percent, fraction | either reading | How a bare number reads |
pattern | text | identifier | a regular expression, up to 500 characters | none | The value must match it entirely |
code_list | text | code (required) | a list in code_lists | none | The list values come from |
fields | list | object (required) | 1–100 fields; records nest at most 3 deep | none | The record's fields |
Patterns: write \. for a dot. \Q…\E, the (?U) flag and \x{…} are refused, because they would read differently when an answer is checked.
Minimal:
handoff_contracts:
- to: adjudication
fields:
- {name: onset_date, type: date, required: true}
The full example is the claims intake contract under Use cases, above.
Validation messages
| Problem | Message |
|---|---|
| No receiving agent | Hand-off contract 1: 'to' (the receiving agent) is required. |
| Two for one agent | Two hand-off contracts for "adjudication". |
| Bad type | Hand-off contract "adjudication", field "onset": type must be one of date, time, …, object. |
| Option of another type | Hand-off contract "adjudication", field "onset_date": "currency" is not an option of date. |
| Code field without its list | … field "leave_type": a code field names its code_list. / … code list "leave_type" is not declared in code_lists. |
| Currency | … currency must be an ISO 4217 code (USD, EUR, INR…). / … give currency (every amount) or default_currency (for $, ¥), not both. |
| Scale | … scale is "percent" (12.5 means 12.5%) or "fraction" (0.125 means 12.5%). |
| Date order | … date_order is "DMY" (04/03/2026 is 4 March) or "MDY" (04/03/2026 is April 3). |
| Tolerance | tolerance is {"absolute": n} and/or {"relative": r}, each a number ≥ 0 (relative ≤ 1). |
| Pattern | … pattern does not compile (RE2 syntax): … / … pattern uses the (?U) flag: write lazy repeats (+?, *?) instead |
| Template | Hand-off contract "refunds" uses requirement template "refund-intake", which this experiment does not have |
Concepts on this page: Data definitions