All docs
Evaluation policyData definitionsHand-off contractsdashboard

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.

What you'll have

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]):

FindingMeaningVerdict
droppeda required field missing or emptyfail
invalidnot a value of its type (format, unit, currency, code)fail
changedA had values of the type, none the same factfail
changed between hopsthe same field arrived at A with another valuefail
untracednothing A had can decide itN/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.

Data definitions: Hand-off contractsData definitions: Hand-off contracts

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 sentIt hadResult
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", MDYpass: 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 within tolerance: {"relative": "0.001"}.
  • Customer support: a triage agent → a refund agent with order_id, refund_amount and reason (code list), plus requirements the message must address.

Edge cases

SituationWhat happens
Field missing vs emptyBoth are dropped when required: true; when not required, the field is skipped. An empty value inside a list is invalid.
Field present but changedchanged, with both values: "intake had onset_date as 2026-04-03; sent adjudication 2026-03-04."
Dates in different formatsRead 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 order04/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.
RoundingNumbers, money, quantities, percentages and durations compare within tolerance (absolute and/or relative); without it, exactly.
Percent written two waysscale: 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 currenciesNever 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 hadchanged 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 fieldShown 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

  1. Create the code lists the contract's code fields use (Code lists).
  2. Open Evaluation policy › Advanced settings ▸ › Data definitions › Hand-off contracts and click Add contract.
  3. Click Insert example, replace adjudication with your receiving agent's agent_name and the fields with yours. The JSON, key by key explains every key.
  4. 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)").
  5. 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.

Prompt for your coding agent
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

MistakeWhat happensFix
The contract's to doesn't match the receiving step's agent_nameThe contract is never used; the hand-off may show Not configuredUse 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 withSend the sender's references or tool results on the same step
A code field naming a list that doesn't existRefused when you saveAdd the code list first
Dates like 04/03/2026 without a date orderThe field is untraced, never guessedSet the field's date_order, or the policy's

Format reference

handoff_contracts is a list of contracts, one per receiving agent.

Contract fieldTypeRequiredAllowed valuesMeaning
totextyesthe receiving agent's agent_name; one contract per agentWho receives
fieldslist of fieldsyes, unless the contract has only requirementsup to 100 per record, 500 in allWhat the hand-off must carry
requirementslistnoas in requirement templates, content onlyWhat the message must address in plain words
requirements_reftextnoname or name@vN of a template; not with requirementsThe same, from a template
descriptiontextnoanyYour note
Field keyTypeApplies toAllowed valuesDefaultMeaning
nametextallnon-empty, unique in its recordnoneThe key in handoff.fields
typetextalldate, time, datetime, date_range, number, money, quantity, percent, duration, boolean, identifier, code, string, text, objectnoneHow the value is read and compared
requiredtrue / falseallfalseMissing or empty is dropped
listtrue / falseallfalseSeveral values, order aside
aliaseslist of textallup to 10noneOther key names in tool results
descriptiontextallnoneYour note
date_ordertextdateDMY, MDYthe policy's date_orderHow 04/03/2026 is read
timezonetextdatetimean IANA zone (America/New_York)noneThe zone of a time written without one
toleranceobjectnumber, money, quantity, percent, duration{"absolute": n} and/or {"relative": r}, n ≥ 0, 0 ≤ r ≤ 1exactHow far two values may differ and be the same
currencytextmoneyISO 4217 (USD, EUR, INR)noneEvery amount is in this currency
default_currencytextmoneyISO 4217; not with currencynoneWhat $ or ¥ means
unitslist of textquantity1–50 unit names, up to 32 charactersnoneThe units allowed
scaletextpercentpercent, fractioneither readingHow a bare number reads
patterntextidentifiera regular expression, up to 500 charactersnoneThe value must match it entirely
code_listtextcode (required)a list in code_listsnoneThe list values come from
fieldslistobject (required)1–100 fields; records nest at most 3 deepnoneThe 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

ProblemMessage
No receiving agentHand-off contract 1: 'to' (the receiving agent) is required.
Two for one agentTwo hand-off contracts for "adjudication".
Bad typeHand-off contract "adjudication", field "onset": type must be one of date, time, …, object.
Option of another typeHand-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).
Tolerancetolerance 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
TemplateHand-off contract "refunds" uses requirement template "refund-intake", which this experiment does not have

Concepts on this page: Data definitions