Skip to main content
Experimental Feature: Approval gates and the Approval API are experimental. The web UI, API response shape, and channel config may change based on production feedback.
Approval gates let an agent prepare work, pause before finalizing it, and continue only after a reviewer approves, rejects, or comments. Every run is a session. The review surface is the unified session page at /sessions/<id> in agentuse serve: it shows the run log, and when the session is suspended on an approval gate it also offers approve / reject / comment right there. /approvals remains as a filtered list of sessions currently waiting for review, and each row links to the session page. Slack is optional: it can notify reviewers and link them into the session page, but Slack is not where approval state lives.

​
How It Works

  1. Add approval: true to the agent frontmatter.
  2. Run agentuse serve.
  3. The agent works normally until it reaches the approval point.
  4. AgentUse suspends the session on a pending approval gate.
  5. Reviewers open the session page (/sessions/<id>), either from /approvals or from a tokenized link.
  6. A reviewer approves, rejects, or comments.
  7. AgentUse resumes the suspended session with the reviewer result.
  8. After the session finishes, reviewers can send follow-up instructions from the same session page to continue the session with its existing context.
Approval gates are only supported on the top-level agent, not on delegated sub-agents. Suspend/resume operates on a single top-level session, so an approval gate inside a delegated sub-agent could never suspend the run. If a sub-agent sets approval in its frontmatter, AgentUse fails the run at load time with a clear error. Put the gate on the top-level (or type: manager) agent instead.

​
Create an Agent with Approval

Use the smallest possible config: 
---
model: anthropic:claude-sonnet-4-6
approval: true
---

Write a polished launch email from the user request.
The markdown body stays focused on the work. You do not need to write instructions like “wait for approval before publishing.” If an approval should expire, set a timeout: 
approval:
  timeout: 24h
By default, approvals do not expire.

​
Define the Approval Boundary

Approval gates are agent-driven: the agent calls the internal await_human tool when it reaches the point where review is needed. AgentUse injects the approval mechanism, but your agent instructions can still define the policy boundary for your workflow. Write the boundary in business terms. Describe what the agent may prepare without approval, and what it must not finalize until approval is granted. For a social publishing agent: 
---
model: anthropic:claude-sonnet-4-6
approval: true
channels:
  slack:
    events: [approval]
---

Draft the social post and save any working files under `.agentuse/tmp/`.

You may create drafts, previews, and local artifacts without approval.

Before scheduling or publishing the post through any external service, request approval with:
- a short summary of the post
- the final post text
- the target account or channel
- the scheduled time, if any
- any risks or assumptions
For a release agent: 
---
model: anthropic:claude-sonnet-4-6
approval:
  timeout: 24h
---

Prepare the release notes and open a draft pull request if needed.

Do not publish the package, tag the release, merge the PR, or announce the release until the approval gate is approved.
Good approval boundaries usually separate reversible preparation from external side effects:
  • Usually safe before approval: local temp files, drafts, previews, dry runs, summaries, draft PRs
  • Usually approval-required: publishing, sending email, scheduling posts, deploying, merging, deleting, charging, or changing production/external state
  • If unsure, ask for approval before the action

​
Start the Server

Start the AgentUse daemon: 
agentuse serve
Open the sessions dashboard (every run) or the approvals view (sessions waiting for review): 
http://127.0.0.1:12233/sessions
http://127.0.0.1:12233/approvals
Both link into the per-session page at /sessions/<id>. If reviewers open links from another machine, start serve with a reachable public URL: 
agentuse serve --public-url https://agentuse.mycompany.com
AgentUse runs one serve daemon at a time. When the daemon is serving this project, approval links use its registered port. Use --public-url when reviewers need a URL other than the local server address.

​
Optional Slack Channel

Slack can alert reviewers when an approval is waiting. Approval state still lives in the AgentUse session page. The Slack channel message stays concise, and supporting approval details are posted in the message thread when the agent provides them. Those thread details can include summary, draft, artifact, context, and risk. 
approval: true

channels:
  slack:
    events: [approval]
See Channels for Slack setup, channel ids, events, and completion/failure channel messages.

​
Reviewer Flow

The session page shows the best available review details from the agent:
  • prompt: the reviewer-facing decision prompt
  • summary: what changed and what is being approved
  • draft: inline draft content
  • draft_url: URL to a draft artifact
  • artifact_url: URL to the primary review artifact, such as a PR, preview, document, or generated artifact
  • context: relevant background, constraints, or work completed so far
  • risk: known risks, unresolved questions, or reviewer attention areas
  • Session logs before and after the decision
Reviewer actions are fixed:
  • Approve: resumes the agent with status: "approve"
  • Reject: resumes the agent with status: "reject"
  • Comment: resumes the agent with status: "comment" and the reviewer comment
