Skip to main content
Every Agents Ask call is made by a registered agent. Registering one in the BotShield Console gives you an agent key, fixes the name your users see on every card, and declares which kinds of action the agent may propose. Registration is self-serve at console.botshield.ai.
Agents Ask is labelled Beta in the BotShield Console.

Who can manage agents

The engine enforces these rules, not only the Console: a Member’s request to change an agent is refused. Production changes also need a passkey confirmation; see Production needs a passkey confirmation.

Register the agent

1

Open Trusted Agents

In the BotShield Console, go to Agents Ask → Trusted Agents. The page has three tabs: Trusted Agents, Resolutions, and Sandbox. Your plan is shown next to the tabs and managed under Settings → Plans.
2

Pick the environment

Use the Development | Production toggle in the page header. The agent is created in the environment that is selected, and it cannot be moved later. Start in Development.
3

Click Register Agent and fill in the form

The Register a Trusted Agent dialog asks for three fields:
4

Click Register and copy the key

The Console shows the agent key once. Copy it into your secret store before you click Done.
The agent key is shown only once. BotShield keeps a hash of it, not the key, so nobody can show it to you again. If you lose it, rotate the key to get a new one.
After you click Done, the agent appears in the Trusted Agents list with its display name, its agent name, its Agent ID, its allowed categories, and an Active status. Each active row has three actions: Edit, Rotate key, and Revoke.

The agent key

  • <AgentName> is the agent name you entered. <secret> is a random 43-character string.
  • Send it as a Bearer token on every Agents Ask call: Authorization: Bearer bs_agent_MeridianConcierge__….
  • It is a server-side secret. Never ship it in a browser, a mobile app, or a prompt.
  • A key belongs to one agent in one environment.
If a name is already in use, registration fails with the code agent_name_taken. Choose another name, or revoke the existing agent first.

The Agent ID

Every agent also has an Agent ID, a UUID that BotShield assigns at registration. It is shown on the agent’s row in Trusted Agents, under the agent name, with a copy button next to it.
  • The Agent ID is the aud claim of every Proof of Resolution issued for this agent. Copy it into your configuration next to the agent key, and pin the audience check to it.
  • It is an identifier, not a secret. It also appears as agent_id in the agents_ask.* webhook events.
  • It never changes, including when you rotate the key. A development agent and a production agent have different Agent IDs, even when they share a name.

Action categories

A category is a short label for a kind of action, in domain.verb form. You choose your own categories; there is no fixed list to pick from. BotShield enforces them per agent: a proposal whose action.category is not in the agent’s list is rejected with a 403 error. See Propose an action. Format rules for each category:
  • Starts with a lowercase letter.
  • Then 1 to 40 more characters from lowercase letters, digits, ., _, and -.
Examples: travel.book, travel.refund, payment.authorize, account.update. To change an agent’s categories later, click Edit on its row in Trusted Agents, update the comma-separated list, and click Save. At least one category is required.
Keep categories narrow. An agent that only issues refunds should hold travel.refund and nothing else, so a compromised prompt cannot make it propose a payment.

Development and production agents

Each environment’s API accepts only its own agents. The production API rejects a development key with a 401 error whose message reads Trusted agent "MeridianConcierge" exists but is registered for development; this endpoint is production.

Production needs a passkey confirmation

When the header toggle is on Production:
  1. If your Console account has no passkey yet, Register Agent first asks you to create one.
  2. When you click Register, the Console asks you to confirm with that passkey. The confirmation must be from the last 5 minutes; if it is declined or cancelled, nothing is created.
Rotate key and Revoke on a production agent ask for the same passkey confirmation, because they issue or end a production credential. Development agents need no passkey. Editing an agent’s display name or categories needs no passkey in either environment.

Rotate a key

Rotate a key when it may have been exposed, when someone who had it leaves, or on your own schedule. Rotation replaces the secret and keeps the agent: its agent name, display name, Agent ID, and allowed categories stay the same. The people who linked to the agent stay linked, and proposals that are waiting for a decision stay open.
1

