Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentuse.io/llms.txt

Use this file to discover all available pages before exploring further.

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. The main approval surface is agentuse serve at /approvals. Slack is optional: it can notify reviewers and link them into the approval 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 creates a pending approval request.
  5. Reviewers open /approvals or a tokenized approval 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 approval page to continue the session with its existing context.

​
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 approval dashboard: 
http://127.0.0.1:12233/approvals
If reviewers open approval 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 approval 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 approval 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 use the Review approval button to decide in /approvals. 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 approval 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 approval 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

​
Experimental Approval API

The Approval API is experimental and mirrors the web approval page contract. Use it to build custom approval UIs or integrations. List approvals as JSON: 
curl "http://127.0.0.1:12233/approvals?format=json"
You can also send Accept: application/json. Check one approval: 
curl "http://127.0.0.1:12233/approvals/session_abc123/status?token=$resumeToken"
Submit a decision: 
curl -X POST "http://127.0.0.1:12233/approvals/session_abc123/decision" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "approve",
    "comment": "Looks good",
    "resumeToken": "'"$resumeToken"'",
    "project": "optional-project-id"
  }'
The decision endpoint returns immediately while the suspended session resumes in the background: 
{
  "sessionId": "session_abc123",
  "status": "resuming"
}
Continue a completed or errored session from an approval page token: 
curl -X POST "http://127.0.0.1:12233/approvals/session_abc123/continue" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Please revise the CTA and run the smoke test again",
    "resumeToken": "'"$resumeToken"'",
    "project": "optional-project-id"
  }'
The continuation endpoint also returns immediately while AgentUse starts the follow-up run: 
{
  "sessionId": "session_abc123",
  "status": "continuing"
}
/approvals follows the agentuse serve auth setting. Tokenized approval detail, status, decision, and continuation URLs validate the approval token so reviewers can open Slack links without a separate API-key login.

​
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.