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>:
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
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}'
state | The run becomes |
|---|---|
accepted | stays running |
succeeded | succeeded, with the outcome |
failed | failed, or compensated when the action has execution.compensate |
unknown | uncertain, 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.