One hire, step by step
The examples of SaaCIP 0.1, in the order they happen. Each step says who does what, then shows the real documents and messages produced at that moment. Every file is checked against its schema with the published validator, and the receipts are really signed with an example key that is published for that purpose and must never be used for a real hire. All names are made up.
The story: a hirer takes a capability called example-log-watch, from Example Provider, on a 14-day trial to watch the logs of its api service in prod-eu. It finds one problem, reports it, asks to restart the service, a person approves, the restart works, the person judges the finding real, and the trial ends with a statement.
One hire over the HTTP binding
The seven calls of the Resident binding in the order they happen, with the schema name on each arrow and the receipts the capability writes on the left. Steps are numbered 0 to 8, as in the walkthrough. Open full size
0Before the hire
The provider, then the hirer. Nothing runs yet.
The provider publishes a capability manifest: what the capability does, what it may read, every action it could ever propose, and what data stays and leaves. A person at the hirer reads it, then writes and approves the declared actions file: the only commands the capability will ever be allowed to run. Finally the hirer creates the hire at its hub (a 14-day trial, who approves, who judges) and is shown a one-time enrolment token, enrol_..., which it passes to the capability it is about to start.
capability-manifest.example.yamlthe capability's CV, as the provider writes it
Written in YAML with comments, converted to JSON before it is published. Note autonomy.max: 3 and the two declared actions: this is what the hirer can see before deciding.
# A capability manifest, as its provider writes it (YAML).
# It is converted to JSON before it is published or sent.
protocol: saacip/0.1
id: example-log-watch
name: Example Log Watch
version: 1.0.0
provider: Example Provider
description: >
Watches logs inside the hirer's environment, reports what is unusual to the
hirer's help desk and acts only through actions a person declared in advance.
profiles: [resident]
hire_kinds: [task, trial, standing]
autonomy:
default: 1 # report only
max: 3 # act within declared limits, only if the hirer allows it
work_items:
kind: incident
declared_actions: # a summary of the declared actions file
- id: restart-api
title: Rolling restart of the api service
reversible: true
auto_allowed: true
- id: clear-tmp
title: Clear temporary files on the worker volume
reversible: false
auto_allowed: false
data:
stays: "in the hirer's environment: logs, baselines, receipts, signing key"
leaves_by_default: "nothing; redacted work item summaries to the hirer's help desk when one is set"
connectors: [file, cloud-logs, mcp]
ext:
com.example.support: # an extension: ignored by anyone who does not understand it
hours: business
timezone: Europe/Dublindeclared-actions.example.yamlthe complete list of things it may do
Two actions. restart-api is reversible and may run alone at most twice a day; clear-tmp deletes files, so it always waits for a person. The {service} placeholder can only be filled from services.
# The only things the capability can ever do. A person writes and approves this file
# before the hire. Commands are argument lists (no shell). {service} is only ever
# filled with a name from "services".
actions:
- id: restart-api
title: Rolling restart of the api service
match: ["connection pool exhausted", "OutOfMemory"]
services: [api]
command: [kubectl, rollout, restart, "deployment/{service}", -n, prod]
reversible: true # a rolling restart can be repeated or rolled back safely
auto_allowed: true # may run by itself at autonomy level 3 ...
max_per_day: 2 # ... at most twice in one UTC day
- id: clear-tmp
title: Clear temporary files on the worker volume
match: ["No space left on device"]
services: [worker]
command: [kubectl, exec, "deployment/{service}", -n, prod, --, find, /tmp/work, -mtime, "+1", -delete]
reversible: false # deleted files do not come back: always waits for approval
auto_allowed: false1Enrol
The capability, once. The hub checks and answers.
The capability starts inside the hirer's environment, discovers its one source (a log file) and builds its terms: the kind of hire, the autonomy ceiling, what it reads, what leaves, and the public key that will sign its receipts. It sends the terms with the enrolment token. The hub checks the protocol version, the profile and that the terms match the hire the hirer created (a 14-day trial), then answers with a credential, agent_..., and the hirer's current settings. The capability writes its first two receipts.
The terms of a hire, annotated
terms.example.json, shortened. Six groups of members, each tied to the section that defines it. The capability builds this document, sends it at enrolment and keeps it in its first receipt. Open full size
terms.example.jsonthe contract for this hire, built by the capability
Compare it with the picture above. autonomy_ceiling: 2 means a person must approve every action; the hub can lower that, never raise it. This hirer chose dry_run: false, so approved actions really run; the core recommends starting a new hire with true.
{
"protocol": "saacip/0.1",
"profile": "resident",
"kind": "trial",
"term": {
"days": 14
},
"autonomy_ceiling": 2,
"dry_run": false,
"connectors": [
{
"protocol": "saacip/0.1",
"id": "api-logs",
"kind": "file",
"version": "1.0.0",
"signals": [
"logs"
],
"scopes": [
"read"
],
"data_location": "a log file on a volume mounted into the capability; read in place",
"auth": "file system permission (read-only mount)"
}
],
"data_leaving": "work item summaries (redacted) to the hirer's help desk; nothing else",
"model": "offline",
"public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
"environment": "prod-eu"
}connector-manifest.example.jsonthe one source it will read, as carried inside the terms
{
"protocol": "saacip/0.1",
"id": "api-logs",
"kind": "file",
"version": "1.0.0",
"signals": [
"logs"
],
"scopes": [
"read"
],
"data_location": "a log file on a volume mounted into the capability; read in place",
"auth": "file system permission (read-only mount)"
}enrol-request.example.jsonPOST enrol/: the token, the versions it speaks, and the terms
{
"enrolment_token": "enrol_8yQm...shown-once-by-the-hub",
"protocol_versions": [
"saacip/0.1"
],
"profile": "resident",
"version": "1.0.0",
"terms": {
"protocol": "saacip/0.1",
"profile": "resident",
"kind": "trial",
"term": {
"days": 14
},
"autonomy_ceiling": 2,
"dry_run": false,
"connectors": [
{
"protocol": "saacip/0.1",
"id": "api-logs",
"kind": "file",
"version": "1.0.0",
"signals": [
"logs"
],
"scopes": [
"read"
],
"data_location": "a log file on a volume mounted into the capability; read in place",
"auth": "file system permission (read-only mount)"
}
],
"data_leaving": "work item summaries (redacted) to the hirer's help desk; nothing else",
"model": "offline",
"public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
"environment": "prod-eu"
}
}enrol-response.example.json201: the credential and the settings
agent_token is shown once. settings.autonomy_level: 2 with a ceiling of 2 gives an effective level of 2.
{
"protocol": "saacip/0.1",
"profile": "resident",
"agent_id": "5b1b273c-847f-4ecc-8dc7-0c2f5246cecd",
"agent_token": "agent_Qe4c7v1Zr0VJ2bq9tN6yXw3kHf8sLp5uYa1dC0mGiE",
"settings": {
"autonomy_level": 2,
"hire_kind": "trial",
"trial_days": 14,
"poll_seconds": 60
}
}receipt: hire_startedthe first line of the chain, carrying the full terms
{
"body": {
"expires": 1794474000,
"hire_id": "hire-74804b49c3",
"terms": {
"autonomy_ceiling": 2,
"connectors": [
{
"auth": "file system permission (read-only mount)",
"data_location": "a log file on a volume mounted into the capability; read in place",
"id": "api-logs",
"kind": "file",
"protocol": "saacip/0.1",
"scopes": [
"read"
],
"signals": [
"logs"
],
"version": "1.0.0"
}
],
"data_leaving": "work item summaries (redacted) to the hirer's help desk; nothing else",
"dry_run": false,
"environment": "prod-eu",
"kind": "trial",
"model": "offline",
"profile": "resident",
"protocol": "saacip/0.1",
"public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
"term": {
"days": 14
}
}
},
"id": "rcpt-49f23486900f",
"kind": "hire_started",
"prev": "0000000000000000000000000000000000000000000000000000000000000000",
"public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
"purpose": {
"autonomy_level": 2,
"environment": "prod-eu",
"kind": "trial",
"why": "hire"
},
"signature": "hcG1oUeh+BS36E6yEMZsY51/ADBgpNgtqAYRAkCxFZXJ1+eE9aS0JW7EWds25m5PUNHWkxLHGmJ/5fwG8+7KCA==",
"ts": 1793264400
}receipt: enrolledthe hub accepted
{
"body": {
"agent_id": "5b1b273c-847f-4ecc-8dc7-0c2f5246cecd",
"hub": "https://acme.hub.example.com/saacip/",
"protocol": "saacip/0.1"
},
"id": "rcpt-505f36f31b33",
"kind": "enrolled",
"prev": "5e3d14813ffc33a2e7846524ca121236e44818934ce982a19838b23680fe54fd",
"public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
"purpose": {
"why": "hire"
},
"signature": "321CcQlVLwcJUi5Bzy08N1muqdkUERGJhtDw+ow6u4UZg2ceR69DZiuV7fNcMSVW0/YwMwFD+UEOKfjxKv6+Dw==",
"ts": 1793264401
}2Heartbeat
The capability, every few minutes.
A heartbeat tells the hub the capability is alive, how each connector is doing, the current counts, and the hash of its latest receipt line, so the hub holds a checkpoint of the chain. The reply carries the hirer's current settings, which is how a person lowering the autonomy level at the hub reaches the capability within minutes, and release_requested.
heartbeat.example.jsonPOST heartbeat/: health, counters, receipt_head
This particular heartbeat was sent after step 4: its counters show one item reported and one approval awaiting, and receipt_head is the hash of line 4 of the chain.
{
"status": "ok",
"connectors": [
{
"id": "api-logs",
"kind": "file",
"ok": true,
"detail": "read 1,204 lines in the last minute"
}
],
"counters": {
"findings": 1,
"reported": 1,
"judged": 0,
"real": 0,
"false_alarms": 0,
"share_real": null,
"actions": {
"awaiting": 1
}
},
"receipt_head": "6e2a78590e39407150dee55d3d66bfa7ebb97b8639ed561f3e8183830cdc9de7",
"hire": {
"id": "hire-74804b49c3",
"kind": "trial",
"status": "active",
"expires": 1794474000.0
}
}heartbeat-response.example.json200: the settings as they stand now
{
"settings": {
"autonomy_level": 2,
"hire_kind": "trial",
"trial_days": 14,
"poll_seconds": 60
},
"release_requested": false
}3Report
The capability, when it finds something. A person at the hub sees a ticket.
At 09:15 the connector reads 22 new lines like the record below: a database connection pool exhausted, a pattern never seen before in api. The capability gives the finding a ref, wi-5516e077e5, and reports it with PUT work-items/wi-5516e077e5/. The hub opens ticket TKT-2026-0042 and answers with that number. Because the ref is the capability's own, sending the same report again after a network failure would add nothing: the hub already knows the ref.
record.example.jsonone line read from the log, in the shape every connector uses
{
"ts": 1793265292.0,
"source": "api-logs",
"service": "api",
"kind": "log",
"level": "ERROR",
"body": "database connection pool exhausted after 30s (active=50, request_id=9f3c1a)",
"attributes": {
"pod": "api-7d9f6b5c4-x2k8q",
"version": "2.4.1"
}
}report.example.jsonPUT work-items/<ref>/: subject, description, priority
{
"subject": "[prod-eu] A new error pattern in api",
"description_html": "<p>A new error pattern in api, seen 22 times in one minute.</p><p><b>Likely cause:</b> started shortly after the deploy of 2.4.1.</p>",
"priority_level": 3
}report-response.example.json201: the hub's own reference for the item
{
"hub_ref": "TKT-2026-0042",
"status": "open",
"created": true
}receipt: work_item_reportedwhat was found, what was decided, and the hub's reference
The receipt records the evidence and the explanation, and that the decision was await_approval: the next step.
{
"body": {
"created": true,
"decision": "await_approval",
"evidence": [
{
"count": 22,
"kind": "new_error",
"level": "ERROR",
"template": "database connection pool exhausted after <NUM><UNIT> (active=<NUM>, request_id=<HEX>)"
}
],
"explanation": {
"by": "offline",
"confidence": "medium",
"headline": "A new error pattern in api",
"likely_cause": "started shortly after the deploy of 2.4.1"
},
"hub_ref": "TKT-2026-0042",
"service": "api"
},
"id": "rcpt-fbe0ab16ddff",
"kind": "work_item_reported",
"prev": "f8e90402e8173150a0daea7c5485046e1dc5018e7cbcaf26f666e2a9a5318f9a",
"public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
"purpose": {
"autonomy_level": 2,
"ref": "wi-5516e077e5",
"why": "monitoring"
},
"signature": "vUnFGjfoJuC3OdhQI4pBPNXgjwyUaVmzP5/W7aXFEvFwuQB1NJPC8yL7vi6B53U8A5ZuwkRl2QA5jamNQsCKAg==",
"ts": 1793265301
}4Ask for approval
The capability asks; a person at the hirer decides.
The declared actions file has restart-api, whose match includes "connection pool exhausted" and whose services include api. The effective level is 2, so the capability may not run it alone: it sends an approval request with its own action_id, act-3f9a1c2b7d. The hub answers with the approval in state pending; a hub that is a help desk might also note it on the ticket. At 09:41 the on-call engineer approves it at the hub.
approval-request.example.jsonPOST approvals/: which action, for which work item
{
"action_id": "act-3f9a1c2b7d",
"ref": "wi-5516e077e5",
"action": "restart-api",
"summary": "Rolling restart of the api service"
}receipt: approval_requestedthe ask, with the action's reversibility on record
{
"body": {
"action": "restart-api",
"action_id": "act-3f9a1c2b7d",
"reversible": true
},
"id": "rcpt-e07cb4d8bd85",
"kind": "approval_requested",
"prev": "e73cc733a7db6aac15dcf75a9727b9d29d71ace9545d9e03ce9cd83a86fd1552",
"public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
"purpose": {
"ref": "wi-5516e077e5",
"why": "remediation"
},
"signature": "xGe8jzLu0V4Jb389MDrRulg7Vj6W7wKgaVpWXGgYoKfs7jtbSVHblvKrxdEB3DAC4fn1kKOGevR63D4q/5LQCg==",
"ts": 1793265302
}approval.example.jsonthe hub's record of the approval, once decided
The 201 reply to the request has the same shape with status: pending and decided_by null. This is how it looks after the engineer approved.
{
"id": "7",
"action_id": "act-3f9a1c2b7d",
"ref": "wi-5516e077e5",
"action": "restart-api",
"summary": "Rolling restart of the api service",
"status": "approved",
"decided_by": "on-call engineer",
"decided_at": "2026-10-29T09:41:07Z"
}5Decisions come back
The capability collects its inbox; the hub hands over what people decided.
The capability never receives a call. It asks the hub, every poll_seconds, for its inbox: approvals that were decided, outcomes that people recorded, and whether the hirer has asked it to finish. Here the inbox carries the approved action and, because the engineer later resolved the ticket as real, an outcome for the work item; in the real timeline these arrived in two collections, 09:41 and 10:31, and are shown as one inbox for brevity. Each item stays in the inbox until the capability acknowledges it, and applying one twice has no further effect.
inbox.example.jsonGET inbox/: an approval decided, an outcome recorded, no release
{
"approvals": [
{
"id": "7",
"action_id": "act-3f9a1c2b7d",
"ref": "wi-5516e077e5",
"action": "restart-api",
"summary": "Rolling restart of the api service",
"status": "approved",
"decided_by": "on-call engineer",
"decided_at": "2026-10-29T09:41:07Z"
}
],
"outcomes": [
{
"ref": "wi-5516e077e5",
"outcome": "real",
"action_worked": true,
"note": "pool too small after the 2.4.1 deploy",
"hub_ref": "TKT-2026-0042",
"hub_status": "resolved"
}
],
"release_requested": false
}outcome.example.jsona person's judgement: real, and the action worked
A hub only sends an outcome a person made. A ticket closed with nothing said produces none.
{
"ref": "wi-5516e077e5",
"outcome": "real",
"action_worked": true,
"note": "pool too small after the 2.4.1 deploy",
"hub_ref": "TKT-2026-0042",
"hub_status": "resolved"
}6Act and learn
The capability runs the action, learns from the judgement, and acknowledges both.
Before running an approved action the capability re-checks its limits: the level is still 2 or more, restart-api is still in the file, and it has not already run twice today. All true, so it runs the command, without a shell, with {service} filled with api, and writes an action_taken receipt naming the approver. It then applies the outcome (how it learns from it is its own affair; this one records a weight before and after in the receipt body) and acknowledges both inbox items so they are not sent again.
A receipt, annotated
The action_taken line from receipt.example.jsonl, shortened. Each line in the file is one receipt in canonical JSON; the signature verifies with the public key, and prev ties it to the line before. Open full size
receipt: action_takenthe command that ran, its result, and who approved it
Compare it with the picture above. purpose.approved_by is the person; body.argv is the exact command.
{
"body": {
"action": "restart-api",
"action_id": "act-3f9a1c2b7d",
"argv": [
"kubectl",
"rollout",
"restart",
"deployment/api",
"-n",
"prod"
],
"dry_run": false,
"returncode": 0,
"stdout_sha256": "8c9d5ac0eb2ac4c9bbbb6b813ffb32e764b1d0db9a397ed32a0207970957c558"
},
"id": "rcpt-64c55d295ef2",
"kind": "action_taken",
"prev": "6e2a78590e39407150dee55d3d66bfa7ebb97b8639ed561f3e8183830cdc9de7",
"public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
"purpose": {
"approved_by": "on-call engineer",
"ref": "wi-5516e077e5",
"why": "remediation"
},
"signature": "7+KKv9iewBDoNDaELmsY0PGrnjXZrnIZs7TuVBIJEZaRMRItX8kT2Wj/vpfKahyLVDyJmo718SQpV3tqIHdVAw==",
"ts": 1793266870
}receipt: feedback_appliedthe judgement applied: the capability learned
{
"body": {
"action_worked": true,
"outcome": "real",
"weight_after": 1.1,
"weight_before": 1
},
"id": "rcpt-21bedbe059f9",
"kind": "feedback_applied",
"prev": "94645efba7528860ab8075d3ac284b8018760c7751719a1c3464cda0abc6c1c8",
"public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
"purpose": {
"ref": "wi-5516e077e5",
"why": "learning"
},
"signature": "kWddzB8wnvHZmioRXr9ITdCBqryzF+hXMvZbHnl1RTnyU/RdoBXjAmtfhDEIXKkYRFl1wwgsLj0wGOMAUNEFBA==",
"ts": 1793269860
}ack.example.jsonPOST inbox/ack/: the approval id and the outcome ref applied
{
"approvals": [
"7"
],
"outcomes": [
"wi-5516e077e5"
]
}ack-response.example.json200: how many of each the hub marked delivered
{
"approvals": 1,
"outcomes": 1
}7The statement
The capability, at the end. The hirer reads it.
On day 14 the trial ends. The capability builds its statement from its own receipts: one finding, one reported, one judged real, one action done. It sends it with final: true, the hub marks the hire ended, and the capability writes its last receipt and goes idle. The statement is what a review, a renewal or a bill is based on, and what a registry would turn into a track record. Every number in it can be recomputed from the receipts.
statement.example.jsonthe account of the hire, from its own records
{
"hire_id": "hire-74804b49c3",
"kind": "trial",
"reason": "trial term ended",
"track_record": {
"findings": 1,
"reported": 1,
"judged": 1,
"real": 1,
"false_alarms": 0,
"share_real": 1.0,
"actions": {
"done": 1,
"dry_run": 0,
"failed": 0,
"rejected": 0,
"refused": 0,
"awaiting": 0
}
}
}statement-request.example.jsonPOST statement/: the statement, final
{
"statement": {
"hire_id": "hire-74804b49c3",
"kind": "trial",
"reason": "trial term ended",
"track_record": {
"findings": 1,
"reported": 1,
"judged": 1,
"real": 1,
"false_alarms": 0,
"share_real": 1.0,
"actions": {
"done": 1,
"dry_run": 0,
"failed": 0,
"rejected": 0,
"refused": 0,
"awaiting": 0
}
}
},
"final": true
}statement-response.example.json200: the hire is ended
{
"status": "ended"
}receipt: hire_endedthe last line of the chain, carrying the final statement
{
"body": {
"hire_id": "hire-74804b49c3",
"statement": {
"hire_id": "hire-74804b49c3",
"kind": "trial",
"reason": "trial term ended",
"track_record": {
"actions": {
"awaiting": 0,
"done": 1,
"dry_run": 0,
"failed": 0,
"refused": 0,
"rejected": 0
},
"false_alarms": 0,
"findings": 1,
"judged": 1,
"real": 1,
"reported": 1,
"share_real": 1
}
}
},
"id": "rcpt-d381990ce7de",
"kind": "hire_ended",
"prev": "0744c1df41fc964748b04e1c5812471c19138694ed0751c7010141d71a00ffd7",
"public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
"purpose": {
"reason": "trial term ended",
"why": "hire"
},
"signature": "RGQNujw0bllR9M/sxhMPfO0Sy4PeMIrx9AeoKpSHOwXdcIUYvgFbaKAZ1hlLA210LGHDUzpz2+DvVkQabzJmBA==",
"ts": 1794474000
}8When things go wrong
The hub answers every error the same way.
Every error is RFC 9457 problem details: a type URI from the list of problem types, an HTTP status, a title and a detail. A capability acts on the type and the status, never on the wording. Two cases worth knowing: a refusal at enrolment (wrong version, terms that disagree with the hire, an extension the hub does not understand) never uses up the enrolment token; and a 401 is retried once before the capability concludes it has been revoked and ends the hire on its own side.
problem.example.json400: none of the offered versions is supported
{
"type": "https://thesoftwarelens.com/saacip/0.1/errors/#unsupported-version",
"title": "Unsupported version",
"status": 400,
"detail": "None of the offered protocol versions is supported.",
"supported": [
"saacip/0.1"
]
}Important notice. This page is part of my ongoing research into the Agentic Economy and reflects my thinking at the time of writing. It is shared in good faith, for information and discussion. It is not legal, regulatory, technical, financial or other professional advice, and it is not a verdict on how the EU AI Act or any other law applies to any organisation, system or situation. Laws, guidance, technology and my own research all move on, and others may reach different conclusions. The examples, designs, diagrams and technology choices show one possible approach. Before relying on, adapting or applying any part of it in your own situation, you must test and verify it, design it for your own architecture, and take independent expert advice, including from qualified lawyers and from your own IT, security and data protection specialists. Any decision to act on it, and its consequences, rest with you. To the fullest extent permitted by law, the author accepts no responsibility or liability for any loss, damage or consequence arising from any use of, or reliance on, this page, which is provided without any warranty of accuracy, completeness or fitness for a particular purpose. Reading it does not create a professional or advisory relationship with the author. The views expressed are the author’s own.