Agent Access

Quick Setup Guides

Two different things get called "agent setup." Pick the one that matches what you're building — full details for each are linked at the end.

A — Independent agent caller (no specific user involved)

A partner or third-party agent calling your public/shared actions — e.g. a support bot answering from your docs, or a stats lookup. Nobody is logging in; the agent just needs scoped, revocable access.

Full reference: Agent Access Profiles (scopes, webhooks, staleness).

B — Human-delegated agent caller (acts on behalf of a specific user)

An agent that reads or changes data for one of your users — e.g. "check my last five orders." The agent proves which user it's acting for by carrying a consent token that user explicitly granted.

Full reference: Third-Party Agents And User Identity and Identity resolver.

Partner handoff

Give partner developers only public identifiers — never DUCT_SECRET_KEY or sk_duct_…. Dashboard → Shell → Agent setup has a copyable handoff block with your shell_id, profile slug, and endpoint skeletons.

Optional: paste the handoff block into your site's llms.txt or partner README so agents that fetch your domain can find public IDs. Do not put secrets in those files.

# Duct partner access — Acme

Token checklist

Partner agents always authenticate with at_. User consent is additive, not a replacement.

# Independent — Bearer only

See Third-Party Agents And User Identity for consent setup and Agent Confirmation Protocol for per-call side-effect approval.

How Agent Calls Work

Company Backend And Internal Automations

When the caller runs on infrastructure you control, exchange your shell secret for a short-lived shell token. Pass user_consent_token or X-Duct-User-Consent when acting on behalf of a specific user — your backend can mint duct_delegated after the user has logged in.

import os

Agent Access Profiles (Partner And External Agents)

Create named profiles in Dashboard → Shell → Agent setup. Each profile has a unique slug per shell (like partner-read, support-bot, or public-stats), a scope list, and an optional webhook URL. External callers request tokens with only those public identifiers — no sk_duct_….

# Agent requests a 1-hour token (no company secrets required)

Company webhook (optional)

When a profile has a webhook_url, Duct POSTs before minting the token. Verify X-Duct-Signature: sha256=… using your profile webhook secret. Respond with { "approved": true } or { "approved": false, "reason": "..." }.

// Duct → your backend

Scope grammar

Scopes are strings on the agent access profile. Prefer narrow tiers:

After a manifest push

Every push increments manifest_version. Agent tokens record the version at exchange time. If you push again before the token expires, invoke may return 409 with MANIFEST_STALE. Re-run POST /v1/agent-access-token and retry with the new token. Shell tokens are not version-pinned the same way. Use agent access profiles when the caller should not hold your root secret; use shell tokens for company-owned backends on your servers.

Natural-Language Agent Query

/message accepts both agent_token (at_…) and shell_token (st_…). Company backends typically use a shell token; partner agents use their scoped agent token. Scope enforcement applies to agent tokens: if the router resolves a side-effect action, the agent token must carry the matching write: scope.

# Company backend (shell token)

Human Shell vs Agent API

Deeplink handoff for agents

When a capability exists only as a UI page (no matching agentAccessible action), the router blocks browser navigation for agents but resolves the deeplink URL server-side. The /message response may include:

Without product.baseUrl (or top-level baseUrl), Duct cannot build a navigable handoff link and omits handoff_url.

