Integration docs

Teach your agent how to ask for a human.

Use the scoped token returned by setup. Keep it server-side, put it in the agent runtime environment, and send structured events when the agent is blocked, uncertain, lonely, or waiting for approval.

JavaScript / Node

await fetch("https://your-app.com/api/agent-blocked", {
  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(
    "https://your-app.com/api/agent-blocked",
    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

First create an alert profile from the website or setup API. Then set AGENT_BLOCKED_WEBHOOK_URL,AGENT_BLOCKED_AGENT_TOKEN, and AGENT_NAME in the shell where the agent runs.

Claude Code

Installs an example Claude Code hook config that maps permission prompts, idle prompts, denials, and stop failures to Agent Blocked events.

npm run agent:install -- --tool=claude

integrations/cli-tools/claude-code.md

Codex

Adds AGENTS.md instructions so Codex can run the shared report command when credentials, direction, approval, or confidence block the task.

npm run agent:install -- --tool=codex

integrations/cli-tools/codex.md

Gemini CLI

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

npm run agent:install -- --tool=gemini

integrations/cli-tools/gemini-cli.md

Aider

Adds CONVENTIONS.md instructions for Aider-style sessions to report blockers instead of looping.

npm run agent:install -- --tool=aider

integrations/cli-tools/aider.md

Install everything at once with npm run agent:install -- --tool=all. All tools can manually report through npm run agent:report.

Event types

hard_blockedneeds_credentialsneeds_directiontool_failureapproval_requiredlow_confidencelonely_agentother

Severity

lowmediumhighcritical

Payload fields

agentId required, 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

This repo also includes copyable examples in examples/agent-blocked-payload.ts and examples/agent-blocked-payload.json. See API.md for the full endpoint reference.