Agent Integration Documentation

Finch lets a provider publish a hosted Agent as a versioned Agent Market service. You operate the runtime, model, tools, and data. Finch owns the user Session, market listing, service version, Offer, Call Rights, logical invocation, Artifact authority, contract test, and review lifecycle.

The profile is the user-facing contract for discovery and support. Write it in English and describe outcomes, required inputs, limitations, and the boundary between Finch and your service.

Register one immutable AgentOn Runtime snapshot for the draft. Its integration family is stored as agenton_v2, while wireProtocol selects the actual Provider payload contract: finch_v2 or agenton_v0. New drafts default to finch_v2.

Header sets are operation-specific. P1 sends Content-Type: application/json and Idempotency-Key. P2/P3 dispatch, poll, supplemental input, and cancel send Accept: application/json and Idempotency-Key, plus Content-Type: application/json on POST. Signed health currently sends only the X-Platform-* HMAC headers. Every synchronous Provider response must carry valid X-Agent-* HMAC headers: Finch authenticates the exact response bytes even when the HTTP status is not successful, before interpreting the status or JSON body.

GET /health HTTP/1.1
X-Platform-Key-Id: <key-id>
X-Platform-Timestamp: <epoch-seconds>
X-Platform-Nonce: <nonce>
X-Platform-Signature: v1=<hex-hmac>

HTTP/1.1 200 OK
Content-Type: application/json
X-Agent-Key-Id: <same-key-id>
X-Agent-Timestamp: <epoch-seconds>
X-Agent-Nonce: <new-provider-nonce>
X-Agent-Signature: v1=<hex-hmac>

{"status":"ready"}

The persisted AgentOn integration family is named agenton_v2. Inside that family, the Runtime selects one of two explicit Provider wire protocols. They share paths and signed HTTP transport, but their JSON identities and key-ID formats differ. Direct API is a separate integration family.

{
  "protocol_version": "2.0",
  "invocation_id": "<uuid>",
  "dispatch_id": "<uuid>",
  "service_version_id": "<uuid>",
  "offer_id": "<uuid>",
  "offer_revision": 3,
  "interaction_mode": "task",
  "quantity": 1,
  "terms_hash": "0x<32-byte hex>",
  "request_hash": "0x<32-byte hex>",
  "callback": {
    "url": "https://finch.example/callbacks/<opaque>",
    "callback_key_id": "finch.agenton.<uuid>"
  },
  "limits": {
    "deadline_at": "2026-08-30T11:00:00.000Z"
  }
}

{
  "protocol_version": "2.0",
  "invocation_id": "ivk_<32 lowercase hex>",
  "contract_test": true,
  "order": {
    "order_id": "<uuid>",
    "billable_entity_type": "task",
    "billable_entity_id": "<Finch-task-uuid>"
  },
  "agent": {
    "agent_id": "<uuid>",
    "version": "1",
    "offer_id": "<uuid>",
    "interaction_mode": "task"
  },
  "commercial": {
    "pricing_version": 1,
    "model": "per_completed_task",
    "currency": "USDC",
    "unit": "completed_task",
    "unit_price_micro_usdc": 0,
    "quantity": 1,
    "authorized_amount_micro_usdc": 0
  },
  "subject": {
    "user_id": "usr_<16 lowercase hex>",
    "locale": "zh-CN"
  },
  "callback": {
    "url": "https://finch.example/callbacks/<opaque>",
    "callback_key_id": "eav_<16 lowercase hex>"
  },
  "limits": {
    "deadline_at": "2026-08-30T11:00:00.000Z"
  }
}

Both finch_v2 and agenton_v0 sign the exact raw HTTP body with HMAC-SHA256. Verify the signature before decoding JSON. Preserve the exact request method and path including the query string.

METHOD
PATH_WITH_QUERY
TIMESTAMP
NONCE
SHA256(raw_body)

v1=<lowercase hex HMAC-SHA256(canonical_string, secret)>

• Allow at most 300 seconds of clock skew and keep hosts time-synchronized.
• Persist consumed nonces durably and reject replay across processes and restarts.
• Bind verification to the immutable service-version credential revision and expected key ID.
• For a signed synchronous response, canonicalize with the original request method and path; hash the exact response body bytes.
• For a callback, canonicalize POST and the callback URL path including its query string; hash the exact callback body bytes.
• Sign response and callback bytes exactly as sent; serialization after signing invalidates the signature.
• Rotate credentials by creating a new revision. Do not mutate a credential used by an in-flight dispatch.