When Slack Socket Mode is configured, the approval details thread can also accept Approve, Reject, Comment, and normal thread replies. Without Socket Mode, reviewers open the session page link to decide. When the agent receives a comment, it decides whether to revise, ask for approval again, or stop with a clear explanation. After the run completes, the same session page becomes a lightweight continuation surface. Add a follow-up instruction in the Continue session box to resume the completed or errored session with its existing context. This matches Slack thread replies, but keeps the web session page as the source of truth for details and logs.

​
Configuration Fields

Approval config is intentionally small: 
approval: true
or: 
approval:
  timeout: 24h
  • approval: true or an object to enable the approval gate
  • approval.timeout: optional suspension timeout, such as 30m, 24h, or 7d
Channel config is separate: 
channels:
  slack:
    events: [approval]
    channel_id: C0123456789
  • channels: optional external collaboration channels, such as channels: [slack]
  • channels.slack.events: events for Slack. Approval gates use approval; terminal run events are documented in Channels.
  • channels.slack.channel_id: Slack channel id. If omitted, AgentUse uses SLACK_APPROVAL_CHANNEL.
  • channels.slack.enabled: optional switch for temporarily disabling Slack

​
Auth and the session token

Authentication follows the deployment invariant:
  • Local bind (127.0.0.1 / localhost): no API key, no token. View and approve are fully open.
  • Exposed host: serve refuses to start without AGENTUSE_API_KEY (use --no-auth to bypass, dangerous). The API key (Authorization: Bearer) authorizes everything.
Because a Bearer header is not clickable from a Slack message or an email, each session also has a session token: a stateless, per-session value that stands in for the API key on that one session’s page. 
sessionToken = base64url( HMAC-SHA256(key = AGENTUSE_API_KEY, msg = sessionId) )
One token grants both view and approve for its session, and the same value works for every gate in that session. It is unguessable without the API key and is scoped to a single session (a token for session A never authorizes session B). On localhost there is no API key, so there is no token and links omit it. await_human mints this token when it builds the reviewer link, so Slack/email links are clickable without an API-key login.
While a run is suspended, anyone with its session link can approve it. A completed run has no pending gate, so a shared completed-log link cannot approve anything. The view + approve conflation only matters during the approval window.

​
Experimental session / approval API

The API is experimental and mirrors the web session page contract. Use it to build custom review UIs or integrations. JSON endpoints live under the /api/* prefix and are always API-key gated on an exposed host. The HTML session page and its action subroutes carry their own capability auth (session token / API key / local), so a tokenized link works without a Bearer header. List sessions as JSON (filter by agent, trigger, or time window with days): 
curl "http://127.0.0.1:12233/api/sessions?trigger=scheduled&days=7" \
  -H "Authorization: Bearer $AGENTUSE_API_KEY"
Fetch one session (summary + run-log entries): 
curl "http://127.0.0.1:12233/api/sessions/session_abc123" \
  -H "Authorization: Bearer $AGENTUSE_API_KEY"
Poll a session’s live status (session token works in place of a header): 
curl "http://127.0.0.1:12233/sessions/session_abc123/status?token=$sessionToken"
Submit a decision. Authorize with the session token (?token=) or a Bearer header; the current pending gate is resolved server-side, so you do not pass a gate token: 
curl -X POST "http://127.0.0.1:12233/sessions/session_abc123/decision?token=$sessionToken" \
  -H "Content-Type: application/json" \
  -d '{ "status": "approve", "comment": "Looks good" }'
The decision endpoint returns immediately while the suspended session resumes in the background: 
{
  "sessionId": "session_abc123",
  "status": "resuming"
}
Continue a completed or errored session: 
curl -X POST "http://127.0.0.1:12233/sessions/session_abc123/continue?token=$sessionToken" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Please revise the CTA and run the smoke test again" }'
The continuation endpoint also returns immediately while AgentUse starts the follow-up run: 
{
  "sessionId": "session_abc123",
  "status": "continuing"
}
Legacy approval routes. GET /approvals/:id now redirects to /sessions/:id, and the older /approvals JSON list plus the /api/approvals/:id/{status,decision,continue} action endpoints remain available for backward compatibility. Those legacy action endpoints still take a gate resumeToken in the body. In-flight Slack links from before the upgrade keep working: the session page also accepts a valid gate resumeToken as a credential until those approvals expire. Prefer the /sessions routes and the session token for new integrations.

​
Local Testing

For development or manual testing, you can resume a suspended session from the CLI: 
agentuse sessions resume session_abc123 --approve
You can also reject or comment without writing JSON: 
agentuse sessions resume session_abc123 --reject "Not ready"
agentuse sessions resume session_abc123 --comment "Shorten this and add pricing"
Prefer the /approvals UI for normal review, Slack for reviewer alerts, the Approval API for custom review surfaces, and agentuse sessions resume for local testing.