Integrations

An agent can inspect and manage its own integrations through the agent API — the same integrations you’d otherwise manage from the dashboard or the alfe integration CLI. For background on what integrations are and how their lifecycle works, see How integrations work.

All examples use the @alfe.ai/agent-api-client.

List effective integrations

integrations.ts

const { integrations } = await client.listIntegrations();
// GET /agent/integrations

Returns every integration EFFECTIVE for the agent, discriminated by source:

• Explicit agent-scope installs (source: "explicit", scope: "agent") — the full install row with integrationId, statuses, version, and config.
• Driven activations (source: "driven-by-connection" / "driven-by-channel" / "driven-by-custom") — integrations like Xero, Google, or MYOB that activate whenever their backing connection or channel is active. They have no install row and carry no config; that’s normal, not a fault.
• Inherited installs (source: "explicit" with scope of org, team, or project) — installed at a broader scope; the narrow projection without config.

Browse the registry

See what’s available to install.

const { integrations } = await client.getRegistry();
// GET /integrations/registry

Install an integration

const install = await client.installIntegration("github", {
  version: "1.2.0",             // optional — omit for latest
  config: { defaultBranch: "main" }, // optional initial config
});
// POST /agent/integrations

Read and update config

const config = await client.getIntegrationConfig("github");
// GET /agent/integrations/{integrationId}/config

await client.updateIntegrationConfig("github", { defaultBranch: "develop" });
// PATCH /agent/integrations/{integrationId}

A successful read answers with installed plus the entry’s desiredStatus, source, and (for explicit installs) the scope the config lives at. A driven integration answers installed: true with empty config/configSchema — it’s active via its connection and has nothing to configure. An explicit install that has been soft-removed (desiredStatus: "removed", awaiting daemon reconciliation) answers installed: false even though its row still exists. Only scope: "agent" config is writable through updateIntegrationConfig; inherited org/team/project config is read-only from the agent API.

Remove an integration

const removed = await client.removeIntegration("github");
// DELETE /agent/integrations/{integrationId}

OAuth connect flows

Some integrations connect to a third-party account over OAuth. The agent can start that flow and check its result:

// Get an authorization URL to send the user to.
const { url, expiresIn } = await client.getOAuthUrl("github", ["repo", "read:org"]);
// GET /agent/integrations/oauth/url?provider=github&scopes=repo,read:org

// Later, check whether the account is connected.
const status = await client.getOAuthStatus("github");
// GET /agent/integrations/oauth/status?provider=github

{ "data": { "provider": "github", "connected": true } }

Once an account is connected, the agent can read its credentials to make API calls on the user’s behalf — see Connected accounts.

Calling without the client

List installs with curl:

curl https://api.alfe.ai/agent/integrations \
  -H "Authorization: Bearer $ALFE_API_KEY"

The result is wrapped in a data field, as with every agent API response.