Connect Integrations to Your Super Agent

Before You Start

Use this guide when your Super Agent or one of its agents needs to work in Gmail, Slack, Linear, Stripe, Notion, or another connected app. Integrations are scoped to the active organization or workspace, so first confirm you are in the workspace that owns the agent.

You need permission to connect apps for that workspace and permission inside the provider account you are authorizing. For team workflows, use a shared or admin-approved provider account when your security policy requires it.

Have required provider approvals, API keys, workspace ids, project ids, or OAuth access ready before you start. Connect the smallest useful set of apps first, then test before adding more tools.

Connect an Organization Integration

Open Integrations from the workspace that owns your Super Agent. Search for the service, select it, and choose Connect.

For OAuth providers, Agentic Workers sends you to the provider to approve access. For key-based providers, paste the required key or token from the provider account. Use the narrowest permissions that still support the workflow.

When the provider returns you to Agentic Workers, confirm the integration appears as connected in the same organization or workspace. Do not continue if the active workspace changed during authorization.

Check Status Before You Use It

Open the integration detail or Integrations list to check status. A connected status means the organization has an authorized provider account that agents can use after the relevant tools are enabled.

If status is pending, finish the provider authorization or refresh the page after the callback completes. If status is disconnected, reconnect before asking the agent to use the app.

If status is stale, expired, failed, or needs attention, reconnect the integration from the same organization. OAuth providers can expire or lose scopes when a provider admin changes policy, an account password changes, or access is revoked at the provider.

Enable Composio Tools Per Agent

After the organization connection exists, open the agent that should use the app and enable the Composio integration tools for that agent. Organization connection and per-agent tool enablement are separate steps.

Keep each agent focused. Enable only the app actions the role needs, such as reading Gmail and creating drafts for a support agent, or searching Linear and creating issues for an engineering triage agent.

Add instructions that explain when the agent should use each app, what source of truth to prefer, and which actions require human approval. Require approval before sending external messages, changing customer records, issuing refunds, or posting publicly unless your workflow explicitly allows autonomous execution.

Verify With a Small Prompt

Run a low-risk read-only check from the Super Agent or the specific agent. Ask for a narrow result, such as finding recent unread emails, listing open Linear issues in one project, or checking one customer record.

Then test write access safely. Ask the agent to create a draft, prepare the exact update, or describe the change it would make before you approve execution.

Review the latest trace, the step-by-step run log, after the test. Confirm the run used the expected organization, connected account, Composio toolkit, and action. If the wrong tool or account appears, stop and adjust the connection or agent tool settings before production use.

Disconnect or Reconnect

Disconnect an integration from the organization when the account should no longer be available to agents. This removes the workspace connection, so agents that relied on it will stop being able to call that provider until someone reconnects it.

Reconnect when credentials rotate, scopes change, a provider admin reauthorizes access, or status shows stale, expired, failed, or needs attention. Reconnect from the same workspace where the agent lives.

After disconnecting or reconnecting, rerun a small verification prompt and inspect the trace. This confirms both the organization status and per-agent Composio enablement are aligned again.

Troubleshooting States

Not connected means the organization does not have an authorized account for that provider. Connect it from Integrations before enabling or testing agent tools.

Connected but unavailable to the agent usually means the organization connection exists, but the Composio tools are not enabled for that agent. Open the agent tools area and enable the needed app actions.

Pending means the authorization has not completed. Finish the provider approval, return through the callback, and refresh status before running the agent.

Expired, stale, failed, or needs attention means the provider connection should be reauthorized. Reconnect from Integrations, then rerun a read-only prompt.

Permission or scope errors mean the connected provider account cannot access the requested resource or action. Reconnect with the required scope, use an account with access, or narrow the agent request to resources the connected account can see.

Wrong workspace or wrong account means the connection was made under a different organization or provider login than expected. Switch to the intended workspace, disconnect the incorrect connection if needed, and connect again with the correct account.

Related Guides

Read "Connect Apps and Tools to Your Agents" for the broader workflow of attaching tools, writing instructions, and testing approvals.

Read "Create Your First Agent With Your Super Agent" when you need a dedicated role before enabling tools.

Read "Read an Agent Trace" when a connected app fails, uses the wrong action, or returns unexpected data.