Source: docs/integration/migrate-agent-contract-4-to-5.md

Migrating from Agent API 4.x to 5.0

> Release 5.0.1: the breaking cutover is complete. The 4.x action and

> resolution routes are no longer available.

What changes

Version 5.0 replaces Forgium-managed mutation approvals with host-managed

interactions. Forgium still resolves intent and calls a configured read-only

preparation capability, but the host application owns selection, confirmation,

authorization, idempotency, concurrency, and the mutation itself.

The new preparation capability declares:

{
  "result_handling": "host_interaction",
  "side_effect": "read",
  "requires_approval": false,
  "retry_count": 0,
  "cache_ttl_seconds": 0
}

Its endpoint returns exactly one of confirmation_required,

selection_required, or not_found. The Agent API returns a closed

interaction union with owner: "host" and either `type:

"confirm_operation" or type: "select_option"`.

The exact preparation response bodies, bounds, canonical output_schema, and

contract-test behavior are documented in the [host-managed interaction

reference](capability-handoff.md#host-managed-interactions). In particular,

not_found is exactly { "status": "not_found" }; ambiguity must return

selection_required with two to eight host-bounded options.

not_found means zero currently eligible operations, not necessarily zero

matching resources. It is also correct when matching resources exist but their

current state makes the requested operation ineligible. Forgium calls this

read-only endpoint as a just-in-time preflight after detecting the user's

intent; the host must check eligibility then and repeat the check before the

eventual mutation.

This is a host-side data-resolution rule, not a Forgium routing rule: the host

adapter must test the number of eligible matches before choosing the status.

Forgium checks that the selected branch is structurally valid, but it cannot

detect a false not_found produced for an ambiguous business query.

Contract 5 intentionally removes the 4.x mutation-test contract: capability

definitions no longer accept test/dry_run or idempotency_header, and

CapabilityTestRequest no longer accepts expect. Contract tests exercise a

real active endpoint at its current revision under deterministic test scope, accept any valid

preparation branch, and may allocate only a temporary preparation record;

they must never execute a business mutation.

Client migration

1. Keep sending ordinary messages to
   POST /v1/channels/http/messages.
2. Route by interaction.owner and interaction.type; do not inspect the
   assistant text or capability name.
3. Send selections and confirmations to the host backend, not to Forgium.
   Forgium does not return callback URLs and the client must not expose its
   Forgium API key to the host interaction UI.
4. Optionally report the terminal host outcome to
   POST /v1/conversations/{conversationId}/operation-results using the
   account API key and an Idempotency-Key. The report body is limited to:

```json

{

"interaction_id": "int_123",

"operation": "cancel_expense",

"status": "succeeded"

}

```

status is one of succeeded, resource_changed, rejected, or

failed. Do not send operation references, mutation arguments, result

bodies, or user-authored error messages.

Server migration sequence

1. Add and contract-test the read-only preparation capabilities while the
   existing 4.x contract is still active.
2. Implement host-owned selection and confirmation with subject binding,
   expiry, replay protection, idempotency, and atomic material-revision
   checks. A stale revision must return resource_changed without mutating.
3. Deploy the host backend and client routing before enabling the preparation
   capability for migrated accounts.
4. Expire any historical 4.x pending records and record the cutover evidence.
   Do not convert their stored arguments into host interactions.
5. Switch clients to the latest 5.0.x manifest and OpenAPI contract. Existing
   legacy tables may remain as retention data, but their public routes are
   removed and dormant tables do not imply that the old workflows remain
   supported.

Security boundaries

Opaque operation, selection, and option references may appear in the host's

preparation response and in the public interaction envelope. They must not

appear in Workers AI prompts, logs, traces, audit records, conversation

metadata, or Forgium's interaction metadata. Render preview values as text.

The host remains authoritative for authorization and concurrency; a successful

preparation never authorizes a mutation by itself.