Skip to content
streams docsstreams docsstreams docs

Connecting an agent provider

Streams connects agents you already own. You keep the agent where it lives — Anthropic, Mistral, ElevenLabs, Microsoft Copilot Studio, Cursor — and Streams gives it a place in the conversation: a name people can @mention, a reply that streams into the thread, and an MCP server it can call back through to read and act on streams, messages and resources.

How a connection works

Section titled “How a connection works”
  1. Pick the provider in Agents → Connect agent.
  2. Supply a credential. Most providers take an API key; Copilot Studio uses a Direct Line secret. Credentials are stored per account, sealed in the secret vault, and can be reused by several agents. They are never returned by the API once saved.
  3. Fill the provider’s fields — which agent or model to use, the name it appears under in streams, and anything else that provider needs.
  4. Streams sets up the far side. For most providers this means registering our MCP server on your agent so it can call back into Streams. What each provider does is listed below.
  5. Add the agent to a stream from the stream’s members dialog, then @mention it.

Two values are generated per registration and shown exactly once, for the providers that need you to hold them:

Value What it is
Signing secret The HMAC key your endpoint verifies our webhooks with (custom_webhook only).
API key The bearer token your agent presents on POST /api/agents/reply and on our MCP server.

Neither can be read back. Rotate secrets on the agent’s row mints new ones and invalidates the old pair immediately. For the providers where Streams wires the MCP server itself, rotation also re-runs that wiring, so the new key reaches the agent without you touching the provider. For custom_webhook, custom_token_only and Copilot Studio you have to install the new values yourself.

Limits that apply to every provider

Section titled “Limits that apply to every provider”
  • Deadlines. A webhook agent has 30 seconds to start responding and 10 minutes of silence after ack to post a final (AGENTS_WEBHOOK_TIMEOUT_MS / AGENTS_REPLY_TIMEOUT_MS; chunks re-arm the silence window). Hosted providers that return { kind: 'ack', continue } are capped at 5 minutes to start the remote run (AGENTS_PROVIDER_TIMEOUT_MS); after ack, Streams holds continue in-process and does not apply the silence reply deadline — the turn stays open until continue settles (quiet multi-minute tool work is fine). Providers that still finish synchronously stay under the 5-minute start cap for the whole turn.
  • One registration per external agent. Connecting the same remote agent twice fails with agents.provider_already_connected.
  • Pause, resume, delete. Pausing stops invocations without losing the registration. Deleting also undoes what Streams created on the provider side, best effort.
  • Instructions. Every registration can carry operator instructions — a system prompt for the model providers, prepended framing elsewhere. Set through POST /api/agents or PATCH /api/agents/:id.

Session continuity

Section titled “Session continuity”

A top-level @mention always starts a new vendor session. A follow-up @mention inside the same thread resumes the prior session: Streams retrieves the opaque session reference stored per agent + thread (agents.agent_provider_sessions) and sends only the messages posted since the last turn together with the new request — no briefing, no full history replay.

Fallback rules:

  • Fallback to a fresh session only happens if the prior session is gone (404 / 410 / AgentNotFoundError) and no output has been streamed yet. If the agent has already started replying, the error surfaces instead.
  • Busy is not a fallback. If the prior agent still has a run in progress (409 / AgentBusyError), Streams retries and then fails the turn with agent_busy (“I was still working on your previous request. Wait and resend.”) — it does not start a second cloud agent, which would overwrite the stored session and lose in-flight work.
  • Auth errors and timeouts are never silently retried as a fresh session.
  • Stored session references are cleared when the agent’s endpoint changes, its key is rotated, or its registration is removed. A top-level ack that carries a sessionRef opens the reply thread immediately and stores the ref, so hosted ack+continue providers (Cursor) stay resumable while the run is still going.
Provider Resume mechanism Falls back to a fresh session on
cursor Agent.resume(agentId, { apiKey, mcpServers }) then send; ref is the agentId. 404 / 410 / AgentNotFoundError (not busy)
claude Reuses the existing session id; posts a new user.message event without creating a new session. 404 / 409 / 410 / 422 / session terminated
mistral conversations.appendStream({ conversationId }) with the stored conversation id. 404 (conversation gone)
copilot_studio Reuses the stored Direct Line conversationId; skips POST /conversations. 404 / 410
elevenlabs No session continuity — each turn opens a fresh signed WebSocket session. —
custom_webhook No session continuity — the payload carries the thread history as before. —

