Inflow.aiDocs

Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.

Preserved from source baseline d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.

Agent Execution

Follow one durable run from request to outcome

Retain the run ID as the inspection coordinate. The catalog describes a policy; the run stores its selected snapshot, context, scheduling state, attempts and outcome. A consultant requests bounded work and inspects it. Admitted workers claim leases and invoke underlying services. Starting an agent run, answering its handoff and completing a person's business task are distinct operations.

Stage Retain What it proves
Start returned run ID, agent/model selection and goal A durable request exists.
Claim actual worker identity, lease and attempt That worker claimed execution responsibility.
Wait / resume same run ID, waiting message and explicit patch A real human-wait lifecycle transition.
Inspect status, output, failure, logs and attempts The recorded outcome of this run.

Read before changing state. A timeout or expired lease does not prove that an external effect did not occur. Context and attribution fields do not grant business access. The following requests are source-reviewed examples with deployment-specific IDs; they were not sent to a live worker or provider.

Example UIAI-AGENT_EXECUTION-01 — Start and inspect a summary request

Scenario and inputs. Nadia has the actual start permission and selected an active definition for fictional request leave-2026-014. Its policy permits ai.summarize; any selected model must be a real enabled connection model. The context contains only demonstration data, not an employee's confidential record.

Procedure. Submit POST /api/agent-runs with the selected agent and only permitted requested tools/connectors. Replace requestedBy with the admitted attribution expected by your integration; that payload field is not identity proof. Retain the returned run ID, then read its detail, /logs and /attempts under current authorization.

Request-body example; replace the attribution value before use:

{
  "agentId": "agent.case.worker",
  "goal": "Summarize the fictional request and list questions for Sara.",
  "context": {"caseId": "leave-2026-014", "requestedDays": 5},
  "requestedToolIds": ["ai.summarize"],
  "requestedConnectorIds": [],
  "requestedBy": "REPLACE_WITH_ACTUAL_ADMITTED_ACTOR_ID"
}

Expected result. Successful creation records PENDING state, the copied catalog policy and a creation log. It has not thereby returned a successful model answer, approved leave or persisted a separate business mutation. Attempts and subsequent state transitions provide additional evidence.

Failure and recovery. Correct missing/inactive agents or rejected policy subsets. If creation's reply is uncertain, reconcile the actual integration's known outcome before repeating an external-effect goal. The start DTO does not promise a universal idempotency-key field.

Sources. Run controller, start body, policy snapshot.

Example UIAI-AGENT_EXECUTION-02 — Inspect a worker claim and lease

Scenario and inputs. An operator is explaining an admitted worker integration, not lending Nadia a worker identity. The fixture has a real pending run and a worker with claim and lease-management permissions. Durations use their actual ISO-8601 representation, such as PT5M.

Procedure. The worker calls /api/agent-runs/claim with workerId, limit and lockDuration. Work only the returned runs. Renew a long-running claim through the exact run's /renew-lease route using the same worker ID. During an authorized shutdown or handoff, release its lease with the appropriate availableAt value instead of falsely completing it.

{"workerId":"owned-ai-worker","limit":1,"lockDuration":"PT5M"}

Expected result. Durable ownership and attempt records distinguish an active claim from merely pending work. An omitted lockDuration defaults to five minutes. Release makes work available for a later claim; it does not undo a remote operation or turn a business failure into success.

Failure and recovery. Never invent a worker ID to take another worker's lease or renew after ownership has changed. Inspect actual lease and status and use the admitted recovery owner. A consultant should inspect/escalate a stuck run rather than call worker endpoints as a substitute for a supported business action.

Sources. Claim and lease routes, claim defaults, attempt recording.

Example UIAI-AGENT_EXECUTION-03 — Resume a genuine human wait

Scenario and inputs. The demonstration run is WAITING_FOR_HUMAN and asks Sara whether to continue preparing a summary. Its stored context already names leave-2026-014. Sara has this run's native resume authority; that does not make her a participant of every workspace task.

Procedure. Read the current run and waiting message. Send a deliberate context patch and message to the same run's /resume route. Use the actual actor attribution expected by the admitted caller. The controller takes runId from the URL rather than trusting an alternate body coordinate. Re-read state and logs before reporting progress.

{
  "context":{"summaryScopeConfirmed":true},
  "message":"Continue the summary only; the leave decision remains a separate task.",
  "resumedBy":"REPLACE_WITH_ACTUAL_ADMITTED_SARA_ID"
}

Expected result. The waiting run becomes PENDING with its original context plus the patch. This is an agent-runtime transition, not a vacation approval or a native task completion receipt. Subsequent effects retain their own participant, form and authorization checks.

Failure and recovery. If the run is no longer waiting, inspect its actual state instead of repeatedly sending approval-like messages. After an uncertain reply, reconcile this same run and logs. Creating a new run or treating natural-language assent as unrelated connector authority would change the original intent.

Sources. Resume route, resume body, context-preserving test.

Example UIAI-AGENT_EXECUTION-04 — Diagnose a timeout without repeating an effect

