Combine an API read with an agent

A process can read an installed API and ask an agent to interpret the response. The result remains structured data that Grid expressions can inspect, share or return alongside the agent's assessment.

In Network → APIs → Services, choose Add API → Import schema, enter the service's exact package ID and version, and supply its OpenAPI URL, file, or pasted definition. Choose Validate definition, review the diagnostics, then Install reviewed definition. Select the installed service and read operation. Enter its connection ID and arguments, then choose Send request to inspect the response and trace. Configure credentials for this connection stores any required credential in the current model's vault. New request drafts use the package ID as the connection, matching pinned model imports; an explicitly edited connection is retained. Validate response separately checks the received value without sending another provider request. Activity shows redacted calls, jobs, and subscriptions. Each action is explicit.

For a service without a schema, choose Add API → Define API. Paste an example request URL to suggest the server, path and query input names; query values are not copied into the definition. Describe inputs with fields and select their types and requiredness. Add operation describes more of the same service. Use Suggest fields from an example response to suggest response types. A sample cannot establish required fields or a complete contract; review the suggestions against the provider's documentation. Advanced schemas remain available for complex inputs and responses.

Under Let the agent draft it, paste documentation or a credential-free example. Review the text that will be sent to your configured AI model, then select Draft with agent. Review its operations and assumptions before selecting Use reviewed draft. Definition drafting sends only the entered example, without attaching model source, request results or vault credentials. Validation, installation and requests require separate explicit actions.

For the read below, use package ID example/service-status, version 1.0.0, server https://status.example.test, GET path /services/{service}, and operation read_status. Add a required string path input named service. Define an object response with required string state and required number pending. Validate the definition and review the native report before installing. Replace the fictional server with the actual provider.

The request tester uses labeled fields when the host supplies complete input metadata. Advanced JSON remains available for complex inputs and older hosts. Configure credentials in the selected model; a storage check and provider access are separate results. The agent can explain a failed check from its displayed summary without receiving the response body.

In Use in model, copy the pinned import and example, or choose Prepare with agent to open a prompt in the existing agent. Review it before sending and review the resulting source proposal before applying. Prepare new version retains the service ID and suggests a new version. Supply updated documentation or examples, compare operation summaries, and inspect the exact package before installation. Existing pinned versions remain available.

A successful provider request and a matching response contract are separate results. Unconstrained response types report an incomplete check. Keep model source and pinned imports in Code; saved Code API links open Network APIs.

An ops: import exposes supported read operations to a process; the existing api: import keeps its workbook meaning.

To create this workflow from the Process surface, choose Create process → API read and assessment. Select an installed read and enter a Grid expression for each parameter: quoted text for strings, BLANK() for omitted optional values. Apply the draft in Code, review and Save, then bind api-analyst and Start. The generated process reads the API, shares its checked result with the analyst, and returns both the observation and assessment. Creation performs no API request or inference and never saves automatically.

The choice is checked against the exact installed package when the draft is prepared. A changed or removed operation requires reopening creation. Only eligible read operations appear; commands require their separate contracts. The catalog exposes at most 128 reads with at most 16 parameters per read. Larger or unavailable catalogs can still be authored in Code through the existing import path. Credentials and server addresses are not copied into the source or creation form. Native generated-workflow execution and UI controls are tested; the new creation flow still awaits a live Desktop walkthrough with a current host executable.

The following example uses example/service-status@1.0.0, whose read_status operation reads /services/{service} and returns {state: string, pending: number}. Install your service's matching definition before saving the model. This example definition uses a fictional server address; replace it with your service's real address. The restart command is included to show the API boundary: it is not admitted by the current read adapter.

openapi: 3.1.0
info: {title: Service status, version: 1.0.0}
servers: [{url: 'https://status.example.test'}]
paths:
  /services/{service}:
    get:
      operationId: read_status
      parameters:
        - name: service
          in: path
          required: true
          schema: {type: string}
      responses:
        '200':
          description: Observed status
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [state, pending]
                properties:
                  state: {type: string}
                  pending: {type: number}
    post:
      operationId: restart
      responses:
        '200': {description: Restarted}

# Install the matching example/service-status API package before saving.
# The process reads its saved connection; source cannot supply credentials.
USE "ops:example/service-status@1.0.0" AS service

TEAM desk
  analyst USING "service-analyst"
END

PROCESS review(target) WITH analyst
  status = service.read_status(target)
  SHARE status WITH analyst
  assessment = ASK(analyst, "Explain the observed service status and recommend the next step. Do not take action.")
  {status: status, assessment: assessment}
END

report = review("web") USING desk

