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 installed integrations

integrations.ts

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

Returns the array of the agent’s integration installs, each with its integrationId, status, version, and 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}

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.