Skip to manual
gluon

API and integrations

Hand an approved action to Agent OS

Let an Agent OS process carry out an action after Gluon has decided and approved it.

Executor developer and operator

Gluon runs single actions. Long-running business processes belong to Agent OS. When an action's effect calls an Agent OS process, Gluon makes every decision first (the policy check on execute, the Capability, the kill switch, the autonomy level and the approval bound to the parameters and target) and then hands the run over. Agent OS reports back through a callback and the run settles in Gluon.

The hand-off and the callback are built and have run against a stand-in executor. Agent OS runs no processes yet, and the cancel call on a kill switch is still to be built.

Point an action at a process

An action hands off when its one effect calls a remote Function whose impl.url is agentos:<process>:

GOL · YAML
apiVersion: gluon/v1
kind: Function
metadata: { name: RenewalReview, description: The Agent OS renewal review process. }
spec:
  inputs: { contract: Contract }
  returns: { type: string }
  impl: { kind: remote, url: "agentos:renewal-review" }
---
apiVersion: gluon/v1
kind: ActionType
metadata: { name: ReviewRenewal, title: Review a renewal }
spec:
  target: Contract
  parameters: { contract: { type: Contract, required: true } }
  effects:
    - call: { function: RenewalReview }
  execution:
    idempotencyKey: "params.contract.contractId"

The process call must be the action's only effect, with no webhooks or notifications beside it. Gluon refuses the action while GLUON_AGENTOS_URL is unset, and in production it also needs the external-writes gate, like any write to an external system.

Configure the connection

Set two environment variables on the Gluon API and worker:

  • GLUON_AGENTOS_URL: the Agent OS base URL.
  • GLUON_AGENTOS_CLIENT: the id of the Gluon user whose token Agent OS presents on callbacks. Callbacks from anyone else answer 403.

What Agent OS receives

When the run executes, after any approval, Gluon posts to <agentos>/v1/runs with the header Idempotency-Key set to the run's key. The body carries the run id, the process, tenant and environment, the decision (action, Capability, autonomy, risk tier, decision time, disableRevision), the approval (whether one was required, the approvers and the binding paramsHash, targetRev and ontology), the params, requestedBy, the callback URL and expiresAt.

  • Answer a replay of the same key with the run you already have. After a timeout Gluon asks for the run's state and does not post it again.
  • Refuse to start a run past expiresAt: the approval deadline, or one hour when none is set.
  • Ask Gluon's policy engine again before every step that reads or writes governed data.

A 2xx answer leaves the run running with a handed-off step in Action runs. A 4xx answer fails the run, and Gluon compensates what it already wrote. A timeout (30 seconds) or a 5xx makes it uncertain, and Gluon reconciles it by asking GET <agentos>/v1/runs/<run> before any compensation.

Report back

Shell
curl -s https://gluon.example/api/actions/callbacks/$RUN \
  -H "Authorization: Bearer $AGENTOS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"state": "succeeded", "outcome": {"reviewId": "r-9"}, "attempt": 1}'
stateThe run becomes
acceptedstays running
succeededsucceeded, with the outcome
failedfailed, or compensated when the action has execution.compensate
unknownuncertain, then reconciled

Callbacks are idempotent on state and attempt, and only a run that was handed off accepts them. A callback for a run that is already settled, cancelled or voided is recorded and changes nothing. The outcome keeps camelCase keys with integer or identifier values only; anything else is dropped. Every callback is audited as action.callback.

When reconcile finds the process accepted or still running, the run goes back to running, so a long process never becomes eligible for compensation through retries alone.