Hermes structured runs and approvals

Use these five endpoint-qualified capabilities when an application needs a Hermes run ID, pollable status, structured lifecycle events, a provider approval continuation, or an explicit stop request.

The run is asynchronous, but its provider state is not durable. The pinned Hermes implementation keeps run status, event queues, active-task references, and approval queues in one process. A restart loses them. Treat run_id as a temporary handle, not as a durable AIP execution record.

Operations

Replace <endpoint_id> with the normalized endpoint ID present in AIP discovery.

All five are stable AIP Workflow capabilities. Every provider request requires the selected endpoint’s Bearer token. The endpoint comes from the capability ID; input cannot select another endpoint or base URL.

run_events is a safe read in the mutation sense. Reconnecting does not replay events already removed from the provider’s single live queue. Do not interpret the retry marker as an event-delivery guarantee.

Choose the run lifecycle

Use a normal Chat or Responses capability when the application needs only one HTTP model turn. Use the governed operator capability when Hermes must delegate child AIP actions and retain a recoverable AIP-to-provider binding.

Shared AIP contract

Start, approval, and stop publish read, write, and external_network side effects. Status and events publish read and external_network. None declares a transaction. Every compensation contract says rollback is not supported.

The AIP contract also publishes a 10-second maximum queue-delay hint and a 99.9% availability target. These are declared values, not measurements or qualification evidence.

The status schema understates the possible data. A completed status can contain model output, and a failed status can contain a redacted error. Events can contain message text, tool names, previews, and approval detail. Handle both as confidential application data even though the published read contracts do not mark them as PII-bearing.

Start a run

The connector publishes an open object schema. Hermes still requires a truthy input value. A string is the least ambiguous form. A message array is also accepted when its final item has usable content.

Use the body object for provider input and keep transport controls at the AIP level:

{
  "body": {
    "input": "Prepare a concise incident summary.",
    "instructions": "Do not perform external mutations.",
    "model": "hermes-agent",
    "session_id": "incident-review-2030-01"
  },
  "session_key": "support:incident-review"
}

The provider also accepts conversation_history and previous_response_id. An explicit, non-empty history takes precedence. When no explicit history is present, Hermes can load the history and session ID stored for a previous Responses object. A missing previous response does not fail the start; Hermes continues without that stored history.

For a multi-message input, Hermes turns all usable items except the last into history. The final item’s content becomes current input. Supply valid message objects and end with the visible user request.

A successful start returns immediately:

{
  "run_id": "run_0123456789abcdef0123456789abcdef",
  "status": "started"
}

The provider HTTP status is 202. This receipt proves only that Hermes created the in-process run structures and scheduled background work. It does not prove that the model started, a tool succeeded, or the run reached a terminal state.

Keep run and continuity identities separate

If session_id is absent, Hermes uses the new run_id as the conversation task ID. Several runs may intentionally share one explicit session ID or memory key. They still receive isolated approval queues, so approval for one run cannot release another run’s pending command.

Trusted execution adds AIP principal, tenant, issuer, trace, delegation, session, idempotency, and deadline headers. The connector verifies an endpoint’s configured tenant binding before it sends the request.

Poll run status

Call run_status with the exact provider handle:

{
  "run_id": "run_0123456789abcdef0123456789abcdef"
}

The connector percent-encodes the path segment and rejects carriage return, line feed, and NUL characters. The provider returns 404 run_not_found when the handle is absent from that process.

The current status object can contain these fields:

Interpret the states as follows:

Terminal status is retained in memory for one hour after its last update, then becomes eligible for the periodic sweep. There is no run-list operation. A missing status can mean an unknown ID, retention expiry, or process restart.

Consume run events

run_events opens GET /v1/runs/{run_id}/events and aggregates provider SSE frames. It accepts run_id and an optional positive max_events. The connector defaults to 4096 parsed events.

The provider can emit:

• message.delta for generated text;
• tool.started and tool.completed for tool progress;
• reasoning.available for exposed reasoning previews;
• approval.request and approval.responded for provider approval flow;
• run.completed, run.failed, or run.cancelled as terminal events.

Hermes sends a keepalive comment after 30 seconds without an event. Comments do not enter the connector’s event array. The provider sends : stream closed after its queue sentinel; that comment is not a terminal event by itself.

The queue is live, in memory, and consumed destructively. There is no cursor, history store, fan-out, or supported resume. Use one subscriber per run. A second subscriber can split events with the first. When a subscriber closes, Hermes removes the public queue handle, so a reconnect can return 404 while the underlying run continues.

If a stream ends without a recognized terminal event, the connector marks the AIP action incomplete rather than completed. If max_events truncates the aggregate, terminal is false. Poll run_status before deciding what happened.

Detailed frame parsing, AIP stream publication, disconnects, and cancellation are owned by the streaming guide and cursor reference.

