Let your agent use a user's connections

A connection is a third-party account, such as GitHub, that a person has linked to Astropods. When you declare a connection in astropods.yml, each user who chats with your agent decides whether to let it use their account. The agent then acts as that user, for example by opening a pull request in their name, instead of sharing one static token across everyone.

By the end of this guide, your agent asks for a GitHub connection, the user allows it, and the agent calls GitHub as that user.

Before you start

• An agent project you can run with ast project start. Your first project sets one up.
• You are signed in with ast login.
• Users link the provider on their personal account first, under Settings > Connectors. The consent card in chat also offers a Connect button.

Supported providers

Pushing a spec with any other provider value fails validation.

How it works

1. Your spec lists the connections the agent needs.
2. Before the first message of a new chat, the user sees a consent card. It shows each provider, your reason, and the scopes.
3. The user allows it for a duration they pick: until they revoke it, 24 hours, 7 days, or 30 days.
4. During a turn, your agent requests an access token for that user and calls the provider with it.

Astropods never stores the provider token. The agent gets a token only for a user who allowed it and is chatting now.

Declare connections

Add a connections list to astropods.yml:

connections:
  - provider: github
    scopes: [repo, read:org]
    required: true
    reason: Open pull requests in your repositories
  - provider: postman
    required: false
    reason: Link collections to the pull requests it opens

Run ast spec validate to check the file before you push. Connections are separate from integrations, which are labels for the Agent Card.

Use a connection in your agent

Create a ConnectionClient once, then call getToken with the provider and the ID of the user in the current turn. Your adapter passes that ID as userId in the stream options.

import { ConnectionClient, ConnectionError } from "@astropods/adapter-core/connections";
const connections = new ConnectionClient();
async function openPullRequest(userId: string) {
  try {
    const { accessToken } = await connections.getToken("github", userId);
    return await fetch("https://api.github.com/user", {
      headers: { authorization: `Bearer ${accessToken}` },
    });
  } catch (err) {
    if (err instanceof ConnectionError) {
      return `I can't use your GitHub account yet (${err.code}).`;
    }
    throw err;
  }
}

The client reads its credentials from the environment Astropods sets for your agent. It reuses a token until about a minute before the token expires.

Handle refusals

A refused request carries a code:

Test locally

Run the agent with ast dev. When the spec declares connections, the CLI opens a dev session and the agent calls the provider as you, from your own personal account. Local runs skip the consent card. Connect the provider under Settings > Connectors first.

Manage access

Users review what they have allowed in Settings > Connectors > Agent access. Revoke access takes effect on the agent’s next token request. Disconnecting a provider on a personal account revokes every agent’s access to it.

As the agent’s owner, you see how many people allowed each connection under Configure > Access. You never see who.

What users see

When a user opens a new chat with an agent that declares connections they haven’t allowed, a consent card appears above the message box. Here <agent> stands for your agent’s name.

While the card is open, the message box is disabled and reads “Allow access to chat with <agent>”.

If a required connection is still not allowed after Not now, the card is replaced by a notice: “<agent> needs access to your accounts before you can chat”. Its Review access button reopens the card. If only optional connections are left, Not now enables the message box.

What to expect

• The connection always comes from the user’s personal account, even when the agent belongs to a team account. A connection made on a team account does not count.
• Token requests succeed only in Astropods web chat. Agents that serve their own UI and Slack chats get not_active.
• When a new version adds a scope the user has not seen, the consent card appears again.
• Background work with no open chat can’t fetch a token.

Next steps

• Managing secrets: store a shared, account-wide credential instead
• Known integrations: label what your agent talks to