Skip to main content

Integration Patterns

Integrations connect agents to external services -- Google Workspace, Slack, Jira, GitHub, and others. The platform's integration model is designed around a simple principle: credentials are configured once at the workspace level. However, agents only receive credentials for the integrations relevant to their configured tools -- not every credential in the workspace. This section explains how that works, why it was designed this way, and what happens under the hood when an agent uses an integration.

Workspace-Level Integrations​

Integrations are stored at the workspace level, not the project level. When you connect your Google Workspace account, that connection is available to every project in the workspace. This means:

  • One OAuth flow for the whole workspace
  • Agents across all projects can access the integration if their tools require it
  • No need to re-authenticate when creating a new project
note

Per-project credential overrides are planned for a future release. This will allow you to use different Google accounts for different projects within the same workspace, for example.

How Credentials Flow to Agents​

Integration credentials (OAuth tokens, API keys, service account JSON) are encrypted at rest using FieldEncryptionService and stored in the database. When an agent is deployed, the platform:

  1. Looks up the workspace's integrations
  2. Decrypts the credentials
  3. Injects them as environment variables in the Knative service manifest

The credentials never touch the agent's filesystem -- they exist only as environment variables in the running container. If the container is stopped, the credentials are gone. This reduces the attack surface compared to writing credentials to a file on the NFS mount.

warning

Because credentials are injected at deploy time, changing an integration's credentials requires redeploying the affected agents. The platform does not currently hot-reload credentials into running containers.

Available Integrations​

Each integration provides a specific set of agent tools. When an integration is configured, the corresponding tools become available to agents in that workspace.

Google Workspace​

Provides a set of tools for Google Workspace interaction:

ToolCapability
Create/read/update Google DocsFull document CRUD
Create/read/update Google SheetsSpreadsheet CRUD, cell-level operations
Create/read/update Google SlidesPresentation CRUD
List files in DriveDirectory browsing
Search DriveFull-text search across Drive files

Atlassian (Confluence + Jira)​

Provides multiple tools for Confluence and Jira interaction:

ToolCapability
Create/read/update Confluence pagesWiki and documentation management
Search ConfluenceFull-text search across spaces
Create/read/update Jira issuesIssue tracking and project management
Transition Jira issuesMove issues through workflow states
Add comments to issuesCollaboration on tickets
Search Jira (JQL)Advanced issue queries

Communication Platforms​

IntegrationWhat It Enables
SlackSend messages to channels, respond to mentions, thread conversations
TelegramBot messaging -- receive and respond to Telegram messages
Microsoft TeamsChannel messaging and notifications

Developer Tools​

IntegrationWhat It Enables
GitHubRepository access, create/review pull requests, manage issues
SendGridAgent email gateway (see Email System Design)

Infrastructure​

IntegrationWhat It Enables
TwilioSMS sending/receiving and voice call capabilities
AWSS3 storage access and other AWS services
Microsoft AzureAzure service access

Integration Architecture​

While credentials are stored at the workspace level, agents only receive credentials for integrations relevant to their configured tools. In this example, all four agents have Google Workspace tools configured, so they all receive those credentials. Only the Customer Support agents have Slack and Jira tools configured, so only they receive those credentials.

How Agent Tools Discover Integrations​

The tool discovery process works as follows:

  1. At deploy time, the platform checks which integrations the workspace has configured
  2. For each configured integration, the corresponding environment variables are set in the Knative manifest
  3. At agent runtime, tool modules check for the presence of their required environment variables
  4. If the variables exist, the tools register themselves as available
  5. If the variables are missing, the tools silently skip registration

This means an agent will only advertise tools it can actually use. If the workspace has not configured Google Workspace, Google-related tools will not appear in the agent's tool list, and the LLM will not attempt to call them.

Design Trade-Offs​

Why workspace-level and not project-level? Most organizations use one Google Workspace account, one Slack workspace, and one Jira instance across all their projects. Requiring per-project configuration would mean repeating the same OAuth flow for each project. Workspace-level sharing matches the organizational reality for the majority of users.

Why environment variables and not a credentials API? Environment variables are the standard mechanism for passing secrets to containers in Kubernetes. They work with every programming language, require no client library, and are well-understood by developers. A credentials API would add latency (network call to fetch credentials) and complexity (auth for the credentials API itself).

Why encrypt at rest if they are just going into env vars? The encryption protects credentials in the database. If the database is compromised (backup leak, SQL injection, unauthorized access), the credentials are not immediately usable. The decryption happens in-memory on the platform API server during deployment, and the plaintext only exists as an environment variable in the running container.

See Also​