Connections and secrets

Declare what the agent needs

An agent says what it cannot work without, and says who supplies it. Declaring is part of the configuration; supplying is not.

await ws.agents.create({
  name: 'Outreach assistant',
  instructions: '...',
  connections: [{ provider: 'gmail',      scope: 'conversation', required: true }],
  secrets:     [{ name: 'APOLLO_API_KEY', scope: 'fixed',   required: true }],
});

The two do not substitute for each other. Connecting an account on the agent does not satisfy a declaration that said conversation, and a conversation cannot supply a fixed one on its own.

Connecting an account

A connection is an account somebody signs in to, so it takes a round trip through their browser. You never see a token.

One account for everyone

const { url } = await agent.authorize('gmail');
// send them to `url`; the account attaches when they finish

await agent.connections();
// [{ provider: 'gmail', declared: true, connected: true, accountLabel: 'ops@…' }]

Each of your users connects their own

Three steps: ask for a link, put the person in front of it, wait for them to finish. The waiting is the part worth getting right, because it is the only one this SDK cannot do for you silently.

const conversation = await agent.start();

// 1. a link for THIS person, bound to THIS conversation
const { url } = await conversation.authorize('gmail');

// 2. show it however suits your app: a popup, a redirect, even a QR code.
//    This SDK runs on your server, so the browser half is yours.
showToUser(url);

// 3. wait for them to finish. Resolves once nothing required is outstanding.
await conversation.waitUntilReady();

// now it is safe to start work
await conversation.ask('Summarise my unread mail.');

Their account belongs to their conversation. A second person starting their own conversation with the same agent connects their own Gmail, and neither can see the other's.

If you would rather not wait

waitUntilReady() is a convenience over two fields you can read yourself. Use them directly when the waiting belongs somewhere else, such as a webhook or a page the person returns to.

const { ready, requires } = await conversation.get();
// ready    -> true when nothing REQUIRED is outstanding
// requires -> [{ kind: 'connection', name: 'gmail', required: true }]

Supplying a secret

A secret is a value you already hold, so there is no round trip and no browser. You write it and it is gone: nothing reads it back.

await agent.attach({ secrets: { APOLLO_API_KEY: '...' } });        // every conversation
await conversation.attach({ secrets: { APOLLO_API_KEY: theirKey } }); // this thread only

Both merge, so supplying one key leaves the others in place.

Storing a secret you can rotate later

The two calls above supply a value for one agent or one conversation. To keep a secret in the workspace, so it survives and can be replaced, store it:

const key = await ws.secrets.create({ name: 'APOLLO_API_KEY', value, agentId });
await ws.secrets.list(agentId);        // what exists, never the values

Rotating one

This is what you do when a key leaks, and it lives on the secret itself rather than on the collection:

await ws.secret(id).update('rotated-value');   // by id
await ws.secret(id).delete();

// or from a listing, because list() returns objects rather than records:
const mine = await ws.secrets.list(agentId);
const existing = mine.find((s) => s.name === 'APOLLO_API_KEY');
if (existing) await existing.update(value);
else await ws.secrets.create({ name: 'APOLLO_API_KEY', value, agentId });

Building for many end users

If your application serves its own users, each of them has their own accounts. Ananya has her Gmail, and so do the other ten thousand. An end user connects once, and the account stays theirs across every conversation, so you never send them through a sign-in again per thread.

const ananya = ws.endUser(row.userId);            // no request

const gmail = await ananya.connections.create({ provider: 'gmail' });
showToUser(gmail.url);                            // they sign in, once
await gmail.waitUntilConnected();

const conversation = await agent.start({ endUserId: ananya.id, attach: gmail });
await conversation.ask('what did I miss this morning?');

Owning an account grants nothing

Naming someone on a conversation is a label. It lets you list their conversations back to them and revoke them when they leave. It does not hand the agent their accounts.

The grant is a separate line, and you can read it:

await agent.attach(gmail);           // every conversation with this agent
await conversation.attach(gmail);    // this one thread only

// or at the moment you start, which is usually what you want:
await agent.start({ endUserId: ananya.id, attach: gmail });

Attaching at start closes a gap

Between start() and a later conversation.attach(), the conversation exists and can be asked something, and it would answer without the account. Passing attach to start means the first turn already has it.

When somebody leaves

await ananya.connections.list();     // what she has connected, for showing her
await ananya.conversations();        // everything she has said, across every agent
await ananya.revokeConnections();    // cut her off, in one call

Every conversation of hers stops acting as her from the next turn, and nothing is retained.

const ananya = ws.endUser(row.userId);
const key = await ananya.secrets.create({ name: 'ZENDESK_TOKEN', value: token });

const conversation = await agent.start({ endUserId: ananya.id });
await conversation.attach(key);

Which connections you can declare

130 providers connect today. Use the provider id exactly as written.

Available now (38)

Your user approves the account through a hosted sign-in page. You never register an OAuth application, and neither we nor you ever see their password.

Also available (92)

These come from our integration partner's managed catalog and connect the same way, with the same hosted sign-in. They are not in the list above only because we have not written our own description for each one.

Anything else

The provider id is not checked against this list when you create an agent. A provider outside it is accepted, and whether it can then connect depends on our integration partner offering a hosted sign-in for it. So a typo in a provider id will not be reported when you create the agent: it surfaces later, when someone tries to connect. Check the id against this table.

The two tables above are generated from the provider catalog the API reads, so they cannot drift from it. A test fails if they do.

What a conversation still needs

conversation.ready;      // true when nothing REQUIRED is outstanding
conversation.requires;   // [{ kind: 'connection', name: 'gmail', required: true }]

ready is the answer most callers want. requires is the detail behind it, and the two are not the same question: a conversation can be ready and still list a requirement, because one declared required: false is something the agent works without.