custom_webhook

Section titled “custom_webhook”

Your own HTTPS endpoint. Streams posts a signed webhook when the agent is mentioned and your service answers.

Prerequisites: a service reachable over HTTPS on a public address. The full request and reply format is in webhook and reply contract.

Fields

Field Label What to enter
name Agent name How the agent appears in streams.
triggeredByStreams Can this agent be triggered by Streams? Yes, it has an endpoint for a webhook agent. No, it only posts to Streams registers a token-only agent instead (see below).
endpointUrl Webhook URL The HTTPS URL Streams posts to. Private and localhost addresses are rejected unless the deployment allows them for local development.

What Streams configures: nothing on your side. It generates the signing secret and API key and shows both once (along with mcpUrl).

Known limits: no provider-side conversation state — the payload carries the recent history and your service decides what to do with it. Retries are up to three attempts with 1 s / 4 s / 16 s back-off; every attempt carries the same delivery id.

The token-only variant

Section titled “The token-only variant”

Answering No, it only posts to Streams registers the agent as custom_token_only. Streams hands back { apiKey, mcpUrl } rather than a signing secret: the agent authenticates to our MCP server with that key and acts on Streams on its own schedule. Such an agent cannot be triggered from Streams — a mention fails with agents.agent_not_triggerable and the agent’s row shows “Not triggerable”.

claude

Section titled “claude”

A managed agent in your Anthropic account. Streams runs sessions against it and gives it a route back into the conversation.

Prerequisites: an Anthropic API key with access to managed agents (console.anthropic.com/settings/keys). Either an agent that already exists, or use Start with template to have Streams create one.

Fields

Field Label What to enter
apiKey API key Your Anthropic key.
externalAgentId Agent The agent to connect, picked from your account. Choosing one fills the name for you.
name Agent name How the agent appears in streams.
environmentId Environment Optional. Run the agent in an environment you already have; leave empty and Streams creates one named after the agent.
vaultId Vault Optional. An existing secrets vault; leave empty and Streams creates one.

Templates. Claude is the one provider that can create the agent for you. The Start with template tab offers starter agents. Streams posts the template’s definition to your account under the name you typed, then connects the result.

What Streams configures on Anthropic’s side:

  • an environment and a vault, if you did not name your own;
  • a credential in that vault holding this registration’s API key, so the agent can authenticate to our MCP server as a bearer token;
  • our MCP server (streams) on the agent, plus an mcp_toolset entry referencing it with an always-allow permission policy.

Each step is idempotent, so a rotation or a reconnect runs it again. A failed connect undoes whatever that attempt created. Deleting the agent removes the MCP server, the vault credential, and only the environment and vault that Streams itself created.

Known limits: replies stream. Follow-up @mentions in the same thread resume the vendor session (see session continuity above). Management calls (listing, setup, teardown) have a separate 20-second deadline.

mistral

Section titled “mistral”

An agent in your Mistral account, reached through the Conversations API.

Prerequisites: a Mistral API key, and an agent that already exists in the account. Connectors must be available to your workspace.

Fields

Field Label What to enter
apiKey API key Your Mistral key.
externalAgentId Agent The agent to connect, picked from your account. Choosing one fills the name for you.
name Agent name How the agent appears in streams.

What Streams configures on Mistral’s side: a connector pointing at our MCP server, with this registration’s API key as its Authorization header and workspace-shared visibility, and that connector added to the agent’s tools. A connector left over from an earlier connect carries a stale key, so it is replaced rather than reused. Deleting the registration removes the connector from the agent and then deletes it.

Known limits: replies stream. Follow-up @mentions in the same thread resume the Mistral conversation (see session continuity above).

elevenlabs

Section titled “elevenlabs”

A Conversational AI agent in your ElevenLabs account, run text-only.

