Integrations

An integration wraps an external service (Slack, Gmail, GitHub, Stripe, Linear, BigQuery, and others) into a uniform shape that agents can call. Every provider contributes a set of typed actions to the platform-wide tool registry.

The provider shape

Each provider lives under apps/admin/src/lib/agent-core/integrations/providers/{name}/ and exports a definition built with createIntegration():

createIntegration({
  name: "slack",
  displayName: "Slack",
  description: "Post messages and react to events in Slack.",
  auth: slackAuth,        // AuthDefinition
  ui: slackUI,            // helpUrl, setupSteps shown in the Integrations page
  actions: [slackPostMessage, slackListChannels, ...],
});

The full provider list is collected in providers/index.ts and exposed as ALL_PROVIDERS. Both the UI catalog and the tool registry derive from that single array — there is no manual registration step beyond adding the import and pushing into ALL_PROVIDERS.

Auth types

Action naming

Actions follow {prefix}_{service}_{verb}_{noun}:

slack_post_message
gw_gmail_list_messages
gw_gsc_search_analytics
github_create_pull_request

When a flow node references an action, set integrationAction to the full action name. The executor resolves tools by action name directly — do not strip or add the provider prefix.

Risk levels

Every action is tagged with one of:

• safe — read-only.
• moderate — writes user-visible state.
• destructive — deletes or irreversibly modifies state.

The UI surfaces these to operators, and agents can be configured to require approval for anything above a threshold.

Adding a new provider

The full checklist lives in .claude/rules/integrations.md. The short version:

1. Create providers/{name}/ with index.ts, auth.ts, client.ts, types.ts, actions/.
2. Import the provider in providers/index.ts and add it to ALL_PROVIDERS.
3. Add an icon entry in components/agents/integration-icons.tsx — one key, both kebab and snake variants are auto-generated.
4. (Optional) Seed agents that use the provider under packages/cli/src/seeds/data/agents/.

The UI catalog auto-derives from ALL_PROVIDERS; no extra wiring needed.