SyntrumDocs
Open app

Connecting tools

Integrations are how your agents sense and act on the outside world. Connecting Gmail lets an agent read and send email; connecting Salesforce lets it read and update CRM records. Without tools, an agent can think but not do.

Open Company Systems Access from the sidebar (Integrations). The subtitle says it plainly: Grant AI employees access to company infrastructure.

Syntrum supports hundreds of tools out of the box. When you connect one, Syntrum brokers the OAuth connection to the provider and reads back the real granted scopes — so what an agent may do is bounded by the actual permissions the provider gives, not just our UI copy.

Two ideas: connected vs. attached#

Keep these separate — they're the whole model:

  • Connected means an account exists in your workspace: you completed OAuth for, say, Gmail, and the workspace now holds a live connection to it.
  • Attached means a specific agent has been granted that connected account as a tool, at a chosen access level.

You connect once, then attach to as many agents as you like. A tool has to be connected before it can be attached.

The connect wizard#

Click Connect Apps (top right) to open the guided wizard. It has up to four steps, shown with a progress bar:

  1. Select — "Give your AI team access to a company system." Search the catalog and pick an app. The grid shows the top options with Show all to expand; already-connected apps carry a green Connected badge and sort to the front.
  2. Explain — a plain-language summary of what agents WILL be able to do with this app and what they will NOT do. This is the honest "here's the deal" screen before you authorize anything.
  3. OAuth — "Connect to [app]." Click Open [app] login and you're taken to the provider in a new tab to sign in and review permissions. OAuth pages can't be embedded, so the wizard stays open in the original tab. When you're done, come back and click I completed connection, sync now.
  4. Confirm — success. A reminder that the tool is Governed by your policies: "Risky actions follow the workspace safety rules and each agent's supervision mode — adjust anytime in the agent's Permissions tab."

Per-user OAuth. Each person authorizes their own account. The agent acts through the account you connected, with your granted scopes — it never gets a shared, all-powerful key. Connect Gmail and the agent works with your mailbox, within the permissions you approved.

Sync#

OAuth happens on the provider's site, so the workspace has to sync to learn the result. The wizard's "sync now" button does this after a connection; the header's Sync button does it any time. Syncing pulls the latest connected accounts, their status, and their real granted scopes. If you ever return from a provider and don't see your account, click Sync.

Connected accounts#

Once connected, each app appears as a card in the main grid. A card shows:

  • The app's logo, name, and the connected account label (or "Hidden by provider" when the provider redacts it).
  • Status badges — the connection status (e.g. ACTIVE / CONNECTED, INITIATED, or EXPIRED/ERROR), a sync status badge (IDLE, SYNCING, ERROR), and an ATTACHED badge when it's attached to the agent you're viewing.
  • Account meta — the last successful sync time, or a sync error if one occurred.
  • What it can do / What it cannot do — the capability summary.
  • Granted scope — expandable; the real OAuth scopes the provider returned for the account.

Managing a connection#

  • Disconnect (bottom of the card) removes the connected account from the workspace. Any agent that relied on it loses that tool.
  • Sync status tells you whether the agent is currently ingesting data from the system. An ERROR badge with a message means the connection needs attention — often a re-auth.

Attaching and detaching per agent#

To attach tools to a specific agent, open the wizard from that agent's Tools tab (via Connect more apps), or navigate to Integrations with the agent in context. In agent-attach mode a violet banner reminds you "You are attaching tools to this agent."

  • If the app is already connected, its card shows Attach — one click grants it to the agent at your chosen access level (no OAuth needed). If you pick an already-connected app in the wizard, it defaults to "attach existing" and skips straight to confirm.
  • If the app isn't connected yet, the wizard runs the full connect-then-attach flow, and attaches automatically when you return from OAuth.
  • To remove a tool from an agent, click Detach on its card (here or on the agent's Tools tab). Detaching revokes the tool from that agent only — the account stays connected for everyone else.

Access level at attach time#

When you attach, you choose how the agent may use the tool:

Access level Meaning
Observe Can only read — no actions
Assist Can draft — every send requires approval
Act Can execute automatically (still gated by the workspace floor and the agent's mode)

This access level is the foundation of the per-tool permission dial. Tune it any time from the agent's Tools or Permissions tab — see Tool permissions.

Connecting integrations and attaching or detaching tools requires an Admin or Owner role. If the catalog is empty, the workspace's integrations aren't configured yet — an admin needs to set them up. See Team & roles.

What's next#