> ## Documentation Index
> Fetch the complete documentation index at: https://docs.botshield.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents Ask overview

> Have a verified human confirm or deny a consequential action your AI agent proposes, and get back a signed Proof of Resolution.

**Agents Ask** puts a real human in the loop for actions your AI agent should not take on its own word. Your agent proposes the action. The human sees it as a card in the BotShield app and gives a **Confirm** or **Deny** with their device biometric (passkey). You receive a signed **Proof of Resolution** that your code verifies before it executes anything.

<Info>
  **BotShield notarizes; your platform executes.** BotShield records and signs the human's decision. It never performs the action and never decides what a Confirm permits. Your own code checks the proof and then acts.
</Info>

## When to use it

Use Agents Ask wherever an agent is about to do something that costs money, moves data, or is hard to undo:

| Action | Example card |
| - | - |
| Refunds | "Refund booking MA-48213" · TOTAL · \$168.45 |
| Payments and bookings | "Book round-trip DEN → MIA" · TOTAL · \$487.60 |
| Account changes | "Change the email on your Meridian Airlines account" |
| Sign-offs | "Release purchase order PO-2291 to the supplier" · TOTAL · \$12,400.00 |

A confirmation typed into a chat window proves nothing: the agent's own surface cannot show that a person was there. Agents Ask moves the decision to the human's own phone, in the BotShield app, and returns a proof that any system can check without trusting the agent.

<Tip>
  **Try the whole loop in five minutes.** The [BotShield Demos](https://demo.botshield.ai) include **Ticketz · Agents Ask**: chat with a ticket-buying agent (Claude, through the hosted MCP server), link your BotShield ID, ask it to book seats, and confirm the purchase on your phone. The chat then shows the order and its Proof of Resolution.
</Tip>

## The three building blocks

<CardGroup cols={3}>
  <Card title="A registered agent" icon="robot" href="/agents-ask/register-an-agent">
    You register the requesting agent in the BotShield Console and receive an agent key, `bs_agent_…`. The key authenticates every Agents Ask call. The Console also shows the agent's **Agent ID**, and lets you rotate the key.
  </Card>

  <Card title="A linked human" icon="link" href="/agents-ask/link-a-human">
    The human links to your agent once, in the BotShield app. You get back an `opaque_id` (`OP_…`) that only your agent can use. No name, no email.
  </Card>

  <Card title="A proposed action" icon="circle-check" href="/agents-ask/propose-an-action">
    Your agent proposes an action to that `opaque_id`. The result is **Confirmed**, **Denied**, or **Expired**. Confirmed and Denied come with a signed proof.
  </Card>
</CardGroup>

## The whole loop

```mermaid theme={null}
sequenceDiagram
    participant A as Your agent
    participant B as BotShield API
    participant P as User's phone (BotShield app)
    participant S as Your server / webhook endpoint

    Note over A,P: Once per human
    A->>B: POST /agent/bind-session
    B-->>A: code + claim_url
    A->>P: Show the code or link to the user
    P->>B: User confirms the link with their biometric
    A->>B: GET /agent/check-binding
    B-->>A: opaque_id (OP_…)

    Note over A,S: Every consequential action
    A->>B: POST /agentlink/inquire (opaque_id, action)
    B->>P: Card: what the agent wants to do
    P->>B: Confirm or Deny with biometric
    A->>B: GET /agentlink/check-status (long-poll)
    B-->>A: verdict + resolution_jwt
    B-->>S: Webhook agents_ask.resolution.confirmed
    S->>S: Verify the proof, then execute
```

## What you can rely on

* **Every decision is a fresh biometric.** The human confirms each action on their own device. A link alone never authorizes anything.
* **The proof is bound to one action.** Its `jti` is the `request_id` you supplied, and its `aud` is your agent's **Agent ID**, which you copy from **Agents Ask → Trusted Agents** in the Console. A proof for one action cannot be replayed for another.
* **You verify it yourself.** The proof is an ES256 JWT. Check it locally against BotShield's public keys. See [Proof of Resolution](/agents-ask/proof-of-resolution).
* **Silence is not consent.** A proposal that the human never answers expires and produces no proof. A **Deny** is an explicit, signed decision.
* **No personal data crosses to you.** BotShield tells you *that* a verified human decided, never *who* they are. You address the human by an `opaque_id` that is meaningless outside your agent. See [Privacy boundary](/concepts/privacy-boundary).

<Note>
  Agents Ask is labelled **Beta** in the BotShield Console.
</Note>

## Ways to integrate

| Path | Use it when |
| - | - |
| REST API or the [TypeScript SDK](/sdk/typescript) | Your own backend or agent runtime makes the calls. Start with [Register an agent](/agents-ask/register-an-agent). |
| [Hosted MCP server](/agents-ask/mcp-server) | Your agent speaks the Model Context Protocol and should call Agents Ask as tools. |
| [Salesforce package](/integrations/salesforce/overview) | You run Agentforce agents or Flows and want packaged actions. |

## Next steps

<CardGroup cols={2}>
  <Card title="Register an agent" icon="robot" href="/agents-ask/register-an-agent">
    Create the agent in the Console, then copy its key and its Agent ID.
  </Card>

  <Card title="Link a human" icon="link" href="/agents-ask/link-a-human">
    Run the one-time link and store the `opaque_id`.
  </Card>

  <Card title="Propose an action" icon="paper-plane" href="/agents-ask/propose-an-action">
    Send the proposal, wait for the decision, or cancel it.
  </Card>

  <Card title="Proof of Resolution" icon="file-signature" href="/agents-ask/proof-of-resolution">
    Verify the signed result before you execute.
  </Card>

  <Card title="Live demo" icon="play" href="https://demo.botshield.ai/#agent">
    Ticketz · Agents Ask — an agent buys, a human approves, on production.
  </Card>
</CardGroup>