Save the model and open Agent → Tasks → Processes. Select report, choose the model for service-analyst, and press Start process. The process first reads the service, validates its response, then gives that response to the analyst. Inspect the agent's reply and the final {status, assessment} result in the run. Existing API activity records identify the service request and outcome. A failed read stops the process before the analyst is called.

The installed API package determines parameter order and response validation. Pass BLANK() for an omitted optional parameter. Source does not contain credentials, change server addresses or select a different connection: the connection is named by the package ID and credentials remain scoped to the model. A run pins its installed package; changed package contents refuse admission.

Current boundaries

This Desktop adapter supports single HTTP GET/HEAD queries. It makes one request, with no hidden retries or pagination, at most 256 KiB encoded input, 1 MiB response/result and ten seconds, bounded further by the process's original deadline and gateway limits. Existing host/network restrictions still apply.

Commands, subscriptions, paginated queries and other transports do not become available through this read adapter. They require their own operation contract; commands still need durable intent and receipts. Cancelling prevents further steps and acceptance of a late result; an already dispatched read may take until its bounded HTTP request drains.

When the host selects recoverable process storage, an accepted API result is retained with the process. After a restart, explicitly resume the suspended run: it reuses that result and restores subsequent agent context or a pending human question without repeating the read. The original deadline and work limits still apply, and the installed API package and responder bindings must still match. A read interrupted without a retained result remains Unknown. A saved result that was not yet accepted can now finish validation on explicit resume, within the original operation deadline. Record-only storage preserves inspection records, not an executable continuation. Without selected storage, runs remain volatile.

Waiting for an operation

The process panel can display a pending operation supplied by an installed adapter: requests sent, outcome checks and the original deadline. The owner can choose Check operation outcome to request one bounded observation of that same operation. Refreshing the panel only reads Grid's record. It does not poll the provider or send the command again. An outdated check is refused; inspect the current run before checking again. Read-only views expose no action button.

This control does not add command support to the GET/HEAD adapter above. That adapter completes within its single request. The fixed service adapter below supplies the command workflow; its product walkthrough is recorded in the initial release evidence.

Human answers used by an adapter

An installed adapter can require an argument to come from an accepted human answer. The runtime preserves that origin through direct aliases and child processes. A model answer, copied literal or reconstructed record cannot satisfy the requirement, even if its contents match. The adapter receives the respondent and the exact accepted question/context/value identities. The current bridge requires one statically traceable human ASK; selecting between different human origins and importing human evidence from another run remain unavailable.

This proves who answered and what was accepted. An installed adapter can now also require snapshot-bound consent. Its pinned policy identifies the action, human selector, snapshot argument and explicit context field, Boolean approval field, and maximum age. Grid's reply form shows the trusted target, version, expiry and single-use scope. A declined, expired or reused decision cannot advance the operation; copying a Boolean does not grant permission.

The snapshot consent sample exercises this through a test-installed read adapter. The built-in GET/HEAD adapter does not require this policy. The fixed service adapter below requires snapshot-bound consent and owner-issued service values. Its product walkthrough must demonstrate that complete sequence.

If Grid stops after receiving an API result but before accepting it into the process, the saved receipt can now be resumed through the original result type and deadline checks. Resume does not repeat that API request. An expired deadline, cancellation or invalid result prevents the next step. A request without a retained result remains uncertain and is not automatically retried.

Installed durable owners also have a local receipt-repair interface for the gap between the operation journal and process journal. The host must bind the exact owner journal before using it; this is not an arbitrary receipt-upload interface. The recoverable host selects and restores the exact operation journals automatically, as described below.

With GRID_PROCESS_RECOVERY_DIR selected, the host also saves operation-owner intents, result bodies and acknowledgements. After a restart it repairs missing process receipts from the exact known owner journals before offering Resume. It also finishes acknowledgements for results the process already accepted. Neither action calls the API again. This works with the built-in GET/HEAD adapter; its package still declares the same read-only contract.

New recoverable runs require these journals to remain present. Missing or corrupt required storage is refused; it does not silently become a volatile run. Older saved runs without owner journals retain their existing recovery behavior.

This storage profile retains at most 128 operation journals, with a 4 MiB logical reservation per journal. Capacity exhaustion refuses the operation before dispatch. Removing a finished process retires its journals that hold no unresolved outcome (never sent, or settled). A journal whose outcome is uncertain, in flight or pending stays as evidence and keeps counting toward the capacity; operator controls for those remain unfinished. Record-only and volatile runs do not select this extra storage.

Choose which API step runs

An installed operation can be the result of a MATCH arm:

status = MATCH(target,
  "web" -> service.read_status(target),
  _ -> {state: "unknown", pending: 0}
)

