Skip to main content

Integrations

Integrations are how your agents connect to external services. Each one wraps a single service's configuration (its URL, auth, and any secrets) so multiple agents can reuse it without duplicating setup.

Open Integrations in the main menu to see everything connected to your workspace.

Three kinds of integrations​

KindUse for
Custom APIAny HTTP API. You define the URL, auth, and the set of actions the agent can call.
MCP serverA Model Context Protocol server. Tools are discovered automatically from the server, so you don't define them by hand.
Messaging channelOutbound SMS through Telnyx. Used by send text message actions.

Click + Add integration to add one. Custom API and MCP server open a short configuration flow; messaging channel opens a channel-specific form.

Custom API and MCP integrations host reusable actions and tools that agents link. Messaging channels are the exception: they don't host actions of their own, they're picked by a send text message action on the agent.

Shared actions​

Once a Custom API or MCP integration is connected, you define shared actions under it. For example, a lookup_invoice API call sitting under a "Billing API" integration. Shared actions live on the integration, so any agent can link them.

The point of a shared action is to define it once and reuse it everywhere. The integration owns the action's definition (the parts that stay the same for every agent), and each agent that links it tunes only a small set of per-agent fields (the parts that are specific to how that agent uses it).

Defined once on the integrationTuned per agent
Name and descriptionParameters schema (what the AI collects)
URL and methodRequest body template
HeadersConversation phases
Output variablesAllowed states
Max successful calls

Change something in the left column and every linked agent picks it up (see Live references). Change something in the right column and only that one agent is affected.

Agent-specific actions​

Not every action belongs under an integration. Static responses, end-call rules, simple handover scripts, and client-side events are usually specific to one agent, so there's nothing to share. Create those directly on the agent's Actions tab via Add an agent specific action.

API calls that only one agent will ever make can also live as agent-specific actions if you don't want to set up a full integration first. You can always promote one to a shared action later by creating an integration and recreating the action under it.

Choosing between them​

Reach for a shared (integration) action when:

  • The same operation is used by more than one agent.
  • You want credentials managed in one place.
  • You want API changes, like a new header or a renamed field, to reach every agent live.
  • The per-agent differences are limited to a few fields: parameters schema, request body template, phases, allowed states, and max successful calls.

Keep it an agent-specific action when:

  • The behavior is unique to one agent, like tailored static-response copy or a specific handover script.
  • It's a one-off you don't expect to reuse.
  • You want the action snapshotted with the agent version, so restoring an old version restores the exact action it had.

That last point is the key contrast with the live-reference behavior below.

Live references​

When you change a shared action (rename an output variable, add a header, change the URL), every agent linking it picks up the new shape immediately. This keeps your API contract in one place: fix it once on the integration and every agent using it stays in sync.

Restore behavior​

Restoring an older agent version doesn't roll back the shared actions that version was using. The restored agent uses the current shape of each linked action, which may have changed since the version was last published.

Three checks surface what's changed so you can react:

  • Restore preview. Before you confirm a restore, the preview dialog lists shared actions that have changed since this version was locked, or that have been deleted.
  • Post-restore banner. After restore, the agent's Actions tab shows a banner listing any actions whose shape no longer matches what the restored version expects. Each entry links to the action so you can review prompts or unlink.
  • Publish-time validation. When you publish a version, Stellar blocks publishing if any binding references a deleted or moved shared action, and lists the broken references so you can re-link or remove them.

Next steps​