Click Rotate key

In Agents Ask → Trusted Agents, click Rotate key on the agent’s row. The Console asks you to confirm: Rotate the production key for "Meridian Airlines Concierge"? The current key stops working immediately.
2

Confirm with your passkey (Production only)

For a production agent, the Console asks you to confirm with your console passkey. If your account has no passkey yet, it asks you to create one first and then continues. If you cancel or decline the passkey prompt, nothing changes and the current key keeps working. Development agents skip this step.
3

Copy the new key

A New agent key for … panel appears above the agent list with the new key and a Copy button. The key is shown once. Copy it into your secret store before you leave the page.
The previous key stops working the moment the new one is issued. There is no overlap period. Calls that still send the old key fail with a 401 error until you deploy the new one, so have the change to your secret store ready before you rotate.
A revoked agent cannot be rotated. Register a new agent instead.

Revoke an agent

Click Revoke on the agent’s row and confirm. For a production agent, the Console then asks you to confirm with your passkey; if you cancel, nothing changes. Revocation is permanent and takes effect immediately: the next call with that key fails with a 401 error and the message Trusted agent "…" has been revoked. A revoked agent cannot be restored, and its key cannot be rotated. The name becomes available again once the agent is revoked, so you can register a new agent under it. The new agent has a new key and a new Agent ID. To replace a key and keep the agent, use Rotate a key instead.

Test in the Sandbox

Agents Ask → Sandbox fires a real proposal to a real phone on behalf of one of your development agents, so you can see the whole loop before you write code. You do not paste a key; the Console acts as the agent you select. Only an Admin can create a link code or send a test Request Card; a Member sees the preview and the code with the buttons turned off.
1

Select a development agent

The picker lists only development agents and shows each agent’s allowed categories.
2

Step 1 · Link with BotShield

Click Create link code. In the BotShield app on your phone, open the Agents Ask tab and tap Link an agent, enter the 6-character code, and confirm with your passkey. The Opaque ID appears in the Sandbox and pre-fills the next step. Codes last 10 minutes.
3

Step 2 · The Request Card

Choose an Action category, then set the Summary, optional Detail label and Detail value, Expires after (seconds) (60–86400, default 600), and an optional Adaptive Card payload. Load demo fills in a sample payload. The Preview tab renders the card as your user will see it.
4

Fire test action

Your phone receives the card. Confirm or Deny it. The Result panel checks every 2 seconds, for up to 15 minutes, and shows the status, timestamps, and the signed Proof of Resolution when the decision lands.
Sandbox proposals behave like API proposals: they send a real push, appear under Resolutions, and emit the agents_ask.* webhook events to your configured endpoints. The panel to the right of the form has three tabs. Preview renders the card. TypeScript SDK and cURL show the agentlink/inquire call for the card you built, with your values filled in and a placeholder where the agent key goes. The TypeScript snippet is written for botshield-sdk 2.0.0: it passes serverURL, sends the key as Bearer … through security.agentKeyAuth, uses the camelCase request fields, and checks result.data.error before it reads the result. It matches the samples in Propose an action, so you can paste it into your project and supply the key from your secret store.

Review activity

The Resolutions tab lists every proposal for the selected environment, 50 to a page, with the columns Time Stamp, Agent, Action, Category, and Verdict. Select a row to see its detail: the agent and its Agent ID, the category, the environment, when it was asked, resolved, and due to expire, and the Request ID with a copy button. The Verdict column uses the display words, not the wire values: The Sandbox’s Result panel uses the same display words, except that it shows Waiting while the card is queued.

Next steps

Link a human

Get the opaque_id your agent will propose to.

Propose an action

Call the API with your new agent key.

Keys and environments

How agent keys sit alongside site keys and API keys.

Hosted MCP server

Give the same key to an MCP-capable agent.