Connect apps and data
An agent reaches the outside world through what you give it: app accounts, databases, documents, your own tools and secrets. Each is set up once for the workspace, then given to the agents that need it.
Apps
In the rail, open Connections, the page called Connected accounts. Press Connect an account, search for the app and press Connect. The app's own sign-in opens in a window; when you finish, the window closes and the account appears. A few apps ask for an API key instead of a sign-in. The list in that dialog is what you can connect today.
Connecting an account gives it to no agent yet. In the agent's Build screen, open the Connections tab, press Add a connection, choose the app, choose whose account (below), and pick the account. It goes into the draft, and the agent uses it after you publish.
An agent given an app can use everything that sign-in allows, including sending, changing and deleting, not only reading. Connect the account whose access you are comfortable giving the agent, and say in its instructions what it may and may not do.
| You see | What it means, and what to do |
|---|---|
| Needs sign-in | The app stopped accepting the sign-in. Press Reconnect. Signing in again as the same account fixes it for every agent that uses it, with nothing to publish. |
| Sign-in not completed | The sign-in window was closed early. Press Finish connecting. |
| "That sign-in was a different account" | You signed in as someone else. That was saved as a new account and the old one is unchanged. You choose whether the agents move to it; moving goes into each agent's draft. |
| Disconnect | Revokes the sign-in at the app. Agents that used it cannot use that app until someone picks another account. |
You can connect several accounts of one app and give each a nickname, such as "Support inbox". An agent uses only the account its setup names, never another. Anyone in the workspace can connect, reconnect or disconnect an account, and Check it works, in a row's menu, tests a sign-in.
Whose account the agent uses
When you add a connection, the dialog asks Whose account should the agent use?
| Agent creator's account | End user's account | |
|---|---|---|
| Who signs in | You, once | Each person talking to the agent, the first time |
| Good for | The company CRM, a shared inbox, the team's Slack | Each salesperson's own calendar or mailbox |
| Every conversation uses | That one account, including website visitors when website chat is open | The account of the person in that conversation |
| Website chat | Works | Not offered: website visitors have no sign-in |
When an agent needs someone's own account, their chat shows a card asking them to connect it, with a Connect button for that app. After they sign in, the conversation carries on by itself, and that next turn is charged as usual. Each person's own sign-ins are listed under Your own accounts in Connected accounts. Only they can use them, and only in their own conversations.
Databases
In the rail, open Data and press Connect a database. Choose PostgreSQL or MySQL, paste a connection string or fill in the fields, give it a name (the agent calls the database by it, and it cannot change later), and press Test connection before Connect database. Then add it to an agent in the Connections tab with Add a database, and publish.
- Read-only is the default. Choose Read & write only if the agent has to change rows, and use a login that can only read otherwise.
- Each query runs for up to 30 seconds and returns up to 1,000 rows.
- The login is saved encrypted. The agent sees table and column names, never the password.
- The database must be reachable from the internet. Private addresses, such as 10.x or 192.168.x, are refused, and databases behind a firewall that admits only known addresses are not supported yet.
Knowledge
A knowledge base is a folder of documents that any number of agents can read. Create one in Data with Create a knowledge base, then add it to an agent in its Knowledge tab and publish.
| A knowledge base takes | Limits and timing |
|---|---|
| Up to 25 MB. Shows "being prepared" for about a minute while it is turned into text. | |
| Word (.docx) | Up to 5 MB. Ready at once. Old .doc files cannot be read: save them as .docx. |
| Text, Markdown, CSV, JSON, HTML | Ready at once. A text file over 4 MB cannot be read in one go: split it. |
| The whole folder | Up to 200 files and 50 MB. |
Spreadsheets, slides, images, audio and video cannot be read yet. Adding a file with the same name replaces the old one, and changes to the files reach every agent on its next message, without Publish.
The agent reads a knowledge base the way a person would: it opens the folder, searches file names and text, and
reads whole documents. So name files clearly: refund-policy.pdf is found, doc7.pdf is not.
Each knowledge base also adds a librarian to Agents, which keeps its documents ready; its work is
charged like any agent's turns.
Files only this agent has, in the Knowledge tab, are for a single agent, up to 25 MB each: Word, text, Markdown, CSV, JSON or HTML. PDFs go in a knowledge base, which turns them into text the agent can read.
Your own tools
If your company runs its own tools, add them in the agent's Connections tab:
- MCP servers: the server URL, a name, HTTP or SSE, and how to sign in to it. The agent loads the server's tools when it runs; if the server cannot be reached, the agent has none of its tools for that turn.
- HTTP endpoints: a name, the method, the URL (use
{{params.NAME}}for values the agent fills in), and a description that tells the agent when to use it. Import adds many at once from an OpenAPI document, a Postman collection or a curl command.
Save the API token under Secrets, then type {{secrets.NAME}} as the bearer
token or header value. The token is filled in on our servers when the tool runs, and stays out of the agent's
setup.
A tool that uses a secret must have its full address, like https://api.example.com/orders: the
host cannot come from {{params.NAME}} or another secret. The first time you save it, the secret is
pinned to the hosts it is sent to, and from then on it goes only there. To use it with another host, add a
separate secret. More in Where a key may be sent.
Secrets
In the agent's Secrets tab, press Add secret, then give a name in UPPER_SNAKE_CASE (up to 64 characters), the value (at least 8 characters), and an optional description. A secret is saved at once, with no Publish. Rotate replaces its value and Remove deletes it.
Nobody can read a value back, you included, and the agent never sees it either: the value is filled into tool calls on our servers, and the agent is told never to ask anyone to type a secret into the chat.
A secret the agent needs is either Shared, one key for everybody, or Per session, supplied by whoever starts a session. Like an end user's account, a per-session secret keeps the agent off website chat.
- A per-session secret comes only from that session. It is never filled from a shared secret with the same name.
- A key you type into a chat's Secrets tab, or when you start a session, lasts one day. After that the chat lists it as missing again, and you type it again.
- Rotating or removing a secret reaches running sessions on their next tool call.
Developers who pass each person's own token from their app: see Credentials for your users.