Only the selected arm calls the API. Guards and arguments are pure expressions; unmatched input stops the process unless an arm handles it. The typed branch sample also shows a nominal choice whose payload supplies the service key, followed by an analyst turn. It uses the same installed GET adapter as this guide. This does not install the proposed restart command or confer restart authority.

For adapters requiring an original accepted result, an alias or child process can forward its receipt evidence. Reconstructing an equal object or pasting inspection JSON cannot supply that evidence. The fixed service adapter uses this contract for its snapshot, approved command and verification. Its current installation and remaining product validation are described below. Implementation history remains in the coordination progress ledger.

Create an approved service action

Choose Create process → Approve and verify a service action. The generated workflow reads the current service snapshot, asks service-triage to assess that observation alongside the incident, asks the authenticated service-owner privately for consent, and then restarts and verifies that exact command. Declining returns a typed declined result without sending a command. A refusal returns its reason. Successful verification returns either restored or needs-follow-up together with the original receipt and health observation.

Creation only prepares a Code draft. Review and Save it, then bind participants and explicitly Start. The administrator must first install the fixed service API, connection, durable storage and explicit services grant described below. This starter does not turn arbitrary OpenAPI POST methods into supported commands. The fixed provider contract is necessary for deduplication, original-outcome lookup and generation-specific verification.

If a command response is lost, keep the original run. Use its bounded outcome check instead of starting another run: a new run represents a new command. Pending recovery retains the original identity, arguments, consent, consumed attempts and deadlines. Revocation, changed binding or missing evidence refuses recovery. Unknown execution is never treated as a successful restart.

The starter, its regressions and a local product walkthrough — a lost reply across a host restart, explicit Resume with one delivery, decline without a command, and a stopped-command lookup — are recorded in the initial release evidence. That evidence uses a scripted provider and the fictional service; it is not packaged-candidate qualification.

Enable the service fixture on a development host

The recoverable product Start route can now select the native service adapter. Install fixtures/service-recovery@1.0.0 and an explicit API connection first. A host operator then configures GRID_PROCESS_RECOVERY_DIR and supplies GRID_PROCESS_SERVICE_GRANTS_JSON before starting the host. The grant is separate from the Grid program; importing a package or configuring a connection does not authorize a restart.

The grant setting is an array of objects with these fields:

Field	Value
principal, model	Exact authenticated owner and model IDs
resource	Room resource name, such as services
provider, account, connection	Exact installed service scope
packageDigest	Full sha256: digest of the installed API package
generation	Positive grant revision
allowRestart	Explicitly true to allow approved restarts; omitted means false
allowReconciliation	Explicitly true to allow lookup-only checks of stopped commands; omitted means false

Restart the host after changing grants; increment the generation when revising one. Reloading API configuration invalidates the previous installation until host restart. Keep provider credentials in the existing connection configuration. The service example uses its declared recovery room and still requires a typed human response from the grant’s authenticated owner before restart. Product selection and its pending recovery controls were exercised in the initial release walkthrough.

The checked-in fictional provider walkthrough supplies the matching OpenAPI, local service and scripted analyst for this example. It includes approval/decline checks and inspection of the exact restart generation. These are preparation instructions, not a recorded successful product run.

Restore a retained pending service command

The selected service recovery implementation now recognizes an authenticated pending restart with its original owner journal and episode. Resume reconstructs accepted agent/human history and returns to Waiting without sending a request. An explicit outcome Check uses the original command; refreshing does not poll. Resume requires the same installed scope and current authority, intact issuer and operation journals, and the original unexpired deadline. It cannot continue an interrupted dispatch or stopped command; those still need separate reconciliation. Host integration is compile-checked, while its full product walkthrough remains unverified. This does not add pending recovery to arbitrary API packages.

Inspect a stopped command

Selecting a stopped service run now requests its retained original-command evidence. The process panel shows the command identity, requests sent, outcome checks, known outcome (or Unknown), and original lookup-retention deadline. Inspection is read-only: it does not contact the provider, retry a command, or resume source execution. A known completed command can belong to a stopped workflow; these are separate facts. The selected service grant must still authorize reading the original scope. With an explicit allowReconciliation grant, the panel offers Check original outcome while the original lookup budget and retention window permit it. This queues one bounded lookup using the original command identity and revision. Concurrent/stale requests refuse; no POST is repeated and the workflow stays stopped. The panel observes the check's local progress and shows a retained result or error. Source cancellation is preserved; a separate request timeout bounds this lookup. The temporary executor reservation is released after the check drains. Capacity exhaustion refuses without provider work. The initial release walkthrough exercised this check on a stopped workflow; it added only a lookup.

The fictional provider now supports lost restart responses. Its walkthrough separately exercises pending Resume followed by verification and cancelled-source reconciliation, distinguishing command lookups from health observations. The initial release walkthrough exercised both through the product.