Scenario and inputs. An admitted worker exceeded its deadline or lost a lease while preparing a summary. The operator has the actual run ID and inspection authority. Some permitted tools may contact an external connector, so a missing acknowledgement is not evidence that nothing happened.

Procedure. Inspect status, attempts and logs before using recover-timeouts. Determine whether work is waiting for a person, still leased, failed with a scheduled retry, or terminal. Compare the attempt's deadline/failure with the actual connector or provider receipt available to its owner. Only the admitted recovery worker should request recovery for its bounded due-work set.

Expected result. The operator distinguishes active work from pending retry and genuine human waits. Recovery follows the durable run policy and does not reclassify a failed attempt as an observed success. A completed remote action must be reconciled through its native contract before any repeat is considered.

Failure and recovery. Do not edit timestamps, force completion, erase failed attempts or create another business request merely to make the queue look healthy. Preserve an unknown remote outcome and ask its accountable service owner for supported reconciliation. A provider deadline, worker lease and business task due date are separate facts requiring different remedies.

Sources. Recovery route, timeout recovery contract, recovery implementation.

Document status: Current durable agent-runtime reference. Verified against origin/master on 2026-08-14.

Agent execution is the runtime layer for governed AI agents. The catalog defines what an agent is allowed to do; an agent run records one execution request with a snapshot of those rules.

flowchart LR
    A["/api/agent-runs"] --> B["AgentExecutionService"]
    B --> C["AgentRegistryService"]
    B --> D["AgentRunRepository"]
    C --> E["conf/agents/*.xml"]
    D --> F["AgentRun"]
    D --> G["AgentRunLog / AgentRunAttempt"]
    F --> H["AgentRunWorker"]
    H --> I["AI Gateway"]
    H --> J["Approved Tools / Connectors"]

Runtime Contract

AgentRun stores:

  • selected agent and model
  • goal and workflow context
  • allowed tools and connectors from the agent definition
  • requested tools and connectors for this run
  • memory and human-handoff policy ids
  • process/work-item references
  • lifecycle status, output, failure reason, timestamps, and logs
  • worker lease, attempts, timeout, retry delay, and due time

This lets distributed ai-worker nodes execute the run without losing the policy snapshot approved at creation time.

Statuses

  • PENDING: run has been created and is waiting for an executor
  • RUNNING: reserved for a worker currently executing the run
  • WAITING_FOR_HUMAN: paused for approval, review, or operator input
  • COMPLETED: run finished successfully
  • FAILED: run failed
  • CANCELLED: reserved for cancellation flows

Policy Enforcement

When a run starts, the service loads the agent definition and rejects:

  • missing agents
  • inactive agents
  • requested tools not present in allowedToolIds
  • requested connectors not present in allowedConnectorIds

This is the first guardrail before tool execution. The shipped AI Gateway and connector executors re-enter their owning services, so credential, connector, workspace, rate-limit, and side-effect controls remain authoritative during execution. New executors must preserve that pattern.

API

All routes require authentication.

POST /api/agent-runs
POST /api/agent-runs/claim
POST /api/agent-runs/recover-timeouts
POST /api/agent-runs/{runId}/renew-lease
POST /api/agent-runs/{runId}/release-lease
GET  /api/agent-runs
GET  /api/agent-runs?agentId=agent.connector.operator
GET  /api/agent-runs?processInstanceId=process-123
GET  /api/agent-runs/{runId}
GET  /api/agent-runs/{runId}/logs
GET  /api/agent-runs/{runId}/attempts
POST /api/agent-runs/{runId}/complete
POST /api/agent-runs/{runId}/fail
POST /api/agent-runs/{runId}/resume

Example start request:

{
  "agentId": "agent.connector.operator",
  "goal": "Prepare an integration handoff.",
  "context": {
    "caseId": "CASE-1"
  },
  "requestedToolIds": ["connector.rest"],
  "requestedConnectorIds": ["n8n"],
  "requestedBy": "designer"
}

Permissions

  • AGENT_RUN_START
  • AGENT_RUN_CLAIM
  • AGENT_RUN_LEASE_MANAGE
  • AGENT_RUN_VIEW
  • AGENT_RUN_COMPLETE
  • AGENT_RUN_FAIL
  • AGENT_RUN_RESUME
  • AGENT_RUN_RECOVER_TIMEOUTS

Designers can start, view, and resume runs. Workers can start, claim, view, complete, fail, resume, and recover timed-out runs. Administrators inherit all permissions through *.

Current Implementation

The current repository is a JDBC implementation behind the AgentRunRepository port, with an in-memory implementation still available for isolated tests. The database migration creates:

  • agent_runs
  • agent_run_attempts
  • agent_run_logs

Workers claim pending runs using row-level leases and FOR UPDATE SKIP LOCKED, which allows multiple active-active nodes to process runs without taking the same work item.

Long-running workers can renew a lease while an agent run is still executing:

POST /api/agent-runs/{runId}/renew-lease
Content-Type: application/json

{
  "workerId": "agent-worker-1",
  "lockDuration": "PT5M"
}