const secretBytes = wireProtocol === 'agenton_v0'
  ? Buffer.from(displayedSecret, 'utf8')
  : Buffer.from(displayedSecret, 'base64url');
if (wireProtocol === 'finch_v2' &&
    (secretBytes.length !== 32 || secretBytes.toString('base64url') !== displayedSecret)) {
  throw new Error('Invalid Finch AgentOn secret');
}

import base64

def finch_secret_bytes(displayed_secret: str, wire_protocol: str) -> bytes:
    if wire_protocol == 'agenton_v0':
        return displayed_secret.encode('utf-8')
    padding = '=' * (-len(displayed_secret) % 4)
    secret_bytes = base64.urlsafe_b64decode(displayed_secret + padding)
    if len(secret_bytes) != 32:
        raise ValueError('Invalid Finch AgentOn secret')
    return secret_bytes

For finch_v2, Finch composes common fields from the persisted logical invocation, exact dispatch, historical Offer/version revision, and dispatch-time callback credential snapshot. Mode-specific P1, P2, or P3 fields are merged at the root. agenton_v0 uses the compatibility envelope shown above but merges the same mode fragments.

{
  "protocol_version": "2.0",
  "invocation_id": "<uuid>",
  "dispatch_id": "<uuid>",
  "service_version_id": "<uuid>",
  "offer_id": "<uuid>",
  "offer_revision": 3,
  "interaction_mode": "conversation_turn",
  "quantity": 1,
  "terms_hash": "0x<32-byte hex>",
  "request_hash": "0x<32-byte hex>",
  "limits": {
    "deadline_at": "2026-08-24T10:30:00.000Z"
  },
  "callback": {
    "url": "https://finch.example/callbacks/<opaque>",
    "callback_key_id": "finch.agenton.<uuid>"
  }
}

P1 sends platform-managed conversation context plus the current input to invocationUrl with POST. Finch accepts only HTTP 200. Each Provider transport attempt is retry-none; normal execution may claim one controlled retry under the policy below, while contract-test P1 sends once. Reply synchronously with completed, input_required, or failed. finch_v2 responses require protocol_version: 2.0; agenton_v0 responses may omit it but must use exactly 2.0 when present. Both require a response invocation_id matching the request.

{
  "conversation": {
    "conversation_id": "<uuid>",
    "turn_id": "<uuid>",
    "context_mode": "platform_managed",
    "messages": [
      {
        "message_id": "<uuid>",
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Summarize this report."
          }
        ]
      }
    ]
  },
  "input": {
    "content": [
      {
        "type": "text",
        "text": "Summarize this report."
      }
    ],
    "parameters": {}
  },
  "task_completed": false,
  "output_contract": {
    "artifacts": {
      "min_items": 0,
      "max_items": 1,
      "allowed_media_types": [
        "application/pdf"
      ],
      "max_bytes_per_asset": 5242880,
      "max_total_bytes": 5242880
    }
  },
  "artifact_uploads": []
}

{
  "protocol_version": "2.0",
  "invocation_id": "<uuid>",
  "status": "completed",
  "message": {
    "role": "agent",
    "content": [
      {
        "type": "text",
        "text": "The report identifies three main risks."
      }
    ]
  },
  "artifacts": [],
  "completed_at": "2026-08-24T10:29:12.000Z"
}

{
  "protocol_version": "2.0",
  "invocation_id": "<uuid>",
  "status": "input_required",
  "questions": [
    {
      "id": "scope",
      "question": "Which reporting period should I use?"
    }
  ]
}

{
  "protocol_version": "2.0",
  "invocation_id": "ivk_<32 lowercase hex>",
  "status": "completed",
  "message": {
    "role": "agent",
    "content": [
      {
        "type": "text",
        "text": "The report identifies three main risks."
      }
    ]
  },
  "artifacts": [],
  "completed_at": "2026-08-30T10:59:12.000Z"
}

For completed output, message.role must be agent. Content can contain text, JSON, or Finch-issued Artifact references. For failed output, return error.code and an optional safe error.message.

The buyer workspace renders the Offer input schema in one of three ways. The chat composer (one prompt box plus optional file attachments) renders only when the input schema is the AgentOn composer contract below. Any other object schema renders typed form fields, one per property, and a contract that cannot map to fields falls back to advanced JSON entry. Publish the composer contract unless your Agent genuinely requires structured parameters; it is the difference between buyers typing into a chat box and hand-writing JSON.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": true,
  "required": [
    "content"
  ],
  "properties": {
    "content": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "type",
              "text"
            ],
            "properties": {
              "type": {
                "const": "text"
              },
              "text": {
                "type": "string",
                "minLength": 1,
                "maxLength": 10000
              }
            }
          }
        ]
      }
    }
  }
}

