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

# Other AI agents

> Let an AI agent working in your visitor's browser use the guide as a governed tool — ask, show the way, or ask for an action the visitor approves — through WebMCP or window.Puntego.assist.

Your visitors increasingly bring their own AI: a browser agent, an assistant
built into the browser, or your own in-app agent. **Other AI agents** lets that
agent use the guide on your site as a tool, with the same answers, the same
on-page guidance and the same governed actions your visitors get, and the same
limits.

> **Off until you turn it on.** Nothing is offered to agents until an owner or
> admin turns on **Settings → Guide behavior → Other AI agents**. Answering and
> showing then start on; **asking for actions stays off** until you turn it on
> separately (it asks for your second factor). Turning **Other AI agents** off
> keeps each tool's switch as you left it, so turning it back on while asking
> for actions is still on asks for your second factor too.

> **Release preview:** agent tools are implemented and tested in the repository
> and reach the hosted script with its next release. Feature-detect with
> `typeof window.Puntego?.assist === 'object'`.

<h2 id="tools">
  The three tools
</h2>

| Tool | What the agent gets | What happens on the page | Risk |
| - | - | - | - |
| `ask` | The answer in words, with its sources and follow-up questions | Nothing opens unless the caller asks for it | Read |
| `show_me` | What the person now sees (a pointer, or a tour and its steps) | The guide points at the control or runs a **visual** tour. Nothing is typed, and no control of a form is pressed: a tab or dialog that would need one is pointed at instead | Visual |
| `do_action` | The **receipt** the page or your site verified, or what happened instead | The guide prepares one action you allow; **the visitor approves it on the guide's confirmation card** | Write |

Each tool takes one string argument, described with a JSON Schema:

```json theme={null}
{ "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": ["question"], "additionalProperties": false }
```

`ask` takes `question`, `show_me` takes `goal` and `do_action` takes
`request`. Each tool also carries MCP hints (`readOnlyHint` is true for `ask`
and `show_me`, false for `do_action`).

<h2 id="governance">
  How a write stays governed
</h2>

An agent can ask for an action. It can never approve one.

* **Only `do_action` can lead to a write.** On `ask` and `show_me` turns the
  guide withholds every write declaration and every write action template, and
  `ask` never takes the person to another page.
* **The visitor approves every write, on the page.** The guide's existing
  confirmation card opens with the line *"An AI agent asked for this. Nothing
  changes unless you approve it here."* — even for writes a visitor's own
  request would run without asking.
* **Payments, signatures and deletions are always refused for an agent.** On
  every plan, a write that pays, signs or deletes (your target's class, or the
  automatic detection on the live page) is never prepared for an agent's
  request. The guide points the visitor at the control instead ("Show me") so
  they can do it themselves, and `do_action` returns `not_done` with
  `error.code: "high_risk_refused"`. The same applies to a Verified Action whose
  own words say it pays, signs or deletes.
* **Only a real press counts.** The card lives in the guide's closed shadow
  root and accepts only a press the browser marks as the person's own. Page
  script, `runTurnAction`, `respondToProposal`, `retryTurn` and synthetic
  events never approve or re-send an agent's request. An agent that drives the
  browser's own mouse and keyboard (browser automation, computer use) already
  acts with the person's full input on every page, and no page can tell its
  press from theirs: this guarantee is about agents that use the guide's tools,
  not about software that controls the browser.
* **The same rules as for visitors.** Your targets and actions, your plan's
  limits, elevated actions only from Growth, and every refusal rule apply
  unchanged. In test mode writes become "Show me", as for visitors, except
  on a domain you verified.
* **Honest results.** `do_action` returns the receipt the page or your site
  verified (`receipt.verified`), "sent, not confirmed here" when the page could
  not confirm it, or what happened instead: `declined`, `shown_instead`,
  `not_done` (with `high_risk_refused` for a payment, signature or deletion),
  `failed` or `awaiting_person`. A receipt is delivered once, to the
  call that caused it.
