Waking agents — nudges Module

Vaks PM · Integration guide · Agent orchestration · August 2026

Why a wake-up, when agents already pull

The agent model is deliberately pull-based: an agent asks for its next task, claims it atomically, works it, delivers. Nothing pushes it — that is what keeps the lifecycle server-governed and stops two agents from ever holding the same task. But pull alone leaves one question open: when does the agent ask again? Having it poll the API every few seconds is wasteful and adds latency; having it poll rarely means an agent that answers an hour after it is handed work.

The nudge solves exactly that, without changing the security model. It is a doorbell, not a key: Vaks PM simply signals “there may be work for you,” and the woken agent does what it would have done anyway — it pulls and claims with its own token. The nudge carries no authority and can unlock nothing the agent could not already do.

The model at a glance

When a nudge fires

Three events trigger a wake-up. They cover entering the loop and closing it after a review:

Firing is implicit: there is no organization-wide switch to flip. A nudge fires as soon as (1) the project is agent-enabled (agentsEnabled) and (2) an active subscription matches the agent concerned. An agent without a subscription simply receives nothing — and keeps working in pure pull mode.

Subscribe — the contract

Subscription is self-service and self-only: the subject of the subscription is always derived from the token bearer, never from an id passed in the body. An agent can only subscribe itself.

POST /api/v1/me/webhook-subscriptions
X-Api-Key: vaks_pat_<the agent's token>
Content-Type: application/json

{ "callbackUrl": "https://<your-platform>/callback", "events": ["task.assigned"] }

→ 201 Created
  Location: https://<your-domain>/api/v1/me/webhook-subscriptions/<id>
  { "id": "…", "callbackUrl": "…", "events": [...],
    "secret": "…",              ← shown ONCE ONLY (HMAC secret)
    "unsubscribeUrl": "https://…/me/webhook-subscriptions/<id>" }

• callbackUrl — the URL Vaks PM will call. On Copilot Studio / Power Automate this is the @{listCallbackUrl()} of the “HTTP Webhook” trigger. Its domain must be allowed by webhook governance (see below).
• events (optional) — a subset of the three events. Omitted, the subscription receives all three.
• secret — the HMAC secret, returned once only. Store it: it is used to verify the signature of every nudge.
• Location header — the absolute unsubscribe URL. The Logic Apps “HTTP Webhook” trigger reads it from the response and remembers it.

The operation is an upsert: one active subscription per subject. Calling POST again replaces the URL and regenerates the secret. GET /me/webhook-subscriptions returns the current subscription (without the secret), or null.

Two subscription modes

Which token carries the subscription decides its scope:

Unsubscribe

Three forms, all idempotent (200 even if the subscription is already gone or inactive):

The outbound nudge — headers & body

Vaks PM POSTs a compact JSON body and a set of headers modelled on those of the generic webhooks:

POST <your callbackUrl>
Content-Type: application/json
User-Agent: Vaks-PM-Nudge/1.0
X-Vaks-Event: task.assigned                    ← event name
X-Vaks-Delivery: <delivery id>                  ← idempotency key for the receiver
X-Vaks-Signature: sha256=<hex>                  ← HMAC-SHA256(secret, raw body)
X-Vaks-Timestamp: 1723200000                   ← epoch seconds
X-Vaks-Agent-Id: <agent id>
X-Vaks-Agent-Email: agent-…@agents.invalid
X-Vaks-Agent-Name: Vaks%20Doc%20Agent          ← URL-encoded

{
  "event":      "task.assigned",
  "taskId":     "…",
  "projectId":  "…",
  "agentId":    "…",
  "agentEmail": "agent-…@agents.invalid",
  "agentName":  "Vaks Doc Agent"
}

The agent's identity appears both in the body and in the headers, on purpose: in org-level mode a flow can switch on the X-Vaks-Agent-Email header (a simple Switch) without parsing the body. The name is URL-encoded in the header (HTTP headers do not tolerate arbitrary characters); the body carries it plain.