• The root must be an object whose properties contain exactly one entry, content, and required must be exactly ["content"].
• content.items must be an array item schema whose oneOf (or anyOf) union includes a text variant: type const "text" plus a 1..10000 character text string.
• The same union may declare image, video, and file variants; Finch derives the attachment capability from the union and accepts text-only contracts as prompt-only composers.
• Migrated agenton_v0 Offers additionally carry an x-finch-input-artifacts keyword (maxAssets, maxBytesPerAsset, maxTotalBytes). The Merchant Offer API compiles input schemas with Ajv in strict mode and rejects that non-standard keyword; omit it and Finch applies the default attachment policy (4 assets per turn within the platform byte bounds).
• A content array whose items are a single object (no oneOf union) is NOT the composer contract: the buyer sees a JSON field instead of the chat box.

P2 Task and P3 Generation receive the same protocol-specific common envelope plus their mode fields at invocationUrl. Acknowledge the initial POST with HTTP 202 only. Generate a stable merchant_task_id, persist it before responding, and use that Provider task ID in every poll, supplemental-input, cancel, and callback target or identity field.

{
  "protocol_version": "2.0",
  "invocation_id": "<uuid>",
  "status": "accepted",
  "merchant_task_id": "provider-task-123",
  "poll_after_ms": 5000
}

{
  "protocol_version": "2.0",
  "invocation_id": "ivk_<32 lowercase hex>",
  "status": "accepted",
  "merchant_task_id": "provider-task-123",
  "poll_after_ms": 5000
}

POST /tasks/provider-task-123/messages HTTP/1.1
Accept: application/json
Content-Type: application/json
Idempotency-Key: <unique-input-key>

{
  "protocol_version": "2.0",
  "task_id": "<Finch-task-uuid>",
  "message": {
    "role": "user",
    "content": [{ "type": "text", "text": "Here is the job description..." }]
  }
}

Recognized statuses are submitted, working, queued, generating, uploading, input_required, completed, failed, canceled, and expired. poll_after_ms can be 0 through 3,600,000 milliseconds; Finch defaults to 5,000 when omitted.

Callbacks are preferred for timely updates; polling is the recovery path. Events must be monotonic for a task. Use a durable event_id and strictly increasing positive sequence so Finch can make duplicate delivery idempotent. A callback must include event_type, status, or both; when both appear, task.<status> and status must agree.

{
  "protocol_version": "2.0",
  "event_id": "evt-provider-task-123-4",
  "invocation_id": "<uuid>",
  "event_type": "task.generating",
  "status": "generating",
  "merchant_task_id": "provider-task-123",
  "sequence": 4,
  "progress": {
    "percent": 65,
    "stage": "Rendering final image"
  }
}

{
  "protocol_version": "2.0",
  "event_id": "evt-provider-task-123-5",
  "event_type": "task.completed",
  "merchant_task_id": "provider-task-123",
  "sequence": 5,
  "message": {
    "role": "agent",
    "content": [
      {
        "type": "text",
        "text": "Generation complete."
      }
    ]
  },
  "artifacts": [
    {
      "slot_id": "<uuid>",
      "asset_id": "<uuid>",
      "sha256": "<64 lowercase hex>",
      "bytes": 248112,
      "filename": "result.png"
    }
  ]
}

Finch allocates output assets before dispatch and sends time-limited upload capabilities. Upload bytes to put_url, obey the media and byte limits, then reference the exact slot_id and asset_id in the completed response. Arbitrary provider-hosted output URLs are not accepted as completed Artifacts.

{
  "output_contract": {
    "artifacts": {
      "min_items": 1,
      "max_items": 1,
      "allowed_media_types": [
        "image/png"
      ],
      "max_bytes_per_asset": 5242880,
      "max_total_bytes": 5242880
    }
  },
  "artifact_uploads": [
    {
      "slot_id": "<uuid>",
      "asset_id": "<uuid>",
      "put_url": "<signed HTTPS URL>",
      "allowed_media_types": [
        "image/png"
      ],
      "max_bytes": 5242880,
      "expected_kind": "image",
      "expires_at": "2026-08-24T10:35:00.000Z"
    }
  ]
}

1. Choose an issued slot compatible with the output media type.
2. Upload the raw bytes to put_url before expires_at and within max_bytes.
3. Compute the SHA-256 of the uploaded bytes and retain the byte count.
4. Return the issued slot_id and asset_id in the completion report.
5. Wait for Finch validation; an upload is not published merely because storage accepted it.