* **Requests your team approves.** When an action needs your team's approval
  (Guides → Actions → "Require workspace approval", or an action that always
  asks you), an agent's request never reaches your team on its own: the guide
  shows the person **Send request to the team**, and only their own press sends
  it to your approvals inbox (and to Slack and email). Until then nothing is
  stored in your inbox and `do_action` reads `awaiting_person`; if they cancel,
  `declined`. A tool call alone cannot fill your inbox; the Worker also caps
  how many such requests one visitor and one workspace can send. Once sent, the
  guide tells the person it went to your team. `do_action` keeps waiting in case you approve within the
  wait (then `done`); otherwise it returns `awaiting_person` with a `summary`
  that says your team decides, or `not_done` with `error.code:
  "owner_declined"` when your team does not approve it or it expires.
* **The agent's words are data.** They reach the guide as the visitor's
  question, marked as coming from an agent: they cannot change the guide's
  rules, grant a permission or confirm anything.

<h2 id="webmcp">
  WebMCP
</h2>

Where the browser exposes [WebMCP](https://github.com/webmachinelearning/webmcp)
(`document.modelContext`, or `navigator.modelContext` in earlier drafts of the
API), the guide registers the tools you switched on with `registerTool`, with
their schemas and hints, once:

* the visitor's consent allows the assistant where your consent settings ask
  for it, and
* the page is not in privacy-only mode or on a route the guide is excluded from.

They are unregistered on `destroy()`, opt-out, an identity change and when
consent is withdrawn (through the registration's `AbortSignal`, or
`unregisterTool` where the browser still has it). The guide never polyfills WebMCP, never uses
`provideContext` (it would replace your page's own tools), and leaves a tool
name your page already registered alone. While a `do_action` call waits for the
visitor, the guide asks the agent's browser to hand the page to the person
(`requestUserInteraction`).

<h2 id="assist">
  From your own code: `window.Puntego.assist`
</h2>

The same tools, for an in-page assistant or an agent framework:

```ts theme={null}
// The tools this page may use right now: [] while off or before consent.
const tools = window.Puntego?.assist.tools() ?? [];

// Ask in words and get the typed turn (answer, blocks, sources, follow-ups, proposal).
const { status, turn } = await window.Puntego.assist.query({
  question: 'Which plan includes SSO?',
  open: false, // true also opens the guide so the person sees the answer
});

// Dispatch a framework's tool call.
const result = await window.Puntego.assist.handleToolCall(
  { name: 'do_action', arguments: { request: 'Turn on weekly digests' } },
  { waitMs: 120_000 }, // how long to wait for the person (5 s – 10 min)
);
if (result.status === 'done') console.log(result.receipt); // { verified, text, action, id }
```

Neither method throws. `handleToolCall` resolves a `PuntegoAgentToolResult`:
`status`, a one-sentence `summary` for the agent, the `answer`, `sources`,
`followUps`, what was `shown`, the `receipt`, and an `error` with a code when
the call could not run (`unavailable`, `busy`, `rate_limited`, `error`). The
headless client exposes the same `assist` object, where only `ask` is
available: showing and doing need the guide's own card.

<h2 id="limits">
  Usage, limits and the audit log
</h2>

* **Metered like visitor questions.** Every agent call is a turn against your
  plan's answers; a write counts against the plan's actions, like a visitor's.
* **Per visitor session:** at most 10 agent calls a minute and 120 an hour
  (`429` with `Retry-After` beyond that).
* **Audit log:** every call appears in **Audit log** as *Other AI agent*: the
  tool, whether it was accepted or refused and why. The row holds no question,
  answer, visitor or conversation; an action the visitor approved has its own
  row with the verified result.
* **Who turned it on:** turning **Other AI agents** (or any of its tools) on
  or off is listed under **Audit log → Workspace settings**, with who did it
  and when, like every other switch in Settings.

## Next steps

* [Guide tools SDK](/guide-tools-sdk) for driving the guide from your own code.
* [Verified Actions](/verified-actions) for actions that run on your systems.
* [SDK reference](/sdk-reference#agent-tools) for the full `assist` surface.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.