Resolve a pending provider approval

An approval.request event contains a redacted command where applicable and the provider choices once, session, always, and deny. Review that event before submitting a decision.

There are two different approval gates:

The first does not automatically decide the second. After tenant policy grants the AIP action, submit the intended provider choice:

{
  "run_id": "run_0123456789abcdef0123456789abcdef",
  "choice": "once",
  "resolve_all": false
}

The published schema also accepts approve and allow; Hermes normalizes them to once. Prefer the four canonical choices so stored intent matches provider events. Set all or resolve_all only when the reviewer has assessed every currently queued approval for this run. Resolution never crosses into another run, even when both share a session ID.

The success object reports run_id, normalized choice, and the number of resolved queue entries. Hermes returns 409 approval_not_active when the run no longer owns an active approval session, or 409 approval_not_pending when the queue has no pending item.

The AIP capability requires tenant-policy approval with reason, input snapshot, and policy-decision evidence. The approval expires after 15 minutes. It is a separate record from the provider’s in-memory queue.

Stop active work

Call run_stop only for a run that is still active:

{
  "run_id": "run_0123456789abcdef0123456789abcdef"
}

The capability requires AIP approval. Hermes sets status to stopping, calls the active agent’s interrupt hook, cancels the asynchronous wrapper task, and waits at most five seconds for that task. It then returns:

{
  "run_id": "run_0123456789abcdef0123456789abcdef",
  "status": "stopping"
}

This receipt is not a terminal cancellation guarantee. The agent runs in an executor thread that task cancellation cannot preempt directly. A current tool call can finish, and effects that already reached another system are not rolled back. Poll status and retain a terminal event when available.

Stopping a completed run returns 404 because Hermes has already removed its active agent and task references. Runtime cancellation dispatches the same provider stop operation only when the cancelled AIP action input contains a run_id; cancelling run_start before its receipt has no provider handle to stop.

Understand retention and process loss

Run streams become eligible for the orphan sweep 300 seconds after creation. The sweep runs once per minute. It removes active references and provider approval routing but does not prove that an executor thread stopped. A run that exceeds this window can become unmanageable through events, approval, or stop even while underlying work is still settling.

Subscribe promptly and design runs to finish within the admitted deadline. Do not use the run API as a durable job store. Preserve AIP lifecycle and execution evidence outside this provider memory boundary.

Apply idempotency and retry rules

Start, approval, and stop require a capability-scoped AIP idempotency key. The published TTL is 24 hours, and collision behavior is ReturnOriginalResult. The Hermes run handlers do not enforce the forwarded Idempotency-Key header.

Consequently, durable replay protection depends on the AIP runtime’s configured idempotency backend. Repeating run_start directly at Hermes creates another run. Repeating an approval or stop after provider success commonly returns a conflict or not-found response rather than the original result.

Use these recovery decisions:

The provider has no endpoint for listing runs or reconciling a lost start receipt. Do not auto-retry a mutating call after an unknown outcome.

Account for shared limits

Hermes applies one concurrency gate across Chat, Responses, and structured runs. The default is 10 in-flight agent runs; zero disables the cap. Saturation returns 429 with Retry-After: 1, although the connector’s typed failure does not retain that response header.

For structured runs, the gate counts entries in the live run-stream map. A completed run whose event queue was never consumed can therefore occupy a slot until a subscriber drains it or the orphan sweep removes it. Consume the event stream even when the application also polls status.

The provider rejects request bodies over 10,000,000 bytes. The connector does not publish a separate response-size bound. Trusted AIP execution can end any operation at its action deadline, even when the connector or provider would otherwise keep waiting.

Handle failures

The connector reports provider non-success bodies through a typed failure and marks mutating failures as non-retryable. Authentication, tenant mismatch, expired trusted deadlines, and runtime cancellation are separate failures.

Verify an integration

For each admitted endpoint, verify and retain evidence that:

1. discovery exposes exactly the five expected capability IDs and contracts;
2. one approved start returns a unique run_id and status becomes visible;
3. the single event consumer observes ordered frames and a terminal condition;
4. two runs sharing a session ID still have isolated approval queues;
5. approval requires AIP evidence and changes only the selected run;
6. stop is followed until cancelled, failed, or another explained outcome;
7. a disconnected stream is reconciled through status without claiming replay;
8. process restart and retention expiry are reported as evidence loss, not as proof that no external effect occurred.

Record the AIP source revision, Hermes revision, connector and host artifact identities, endpoint ID, tenant binding, credential revision, timestamps, and retained results. Source presence alone is not qualification or live-product evidence.

Related documentation

• Hermes Agent capabilities
• Chat and Responses capabilities
• Actions and sessions
• Approvals and policy
• Errors and recovery