Verify the signature

Every nudge is signed with HMAC-SHA256 over the raw body, using the secret returned at subscribe time. The receiver recomputes and compares — that is what proves the nudge came from Vaks PM and was not tampered with.

// receiver-side pseudo-code
const expected = "sha256=" + hmacSha256(secret, rawBody).hex();
if (!timingSafeEqual(expected, header["X-Vaks-Signature"])) reject(401);

• Sign the exact body received, byte for byte — do not re-serialize it before verifying; the slightest whitespace difference breaks the comparison.
• Use X-Vaks-Timestamp to reject a nudge that is too old if you want replay protection.
• Use X-Vaks-Delivery as an idempotency key: the same nudge may be re-sent after a network failure (see retries).

What the agent does next

Once woken, the agent returns to the normal loop — the nudge replaces none of its steps:

1. It pulls and claims with its own PAT: vaks_claim_task for the exact task the nudge names, or vaks_claim_next_task to take the project's next eligible task.
2. It reads the work context (vaks_get_work_context) — including, on a task.changes_requested, the most recent review verdict.
3. It works, delivers, reports its cost, resubmits for review — exactly the work loop described elsewhere.

Capacity & backpressure

Waking an agent that has no capacity to take the work achieves nothing — worse, it makes it pay for a conversation only to hit a refusal. A capacity control (adjustable, under Agent nudges) filters nudges at emission time against two independent thresholds:

Reserving a slot is atomic (to prevent three approvals in quick succession from waking nine agents for three slots) and is only consumed at claim time. When a project's review queue is saturated, a review_queue_full alert fires once for the project — not one per blocked agent. When a slot frees up (a deliverable is approved), the agent is woken and drains one task; if the queue goes back over the cap, it re-saturates immediately, as designed.

Retries & auto-disable. A failed delivery is retried (exponential backoff), with a 10 s timeout per attempt. A subscription that accumulates 5 terminal failures is automatically disabled — a dead callback does not retry forever. It reappears as “auto-disabled” in the admin console, where it can be re-enabled after the cause is fixed.

Callbacks to a private IP (on-premise)

By default, Vaks PM applies strict anti-SSRF protection to every outbound URL: private, loopback and metadata addresses are refused. That is the right default in shared SaaS. But an on-premise deployment often has its orchestrator (n8n, a runner) on the same private network — the callback then legitimately targets a LAN IP.

This case is allowed without lifting the general protection, via a double lock:

• The mode must be open — either the deployment is dedicated (single-tenant), or the operator sets the environment variable ALLOW_INTERNAL_NUDGE_CALLBACKS=true. In shared SaaS it is closed by default: systematic refusal.
• The ranges must be declared — the organization explicitly lists the allowed internal CIDRs (nudge.internalCallbackCidrs, editable in the admin console, with a warning and an audit trail). Only those ranges pass.

Admin console & delivery log

Everything is driven under Admin → AI Agent Management → Agent nudges (agent:manage right — administrators, or holders of the AI administrator grant):

• Subscriptions — the list of registered callbacks (agent or org scope), with their state. The host never sees a subscription's full URL or secret — only enough to identify it and enable / disable it.
• Generate the connector key — a button mints a dedicated organization key, scoped nudge:manage and valid ~2 years, to paste into your provider for an org-level subscription. The secret is shown only once.
• Delivery log — every nudge attempted, with its status, the HTTP response code and a snippet of the returned body. This is where you diagnose a callback that refuses.
• Internal callbacks — the state of on-premise mode and the list of approved CIDRs (see above).

Endpoint summary

Troubleshooting

See also: Autonomous agent · Copilot Studio — wire up a dedicated agent (MCP tool + wake-up trigger) · AI agents — the work loop, governance, budgets · Agent authentication — how an agent gets its token · Webhooks — the generic HTTP callbacks · all integrations.