How AgentBlocks works
AgentBlocks sits between your AI agent and the external world. Every action flows through policy rules configured in the dashboard before it can execute. Here's how each piece fits together.
Your Agent
Claude, GPT, custom
AgentBlocks API
Rules + Approvals
External Service
Gmail, GitHub, Slack
Dashboard Rules
Rules are configured in the AgentBlocks dashboard — not in local files. This means your agent can't modify its own rules, and you can update policies without redeploying anything.
Each capability (email, GitHub, Gmail, Drive, Slack) has its own ordered rule list. Rules are evaluated top-to-bottom — the first match wins. When no rule matches, the default action is require approval.
| Action | Description |
|---|---|
| allow | Auto-approve matching requests — no human needed |
| request | Require human approval before execution (default) |
| deny | Auto-reject — the action is blocked immediately |
Rules support pattern matching. For example, email rules can match *@yourcompany.com to auto-approve internal emails. GitHub rules use permission and repo patterns like contents:write:my-staging-repo.
Approval Workflows
When a rule results in request (require approval), AgentBlocks pauses the action and sends a notification to the account operator. Approvals can be handled via:
Slack
Approve or reject directly from a Slack notification.
Dashboard
Review pending actions in the AgentBlocks web dashboard.
Email & WhatsApp
Get notified and approve via email or WhatsApp.
Once approved, the action is executed. If rejected, the agent receives a rejection response. Pending approvals expire if not acted on.
LRO Polling Pattern
All write operations follow a Long-Running Operation (LRO) pattern. When an action needs approval, the API returns a token that the agent polls for a resolution.
| Response type | Meaning | Terminal? |
|---|---|---|
| queued | Awaiting human approval | No |
| approved | Approved and executed | Yes |
| rejected | Human rejected the request | Yes |
| timed_out | Expired before approval | Yes |
| failed | Approved but execution failed | Yes |
Agents poll GET /operations/:token with exponential backoff (every 5–30 seconds) until a terminal status is reached.
Execution Model
How actions are executed depends on the capability:
| Capability | Execution |
|---|---|
| GitHub | Short-lived tokens issued to the agent via the agentblocks-git script. Tokens are revoked immediately after use. |
| Email, Gmail, Drive, Slack | Actions execute on AgentBlocks servers. Your credentials and tokens are never exposed to the agent. |
This means even if an agent is compromised, it cannot access your raw credentials for most services. For GitHub, the blast radius is limited to exactly what was approved — and the token is already revoked.
Audit Trail
Every action — requested, approved, rejected, executed, or blocked — is logged. The dashboard provides full visibility into:
- Which agent requested the action
- Which rule matched and what decision was made
- Who approved or rejected (and when)
- The exact parameters of the executed action
- Outbound and inbound email history