Integration docs

Teach your agent how to ask for a human.

Create a profile, connect an agent, then copy the environment block shown on that profile page. Use the token only in the project or terminal where the agent runs, and report when the agent has something important the user should know or act on.

Use the profile setup first

The profile page gives each agent its own scoped token. Save it with the Agent Blocked CLI from the project where that agent runs, then install and verify the adapter for the CLI you use.

npx agent-blocked@latest configure
npx agent-blocked@latest install --tool=all
npx agent-blocked@latest doctor --tool=all

JavaScript / Node

await fetch(process.env.AGENT_BLOCKED_WEBHOOK_URL, {
  method: "POST",
  headers: {
    "authorization": "Bearer " + process.env.AGENT_BLOCKED_AGENT_TOKEN,
    "content-type": "application/json"
  },
  body: JSON.stringify({
    agentId: "prod-agent",
    eventType: "needs_credentials",
    severity: "critical",
    reason: "AWS deploy role expired.",
    details: "The release agent cannot continue without a refreshed role."
  })
});

Python

import os
import requests

requests.post(
    os.environ["AGENT_BLOCKED_WEBHOOK_URL"],
    headers={
        "authorization": f"Bearer {os.environ['AGENT_BLOCKED_AGENT_TOKEN']}",
        "content-type": "application/json",
    },
    json={
        "agentId": "research-agent",
        "eventType": "needs_direction",
        "severity": "medium",
        "reason": "The next research branch is ambiguous.",
        "details": "Need a human to choose between pricing and security analysis.",
    },
)

Generic agent helper

async function askHuman({ eventType, severity, reason, details }) {
  return fetch(process.env.AGENT_BLOCKED_WEBHOOK_URL, {
    method: "POST",
    headers: {
      authorization: `Bearer ${process.env.AGENT_BLOCKED_AGENT_TOKEN}`,
      "content-type": "application/json"
    },
    body: JSON.stringify({
      agentId: process.env.AGENT_NAME,
      eventType,
      severity,
      reason,
      details
    })
  });
}

Install in CLI coding tools

The npm package installs small local helper files and project instructions so agents know when to notify the user instead of looping or waiting silently. It also gives them a recent-notification check before they send repeat alerts. Run the installer in each project where you want Agent Blocked active.

Claude Code

Installs and merges Claude Code hooks so automation events like permission prompts, idle prompts, denials, and stop failures can report to Agent Blocked.

npx agent-blocked@latest install --tool=claude

Codex

Adds AGENTS.md instructions and Codex project hooks. After install, start a fresh Codex session so approval requests and failed tool calls can report.

npx agent-blocked@latest install --tool=codex

Gemini CLI

Adds GEMINI.md instructions for Gemini CLI-style automated workflows that need a durable escalation rule in the repository.

npx agent-blocked@latest install --tool=gemini

Aider

Adds CONVENTIONS.md instructions for Aider-style automated sessions to notify you instead of looping.

npx agent-blocked@latest install --tool=aider

Install everything at once with npx agent-blocked@latest install --tool=all. All tools can manually report through npx agent-blocked@latest report.

Event types

hard_blockedneeds_credentialsneeds_directiontool_failureapproval_requiredlow_confidencecontext_limitlonely_agentother

Severity

lowmediumhighcritical

Payload fields

agentId optional with scoped agent tokens, max 160 charseventType optional, defaults to hard_blockedseverity optional, defaults to highreason required, max 1000 charsdetails optional, max 4000 charsconfidence optional, 0-100runId/provider/model optional metadata

Keep reason short and actionable. Put command output, failed URLs, and decision context indetails. Never send API keys, passwords, OAuth tokens, or customer data in either field.