LizzyAgent docs
Contract 2026.08Tool-using AI runtimesReviewed 27 Aug 2026

Give an agent a contract, not a tour.

The human guides teach the product. This version tells an agent which source controls, which action is allowed, what state must be preserved, and when execution must stop.

Load full agent context Open the discovery index

Load sources in this order

Start small. Add the full contract or schema only when the task needs it.

01Discovery index/docs/llms.txtSmall route map for selecting the right contract without crawling the site.02Full agent context/docs/llms-full.txtConsolidated lifecycle, invariants, state rules, and recovery behavior.03REST schemahttps://lizzy.albinilabs.com/v1/openapi.jsonCanonical paths, methods, schemas, required fields, authentication, and operation metadata.04Remote MCP server/docs/mcpConnection, tool, workflow, and authority contract for POST https://lizzy.albinilabs.com/v1/mcp.05Pilot policy/docs/agent-playbook.mdTyped-tool sequences, human handoffs, approval gates, and no-progress stops for Pilot.

Choose one control surface

REST, MCP, and Pilot share resources. Their connection and authority contracts differ.

Standalone REST client

OpenAPI controls request shape and server behavior. The integrating application owns approval, retries, secret handling, and persistence.

Use OpenAPI. Do not apply Pilot-only approval behavior to raw REST calls.

Remote MCP client

Connect to POST https://lizzy.albinilabs.com/v1/mcp with a full-access API token. Use tools/list for current tool schemas and the MCP guide for workflow behavior.

The agent acts with the full authority of the supplied test or live token.

Pilot typed tools

The execution playbook controls tool selection, handoffs, and stop conditions. A proposal or handoff is durable platform state, not chat wording.

Use typed tools. Do not translate REST examples into guessed tool arguments.

Here, agent means a tool-using AI runtime. It does not mean the customer-support agent resource exposed elsewhere in the Lizzy API.

Select the capture source kind explicitly

The source kind controls credentials, model routing, and billing.

Managed (kind: "managed")

Read GET /v1/distill/teachers with distill:read and use an exact current catalog ID as teacher_model. No provider key is needed.

Live calls bill the workspace at catalog rates. Test calls record cost but are not charged.

BYOK (kind: "byok")

Keep base_url and upstream_key outside model context. The proxy forwards the request verbatim to the workspace's provider.

The provider bills the call, and Lizzy records captured cost as zero.

For managed calls, the required request model is recorded asmodel_requested; the source teacher is model_served. Do not infer that the requested model controls routing.

Run one bounded decision loop

Every turn should consume recorded state and produce at most one side effect.

  1. 01

    Read state

    Load the durable workflow and exact saved resource references. Never reconstruct an ID from prose.

  2. 02

    Choose one action

    Select one allowed next action from the current state and the relevant canonical contract.

  3. 03

    Check authority

    Confirm mode, scope, prerequisite state, budget, and any required human decision before a write.

  4. 04

    Execute once

    Send one bounded read or one idempotent mutation. Do not hide retries inside an agent loop.

  5. 05

    Persist the result

    Store returned IDs, request IDs, state, and the next watch or handoff before continuing.

  6. 06

    Stop or advance

    Stop on async work, approval, handoff, input, block, or failure. Advance only from recorded state.

Stop means stop

These states require a later event, a person, or corrected input. Another mutation is not recovery.

Async watch
Persist the resource reference and wait for its registered event. Do not poll in a loop.
approval_required
Name the required role and decision, then stop. A verbal approval does not replace the platform event.
handoff_required
Leave credentials, uploads, and dashboard-only work to the person. Keep the existing workflow.
input_required
Ask for the single missing or corrected choice. Do not substitute a default.
blocked or failed
Branch on the stable error code and preserve diagnostic IDs. Do not create a replacement resource.

Carry a small context packet

Persist facts needed to resume. Keep credentials, raw captured bodies, and upload bytes out of model context.

jsonminimum resumable state
{
  "contract_version": "2026.08",
  "control_surface": "rest | mcp | pilot",
  "mode": "test | live",
  "workflow_id": "<exact saved workflow id>",
  "resource_refs": ["<exact saved resource ref>"],
  "last_status": "<recorded platform status>",
  "last_error_code": null,
  "request_id": null,
  "allowed_next_action": "<one reviewed action>",
  "human_decision": null
}

Resolve conflicts by authority

Do not blend contradictory sources into a plausible answer.

  1. OpenAPIRequest and response shape, methods, requiredness, authentication, and server-declared operation metadata.
  2. MCP server and guideRemote connection, declared tool schemas, shared workflow phases, result envelopes, and token authority.
  3. Pilot playbookTyped-tool policy, handoffs, approval gates, stop rules, and response discipline.
  4. Full agent contextCross-surface invariants, resource flow, state handling, and recovery.
  5. Human guidesExamples, explanation, operator context, and tutorials. Never use tutorial prose to invent an operation.
If the controlling source is missing or ambiguous, stop.Ask for the contract or a human decision. Do not guess an endpoint, identifier, state, or approval.