Guides›Composio Overview

Composio Overview

Composio in Rooaak lets agents run external tools (Gmail, Slack, Calendar, Drive, etc.) with explicit account ownership and execution identity.

Core Concepts

Providers and toolkits

  • A provider is an integration namespace like gmail, slack, or google_calendar.
  • A toolkit is the enabled provider surface for an agent.
  • Each provider can expose many actions/tools (for example gmail.send_email).

Linked accounts

  • A linked account is stored per agent + provider + principal.
  • Link state is tracked in project_agent_provider_accounts.
  • Common states:
    • pending: link started but callback not completed.
    • active: ready for tool execution.
    • revoked / expired / error: reconnect required.

Principals

Rooaak supports two execution principals:

  • service: one shared business/service account per agent/provider.
  • end_user: a per-user account, identified by endUserId.

endUserId format must match:

^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$

Execution Model

  1. Project stores one Composio key (provider_keys.provider = composio).
  2. Project enables providers (Rooaak provisions/maintains Composio authConfigId).
  3. Agent inherits/overrides provider toolkits and tools.
  4. Accounts are linked for service and/or end_user principals.
  5. Each message executes tools as:
    • explicit executionPrincipal from request, or
    • agent default principal (service or end_user).
  6. Runtime resolves the linked account for that principal, executes the Composio action, and reports success/failure in runtime_composio_execution_reports.

Internal Runtime Contract (for context)

  • SSE payload to runtime may include executionPrincipal.
  • Runtime resolves linked accounts via:
    • POST /api/runtime/composio/resolve-linked-account
  • Runtime writes tool execution outcomes via:
    • POST /api/runtime/composio/execution-reports

Related Guides