{

Third-Party Agents And User Identity

An at_ token proves which agent is calling. It does not prove which user the agent acts for. User-scoped actions (requiresAuth: true, agentPermissions.requireUserConsent: true) need a separate user delegation token in user_consent_token on /message (or X-Duct-User-Consent on /invoke).

When consent is missing, both /invoke and /message return 403 permission_denied with a structured remediation block (when webhooks.consentCallback is configured) pointing at POST /v1/consent/request. Deny messages do not embed internal action ids in free text.

Anti-pattern

All agentAccessible actions have requiresAuth: true, and your API middleware only verifies duct_delegated minted after POST /api/auth/login. Result: human shell chat works; Postman or partner agents get 403 permission_denied from Duct or 401 from your API.

Correct patterns

# Third-party agent — user-scoped read (after user approved consent)

user_ref — your opaque user handle

The agent sends only its shell_id — it never sends user_ref, a callback URL, or action names. The user's identity is bound at approval time by your identity resolver (manifest.webhooks.identityUrl), a thin route on your existing login that vouches for an opaque user_ref signed with your shell webhook secret. Duct then issues a uct_ covering everything the agent profile is permitted to call. Side-effect actions still require per-call human approval.

Identity resolver

Set manifest.webhooks.identityUrl in Dashboard → Settings → Webhooks. Duct redirects the user to this route (your existing login/session) at approval time. You confirm who they are, return an opaque user_ref plus sig = HMAC_SHA256(whsec, "<duct_state>.<user_ref>"), and Duct mints the uct_. See the full identity resolver guide for pseudocode and the consent callback contract.

See also the AI integration prompt — especially the third-party agents and user identity section — for middleware checklists when auditing a company codebase.

Consent callback — what to do on your end

After the user approves, Duct redirects to your callback_url with a short-lived duct_consent_code query parameter (90 seconds). Your handler exchanges it server-to-server and stores the grant for the agent:

// Consent callback — exchange duct_consent_code for uct_

On proxied action calls, read X-Duct-User-Ref and map your opaque alias to the live user with your own lookup layer.

Cross-Shell Discovery

Any public Duct shell can call another public shell — no pre-configuration required on either side. The target shell controls exposure via registry_visibility, intershell_enabled, and per-action agentAccessible. Duct routes and enforces consent.

# Search for a capability across the Duct network

To make your shell callable cross-shell, set in your duct.config.ts:

export default defineDuctConfig({

Agent Confirmation Protocol (human in the loop)

Side-effect actions always require a human to approve before execution. When an agent calls a side-effect action, Duct returns 202 confirmation_required with an approval_url — a human-readable page where the authorised user reviews the action and clicks Approve. The page then shows an execution_token the human copies and hands back to the agent. The agent retries the exact same call with X-Duct-Execution-Token and receives a 200.

# Step 1 — agent requests a side-effect action (with user_consent_token)

On execution-token retry (X-Duct-Execution-Token), Duct re-verifies user_consent_token before consuming the execution token. If consent was revoked after approval, the retry returns 403 consent_invalid without burning the token.

Mode 1 — poll for approval (autonomous agents)

The agent never receives a token from a human. It polls GET /v1/confirmations/:confirmation_id/status (rate-limited). While status is pending, keep polling. When approved, the JSON body includes execution_token and execution_token_expires_in — retry your original invoke with X-Duct-Execution-Token.

The token is returned only when the poll carries the agent credential that created the confirmation; an unauthenticated poll still works but returns status alone. Reading a decision grants nothing — only a human can approve, so an agent polling its own confirmation can never approve it.

Mode 2 — confirmation webhook

Pass confirmation_webhook_url on POST /invoke or POST /message. When a human approves, Duct POSTs an HMAC-signed confirmation.approved event to that URL with execution_token, confirmation_id, action, and params. Verify X-Duct-Signature the same way as dashboard webhooks.

Orchestration contract (/message vs /invoke)

POST /message is one orchestration turn: classify → route → bounded execution. It auto-expands manifest dependsOn chains and honors paramMapping between steps — the same behavior as the human shell. POST /invoke runs a single action when you already know action + params.

On upstream_error or partial steps[], your agent owns the outer loop: read outputs, fix params, and call /invoke or another /message (optionally with history or session_id).

Analytics and audit visibility

Human chat and agent API traffic show up differently in the dashboard:

Audit glossary

Terms you will see in Dashboard → Audit turn traces, filters, and Advanced invoke rows. Tap the ? icons in the audit UI for the same short definitions with a link back here.

Outcome Receipts — What They Prove

A receipt is a signed statement that the gate made a decision — it is not proof that a side effect actually completed, and it is not a guarantee about business outcomes. Every receipt carries an explicit scope_of_claim with two lists: what it asserts and what it does_not_assert. Read that field before trusting anything else on the receipt.

Verifying a receipt

Send the receipt to POST /v1/receipts/verify. The response reports valid plus, on failure, a specific reason: WRONG_CLAIM (presented as the wrong claim type), REPLAYED (already honored once), DELEGATION_EXPIRED / DELEGATION_REVOKED (the delegation it references is no longer active), or MANIFEST_STALE (the shell's manifest has changed since the receipt was issued).

When a shell has offline verification keys configured, receipts are signed with Ed25519 and can be verified without calling Duct at all — fetch the public key set from GET /v1/keys/receipts. Receipts without that configuration fall back to a signature Duct itself can check on request.

To prove an execution matches its declared intent (not a hijacked or mutated one), pass the paired duct:intent:v1 receipt as intent_receipt in the same request. Duct verifies both signatures independently and confirms the executed action, params, and order line up before returning intent_matched: true.

Credential recheck timing

By default Duct re-verifies a uct_/at_ consent token on every invoke (on-process). For high-volume, low-risk read actions this round trip is often unnecessary — set an action's or a shell's credentialCheckPolicy to on-accept to verify once and trust a cached acceptance for up to 24h, or both to require a fresh acceptance and still live-check every call for sensitive actions. Leaving it unset keeps today's behavior exactly as-is.