Skip to main content

Give agents website access

A customer asks your support agent "where is my order?". The answer isn't in any document. It's in your order admin, behind a login. The same goes for stock levels, ticket queues, partner dashboards: the freshest answers live in systems, not files.

Agents can go get those answers. You allow specific sites, store a login where the site needs one, and the agent browses like a teammate would, without the password ever appearing in a prompt or a spec.

Start from an employee​

Open the employee's preparation workspace and click Website access above the conversation. The assistant can help set up an allowed website and direct you to its credential controls. Store a password in those controls, not in the preparation prompt.

Website access belongs to the underlying application, so use the employee ID as APP_ID below. For a provider that exposes tools through MCP, use MCP connections instead. MCP Servers explains those connections. A website login and an MCP provider connection are separate resources.

The remaining steps use the CLI and also apply to ordinary applications. Set the application ID once:

export APP_ID=your_application_id    # docana applications list

1. Allow a site​

Allowed websites belong to your company and are linked per application. Add one from the terminal. The output includes the site id you'll use next:

docana app "$APP_ID" allowed-websites create \
  -n "Partner Portal" \
  --url https://portal.example.com \
  --engine advanced \
  --shared

Every run of the application uses the site, including the people your agents answer on WhatsApp or in the widget. --shared also lists it for every member and lets every run use its stored login. Without it the site is private: only you see and edit it, and only your own conversations and runs use its login.

Pick the engine by what the site needs:

  • basic: a read-only fetch of the page. Fast and cheap, right for public pages.
  • advanced: a real headless browser. Needed for logins, JavaScript-heavy apps, and anything interactive.

docana app "$APP_ID" allowed-websites ls shows what's already allowed, including whether a login is stored:

ID        Name             URL                          Engine     Visibility   Enabled   Stored creds
site_a1   Partner Portal   https://portal.example.com   ADVANCED   shared       yes       [email protected] (pw ✓)

2. Store a login​

For sites behind authentication, attach credentials to the allowed website. Pipe the password from your secret manager so it never lands in your shell history:

op read "op://Team/Partner Portal/password" | \
  docana app "$APP_ID" allowed-websites set-credentials <site-id> \
  --username [email protected] \
  --password-stdin

The password is encrypted before storage. Agents log in with it during a browsing session. You never paste it into a spec or a prompt.

Use a dedicated account for agents where you can: it keeps their access auditable and lets you revoke it without touching anyone's personal login.

3. Sessions persist between runs​

Logging in on every run would be slow, so browsing sessions reuse a persistent browser context per application: cookies and login state carry over.

If a login goes stale or you rotated the password, reset the context and the next run logs in fresh:

docana browser-context reset --app-id "$APP_ID"

Add sites from a conversation​

Allowing every site up front gets in the way when you're exploring. With Websites from conversations, the assistant adds a site the moment you need it: ask it to check booking.com, and it adds the site and reads it.

A super admin turns the feature on for a company or one application. Each application then picks how its assistant uses it, under Websites from conversations on its Allowed websites settings page:

  • Off: the assistant opens only the sites on the list.
  • Ask first: before it adds a site, the assistant shows a card in the web chat, and one tap adds it.
  • Automatic: a site you name in your messages is added without asking. Any other site, such as one a web search found or a page mentioned, still asks first in the web chat.

New applications start on Automatic where the company has the feature. Applications that existed before stay Off until an admin picks a mode.

Only an application's admins add sites this way. Each site they add is private to them. It's marked Added in a conversation in the list, with a link back to that conversation. To share one with everyone, edit it on the Allowed websites page: it becomes a regular, shared entry. The assistant reads the site with the basic engine first. It moves the site to the advanced engine when the page needs clicking, typing or signing in, or when the basic read fails. A site already on the list keeps the engine its admin chose, and the assistant never adds a site twice. Adding the same site from the settings page turns the conversation's entry into a regular one.

When a site asks you to sign in, the assistant opens a login form in the chat. The password goes into that form, never into a message: the assistant doesn't ask for a password, a PIN or a code in the conversation. The login is saved on your private site only, so it never signs in other members' conversations. Agents type it only on that site's own pages, or on Microsoft's or Google's sign-in page, never on another site. A link or a redirect can take the browser anywhere, so they check the page right before typing and hold it there while they type: if it tries to go elsewhere, typing stops and nothing is submitted.

The card and the login form only show in the web chat. On WhatsApp, Slack and the other channels, an application on Automatic adds only the sites you name, and one on Ask first adds none.

Manage it over the API​

Everything above is also plain HTTP, for provisioning from your own systems: POST /api/v1/applications/{id}/allowed-websites/ creates and links a site (a plain-text password in the body is encrypted before storage), and PATCH .../allowed-websites/{siteId}/ toggles the per-application link. See the API Reference for the full schemas.

Next steps​

  • Employees: prepare and test the employee using this site

  • CLI: The app commands used here, and everything else

  • Creating an Agent: Build the agent that will do the browsing

  • API Reference: The allowed-websites endpoints in full