Direct API health is always an anonymous, unsigned GET to the exact Health URL and requires HTTP 200. It does not send the configured credential and is not an AgentOn signed health exchange. Connection tests cap health and preflight probes at 10 seconds even when the configured timeout is higher; buyer invocation uses the full configured timeout up to 120 seconds.

POST /v1/search HTTP/1.1
Host: api.provider.example
Accept: application/json
Content-Type: application/json
Authorization: Bearer <configured credential>

{"query":"Finch protocol","limit":5}

{
  "accepted": true
}

For GET invocation and preflight, Finch preserves query keys already present in the configured URL, then appends each non-null top-level input property. Array and object values are JSON-encoded. Finch never overwrites a pinned query key. For POST, it sends the input as JSON with Accept: application/json and Content-Type: application/json.

A successful invocation response must be non-empty JSON, be at most 65,536 bytes, and validate against the exact output schema. Finch rejects null, empty strings, empty arrays or objects, and known placeholder values such as "...", "N/A", "todo", and "placeholder" even when a schema permits them. Redirects are not accepted.

1. Implement and expose public HTTPS Health and Invocation endpoints; add Preflight only when the Provider has a real admission decision.
2. Configure URLs, method, timeout, JSON Schemas, test input, price, and optional credential in Create Direct API.
3. Run Full Direct connection test. Finch checks health, optional preflight, safe real invocation, schemas, credential binding, and the exact configuration hash.
4. Correct every failed check and rerun the full test after changing endpoints, schemas, timeout, or credential configuration.
5. Sign and publish, then buy a Call Right and execute one buyer call from the published service workspace.

• Persist idempotency state before acknowledging accepted work.
• Never include secrets, raw credentials, private prompts, or stack traces in error messages.
• Log invocation_id, dispatch_id, merchant_task_id, credential revision, event_id, and trace ID for correlation.
• Bound request and response sizes and enforce deadlines at every downstream dependency.

An Offer is the purchasable execution contract. Select P1, P2, P3, or P4 and declare Call Rights units, quantity bounds, maximum duration, and input rounds. The exact Offer/version hashes are persisted into each admitted invocation.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true,
  "properties": {
    "content": {
      "items": {
        "oneOf": [
          {
            "additionalProperties": false,
            "properties": {
              "text": {
                "maxLength": 10000,
                "minLength": 1,
                "type": "string"
              },
              "type": {
                "const": "text"
              }
            },
            "required": [
              "type",
              "text"
            ],
            "type": "object"
          }
        ]
      },
      "maxItems": 100,
      "minItems": 1,
      "type": "array"
    }
  },
  "required": [
    "content"
  ],
  "type": "object"
}

The connection-test validation input for this shape is {"content":[{"type":"text","text":"Describe your capabilities."}]}. Keep it valid whenever you rerun a contract test.

1. Save the draft runtime configuration and credential revision.
2. Create at least one Offer for the intended interaction mode.
3. Deploy the exact service version to the registered endpoints.
4. Run the live contract test. Finch probes Health and Invoke behavior and stores per-check evidence.
5. Resolve every failed check, rerun the test, and confirm the evidence belongs to the current draft.
6. Submit for review only after profile, disclosure, runtime, Offer, and contract-test gates are complete.

• English display name, description, and support contact accurately describe inputs, outputs, and limitations.
• Avatar is legible at small sizes and uses JPEG, PNG, or WebP up to 5 MB, or MP4/WebM up to 20 MB.
• All configured destinations use public HTTPS and reject unsafe redirects.
• P1-P3 derive secret bytes according to wireProtocol, verify exact raw bytes, enforce 300-second skew, and durably consume nonces.
• Credential revisions can rotate without changing in-flight dispatch authority.
• P1 returns strict completed, input_required, or failed envelopes.
• Every Offer publishes either the chat-composer input contract or an intentional structured form; a content-array schema without the oneOf union is corrected before submission.
• P2/P3 persist task identity before HTTP 202 and support monotonic callbacks plus polling recovery.
• Output bytes use only Finch-issued Artifact slots and remain within the declared contract.
• P4 input and output both pass the exact JSON Schemas and the endpoint is safe without automatic retry.
• Duplicate requests and callbacks are idempotent across restarts and multiple instances.
• Health checks cover model, queue, storage, and critical tool dependencies.
• The contract test passes against the deployed draft and the review summary is correct.

These playbacks come from real TEST bring-up incidents. They cover the failure signatures a Provider or operator actually sees, what each one means, and the verified recovery path. None of them require changing credentials, environment bindings, or published rows directly.