Approved route for agents

View as Markdown

When an AI agent works in your app on a person's seat, you can offer it a better way in: the tools you reviewed. Telltale tells the agent the tools exist, and counts every call made through them per account, whatever the detector said about the session. You decide what to charge for or include; Telltale never charges anyone.

There are two ways onto the route:

1. Tell the agent the tools exist

Nothing to install beyond the SDK. While a session's verdict is AI agent and your Site has at least one reviewed, enabled tool, the page carries a notice agents can read:

HTML
<meta name="agent-route" content='{"version":1,"offer":"approved-tools","message":"This site offers approved tools for AI agents. Use them instead of operating the page.","webmcp":true,"runner":"window.Telltale.getClient().invokeTool(name, input)","tools":[{"name":"export_report","webmcpName":"export_report__r0k3j9x2m","title":"Export report","readOnly":true}]}'>

It names tools and titles only: no verdict reasons, scores, session or account details. It is removed when the verdict leaves AI agent, when no reviewed tool is left, and on reset or consent withdrawal.

You can also show a short visible note to the agent. It appears only for an AI agent verdict that is not behaviour-only, so a person who was misread sees nothing, and it can be dismissed:

HTML
<script src="https://app.trytelltale.dev/sdk.js" data-telltale-key="ao_pk_…" data-telltale-agent-route-banner></script>

or Telltale.init({ …, agentRoute: { banner: true } }). Turn the notice off entirely with agentRoute: false.

The notice is an offer, not security. Every tool keeps its checks: approval is rechecked before each call, writes ask the person to confirm, and your backend authorizes each request as usual.

2. Count calls per account

Every call an agent makes through a reviewed tool in the page is one approved-route call for the session's account: a call through WebMCP (the browser ran the registered tool), or a call through the in-page runner while the session reads as AI agent. Your page running its own tools for a person with invokeTool is not a route call. A runner call is chargeable only when the AI agent verdict is high confidence (verified identity, an automation trace, injected input, sustained behaviour, a behaviour change, or two or more independent behaviour families agreeing with no physical-device input), never on one behaviour pattern alone; see what counts as chargeable. Identify the user from your server (POST /api/v1/identify with accountId) so calls land on the account you know; an account ID sent only by the page is shown but never counted as chargeable.

The account drawer in Accounts shows "This account's agents moved to approved tools: N calls" for the selected period, split into calls in the page and calls with an agent token. Read the same numbers with GET /api/admin/approved-route/account?site=…&accountId=…&source=server-associated&days=30.

3. Agent tokens for your API

Agent tokens are off until a workspace owner or admin turns them on for the Site, in Settings › Developer tools › Approved route › Agent tokens, or with the dashboard route:

HTTP
# Dashboard session (owners and admins)
POST /api/admin/approved-route {"siteId":"site_…","agentTokens":true}

Issue a token from your backend, signed in as the person, when they connect an agent:

Shell
curl -sS -X POST https://app.trytelltale.dev/api/v1/agent-tokens \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY" -H 'Content-Type: application/json' \
  --data '{"accountId":"acct_42","userId":"user_7","tools":["list_reports","export_report"],"ttlSeconds":900}'
# {"token":"tt_agent_…","tokenId":"atok_…","accountId":"acct_42","userId":"user_7","tools":["list_reports","export_report"],"expiresAt":1762200000000}

When the agent calls your API with the token, verify it before you do the work:

Shell
curl -sS -X POST https://app.trytelltale.dev/api/v1/agent-tokens/verify \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY" -H 'Content-Type: application/json' \
  --data '{"token":"tt_agent_…","tool":"list_reports","eventId":"req_000123"}'
# {"valid":true,"tokenId":"atok_…","accountId":"acct_42","userId":"user_7","tool":"list_reports","expiresAt":…,"callId":"routecall_…","replayed":false}

Revoke one token, or every token of an account when the person disconnects the agent or leaves:

Shell
curl -sS -X POST https://app.trytelltale.dev/api/v1/agent-tokens/revoke \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY" -H 'Content-Type: application/json' \
  --data '{"accountId":"acct_42"}'
# {"revoked":2}

Turning agent tokens off for the Site refuses live tokens at once (reason: disabled). Issuing while they are off answers 409 agent_tokens_disabled with a message saying so.

What counts and what does not

See Agent monetization for offering an agent seat and metering completed work with the usage API.