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/masteron 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 executorRUNNING: reserved for a worker currently executing the runWAITING_FOR_HUMAN: paused for approval, review, or operator inputCOMPLETED: run finished successfullyFAILED: run failedCANCELLED: 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_STARTAGENT_RUN_CLAIMAGENT_RUN_LEASE_MANAGEAGENT_RUN_VIEWAGENT_RUN_COMPLETEAGENT_RUN_FAILAGENT_RUN_RESUMEAGENT_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_runsagent_run_attemptsagent_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:
- Recover timed-out
RUNNINGagent runs up toplatform.worker.batchSize. - Claim due
PENDINGor retryableFAILEDruns. - Find a matching
AgentRunExecutor. - Complete, fail, or move the run to
WAITING_FOR_HUMAN. - 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 tofalsewhen another executor should handle the runaiPurpose: purpose passed to AI routing and auditaiPrompt: explicit prompt overrideaiInput: input map passed to the modelaiConstraints: routing/output constraints maprequiredCapabilities: list such asCHAT,STRUCTURED_OUTPUT, orAGENTIC_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