Connect an agent to your apps
Let an agent act in your connected apps like Gmail, Slack, or GitHub.
Intermediate · ~10 min · Prerequisites: a connected app
Building and editing agents is admin-only. Members can run and observe agents, but only admins can create or change them.
What you'll do
Wire a connected app's actions into your agent so it can do real work in tools your team already uses — reading emails, posting to Slack, opening GitHub issues, and more.
Connect the app first
Before an agent can act in an external app, the app must be connected at the org level. Go to Connecting apps to see which apps your org has already linked, and to add one if needed. The connection is a one-time org-level step that any admin can do — the agent itself doesn't manage credentials.
If the app you need isn't connected yet, connect it first and come back to this guide. The agent can only use actions from apps your org has an active connection for.
Add the app's tools to the agent
Once the app is connected, its Composio actions appear in the agent's tool picker. To add them:
- Open
/admin/agents/<slug>/editand click Tools. - Click + Add tool and filter by the app name (e.g., "Gmail", "Slack", "GitHub").
- Select the specific actions the agent should be able to take — for example, Gmail: Read emails, Gmail: Send email, or Slack: Post message.
- Each action appears in the active tool list. The agent can now call these during a conversation.
For a deeper look at how Composio actions work on agents, see Integrations.
Scope the actions
Only add the actions the agent's role requires. An agent that summarizes support emails needs read access to Gmail — not send or delete. An agent that creates GitHub issues doesn't need to close or merge pull requests.
Over-permissioning makes agents harder to trust and harder to audit. If the role changes, you can always add more actions and publish a new version.
Members will see which apps an agent is connected to on its hub card. A clear, scoped set of actions also helps members understand what the agent will and won't do before they start a conversation.
Test an action
Open the test panel and send a prompt that should trigger one of the app's actions. For example: "Find my last three support emails from Acme and summarize them." Watch the test trace to confirm the right action fires with the right parameters.
If the action fails — wrong credentials, wrong scope, or the app connection dropped — the trace will show the error. Fix the connection at the org level first, then re-test. Once the actions behave correctly, proceed to Add MCP & external tools if you need to extend further, or go straight to testing and publishing.