Prerequisites: an ElevenLabs API key, an existing conversational agent, and MCP accepted for your workspace — ElevenLabs gates MCP servers behind its own terms, and a connect attempt before you accept them fails with agents.provider_mcp_not_enabled.

Fields

Field Label What to enter
apiKey API key Your ElevenLabs key (sk_…).
externalAgentId Agent The agent to connect, picked from your account. Choosing one fills the name for you.
name Agent name How the agent appears in streams.

What Streams configures on the ElevenLabs side: an MCP server named streams on the account, using streamable HTTP with this registration’s API key as the bearer token, auto-approving tool calls and with pre-tool speech off — the first thing the agent says has to be the answer. The server is then referenced from the agent’s prompt, and the agent is switched to text-only. A reconnect replaces the server it created last time; deleting the registration removes it.

Known limits: replies do not stream. There is no conversation continuity — each turn opens a fresh signed conversation, so the recent visible history is sent with every turn.

copilot_studio

Section titled “copilot_studio”

A published Microsoft Copilot Studio agent, reached over Direct Line.

Prerequisites: the agent must be published in Copilot Studio. Enable the Direct Line channel and copy a secret. Streams discovers which Direct Line region your tenant answers on and remembers it, so a run does not search again.

Fields

Field Label What to enter
directLineSecret Direct Line secret From the agent’s channel settings in Copilot Studio.
name Agent name How the agent appears in streams.

What Streams configures — and what you have to do by hand. Copilot Studio has no API for adding an MCP server to an agent, so Streams cannot do it for you. On connect you are shown an MCP server URL and an API key. Add that MCP server to the agent in Copilot Studio with the key as the Authorization bearer header, then publish the agent again — an unpublished change is not live. If you rotate the agent’s secrets in Streams you have to repeat this, because the old key stops working immediately.

Known limits: replies stream as Direct Line activities arrive. Follow-up @mentions in the same thread resume the Direct Line conversation (see session continuity above).

cursor

Section titled “cursor”

A Cursor cloud agent that works in your repositories and opens pull requests.

Prerequisites: a Cursor API key (cursor.com/dashboard), source control connected in your Cursor account, and at least one repository the key may work in.

Fields

Field Label What to enter
apiKey API key Your Cursor key (crsr-…).
name Agent name How the agent appears in streams.
repos Repository One or more repository URLs the agent may work in. At least one is required.
workerPoolName Worker pool Optional. A specific Cursor worker pool; a pool serves a single repository, so it cannot be combined with several.

What Streams configures: nothing persistent. Cursor does not store MCP servers for us, so our MCP server is handed to the cloud agent on every call and the registration keeps a sealed copy of its API key for runtime use.

Attachments: trigger (and thread-history) files ride on trigger.attachments / context.messages[].attachments. Cursor receives up to five images (image/jpeg|png|gif|webp) as SDK images (signed URL form); other files and overflow images are listed as links in the turn text.

Known limits: replies stream. Follow-up @mentions in the same thread resume the cloud agent session (see session continuity above). Long runs (PRs, multi-step work) ack as soon as Cursor accepts the prompt, then finish via held-in-process continue (run.wait() / Agent.getRun) with no silence reply deadline — quiet tool-heavy turns can outlast AGENTS_REPLY_TIMEOUT_MS. Durability is still in-process today (lost on restart; the agent-runner outbox plan replaces that).

Coming soon

Section titled “Coming soon”

The following providers appear in the catalog and their cards are visible in the connect dialog, but a connect attempt is rejected with agents.provider_coming_soon. There is nothing to configure yet.

  • openai — OpenAI Responses API
  • gemini — Google Gemini API
  • azure_ai_foundry — Azure AI Foundry agent
  • aws_bedrock — Amazon Bedrock agent
  • monday — monday.com custom agent
  • globster

Don’t see your provider?

Section titled “Don’t see your provider?”

Two options:

  1. Connect it as a custom agent today. If it can receive an HTTPS webhook, use custom_webhook. If it can only call out, use the token-only variant: it gets an API key and our MCP server, and can post into streams on its own.
  2. Ask for first-class support. The Don’t see your provider? Request it link at the bottom of the provider picker records the request.