Workers that are shutting down or intentionally handing work back can release the lease without failing the run:

POST /api/agent-runs/{runId}/release-lease
Content-Type: application/json

{
  "workerId": "agent-worker-1",
  "availableAt": "2026-07-02T01:00:00Z"
}

availableAt is optional. When it is omitted, the run becomes immediately claimable. Both lease operations require the workerId that currently owns the non-expired lease.

Timeout Recovery

timeoutSeconds is enforced by timeout recovery. A RUNNING agent run whose current attempt has exceeded timeoutSeconds is released and moved back to PENDING for retry, or to FAILED when the run has reached maxAttempts. The current attempt is closed as failed and an error log is written with the recovering worker id.

AgentRunTimeoutRecoveryService calls:

recoverTimedOut(recoveryWorkerId, limit, Instant.now())

Operators can trigger the same recovery path through the API:

POST /api/agent-runs/recover-timeouts?recoveryWorkerId=node-a&limit=100

The endpoint requires AGENT_RUN_RECOVER_TIMEOUTS. The seeded worker role has this permission so AI worker nodes and operations workers can run maintenance sweeps without admin credentials.

When platform.node.roles includes ai-worker, the standard worker loop runs this recovery sweep automatically before processing due agent runs. The sweep uses the node id as the recoveryWorkerId and platform.worker.batchSize as the maximum number of timed-out rows to recover per loop. The worker result exposes the recovered count as agentRunTimeoutsRecovered.

Worker Execution

AgentRunWorker is invoked by nodes with the ai-worker role. It claims due agent runs, finds a matching AgentRunExecutor, and then completes or fails the run through AgentExecutionService so lease ownership is enforced centrally. Executors can also return WAITING_FOR_HUMAN; the worker persists that as a real run status, clears the worker lease, and records the current attempt as waiting. Waiting runs are not reclaimed by workers until the resume endpoint or an approval integration moves them back to a claimable state.

The worker loop processes agent runs as follows:

  1. Recover timed-out RUNNING agent runs up to platform.worker.batchSize.
  2. Claim due PENDING or retryable FAILED runs.
  3. Find a matching AgentRunExecutor.
  4. Complete, fail, or move the run to WAITING_FOR_HUMAN.
  5. Record logs and attempt status changes through the repository.

Human handoff resume uses:

POST /api/agent-runs/{runId}/resume

Example resume request:

{
  "context": {
    "approved": true,
    "approvedBy": "manager"
  },
  "message": "Approved by manager.",
  "resumedBy": "designer"
}

Resume is only valid for runs in WAITING_FOR_HUMAN. The provided context is merged into the existing run context, the run returns to PENDING, the due time is set to now, and the worker lease stays clear so an ai-worker node can claim it again.

The platform ships with AiGatewayAgentRunExecutor, which turns an agent run into an AiGatewayRequest and executes it through the configured AI provider catalog. Additional executor beans can be added beside it for specialized tool-use, connector, memory, human-handoff, or local-model behavior.

The AI Gateway executor can be shaped by context fields on the agent run:

  • aiGatewayEnabled: set to false when another executor should handle the run
  • aiPurpose: purpose passed to AI routing and audit
  • aiPrompt: explicit prompt override
  • aiInput: input map passed to the model
  • aiConstraints: routing/output constraints map
  • requiredCapabilities: list such as CHAT, STRUCTURED_OUTPUT, or AGENTIC_REASONING

When aiPrompt is not provided, the executor combines the agent definition's prompt template with the run goal. When aiInput is not provided, it sends the run goal, workflow context, requested tools/connectors, and process/work-item references as structured input.

ConnectorAgentRunExecutor handles runs whose context contains connectorCall or connectorCalls. It uses ConnectorExecutionService, so all connector catalog, operation, credential, protocol, and approved-query controls remain in one place.

Single-call example:

{
  "connectorCall": {
    "connectorId": "n8n",
    "operationId": "trigger-workflow",
    "input": {
      "workflowId": "wf-123",
      "payload": {
        "caseId": "CASE-1"
      }
    },
    "options": {
      "header.X-Source": "inflow-agent"
    }
  }
}

Multi-call example:

{
  "connectorCalls": [
    {
      "connectorId": "google-sheets",
      "operationId": "read-range",
      "input": {
        "spreadsheetId": "sheet-1",
        "range": "Requests!A:E"
      }
    },
    {
      "connectorId": "n8n",
      "operationId": "trigger-workflow",
      "input": {
        "workflowId": "wf-123"
      }
    }
  ]
}

Connector agent runs still enforce the policy snapshot captured at start:

  • the connector must be present in the agent definition's allowedConnectorIds
  • if the run supplied requestedConnectorIds, each connector call must be in that requested list
  • connector execution failures fail the agent run attempt and use the normal retry rules

Executor implementations can target:

  • AI Gateway chat/tool calling
  • local model runtimes
  • connector/tool execution plans
  • human handoff policies
  • agent memory reads and writes through docs/manuals/agent-memory.md

Try “document generation”, “integrations” or “first form”.