Integrations: model providers, sandboxes, browsers, messaging, and observability vendors --- # Integrations > An index of the external services Everruns agents connect to: cloud sandboxes, browsers, search, messaging and discovery, with setup and tool references. Source: This page lists the external vendors Everruns agents connect to. Tool integrations surface as [capabilities](https://everruns.com/docs/features/capabilities/), so a vendor that has a capability page (Daytona, E2B, Browserless, Slack) is documented there in full: setup, tools, and security. The remaining vendors have their own page in this section. Messaging integrations use [endpoints](https://everruns.com/docs/features/channels/) owned by the Agent. Building with the Framework instead? [Framework integrations](https://everruns.com/docs/framework/integrations/) lists the ones an embedded app can use and the Cargo feature for each. ## Sandboxes & execution Give agents an isolated environment to run code, edit files, and persist state. | Integration | What it provides | | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | | [Daytona](https://everruns.com/docs/capabilities/daytona/) | Cloud sandbox environments via the Daytona REST API | | [E2B](https://everruns.com/docs/capabilities/e2b/) | Cloud sandboxes via the E2B management + runtime APIs (bring your own key) | | [Container Sandbox](https://everruns.com/docs/capabilities/container-sandbox/) | Self-hosted container sandboxes via Docker Engine, no external SaaS | | [Modal](https://everruns.com/docs/integrations/modal/) | Full Linux VM or gVisor sandboxes with filesystem snapshots and public tunnels. Experimental, organisation opt-in | | [boxd](https://everruns.com/docs/integrations/boxd/) | Persistent Linux VMs with Docker that hibernate between turns with running processes intact, in Frankfurt or New York | | [Cursor](https://everruns.com/docs/integrations/cursor/) | Launch and manage asynchronous Cursor Cloud coding agents | ## Browser & web | Integration | What it provides | | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | [Browserless](https://everruns.com/docs/capabilities/browserless/) | Cloud browser automation, screenshots, DOM, scraping, multi-step flows | | [Brave Search](https://everruns.com/docs/integrations/brave-search/) | Web search via the Brave Search API | | [Cloudflare Web Search](https://everruns.com/docs/integrations/cloudflare-web-search/) | Web search through Ceramic, Exa or Linkup via the Cloudflare Web Search API | | [DuckDuckGo](https://everruns.com/docs/integrations/duckduckgo/) | Instant answers via the DuckDuckGo API | | [Parallel](https://everruns.com/docs/integrations/parallel/) | Web search, extract, and task APIs (free and paid tiers) | ## Reasoning & judgment | Integration | What it provides | | ------------------------------------------------------------ | -------------------------------------------------------------------- | | [TypeSafe](https://everruns.com/docs/integrations/typesafe/) | Typed judgments: probabilities, single-choice routing, graded scores | Agents on the [OpenRouter provider](https://everruns.com/docs/providers/openrouter/) can also get web reach without a separate integration via the [OpenRouter Server Tools capability](https://everruns.com/docs/capabilities/openrouter-server-tools/) (`web_search`, `web_fetch`), which OpenRouter executes server-side. ## Messaging channels | Integration | What it provides | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | | [Slack](https://everruns.com/docs/integrations/slack/) | Build and publish an Agent for Slack, with conversations, tools, approvals, and a dedicated agent pane | ## Agent protocols | Integration | What it provides | | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | | [A2A](https://everruns.com/docs/features/a2a/) | Let other agents call an Agent over A2A 1.0, and delegate work to external A2A agents | | [AG-UI](https://everruns.com/docs/integrations/ag-ui/) | Stream agent events to frontends, with tools, interrupts and optional shared state | | [AgentID Sign-In](https://everruns.com/docs/integrations/agentid/) | Let an Agent sign in to apps that support AgentID with its own AgentMail inbox. Experimental | ## Credentials | Guide | What it provides | | --------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | [Secure MCP Credentials](https://everruns.com/docs/integrations/mcp-credentials/) | Write-only Agent credential bindings for secret MCP tool parameters | ## Discovery | Integration | What it provides | | -------------------------------------------------- | ----------------------------------------------------------------------- | | [ARD](https://everruns.com/docs/integrations/ard/) | Client-side discovery of external MCP servers and A2A agents at runtime | ## Model providers Integrations connect agents to tools and services. **[Providers](https://everruns.com/docs/providers/)** connect Everruns to the AI model vendors that run your agents, OpenAI, Anthropic, Google Gemini, AWS Bedrock, OpenRouter, and more. See the [Providers overview](https://everruns.com/docs/providers/) to configure one. --- # AG-UI support > AG-UI 1.0 streaming, tools, interrupts and state support in Everruns, and how the event protocol relates to the chat component gallery. Source: Everruns supports **AG-UI 1.0**, the event protocol used by CopilotKit and other agent frontends. **A2UI** is the component format rendered inside chat messages. Use the [component gallery](https://everruns.com/docs/reference/generative-ui/) to browse all 69 supported components, or [Generative UI in chat](https://everruns.com/docs/features/generative-ui/) to enable them in console chat and Work Chat. ## Protocol support | Feature | Support | | ------------------------------------------ | ---------------------------------------------------------------------------- | | Run lifecycle and streaming assistant text | Supported | | Reasoning and tool activity | Controlled by the endpoint’s visibility policy | | Client-provided frontend tools | Supported; return trailing tool messages to resume parked calls | | Questions and resume | Supported through interrupts | | Tool approval interrupts | Available when explicitly enabled on the channel | | Token usage and subagent events | Available when explicitly enabled on the channel | | Shared state | Todo snapshots and deltas when enabled; client-provided state is not applied | | Capability discovery | Available on the channel’s capabilities endpoint | For a configured AG-UI channel, post `RunAgentInput` to `POST /v1/channels/{channel_id}/ag-ui`. Discover the channel’s declared features at `GET /v1/channels/{channel_id}/ag-ui/capabilities`, using the same authentication as a run. The [channel guide](https://everruns.com/docs/features/channels/#ag-ui) covers channel setup and client migration. To host AG-UI from a Rust application, see [Serve AG-UI](https://everruns.com/docs/framework/ag-ui/). Public Chat uses the same projection with a restricted policy: approval interrupts, usage, subagent events and shared state are disabled. An anonymous AG-UI channel can explicitly enable those features; choose its disclosure policy before exposing it publicly. ## Chat component support Console chat and Work Chat share the A2UI 1.0 standard catalog, including bound forms, charts, tables, layouts, media and composite cards. Form submissions send visible messages through the conversation’s existing permissions and approval path. Busy, archived and read-only conversations disable message actions. The native chat hosts render inline surfaces. They do not execute `callRendererFunction`, `callAgentFunction`, or OpenUI Query/Mutation calls. Maps and media depend on their sources being reachable; generated HTML runs in a sandbox without scripts or external network access. The [generative UI guide](https://everruns.com/docs/features/generative-ui/) describes compatibility with saved nested A2UI and OpenUI messages. --- # AgentID Sign-In > Let an agent sign in to apps that support AgentID as itself, using an AgentMail inbox connected to the agent's service account. Source: > **Status:** Experimental. No feature flag: adding the capability and an AgentMail connection is the opt-in. [AgentID](https://www.agentid.com) is a sign-in for AI agents, run by AgentMail. An agent’s AgentID is an AgentMail inbox. When an app that supports AgentID asks an agent to sign in, it shows a waiting page with a short-lived auth token; the agent’s inbox approves it, and the app sees the agent signed in. The **AgentID sign-in** capability gives an Everruns agent the `agentid_authorize` tool, which does that approval with the agent’s own inbox. This page covers agents signing in to other apps. To let agents sign in to your own channels, see [Channels: Sign in with AgentID](https://everruns.com/docs/features/channels/#sign-in-with-agentid). ## Setup 1. Create an inbox for the agent in AgentMail, register it with AgentID, and create an AgentMail API key. 2. Open the agent, then its **service account** connections, and connect **AgentMail** with the API key and the inbox address (for example `research@acme.agentmail.to`). 3. Add the **\[Experimental] AgentID sign-in** capability to the agent. The connection belongs to the agent. People chatting with the agent never get it, and the tool never uses their own connections or an administrator’s. ## Tool `agentid_authorize` takes one argument: | Parameter | Description | | ------------ | -------------------------------------------------- | | `auth_token` | The auth token from the app’s AgentID waiting page | It asks AgentMail to approve that sign-in for the agent’s inbox, accepting AgentID’s disclosure of the agent’s identity to the app. On success it returns `authorized: true`, the inbox, and AgentMail’s `api_key_id` and `instructions`. If AgentMail refuses (for example the agent has reached its app limit, or the token has expired), the tool returns AgentMail’s reason. The tool sends nothing else to AgentMail: it does not send or read mail. ## Security * The AgentMail key is read only from the agent’s service account. With no AgentMail connection there, the tool refuses. * Requests go only to `https://api.agentmail.to`, through the agent’s network access policy. * Approving a sign-in shares the agent’s AgentID with the app. Only pass a token that the app showed the agent. --- # Agentic Resource Discovery (ARD) > Discover and attach external MCP servers and A2A agents at runtime via the ARD protocol, with registry configuration and trust gating. Source: Everruns integrates with [Agentic Resource Discovery (ARD)](https://agenticresourcediscovery.org/spec/) as a **client**: a running agent can search ARD registries for capabilities it was not pre-provisioned with, MCP servers and A2A agents, and attach them to its session on the fly. Newly attached MCP tools appear on the next turn; attached A2A agents become `spawn_agent` targets. ARD is the discovery layer *above* `tool_search`. `tool_search` defers schemas for tools already attached to a session; ARD decides **which** MCP server / A2A agent to attach in the first place. > **Status:** Experimental. No feature flag: adding the capability and an ARD registry connection is the opt-in. ## What You Get * **Runtime discovery**: `discover_resources` runs a semantic search against a configured registry, outside the model context (like `tool_search`). * **Dynamic attachment**: `attach_resource` materializes a result as a session-scoped MCP server or external A2A agent, reusing existing Everruns config-overlay machinery. The agent loop is unchanged. * **Safety by construction**: registry allowlist, `trustManifest` verification, SSRF-safe URL validation, and a per-session attachment cap. ## Quick Start ### 1. Enable the capability on an agent Add the `resource_discovery` capability and point it at one or more registries. The model selects a registry by `id`, it can never supply a raw URL. ```json { "registries": [ { "id": "public", "url": "https://agenticresourcediscovery.org/api/v1", "federation": "none" } ], "require_trust": [], "allow_attach_types": ["application/mcp-server+json", "application/a2a-agent-card+json"], "max_attachments": 5, "allow_local_urls": false } ``` The ready-made **Capability Scout** seed agent (Dev) ships with this wired to the public reference registry plus `tool_search`. ### 2. (Optional) Connect a registry token For registries that require authentication, connect **Agentic Resource Discovery** under **Settings → Connections** (provider `ard`) and paste a bearer token, or set the `ARD_REGISTRY_TOKEN` session secret. Public anonymous-read registries need no token. ### 3. Discover and attach From a session, ask for something the agent can’t yet do. It will: 1. `discover_resources({ text: "..." })`, search the registry and get ranked candidates, each with a `urn`. 2. `attach_resource({ urn })`, verify trust, validate the URL, and attach. 3. Use the new capability on the next turn, MCP tools appear prefixed `mcp___*` (surfaced through `tool_search`); A2A agents are reachable via `spawn_agent`. 4. `list_attached_resources()`, see what’s attached this session. ## Tools | Tool | Description | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `discover_resources({ text, filter?, registry_id? })` | Search a configured registry (`POST /search`). Returns ranked `{ urn, displayName, type, score, source, description, attachable }`. `registry_id` is optional when one registry is configured. | | `attach_resource({ urn })` | Resolve a discovered entry, verify `trustManifest` + `require_trust`, SSRF-validate the URL, and attach it. Idempotent per URN. | | `list_attached_resources()` | List attachments for the session (visibility / audit). | ## Attachment Lifecycle * Attachments are **session-scoped** and torn down when the session ends. * MCP entries become a session MCP server, the same session-scoped `mcpServers` record a server added for [this conversation only](https://everruns.com/docs/capabilities/user-mcp-servers/#this-conversation-only) uses. Their tools are then subject to `tool_search` deferral, in both the hosted and the in-process worker. * A2A entries merge into the session’s A2A delegation config and are driven through the existing `spawn_agent` / `wait_task` / `message_task` tools. * Re-attaching the same URN is a no-op (reports `already_attached`). ## Security * **Registry allowlist**: only configured registries are queryable; the model picks a `registry_id`, never a URL. * **Trust gate**: an entry’s `trustManifest` identity domain must match its URN publisher, and any `require_trust` attestations (e.g. `["soc2"]`) must be present, before it can be attached. * **SSRF protection**: every resolved artifact and endpoint URL is validated (DNS-pinned; loopback, private, link-local, and cloud-metadata addresses are blocked). `allow_local_urls` relaxes this for local testing only. * **Attachment cap**: `max_attachments` bounds how many capabilities a single session can attach, limiting prompt-injection-driven attach storms. * **Untrusted data**: all registry-returned text is treated as untrusted external input. See the co-located [`SPEC.md`](https://github.com/everruns/everruns/blob/main/crates/ard/SPEC.md) for architecture and the full security review. --- # boxd > boxd machines for code execution, persistent Linux VMs with Docker that hibernate between turns with running processes intact, in Frankfurt or New York. Source: Everruns integrates with [boxd](https://boxd.sh/) machines: persistent Linux virtual machines (Ubuntu 24.04) with their own kernel and Docker preinstalled. A machine stays until it is deleted. When a session goes idle, Everruns hibernates it: memory, running processes and files are kept, and boxd bills only for the disk until the next command wakes it. ## What You Get * **Full VMs**: Docker, system services and anything else that needs a real kernel run as they would on a server * **Sleep without losing work**: hibernation keeps running processes, so a dev server or a container started in one turn is still up in the next * **Regions**: Frankfurt (`fra`) or New York (`nyc`), chosen per template or per machine * **Sizes**: `1x4`, `2x8`, `4x16` or `8x32` (vCPUs x GiB of memory) * **Snapshots**: boot from a boxd snapshot instead of the default image * **Network rules** that boxd enforces outside the machine, DNS included ## Quick Start ### 1. Create a boxd API key 1. Sign in at [app.boxd.sh](https://app.boxd.sh/) 2. Open [API keys](https://app.boxd.sh/keys) and create a key in the organization that should pay for the machines 3. Copy the key (`bxd_...`); it is shown once ### 2. Connect in Everruns 1. Go to **Settings** > **Connections** 2. Find **boxd** in the available providers 3. Click **Connect** and paste the key Everruns checks the key with boxd before saving it. ## Sandbox Templates boxd is a **managed** target in [Sandbox Templates](https://everruns.com/docs/features/sandbox-templates/). Pick **boxd** under **Runs in**, then choose: | Option | Meaning | | ---------------- | -------------------------------------------------------------------------------------------------------------------------- | | Region | `fra` or `nyc`. Left at the provider default, machines go to your boxd organization’s default region | | Compute size | `1x4`, `2x8`, `4x16` or `8x32`. Left at the provider default, boxd uses your organization’s default | | Snapshot | A boxd snapshot to boot from. A machine from a snapshot keeps the snapshot’s size, so size and snapshot cannot both be set | | Workspace path | Where commands and relative paths start (default `/home/boxd/workspace`) | | Outbound network | Open, only listed domains, or blocked | The agent then uses the standard sandbox tools, and Everruns manages the machine for the session: it creates it on first use, hibernates it when the session goes idle, wakes it on the next command, and deletes it with the session. Recovery for boxd templates is `provider_snapshot`: the machine and its disk persist, and if boxd loses a machine, Everruns starts a fresh one. In the API, the same options go in `target.options`: ```json { "target": { "kind": "managed", "provider": "boxd", "options": { "region": "nyc", "size": "4x16" } }, "durability": "provider_snapshot" } ``` ## Agent tools Add the **boxd** capability to an agent to let it manage machines itself: | Tool | Description | | --------------------- | -------------------------------------------------------------------- | | `boxd_create_sandbox` | Create a machine, optionally choosing `region`, `size` or `snapshot` | | `boxd_exec` | Run a shell command and return stdout, stderr and the exit code | | `boxd_read_file` | Read a text file from the machine | | `boxd_write_file` | Write a text file, creating parent directories | | `boxd_list_sandboxes` | List machines created in this session | | `boxd_manage_sandbox` | Check status, hibernate, wake or delete a machine | Commands and relative file paths start in `/home/boxd/workspace`. Each machine also gets an HTTPS URL, returned by `boxd_create_sandbox`. ## Network Templates’ **Outbound network** setting and the session’s network access list become the machine’s egress allowlist on boxd, set when the machine is created and updated when it wakes: * **Blocked**: no outbound traffic, DNS included * **Only listed domains**: just those hosts (`*.example.com` for subdomains) and IPv4 ranges * **Open**: unrestricted boxd machines have no IPv6 egress, and an allowlist holds at most 256 entries; a template that asks for more is refused when it is saved. Open egress leaves directly from boxd, not through an Everruns egress proxy. ## Lifecycle and cost Machines run until the session deletes them or the session’s lease on them expires: Everruns deletes leased machines when the lease runs out, so an abandoned session does not keep one. boxd’s own idle timers are turned off on these machines, so a long build that makes no network traffic is not put to sleep mid-command; Everruns’ idle policy decides when a machine hibernates. boxd bills for the vCPU a machine actively uses, the memory in use and the disk written. ## Security * **Isolation**: each machine is a KVM virtual machine created with boxd’s `isolated` setting, which also keeps boxd’s own CLI and credentials out of it * **Encrypted credentials**: the key is stored in user connections, encrypted at rest, and never enters the machine * **Session ownership**: tools only act on machines this session created * **Network access**: machines have open outbound access unless you block or allowlist it ## Not yet supported * Computer use (a desktop the agent sees and drives) * Checkpointed recovery and rewind * Building a template’s setup into a boxd snapshot --- # Brave Search > Web search through Brave: ranked results, freshness filters, pagination, source attribution, and safe search. Requires a Brave API key. Source: Everruns integrates with [Brave Search](https://brave.com/search/api/) to give agents full web search capabilities. Agents can search the web and get relevant results including titles, URLs, and descriptions, perfect for research, fact-checking, and finding current information. ## What You Get * **Full Web Search**: Query the web and get ranked results with titles, URLs, and descriptions * **Freshness Filters**: Filter results by time (past day, week, month, year) * **Pagination**: Navigate through large result sets * **Source Attribution**: Every result includes a URL for citation and verification * **Free Tier**: Brave Search offers a free plan with 2,000 queries/month ## Quick Start ### 1. Get Your API Key 1. Go to [Brave Search API](https://brave.com/search/api/) 2. Sign up for a **free** plan (2,000 queries/month) 3. Copy your **API Key** from the dashboard ### 2. Connect in Everruns 1. Go to **Settings** > **Connections** 2. Find **Brave Search** in the available providers 3. Click **Connect** and paste your API key Once connected, the Brave Search capability is automatically available in agent sessions. ### 3. Use in Sessions Agents with the Brave Search capability can use this tool: | Tool | Description | | ------------------ | ------------------------------------------ | | `brave_web_search` | Search the web and return relevant results | ### Parameters | Parameter | Type | Required | Description | | ----------- | ------- | -------- | ----------------------------------------------------------------------------------- | | `query` | string | Yes | Search query | | `count` | integer | No | Number of results (1-20, default: 10) | | `offset` | integer | No | Pagination offset | | `freshness` | string | No | Time filter: `pd` (past day), `pw` (past week), `pm` (past month), `py` (past year) | ### Response Fields The tool returns a JSON object with: | Field | Description | | --------- | -------------------------- | | `query` | The original query | | `results` | Array of result objects | | `count` | Number of results returned | Each result object contains: | Field | Description | | ------------- | ----------------------------------------------------- | | `title` | Page title | | `url` | Page URL (use for citations) | | `description` | Snippet/description of the page | | `age` | How old the result is (e.g., “2 hours ago”), optional | ## When to Use Brave Search vs DuckDuckGo | Use Case | Brave Search | DuckDuckGo | | ---------------------------- | ------------------------- | -------------- | | Full web search results | Best choice | Not available | | Current news and articles | Best choice | Limited | | Quick facts and definitions | Works but slower | Best choice | | Wikipedia-style summaries | Not available | Best choice | | Calculations and conversions | Not available | Direct answers | | API key required | Yes (free tier available) | No | Both capabilities can be enabled simultaneously, the agent will choose the right tool based on the task. ## Security * API keys are encrypted at rest (AES-256-GCM envelope encryption) * Keys are validated on connection (test query to Brave Search API) * API key never appears in tool results or message history * Rate limiting deferred to Brave Search API (returns 429 on limit) ## Status Experimental, available without a feature flag. This capability may change in future releases. For provider-neutral search, use [Web Search](https://everruns.com/docs/capabilities/web-search/), which can also use an organization Brave Search account. ## Links * [Brave Search API](https://brave.com/search/api/) * [Brave Search API Documentation](https://api.search.brave.com/app/#/documentation/web-search) --- # Cloudflare Web Search > Search Ceramic, Exa or Linkup through the Cloudflare Web Search API, billed to AI Gateway credits or your own provider key. Source: The [Cloudflare Web Search API](https://developers.cloudflare.com/web-search/) searches the web through one of three indexes and runs every search through your AI Gateway, so searches show up in its logs and analytics. A Cloudflare account connected as an organization search account answers the provider-neutral [Web Search](https://everruns.com/docs/capabilities/web-search/) capability: agents keep their one `web_search` tool. ## Indexes | Index | Price per 1,000 searches | Zero data retention | Results | | ------------------- | ------------------------ | ------------------- | --------------------------------------------------- | | `ceramic` (default) | $0.25 | Yes | Long page descriptions from Ceramic’s own index | | `exa` | $7.00 | No | Highlights: the passages most relevant to the query | | `linkup` | $5.00 | Yes | Sourced results with text snippets | Prices are Cloudflare’s list prices. Searches bill to the account’s AI Gateway credits, or to a provider key stored on the gateway when you give its alias. Each search account uses one index; connect a second account to offer another. ## Setup 1. In the [Cloudflare dashboard](https://dash.cloudflare.com/profile/api-tokens), create an API token with **Account > Workers AI > Read** and **Account > AI Gateway > Read**. 2. Copy the account ID from the dashboard. 3. In **Registers > Web search**, connect **Cloudflare Web Search** and fill in: | Field | Required | Description | | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Account ID | Yes | 32 hexadecimal characters | | API Token | Yes | The token from step 1, stored encrypted | | Search index | No | `ceramic` (default), `exa` or `linkup` | | AI Gateway | No | The gateway searches run through; `default` when empty | | Provider key alias | No | Alias of an Exa or Linkup key stored under AI Gateway > Provider Keys. When set, a missing key fails the search instead of falling back to credits | Connecting runs one test search, so a wrong token, a missing permission, an unknown gateway or a missing key alias is reported before the account is saved. Only the token is a secret; the account ID, gateway, index and alias are stored as the connection’s settings. The API connection is `POST /v1/orgs/{org}/organization-connections/providers/cloudflare_web_search` with `api_key` (the token), `account_id`, and optionally `index`, `gateway_id` and `byok_alias`. ## How it searches Pick the account in an agent’s Web search settings, or put it in the organization’s Automatic order. A search returns at most 10 results, the API’s maximum. The API has no site or date filters, so allowed and blocked sites are applied to the results it returns, and an agent’s freshness setting is not applied (the search details say so). Like every search account, a failure (rate limit, no credit, rejected token) moves Automatic to the next provider. --- # Cursor > Launch and manage Cursor Cloud Agents from Everruns agents. Source: Everruns integrates with [Cursor Cloud Agents](https://docs.cursor.com/en/background-agents) so agents can delegate asynchronous coding work to Cursor. A triage agent can inspect a request, split it into focused tasks, launch Cursor agents against GitHub repositories, send follow-ups, and summarize status or results. ## What You Get * **Launch Cloud Agents**: Start Cursor agents with repository, base ref, task prompt, optional branch name, and PR behavior. * **Track Progress**: Read status, target branch, PR URL, summary, and conversation history. * **Send Follow-ups**: Add more instructions to running Cursor agents. * **Connection Prompt**: Configure a Cursor Cloud Agents API key in Settings → Connections. * **Seed Agent**: Use the built-in **Cursor Agent Manager** example to triage and delegate work. ## Quick Start ### 1. Get a Cursor API Key 1. Open [Cursor Dashboard](https://cursor.com/dashboard?tab=cloud-agents) 2. Go to **Cloud Agents** > **My Settings** > **API Keys** 3. Create a Cloud Agents API key 4. Make sure Cursor’s GitHub app can access the repositories agents should work on Use a Cloud Agents API key. A general Cursor dashboard API key may not be enough to create agents. ### 2. Connect in Everruns 1. Go to **Settings** > **Connections** 2. Find **Cursor** 3. Click **Connect** 4. Paste the Cloud Agents API key ### 3. Use in Sessions Agents with the Cursor capability can use these tools: | Tool | Description | | -------------------------- | -------------------------------------------- | | `cursor_launch_agent` | Start a Cursor Cloud Agent | | `cursor_get_agent` | Get one agent’s status and result metadata | | `cursor_list_agents` | List agents for the connected Cursor account | | `cursor_add_followup` | Send extra instructions to a running agent | | `cursor_get_conversation` | Read an agent’s conversation transcript | | `cursor_delete_agent` | Delete an agent record/resources | | `cursor_list_models` | List recommended Cursor model ids | | `cursor_list_repositories` | List GitHub repositories Cursor can access | | `cursor_key_info` | Check the active Cursor connection | ## Delegation Pattern Use **Cursor Agent Manager** when you want Everruns to triage first and then delegate: 1. Provide the repository URL and base branch 2. Ask the agent to break the work into scoped tasks 3. Let it launch Cursor agents with clear acceptance criteria 4. Review returned Cursor links, branches, PR URLs, summaries, and transcripts ## Lifecycle Cursor owns Cloud Agent lifecycle state. Everruns stores no per-agent state beyond normal session messages and tool results. Keep the returned `agent_id` if you want to poll, send follow-ups, read the conversation, or delete the agent later. `cursor_list_repositories` is heavily rate-limited by Cursor and can be slow for large accounts. Prefer passing the repository URL directly. ## Security * Cursor API keys are encrypted at rest when stored as Everruns user connections * Everruns prompts for missing Cursor credentials through the inline connection dialog, not chat text * Cursor agents run in Cursor-managed remote environments with internet access and command execution * Repository access is controlled by the Cursor GitHub app and Cursor account settings * Webhook secrets and image prompt payloads are intentionally not exposed in the first tool surface ## Links * [Cursor Cloud Agents](https://docs.cursor.com/en/background-agents) * [Cursor Background Agents API](https://docs.cursor.com/en/background-agent/api/overview) * [Launch Agent API](https://docs.cursor.com/en/background-agent/api/launch-an-agent) * [Cursor GitHub app](https://docs.cursor.com/en/github) --- # DuckDuckGo > Instant answers, definitions, and topic summaries via DuckDuckGo. No API key required. Source: Everruns integrates with [DuckDuckGo](https://duckduckgo.com/) to provide instant answers via the [DuckDuckGo Instant Answer API](https://api.duckduckgo.com/api). Agents can look up facts, definitions, topic summaries (from Wikipedia and other sources), and related topics, all without an API key. ## What You Get * **Instant Answers**: Direct answers for calculations, IP lookups, conversions, and more * **Topic Abstracts**: Wikipedia-style summaries for well-known topics * **Definitions**: Dictionary definitions from Wiktionary and other sources * **Related Topics**: Links to related topics for deeper exploration * **No API Key Required**: The DuckDuckGo Instant Answer API is completely free ## Quick Start ### 1. No Setup Needed Unlike other integrations, DuckDuckGo requires no API key or configuration. The DuckDuckGo Instant Answer API is free and public. ### 2. Enable the Capability Add the `duckduckgo` capability to your agent or harness configuration. ### 3. Use in Sessions Agents with the DuckDuckGo capability can use this tool: | Tool | Description | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `duckduckgo_instant_answer` | Look up instant answers, abstracts, definitions, and related topics. Instant-answer lookup only, not a full web/SERP search | ### Parameters | Parameter | Type | Required | Description | | --------- | ------- | -------- | --------------------------------------------- | | `query` | string | Yes | Search query | | `no_html` | boolean | No | Strip HTML from result text (default: `true`) | ### Response Fields The tool returns a JSON object with available fields: | Field | Description | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | The original query | | `type` | Response type: `article`, `disambiguation`, `category`, `name`, `exclusive`, or `nothing` | | `heading` | Topic heading | | `abstract` | `{ text, source, url }`, topic summary | | `answer` | `{ text, type }`, direct answer (calculations, etc.) | | `definition` | `{ text, source, url }`, dictionary definition | | `related_topics` | Array of `{ text, url }`, related topics (max 10) | | `results` | Array of `{ text, url }`, official/direct results | | `note` | Present only when no instant answer was found, a caveat that this is not a definitive web-search result and matching web pages may still exist | Only non-empty fields are included in the response. ## When to Use DuckDuckGo vs Brave Search | Use Case | DuckDuckGo | Brave Search | | ---------------------------- | ---------------- | ---------------- | | Quick facts and definitions | ✅ Best choice | Works but slower | | Wikipedia-style summaries | ✅ Best choice | Not available | | Calculations and conversions | ✅ Direct answers | Not available | | Full web search results | ❌ Not available | ✅ Best choice | | Current news and articles | ❌ Limited | ✅ Best choice | | API key required | No | Yes | Both capabilities can be enabled simultaneously, the agent will choose the right tool based on the task. ## Security * **No secrets**: No API key or credentials to manage * **Read-only**: The API only returns information, no write operations * **Privacy**: DuckDuckGo does not track searches ## Status Experimental, available without a feature flag. This capability may change in future releases. ## Links * [DuckDuckGo](https://duckduckgo.com/) * [DuckDuckGo Instant Answer API](https://api.duckduckgo.com/api) --- # Secure MCP Credentials > Configure write-only credentials with scoped ownership and explicit access for MCP tools that require a secret parameter. Source: Use an Agent credential binding when an MCP tool requires a secret in its input, such as Visti’s `visti_send.channel_key`. Do not paste the value into chat, Agent instructions, memory, or session storage. 1. Attach the MCP server capability to the Agent. 2. Open the Agent and select **Credentials**. 3. Add or open the exact server, tool, and parameter binding. 4. Enter the value in the masked form and save it. The value is encrypted and is never shown again. Everruns removes the bound parameter from the model-visible tool schema and injects the value only when it sends the MCP request. The same Agent binding works for a shared session and for triggers that create a new session per invocation. Use **Replace** to replace a value. Use the revoke action to delete the binding; future calls then return a setup-required result with a link back to the agent’s Credentials settings. Session Storage has a separate encrypted secret lifecycle for session-local workflows. Those secrets do not follow per-invocation sessions and are not injected into MCP tool calls, so they are not a substitute for an MCP credential binding. ## OAuth connections For an MCP attachment that acts as a user, connect the provider from **Settings → Connections**. The grant belongs to your current organization’s virtual user and is used only for turns you initiate. Scheduled execution does not borrow the last speaker’s grant. For an attachment that acts as a service, select the responding agent’s service virtual user and connect the provider on that account’s **Connections** tab. Agent behavior and service credentials remain separate. External integrations can exchange verified channel authentication at `POST /v1/channels/{channel_id}/runtime-auth` for a short-lived runtime bearer token. The token allows virtual-user self-service and authenticated ingress for that channel. It cannot administer organizations, agents, or other users. Use `GET /v1/virtual-users/me` to discover the account, and the canonical `/v1/virtual-users/{id}/connections` routes for its grants. To start browser OAuth with bearer authentication, POST to the provider’s `authorize` subresource and navigate to the returned `authorization_url` while retaining its setup cookie. Setup captures the account and revalidates authority at callback. Credential bindings also support session, virtual-user, and organization owners. Select personal credentials explicitly through an MCP attachment acting as the verified user; service attachments use their service identity. Session ownership and organization membership do not grant personal access. Organization bindings require explicit access grants. Two matching authorized bindings fail as ambiguous rather than selecting one silently. Secure entry uses the revision of the target you reviewed, so a stale form cannot provision a changed target. See [write-only HTTP credentials](https://everruns.com/docs/capabilities/web-fetch/#write-only-credentials) for HTTP form/header bindings and response capture. --- # Modal > Modal sandboxes for code execution, full Linux VMs with their own kernel or lighter gVisor containers, with filesystem snapshots and public tunnels. Source: > **Status:** Available on every deployment. Connecting requires your own Modal credentials. Everruns integrates with [Modal](https://modal.com/) sandboxes. By default an agent gets a [VM sandbox](https://modal.com/blog/vm-sandboxes-agent-computers): a full Linux virtual machine with its own kernel, so workloads that need real kernel features (Docker, FUSE, databases, system services) run as they would on a server. The lighter gVisor container runtime is available too. ## What You Get * **Full VMs or containers**: `runtime: "vm"` (default) boots a real kernel; `runtime: "gvisor"` starts a lighter container * **Any registry image**: start from a public image (default `python:3.13-slim` with git and curl added), optionally with Dockerfile setup commands * **Filesystem snapshots**: save a sandbox’s filesystem as an image and boot copies of it later * **Public tunnels**: expose ports and get HTTPS URLs for them * **Multiple sandboxes per session**, each cleaned up automatically when the session lease expires ## Quick Start ### 1. Create a Modal token 1. Sign in at [modal.com](https://modal.com/) 2. Open [Settings > API Tokens](https://modal.com/settings/tokens) and create a token 3. Copy the token ID (`ak-...`) and token secret (`as-...`) ### 2. Connect in Everruns 1. Go to **Settings** > **Connections** 2. Find **Modal** in the available providers 3. Click **Connect** and paste the token as `ak-...:as-...` The form also accepts the `modal token set --token-id ak-... --token-secret as-...` command Modal shows when the token is created. Everruns checks the token with Modal before saving it. ### 3. Use in Sessions Add the **Modal** capability to an agent. Agents with it can use these tools: | Tool | Description | | ------------------------ | -------------------------------------------------------------------------- | | `modal_create_sandbox` | Create a VM or gVisor sandbox from an image, setup commands, or a snapshot | | `modal_exec` | Run a shell command (`sh -c`) and return stdout, stderr and the exit code | | `modal_read_file` | Read a text file from the sandbox | | `modal_write_file` | Write a text file into the sandbox, creating parent directories | | `modal_list_sandboxes` | List sandboxes created in this session | | `modal_manage_sandbox` | Check a sandbox’s status or terminate it | | `modal_snapshot_sandbox` | Snapshot the filesystem into an image (`im-...`) | | `modal_tunnel_urls` | Get the public HTTPS URLs for exposed ports | Commands and relative file paths start in `/workspace` inside the sandbox. ## Creating Sandboxes `modal_create_sandbox` accepts: | Parameter | Meaning | | ---------------------- | ----------------------------------------------------------------- | | `runtime` | `vm` (default) or `gvisor` | | `image` | Registry image, for example `node:22` | | `setup_commands` | Up to 20 Dockerfile lines (`RUN ...`) applied on top of the image | | `snapshot_image_id` | Boot from a snapshot instead of an image | | `timeout_seconds` | Maximum lifetime, 60 to 86400 (default 3600) | | `idle_timeout_seconds` | Terminate after this long without activity | | `cpu`, `memory_mb` | Resources to request | | `expose_ports` | Up to 10 ports to publish through tunnels | Modal caches built images per workspace, so the first sandbox from a new image takes longer than the ones after it. ## Network and GitHub access Pass `network` to `modal_create_sandbox` to control outbound traffic. Modal enforces it outside the sandbox: * `{"mode": "blocked"}`: no outbound network * `{"mode": "allowlist", "domains": ["pypi.org", "*.pythonhosted.org"], "cidrs": ["10.0.0.0/8"]}`: only those destinations * `{"mode": "open"}`: anything (the default) Pass `"inject_connections": ["github"]` to let the sandbox use your GitHub connection without exposing the token (the agent’s connection when no person is in the run or the person has not connected GitHub). Modal adds it to requests for `api.github.com` and to git over `https://github.com`, so `curl https://api.github.com/user` and `git clone` of private repositories work, but the token never appears in the sandbox environment or files. Injection needs open network or a CIDR-only allowlist. In Sandbox Templates, the template’s network setting (Open, Only listed domains, Blocked) is enforced the same way, and the **Use my GitHub connection** switch turns on injection. ## Snapshots 1. Call `modal_snapshot_sandbox` to save the current filesystem. The sandbox keeps running. 2. Pass the returned `im-...` ID as `snapshot_image_id` to `modal_create_sandbox` to boot a copy with that state. ## Tunnels 1. Create the sandbox with `expose_ports`, for example `[8080]` 2. Start a server listening on `0.0.0.0` at that port 3. Call `modal_tunnel_urls` to get the public HTTPS URL ## Sandbox Templates On deployments that offer it, Modal is also a **managed** target in Sandbox Templates. Pick **Modal** under **Runs in** and choose the runtime (VM or gVisor), an image, CPU cores, memory and a workspace path (default `/workspace`). The agent then uses the standard sandbox tools instead of the `modal_*` tools, and Everruns manages the sandbox for the session. When the session goes idle, Everruns snapshots the sandbox filesystem and terminates the sandbox. The next command boots a new sandbox from that snapshot, so files survive but running processes do not. Recovery for Modal templates is `provider_snapshot`. ## Lifecycle Sandboxes run until the agent terminates them, their `timeout_seconds` or idle timeout passes, or the session’s lease on them expires. Everruns terminates leased sandboxes when the lease expires, so an abandoned session does not keep one running. Modal bills running sandboxes per second; see [Modal pricing](https://modal.com/pricing). ## Security * **Isolation**: VM sandboxes run their own kernel; gVisor sandboxes run behind a user-space kernel * **Encrypted credentials**: the token is stored in user connections, encrypted at rest * **Session ownership**: tools only act on sandboxes this session created * **Network access**: sandboxes have open outbound access unless you block or allowlist it, and exposed ports are public. Treat anything served on a tunnel as public * **Injected credentials**: injected tokens go only to the service’s own domains, and the sandbox never holds them --- # Parallel > Use Parallel's hosted MCP server for free web search, URL fetching and web-grounded decisions, with optional API-key authentication. Source: > **Status:** Experimental, available without a feature flag. Parallel provides hosted MCP tools for web search, URL fetching, and typed questions answered from web evidence. ## Setup Add the `parallel_search` capability to an agent or harness. It works for free without any connection. To use a Parallel API key, add a `Parallel` connection in Settings → Connections, then configure the capability with `auth: "connection"`. To use Parallel’s OAuth-compatible MCP endpoint, configure the capability with `endpoint: "oauth"`. This mode requires the `Parallel` connection because the endpoint rejects anonymous requests. ## As a Web search provider A Parallel API key can also answer the provider-neutral [Web Search](https://everruns.com/docs/capabilities/web-search/) capability. Connect it as an organization search account in **Registers > Web search** (`parallel` connection), then pick it in an agent’s Web search settings or put it in the Automatic order. Searches go to Parallel’s Search API and are billed on that key. Use this instead of `parallel_search` when you want one `web_search` tool that can switch providers. ## Tools | Tool | Purpose | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mcp_parallel__web_search` | Search the web and return ranked URLs with excerpts. | | `mcp_parallel__web_fetch` | Fetch and extract focused content from known URLs. | | `mcp_parallel__web_decisions` | Answer typed questions about a subject from current web evidence: a probability (`noul`), a pick among given options (`choice`), or a score on a given scale (`score`), with call-level citations. Up to 100 questions per call. | | `mcp_parallel__image_search` | Search the web for images. | The default endpoint is `https://mcp.parallel.ai/mcp`. Parallel may add tools to it; the agent sees whatever the server lists. The OAuth endpoint (`endpoint: "oauth"`) is `https://search.parallel.ai/mcp-oauth`, which offers search and fetch only. A `web_decisions` call asks about a subject described as JSON: ```json { "state": { "project": "Everruns", "website": "https://everruns.com" }, "questions": { "open_source": { "type": "noul", "instructions": "Is Everruns open source?" }, "language": { "type": "choice", "instructions": "Main implementation language", "criteria": { "rust": "Rust", "go": "Go", "unknown": "Not enough evidence" } } } } ``` Each answer comes back under its question name, for example `{"type": "choice", "choice": "rust", "probabilities": {"rust": 0.999, ...}}`, with the pages it relied on in `citations`. A question the evidence cannot answer comes back as `{"type": "refusal"}`. Agents should reuse one stable `session_id` across Parallel tool calls in the same conversation. --- # Build Agents for Slack > Give your team an Agent with its own tools, instructions, and identity. Work with it in channels, direct messages, or Slack’s dedicated agent pane. Source: [Build a Slack Agent →](#build-your-first-slack-agent) [Publish an existing Agent](https://everruns.com/docs/how-to/publish-to-slack/) A conversationA daily briefingBased on real conversations ![mike’s Slack avatar](https://everruns.com/docs/_astro/mike.Dtz_EhgX.png) mikeSunday at 22:12 And whose turn is it on December 1? 4 replies ![Kids Duties bot avatar](https://everruns.com/docs/_astro/kids-duties.yc2JAaQz.png) Kids DutiesAPPSunday at 22:12 December 1 (Tuesday) — **Darik 🐻** is on dishes (#2)! 😊 ⚠️ A small hiccup: the briefing (07:00) and review (18:00) schedules haven’t been created yet — the scheduling tool returned an error a few times. I logged it and will try again later. The routine is unaffected 😊 ![mike’s Slack avatar](https://everruns.com/docs/_astro/mike.Dtz_EhgX.png) mikeToday at 00:08 What can they do today? New ![Kids Duties bot avatar](https://everruns.com/docs/_astro/kids-duties.yc2JAaQz.png) Kids DutiesAPPToday at 00:09 Today, **Tuesday, October 13:** * 🍽️ Dishes: **Daniil 🦊** (#1), tomorrow — Darik 🐻 * 🎮 Screen time: **up to 2 hours**, screens off by **20:30** 🌙 Have a lovely day! 😊 ![Kids Duties bot avatar](https://everruns.com/docs/_astro/kids-duties.yc2JAaQz.png) Kids DutiesAPP07:00 🦊 Dishes today: Daniil · 🎮 up to 2 hours\ 🍽️ Dishes: Daniil (#1), tomorrow — Darik 🐻\ 🎮 Screen time: up to 2 hours\ ⏰ Deadline: screens off by 20:30\ 🚫 Reminder: screen-free week, Oct 26 – Nov 1, is just 2 weeks away! 🔗 stend.sh/s/… stend Daily schedule 🏡 🏡 Daily schedule · Tuesday, October 13 · school day 📚 🚫 Screen-free week: October 26 – November 1. Get your board games and bikes ready! 🦊 Dishes today: Daniil #1. Tomorrow: Darik 🐻 🎮… stend stend. ### Daily schedule Daily schedule · Tuesday, October 13 · school day. Screen-free week: October 26 – November 1. Get your board games and bikes ready… stend.sh Kids Duties answers questions, tracks the family routine, and shares a daily briefing with a linked schedule.Recreated from real Slack screenshots. Messages translated into English. ## More than a Slack bot Build the Agent in Everruns. Give your team a familiar place to use it. ### Conversations with context Talk in channels, threads, and DMs. Choose a session per thread, channel, or user. ### Slack’s dedicated agent pane Enable the Agent surface for streaming replies, working status, and suggested prompts. ### Tools that do the work Equip Agents with capabilities, skills, and MCP tools for knowledge, research, or operations. ### Actions inside Slack React, update messages, share files in the thread, and look up users with the Slack capability. ### Human approval in the thread The requester can approve or decline a proposed action through Slack approval cards. ### Visible task progress A Tasks message updates as delegated work finishes. Open the session in Everruns for the full record. ## Build your first Slack Agent Start with a job: answering team questions, researching a topic, or preparing an incident handoff. 01 / DEFINE ### Create the Agent Set its name, avatar, instructions, and model. Add capabilities or MCP tools for its job. 02 / CONNECT ### Add Slack In Integrations, add a Slack channel. Choose a session per thread, channel, or user. 03 / PUBLISH ### Invite your team Publish the channel, select a connected workspace, choose Add to Slack, and approve the installation. Invite the bot and send a message. An administrator connects the workspace once. Installation may need Slack administrator approval. With Socket Mode, a self-hosted install needs no public address. [Check setup requirements →](https://everruns.com/docs/capabilities/slack/#before-you-start) [Follow the setup guide →](https://everruns.com/docs/how-to/publish-to-slack/) [Learn about Agent definitions](https://everruns.com/docs/how-to/define-agents-as-files/) ## Make it a Slack Agent Enable the Agent surface on your Slack channel to give it a dedicated pane alongside channel conversations. Replies stream in the pane; channel threads receive completed messages. Existing Slack apps need an updated manifest and reinstall to grant the Agent surface permissions. [Configure Slack’s agent pane →](https://everruns.com/docs/capabilities/slack/#agent-surface) ## Guides and reference [**Publish an Agent →**Connect, install, and verify the first message.](https://everruns.com/docs/how-to/publish-to-slack/)[**Slack reference →**Scopes, session routing, actions, and troubleshooting.](https://everruns.com/docs/capabilities/slack/) ## Watch Kids Duties in Slack A real Agent setup, its execution trace, and the morning briefing delivered in Slack. English narration and captions; the original Slack messages are Ukrainian. [Slack integration: Kids Duties agent in Everruns](https://www.youtube-nocookie.com/embed/mbbYFif9juY?rel=0) [Watch on YouTube](https://www.youtube.com/watch?v=mbbYFif9juY) --- # TypeSafe > Typed decisions from TypeSafe's System One: calibrated probabilities, routing and graded scores, via TypeSafe, OpenRouter, OpenAI, Microsoft Foundry or Google Gemini. Source: > **Status:** Experimental. Available to every organisation; adding the capability and a TypeSafe connection is the opt-in. Everruns integrates with [TypeSafe](https://typesafe.ai) so agents can ask for a **judgment** rather than an opinion. TypeSafe’s System One model answers typed questions about content and returns numbers your agent — and your code — can act on directly: the probability that something is true, which option out of a set applies, or where something falls on a scale you define. It does not write prose. That is the point: there is no answer to interpret, and no JSON to parse out of a paragraph. ## What You Get * **Yes/no with a probability**: “Is a refund being requested?” → `0.97`, not “Yes, it appears so.” * **Single choice with a distribution**: pick one option and see how close the runners-up were * **Graded scores**: rate against ordered levels you write, with the probability of each level * **Confidence**: how concentrated the answer is, so the agent can escalate instead of guessing * **One call, many questions**: every question in a call is answered together over the same content ## Use an existing OpenRouter account In **Models**, add or enable a **Decisions** model under your OpenRouter provider. Choose the **Jev 1.14** profile and the provider’s model ID `typesafe/jev-1.14`. The same saved OpenRouter credential serves both chat and decisions. Direct TypeSafe uses `jev-1.14.0`. Sync the provider to discover the new profile, or add it manually. Jev 1.13 remains available for existing integrations. The rolling `jev-latest` alias maps to `~typesafe/jev-latest` on OpenRouter. Everruns supports text **Noul**, **Choice**, and **Score** decisions. The shared profile retains TypeSafe’s default limits: 32,000 tokens for state plus any one question and 64,000 for the whole request. [TypeSafe’s model reference](https://docs.typesafe.ai/models) lists input at $0.042 per million tokens and free output. OpenRouter advertises [a larger context](https://openrouter.ai/docs/guides/community/jev), but the shared profile does not promise that limit on direct TypeSafe. Experimental image inputs, Box questions, and direct long-context headers are not enabled by this integration. ## Use an existing OpenAI account OpenAI’s [Decisions API](https://developers.openai.com/api/docs/guides/decisions) answers the same calibrated questions on GPT-6 Luna. In **Models**, enable the **GPT-6 Luna Decisions** model under your OpenAI provider (model ID `gpt-6-luna-decisions`, sent to OpenAI as `gpt-6-luna`). It sits next to the `gpt-6-luna` chat model and uses the same saved OpenAI key. OpenAI bills input tokens only, at $0.10 per million. ## Use an existing Microsoft Foundry account [Microsoft-Decision-1](https://ai.azure.com/catalog/models/microsoft-decision-1) answers the same questions on Microsoft Foundry. Deploy it in the Foundry portal, then, in **Models**, add a **Decisions** model under your Microsoft MAI provider whose model ID is the deployment name. Foundry routes calls by deployment, so a deployment named `Decision-1` is model ID `Decision-1`. The names `Microsoft-Decision-1` and `Decision-1` pick the **Microsoft Decision 1** profile on their own; another name needs that profile chosen by hand. The provider’s saved Foundry API key and resource endpoint serve both chat and decisions. Microsoft bills input tokens only, at $0.042 per million, and a request (content plus questions) fits in 32,768 tokens. ## Use an existing Google Gemini account Google’s [Decisions API](https://aistudio.google.com/docs/decisions-api) answers the same calibrated questions on Gemini Decision 1. In **Models**, add a **Decisions** model under your Google Gemini provider with model ID `gemini-decision-1`; it picks the **Gemini Decision 1** profile. The provider’s saved Gemini API key serves both chat and decisions. On OpenRouter the same model is `google/gemini-decision-1`. Google bills input tokens only, at $0.10 per million, and a request (content plus questions) fits in 262,144 tokens. Gemini Decision 1 also reads images, audio, video and PDFs. Pass session file paths in the tool’s `files` argument (up to 8 files, 15 MiB in total) and every question is answered over the text and the files together: ```json { "state": "Delivery photo for order 1042.", "files": [ "/workspace/delivery.jpg" ], "questions": [ { "id": "damaged", "type": "noul", "instructions": "Is the parcel visibly damaged?" } ] } ``` Other decision models read text only and refuse a call that attaches files. A deployment can make Gemini Decision 1 its own default for guardrail checks with `UTILITY_DECISION_DRIVER=gemini` and `UTILITY_GEMINI_API_KEY` (see [environment variables](https://everruns.com/docs/sre/environment-variables/)). Set the organization decision default in Models, or select an exact model in the **Jev Decisions** capability settings. The tool uses that model’s account. A disabled model or missing credential requires repairing the selection; it does not switch to another account. Decision calls honor session network restrictions and budgets, and appear in session usage. The model service filter keeps decisions out of chat selectors. Model profile details show calibrated primitives and serving limits. Existing TypeSafe connections and session secrets continue to work when no catalog selection or decision default is configured. ## Quick Start ### 1. Get Your API Key 1. Sign in at [typesafe.ai](https://typesafe.ai) 2. Create an **API key** in the dashboard 3. Copy it ### 2. Connect in Everruns 1. Go to **Settings** > **Connections** 2. Find **TypeSafe** in the available providers 3. Click **Connect** and paste your API key Once connected, the TypeSafe capability is available in agent sessions. ### 3. Use in Sessions Agents with the TypeSafe capability get one tool: | Tool | Description | | -------------- | ------------------------------------------------------------ | | `jev_decision` | Ask typed questions about content and get calibrated answers | A call gives it the content plus the questions to ask about it: ```json { "state": "Why did the chicken cross the road? To get to the other side.", "questions": [ { "id": "is_funny", "type": "noul", "instructions": "Would a general audience laugh at this?" }, { "id": "humor", "type": "score", "instructions": "How funny is this joke?", "levels": ["Not funny at all", "Mildly amusing", "Genuinely funny", "Hilarious"] } ] } ``` And gets back numbers, not a review: ```json { "model": "jev-1.14.0", "answers": { "is_funny": { "type": "noul", "probability_yes": 0.43 }, "humor": { "type": "score", "score": 0.58, "normalized": 0.19, "level": 1, "label": "Mildly amusing", "probabilities": { "0": 0.44, "1": 0.55, "2": 0.01, "3": 0.0 }, "confidence": 0.57 } } } ``` ## Question Types | Type | Ask it when | You get | | ------------------------------------------------------ | --------------------------------------- | ---------------------------------------------------------------------------------- | | [`noul`](https://docs.typesafe.ai/primitives/noul) | A condition either holds or it doesn’t | The probability of yes, from 0 to 1 | | [`choice`](https://docs.typesafe.ai/primitives/choice) | Exactly one option out of a set applies | The selected option, every option’s probability, and a confidence | | [`score`](https://docs.typesafe.ai/primitives/score) | Something falls somewhere on a scale | A weighted position across your levels, each level’s probability, and a confidence | These are System One’s own primitives, kept under the same names here; TypeSafe documents them in full under [Primitives](https://docs.typesafe.ai/primitives). Two things worth knowing when you write the questions: * A `noul` near **0.5** means yes and no are roughly equally likely. It does not mean “somewhat” — for degree, use a `score`. * `choice` options and `score` levels must each describe a concrete situation and stand on their own. The question id is never shown to the model, so the instructions have to carry the whole meaning. The `confidence` on a `choice` or `score` is a second axis, not a restatement of the probability: the answer tells you *what*, confidence tells you *whether to act*. See [Confidence](https://docs.typesafe.ai/confidence), and [confidence-gated routing](https://docs.typesafe.ai/patterns/confidence-routing) for the pattern it enables. ## Good Fits * **Verification**: does this answer actually follow from the source it cites? * **Rating**: how severe is this report, how good is this draft, how funny is this joke * **Routing**: which handler, team, or tool should take this — with a confidence to gate on * **Screening**: does this content match a policy, and how clearly ## Embedding the Framework Running the Everruns Framework in your own application rather than on the platform? The same capability attaches to an agent you build yourself, and the decision tool is also callable directly with no agent at all. See [Direct decision](https://everruns.com/docs/framework/direct-model-calls/#decisions). ## Guardrails The same model backs Everruns [guardrails](https://everruns.com/docs/capabilities/guardrails/) when a `llm_judge` or `moderation` check sets `"engine": "jev"`. Instead of asking the utility model to write a verdict, the check gets a calibrated probability and your configured `threshold` decides — and every check on a stage is answered in a single call. That path uses a deployment-owned key (`UTILITY_TYPESAFE_API_KEY`), not your personal connection. ## Security * The API key is stored as a user connection and never exposed to the agent or written into session transcripts. * Content passed to `jev_decision` leaves the platform for TypeSafe, like any other integration that inspects content. Calls are capped at 20 questions and 32 KiB of content. * The content being judged is sent as **data**, and every question states so — a document that tries to instruct the model is being rated, not obeyed. ## Learn more The model and its concepts are TypeSafe’s, and their documentation is the reference for both: * [System One](https://docs.typesafe.ai/concepts/system-one) — the class of model, and how it differs from an LLM * [Primitives](https://docs.typesafe.ai/primitives) — [Noul](https://docs.typesafe.ai/primitives/noul), [Choice](https://docs.typesafe.ai/primitives/choice), [Score](https://docs.typesafe.ai/primitives/score), and [structured criteria](https://docs.typesafe.ai/primitives/advanced) * [State](https://docs.typesafe.ai/concepts/state) — what to send as the thing being judged * [Confidence](https://docs.typesafe.ai/confidence) — certainty as a second axis, distinct from the probability * [Patterns](https://docs.typesafe.ai/patterns) — including [speculative fan-out](https://docs.typesafe.ai/patterns/fan-out) and [confidence-gated routing](https://docs.typesafe.ai/patterns/confidence-routing) --- # Observability > Send Everruns session traces, token usage, and tool-call timings to your observability platform of choice. Source: Everruns emits structured events for every agent turn, model calls, tool invocations, retries, token usage, latency. The integrations in this section forward those signals to observability platforms so you can monitor agents in production, evaluate prompt changes, and debug failures with full trace context. ## Connect your organization and agents Use **Settings → Organization → Tracing** to connect multiple Braintrust projects and OpenTelemetry collectors. Choose organization defaults, then customize each agent from **More → Tracing**. See [Customer tracing destinations](https://everruns.com/docs/observability/destinations/) for setup, privacy controls, routing, and delivery troubleshooting. ## Investigate failed turns In the platform UI, each agent’s activity chart covers the last 24 hours, with one bar per hour. Hover or keyboard-focus the chart to confirm the time window. Click **1 failed** (or the corresponding failure count) to open the agent’s **Sessions** tab filtered to failures in that chart’s window. The filter uses the time a turn failed, so it includes sessions created earlier, archived sessions, and sessions that later recovered. Counts distinguish failed turns from affected sessions. Each card shows its current outcome and the latest matching failure. **View failure** opens that turn in **Trace**, selecting the error step when one was recorded. A failure can exist without a model or tool step; the Trace banner still identifies the failed turn. Use **With failed turns** in an agent’s Sessions tab to investigate failures over the last 24 hours, 7 days, or 30 days. Choose **All sessions** to clear the failure filter. For scripted investigation, run `everruns agents failures list `. Use `--after` and `--before` to choose a failure-time window, and `--limit` and `--offset` to page through matching sessions. ## Available Integrations For live execution inside the platform, use [Monitoring](https://everruns.com/docs/observability/monitoring/). It provides organization-scoped and platform-wide views of execution phases, worker ownership, and actor leases. * [OpenTelemetry](https://everruns.com/docs/observability/opentelemetry/), export traces over OTLP to any tracing backend. Spans follow the Gen-AI semantic conventions and the OpenInference conventions at once, so Grafana Tempo, Jaeger, Datadog, Langfuse, and Arize Phoenix all read them. * [Braintrust](https://everruns.com/docs/observability/braintrust/), LLM observability, evaluation, and trace visualization. Turn traces are grouped by session, with token usage, time-to-first-token, and tool execution times. ## Framework Applications Framework apps export the same traces from the `everruns` crate, behind the `otel` and `braintrust` Cargo features. See [Framework observability](https://everruns.com/docs/framework/observability/) for registering exporters and your own listeners on the Engine, and for flushing them on shutdown. ## Related * [Events](https://everruns.com/docs/features/events/), the streaming event protocol that backs every observability export. * [Environment Variables](https://everruns.com/docs/sre/environment-variables/), configure exporters, sampling, and OTLP endpoints. * [Runnable Framework examples](https://everruns.com/docs/framework/examples/), complete programs built on the `everruns` crate. --- # Braintrust > Send Everruns traces to Braintrust for evaluation and trace visualization. Source: ![Braintrust](https://everruns.com/docs/images/observability/braintrust-logo.png) Everruns integrates with [Braintrust](https://www.braintrust.dev/) to provide LLM observability, evaluation, and trace visualization for your agentic workflows. For organization and agent setup in the UI, use [Customer tracing destinations](https://everruns.com/docs/observability/destinations/). The environment configuration below controls the deployment’s separate platform exporter. ## What You Get * **Turn Traces Grouped by Session**: Keep one trace per turn while grouping the conversation by `metadata.session_id` * **Token Usage Tracking**: Monitor input/output tokens and prompt cache efficiency * **Performance Metrics**: Time-to-first-token, LLM call duration, tool execution times * **Durable-ish Delivery**: Buffered batch delivery with retries for rate limits, `5xx`, and timeout/connect failures * **Privacy Controls**: Raw content, thinking, tool args, and tool results are independently configurable ## Quick Start ### 1. Get Your API Key 1. Sign up at [braintrust.dev](https://www.braintrust.dev/) 2. Go to **Settings** → **API Keys** 3. Create a new API key ### 2. Configure Everruns Set environment variables: ```bash # Optional explicit switch export BRAINTRUST_ENABLED=true # Required export BRAINTRUST_API_KEY=sk-bt-your-api-key # Recommended: specify your project name export BRAINTRUST_PROJECT_NAME="My Project" # Conservative defaults export BRAINTRUST_RECORD_CONTENT=false export BRAINTRUST_RECORD_THINKING=none export BRAINTRUST_TOOL_ARGS_MODE=redacted export BRAINTRUST_TOOL_RESULTS_MODE=summary ``` | Variable | Required | Default | Description | | -------------------------------- | -------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BRAINTRUST_ENABLED` | No | enabled when API key is present | Explicit Braintrust on/off switch | | `BRAINTRUST_API_KEY` | Yes | - | API key from Braintrust settings | | `BRAINTRUST_PROJECT_NAME` | No | `My Project` | Project name for organizing traces | | `BRAINTRUST_PROJECT_ID` | No | - | Direct project UUID (skips name lookup) | | `BRAINTRUST_API_URL` | No | `https://api.braintrust.dev` | API base URL | | `BRAINTRUST_QUEUE_CAPACITY` | No | `1024` | Buffered event capacity before new exports are dropped | | `BRAINTRUST_MAX_BATCH_SIZE` | No | `50` | Max events per Braintrust insert call | | `BRAINTRUST_FLUSH_INTERVAL_MS` | No | `500` | Max delay before a partial batch flushes | | `BRAINTRUST_REQUEST_TIMEOUT_MS` | No | `10000` | Per-request timeout | | `BRAINTRUST_MAX_RETRIES` | No | `3` | Retries for `429`, `5xx`, and timeout/connect failures | | `BRAINTRUST_RETRY_BASE_DELAY_MS` | No | `250` | Initial retry backoff | | `BRAINTRUST_RETRY_MAX_DELAY_MS` | No | `5000` | Retry backoff cap | | `BRAINTRUST_RECORD_CONTENT` | No | `false` | Export raw turn and LLM text content | | `BRAINTRUST_RECORD_THINKING` | No | `none` | Export thinking as `none`, `summary`, or `full` | | `BRAINTRUST_TOOL_ARGS_MODE` | No | `redacted` | Export tool args as `full`, `redacted`, or `none`; also governs `executed_arguments`, the hook-rewritten arguments a tool span carries when a pre-tool hook changed the call | | `BRAINTRUST_TOOL_RESULTS_MODE` | No | `summary` | Export tool results as `full`, `summary`, `redacted`, or `none` | | `BRAINTRUST_DEBUG_PAYLOADS` | No | `false` | Print full outbound Braintrust payload JSON to local debug logs | ### 3. View Traces 1. Open the Braintrust dashboard 2. Navigate to your project 3. Go to **Logs** 4. Group or filter by `metadata.session_id` to reconstruct the full session timeline across turn traces ## Trace Hierarchy Each Everruns turn creates its own trace with the following structure: ```plaintext agent turn (root span) ├── reason (iteration 1) │ └── llm.generation (gpt-6.2-sol) ├── act (iteration 1) │ ├── tool.call (search) │ └── tool.call (fetch) ├── reason (iteration 2) │ └── llm.generation (gpt-6.2-sol) └── (no more tool calls - turn complete) ``` ### Span Types | Span | Type | Description | | -------------- | ------ | ------------------------------------- | | Agent Turn | `task` | Root span for the entire user request | | Reason | `task` | LLM reasoning phase (may iterate) | | Act | `task` | Tool execution phase | | LLM Generation | `llm` | Individual LLM API call | | Tool Call | `tool` | Individual tool execution | ## Session Grouping Everruns does not export one giant trace for the whole conversation. * Each turn remains its own Braintrust trace. * Every root turn span carries `metadata.session_id`. * Session lifecycle events (`session.started`, `session.activated`, `session.idled`) are exported as lightweight logs with the same `session_id`. * Root turn metadata also carries stable filtering fields when available, such as `input_message_id`, monotonic event ordering, deployment grade, session status, model/provider summary, retry info, and compaction info. Use Braintrust grouping, timeline, or thread views on `metadata.session_id` to analyze the session as a whole while keeping per-turn debugging sharp. ## Metrics Captured ### LLM Generations * `prompt_tokens` - Cache-inclusive input token count * `completion_tokens` - Output token count * `prompt_cached_tokens` - Input tokens read from prompt cache * `prompt_cache_creation_tokens` - Input tokens written to prompt cache * `time_to_first_token` - Time until first token received * `duration_ms` - Total LLM call duration * `actual_cost_usd`, `estimated_cost_usd`, `effective_cost_usd` - Cost provenance in metadata when known; missing prices are not reported as zero ### Tool Calls * `status` - Success/failure * `duration_ms` - Execution time * `error` - Failure marker; free-text detail only when the applicable content policy permits it ## Delivery Behavior * Exports enqueue into a bounded in-memory buffer. * The exporter flushes batches to `POST /v1/project_logs/{project_id}/insert`. * `429`, `5xx`, timeout, and connect failures are retried with jittered backoff. * If the queue fills, new events are dropped and the exporter logs the drop counter. * Framework applications that register `Braintrust::from_env()` and call `Engine::shutdown` wait for the final HTTP batch. A flush reports failure when events have already been dropped or batches failed; draining a queue is not proof of delivery. Dropping the listener drains queued work and releases its worker and credentials. This is best-effort delivery, not a disk-backed queue. ## Privacy Controls The Braintrust exporter defaults to conservative content handling: * raw turn and LLM text are off unless `BRAINTRUST_RECORD_CONTENT=true` * when raw content is off, the exporter emits structural metadata only; it does not emit truncated prompt/completion previews * free-text errors and cancellation reasons follow content policy because they may echo private inputs * extended thinking is off unless `BRAINTRUST_RECORD_THINKING` says otherwise * tool arguments default to `redacted` * tool results default to `summary` * tool arg/result modes still apply inside recorded LLM input/output payloads * full outbound payload logging is off unless `BRAINTRUST_DEBUG_PAYLOADS=true` ## Troubleshooting ### Traces Not Appearing 1. **Check API key**: Verify `BRAINTRUST_API_KEY` is set correctly 2. **Check project resolution**: If `BRAINTRUST_PROJECT_NAME` does not match an existing project, startup logs will show a project resolution failure 3. **Check exporter logs**: Look for rate-limit retries, timeout retries, queue drops, or permanent insert failures ### Session Views Are Fragmented 1. Confirm root turn spans include `metadata.session_id` 2. Group Braintrust logs by `metadata.session_id` 3. Check whether privacy controls removed content you expected; the default is conservative ## Links * [Braintrust Documentation](https://www.braintrust.dev/docs) * [API Reference](https://www.braintrust.dev/docs/api-reference/introduction) * [Insert Logs API](https://www.braintrust.dev/docs/api-reference/logs/insert-project-logs-events) --- # Customer tracing destinations > Connect organization and agent traces to Braintrust, Langfuse, LangSmith and OpenTelemetry collectors with explicit privacy and routing controls. Source: Connect your own tracing backends from **Settings → Organization → Tracing**. Organization administrators manage destinations and routing. Members can inspect non-secret destination metadata and routing. Self-hosted deployments must configure `SECRETS_ENCRYPTION_KEY` before creating connections. See [Environment variables](https://everruns.com/docs/sre/environment-variables/). Collector hosts must also be allowed by the deployment’s egress policy. ## Add a destination 1. Choose **Add destination** and give it a recognizable name. 2. Select **Braintrust**, **Langfuse**, **LangSmith**, or **OpenTelemetry / OTLP**. You can add multiple destinations using the same provider. 3. Enter an HTTPS endpoint. For Braintrust, enter the project UUID and API key. For OTLP, choose the authentication header your collector expects, or leave it empty for a collector that needs no authentication. Supported headers are `Authorization`, `X-API-Key`, and `Api-Key`. The exporter uses HTTP/protobuf and appends `/v1/traces` unless it is already present. For Langfuse, enter the project public key and secret key. Use the region’s full `/api/public/otel/v1/traces` HTTPS endpoint. Everruns supplies Basic authentication and the v4 ingestion header automatically. For LangSmith, enter a workspace-scoped API key, project name, and the full `/otel/v1/traces` endpoint for your region (self-hosted deployments may use `/api/v1/otel/v1/traces`). For agent-based LangSmith workspaces, use the environment’s `tracer_session_name` as the project name. Create the agent/environment in LangSmith first; Everruns does not provision it. 4. New destinations start with metadata only. After creation, use **Edit destination** to enable **Include messages and tool content** when your retention policy permits exporting inputs, outputs and tool arguments/results. **Include reasoning content** requires a separate opt-in. 5. Save, then use **Send test trace** from the destination menu. The test contains synthetic metadata. **Export accepted** means the receiver accepted the request, not that the provider has indexed it in its UI. Credentials are encrypted and never returned by the API. Editing a destination leaves stored credentials intact unless you replace authentication. Changing the receiver requires new authentication settings. Endpoints cannot contain URL credentials, queries or fragments. Host egress policy can block private networks or disallowed hosts; customer exports require DNS pinning. New destinations start **Unassigned**. Creating one does not export agent data. Native Langfuse and LangSmith destinations use OTLP/HTTP protobuf with provider span kinds and session correlation, alongside GenAI/OpenInference model, usage, content and error attributes. No collector or process-wide environment variables are required. LangSmith supports either a project name for project-based workspaces, or a registered LangSmith agent ID with its local/development/staging/production environment. These are receiver destinations, independent of the Everruns agent that inherits or overrides organization routing. The two receiver modes are mutually exclusive; each destination has its own exporter and request-level routing headers, so batches do not mix destinations. Regional/self-hosted endpoints remain explicit: switching provider or endpoint requires entering replacement credentials. Provider UI indexing and cost estimation remain receiver-specific; test-trace acceptance is not a live UI verification. See the [Langfuse OTLP reference](https://langfuse.com/integrations/native/opentelemetry) and [LangSmith OTLP reference](https://docs.langchain.com/langsmith/trace-with-opentelemetry). ## Choose routing Use **Edit defaults**, select destinations and **Save changes** to set organization defaults. From an agent’s **More → Tracing** drawer choose: * **Use organization defaults**: use the organization’s current defaults. * **Add to organization defaults**: send to defaults plus the selected destinations, deduplicated. * **Use selected destinations**: send only to the selected destinations. * **Turn off external tracing**: stop customer exports for this agent. You can select up to eight defaults and eight destinations in an agent policy. Each organization can configure up to 32 destinations. Changes apply to new turns, including new turns in existing sessions. A running turn keeps its initial routing. Guest responders use their own agent policy; child sessions resolve their own policy. Personal Chat and sessions descended from it are excluded. **Discard** abandons unsaved routing edits. **History** reviews saved routing; restores use revision checks. A stale Save or Undo requires reloading and reviewing the current configuration. Page-side Chat can draft routing for manual review; credentials and content-capture settings remain protected manual controls. Destination history restores its name and pause state while preserving current credentials, receiver, and content settings. ## Delivery and troubleshooting Exports use independent, bounded queues and retries. A slow or failing receiver does not stop agent execution or other destinations. Delivery is best effort: queue overflow, exporter limits, process restart or a routing lookup failure can lose events. A queued turn-start is omitted if its organization or agent policy changed after the turn began; destinations configured later are also excluded. New consent never applies backward to delayed starts. There is no historical replay or guaranteed delivery. After an exporter restart, already-running turns are omitted rather than re-routed under newer settings. The table shows receiver acceptance, safe failure messages and destination queue drops. Global router drops also have a server metric, `everruns_customer_tracing_router_dropped`. Enabled destinations with delivery failures contribute an organization health issue. **Pause destination** prevents subsequent sends, including queued retries, at the network boundary. Changing configuration or authentication also retires queued sends using the previous revision. An already in-flight request cannot be recalled. Remove a destination from all policies before deleting it; deletion leaves data already exported to the provider intact. Deployment-wide [OpenTelemetry](https://everruns.com/docs/observability/opentelemetry/) and [Braintrust](https://everruns.com/docs/observability/braintrust/) configuration continues independently. Customer settings do not change platform exporters. --- # Monitoring > Watch execution across thousands of sessions, map actor ownership to workers, and inspect durable leases as the fleet runs. Source: Monitoring shows how the execution fleet is working, with aggregate population counts and progressively narrower worker and actor detail. The overview keeps agent names, prompts, and tool arguments out of the display. ## Organization and platform views Open **Observability → Monitoring** to see the selected organization’s execution and actor ownership. Reading this view requires session-read permission. Platform operators open **System → Monitoring** for the cross-org view. This view also exposes worker capacity, reported load, and heartbeat freshness. Organization owners and admins cannot access this view unless they also have platform access. ## Execution **Flow** shows current sessions in runnable, model, tool, waiting, and setup phases. Measured connections show committed event rates over the last minute. Dashed connections illustrate the execution lifecycle. A turn can iterate between model and tools many times before completing. **Density** shows how that population changes over time. Each execution state has its own intensity scale. Select a time bucket to inspect an earlier population summary. **Pause** freezes the displayed snapshot while observations continue to collect. **Replay** retains up to fifteen minutes of population summaries collected while this view is open. History starts at the first successful snapshot; it does not invent earlier data. Historical worker maps are not inferred from today’s ownership. Return to **Live** for worker and actor inspection. ## Timeline **Timeline** shows recorded history instead of the current moment. Pick a range from 15 minutes to 30 days; the server records a sample every 10 seconds and keeps it permanently, so history exists before you open the page. * **Sessions and agents**: open (not archived) sessions, defined agents, and agents with a turn running. * **Working now**: turns running, averaged per bucket and split by phase, with a dashed line for the bucket’s peak. Deploys are marked. * **Turns** finished per bucket by outcome, and **Waiting for a worker**: the longest time a ready turn waited for a lease. * **Tool calls**, **Model spend**, **Errors**, and **Model latency** (p95). Click a bucket to see its numbers, or drag across any chart to select a range and zoom into it. The side panel lists the busiest agents, failed turns by cause, and failed tool calls by tool for the selection; **What failed** under the Errors chart opens the same breakdown in a panel. Each summary tile compares with the previous period of the same length. On the platform view, when sessions run on data plane v2 shards, the charts include them, and an **All / Workers / Shards** switch shows one execution path at a time. Workers are sampled every 10 seconds; each shard reports once a minute, so shard lines move in one-minute steps. An organization sees only the path it runs on: on a data plane, its sessions on shards, opening on Timeline without the Execution, Workers and Actors tabs or worker waits, which all read worker leases; otherwise the worker view, without shards. It never sees the shards themselves, which are shared. The platform view adds worker capacity on the working chart, a **Fleet** chart (server replicas, workers, shards, and shard nodes), the busiest shard node’s CPU and fullest node’s memory against their limits, shard leader changes and session moves, a load strip per worker (red above 90% of its slots), lease takeovers, and worker joins and departures. It ranks organizations by ID only. ## Shards The platform view has a **Shards** tab listing each data plane v2 shard from its newest minute report: nodes (and how many answered the leader), sessions, turns running, messages waiting, the busiest node’s CPU and fullest node’s memory, and admit p99. A shard with no report for three minutes is marked silent. Select a shard for its leader, log shipping p99, leader changes, moves, and charts of its load, CPU and memory, and turns over the range. Shards need no metrics database: the reports travel the shard’s existing feed and are kept with the rest of the history. For a closer look, point the server at a Prometheus-compatible store (VictoriaMetrics or Prometheus) that scrapes the shards’ `/metrics`: ```bash MONITORING_DETAIL=prometheus MONITORING_DETAIL_URL=http://victoriametrics:8428 ``` The selected shard then also shows its last hour by node, every 10 seconds: turns running and memory. The address is read from the environment only. Without it, or when the store does not answer, the tab says why and keeps the minute history. **System → Health** reports whether the minute history is still being recorded and whether the detail store answers. History from before recording started is rebuilt from turn records and drawn in grey: it has running turns and outcomes, but no phase split, queue, or worker load. Samples are taken every 10 seconds, so a spike shorter than that can be missed; turn counts are exact. ## Workers and actors **Workers** groups execution by worker, with organization-to-worker ownership mapping in the detail rail. Change group size to inspect individual workers or larger cohorts. Worker load includes background activities and differs from actor leases: a model phase may retain its lease while releasing a work slot. Parked, unleased sessions remain visible in Execution. **Actors** lists current session actors, with expired leases and the oldest runnable work first. Select one to inspect its holder, fence, lease deadline, last renewal, lease duration, inbox cursors, cancellation, ownership history, and recent trace-step timing. A sequence difference is not a pending-message count. Expiry is a lease observation and does not establish worker death. Ownership history is retained for one day. **Metrics** provides conventional event counts, rates, population trends, and lease health. Overview summaries refresh every second. Failed refreshes are marked stale rather than appearing healthy. ## API Use `GET /api/v1/monitoring` for the selected organization’s summary and `GET /api/v1/durable/monitoring` for platform-wide monitoring. Both are read-only. Use browser credentials or a full-access personal token; scoped personal tokens remain denied. Organization monitoring requires session-read permission, and fleet access requires platform authority. The adjacent `/actors` endpoints provide bounded, filtered pages and actor detail, and `/timeline` returns recorded history in buckets (`range` or `from`/`to`, optional `bucket` seconds) with `/timeline/window` for a selection’s busiest agents, failure causes, and failed tools. `GET /api/v1/durable/monitoring/shards` lists shards with their history. The [API reference](https://everruns.com/docs/api/) owns the request and response contracts. Monitoring complements [OpenTelemetry](https://everruns.com/docs/observability/opentelemetry/) and [Braintrust](https://everruns.com/docs/observability/braintrust/), which provide trace exports and provider-level diagnostics. --- # OpenTelemetry > Export Everruns agent traces over OTLP. Spans follow the OpenTelemetry Gen-AI and OpenInference conventions, so any tracing backend reads them. Source: Everruns turns every agent run into an OpenTelemetry trace and exports it over OTLP. Spans carry two attribute vocabularies at once, the [OpenTelemetry Gen-AI semantic conventions](https://github.com/open-telemetry/semantic-conventions-genai/tree/main/docs/gen-ai) and the [OpenInference conventions](https://arize-ai.github.io/openinference/spec/semantic_conventions.html), so one endpoint feeds general-purpose backends such as Grafana Tempo, Jaeger, and Datadog as well as LLM-native ones such as Arize Phoenix and Langfuse. For organization and agent setup in the UI, use [Customer tracing destinations](https://everruns.com/docs/observability/destinations/). The environment configuration below controls the deployment’s separate platform exporter. ## What You Get * **A trace per turn**: an `invoke_agent` root span named after your agent, with model calls, tool runs, and reasoning phases nested underneath * **Real timings**: spans start and end at the moment each event happened, so waterfalls show true model latency and tool duration * **Token and cost detail**: input, output, and prompt-cache tokens per call and per turn, plus cost where the provider reports it * **Tool visibility**: every tool call is its own span with name, description, call id, and outcome * **Failure detail**: a low-cardinality `error.type`, an error span status carrying a safe classification (the full message requires content capture), and an `exception` event * **Privacy by default**: prompts, completions, reasoning, and tool payloads are never exported unless you turn them on ## Quick Start ### 1. Point Everruns at a collector Set one variable. Any OTLP/HTTP endpoint works. ```bash # Local collector, Grafana Tempo, Datadog agent, ... export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 # Name the service in your traces export OTEL_SERVICE_NAME=everruns-server ``` Traces are exported over OTLP HTTP/protobuf. Point the variable at the base endpoint, usually port `4318`, and Everruns appends the `/v1/traces` path; a full signal URL is used as given. ### 2. Configure | Variable | Required | Default | Description | | ---------------------------------------------------- | -------- | ------------------------------------ | --------------------------------------------------------- | | `OTEL_EXPORTER_OTLP_ENDPOINT` | Yes | - | OTLP/HTTP endpoint. Tracing stays off while unset | | `OTEL_SERVICE_NAME` | No | `everruns-server`, `everruns-worker` | Service name on the spans | | `OTEL_SERVICE_VERSION` | No | - | Service version on the spans | | `OTEL_ENVIRONMENT` | No | - | Deployment environment label | | `OTEL_SDK_DISABLED` | No | `false` | Disable tracing without unsetting the endpoint | | `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | No | `false` | Export instructions, messages, tool arguments and results | | `EVERRUNS_TRACE_CONVENTIONS` | No | `gen_ai,openinference` | Which attribute vocabularies to write | ### 3. View traces Open your backend and look for the `invoke_agent` spans. In Arize Phoenix, point the same variable at Phoenix and its spans appear as AGENT, LLM, and TOOL rows with no extra configuration: ```bash export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:6006 ``` ## Trace Structure Each turn is one trace. Reasoning and acting phases give the trace its shape, and extended thinking sits inside the model call it belongs to: ```plaintext invoke_agent {agent name} (root, INTERNAL) ├── reason reasoning phase │ └── chat {model} model call (CLIENT) │ └── thinking extended thinking, when enabled ├── act tool execution phase │ ├── execute_tool {name} │ └── execute_tool {name} ├── reason │ └── chat {model} └── (no further tool calls, turn complete) ``` | Span | Kind | `gen_ai.operation.name` | `openinference.span.kind` | | --------------------------- | ---------- | ----------------------- | ------------------------- | | `invoke_agent {agent name}` | `INTERNAL` | `invoke_agent` | `AGENT` | | `chat {model}` | `CLIENT` | `chat` | `LLM` | | `execute_tool {name}` | `INTERNAL` | `execute_tool` | `TOOL` | | `reason`, `act`, `thinking` | `INTERNAL` | none | `CHAIN` | The reason, act, and thinking spans are Everruns phases rather than Gen-AI operations, so they carry no `gen_ai.operation.name` and backends do not count them as model calls. ## OpenTelemetry Gen-AI Support | | Supported | Attributes | | - | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ✅ | Agent span per turn | `gen_ai.agent.id`, `gen_ai.agent.name`, `gen_ai.agent.description` | | ✅ | Model call spans | `chat {model}`, CLIENT kind, real call duration | | ✅ | Provider and model identity | `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.response.id` | | ✅ | Finish reasons | `gen_ai.response.finish_reasons` as a string array | | ✅ | Token usage with cache split | `gen_ai.usage.input_tokens`, `output_tokens`, `cache_read.input_tokens`, `cache_write.input_tokens` | | ✅ | Request parameters | `gen_ai.request.temperature`, `max_tokens`, `reasoning.level`, `stream` | | ✅ | Streaming latency and compaction | `gen_ai.response.time_to_first_chunk`, `gen_ai.conversation.compacted` | | ✅ | Tool execution spans | `gen_ai.tool.name`, `gen_ai.tool.type`, `gen_ai.tool.call.id`, `gen_ai.tool.description` | | ✅ | Extended thinking | Nested inside the model call it belongs to | | ✅ | Errors | `error.type`, error span status, `exception` events | | ✅ | Conversation correlation | `gen_ai.conversation.id` on every span | | ✅ | Content capture (opt-in) | `gen_ai.system_instructions`, `gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.tool.definitions`, `gen_ai.tool.call.arguments`, `gen_ai.tool.call.result` | | ✅ | Accurate timestamps | Spans start and end at the times the events record | Input totals include uncached tokens plus cache reads and cache writes; cache attributes are subsets of that total. Sum model spans (`gen_ai.operation.name=chat`) for model usage or turn roots for turn totals. Summing both counts the same usage and cost twice. Not emitted yet: `server.address` and `server.port` on model calls, and parameter schemas inside `gen_ai.tool.definitions`. ## OpenInference Support | | Supported | Attributes | | - | -------------------------------- | ---------------------------------------------------------------------------------------- | | ✅ | Span kinds | `openinference.span.kind`: `AGENT`, `CHAIN`, `LLM`, `TOOL` | | ✅ | Session and virtual user | `session.id`, `agent.name`, `metadata` | | ✅ | Model identity | `llm.model_name`, `llm.provider`, `llm.system` | | ✅ | Token counts | `llm.token_count.prompt`, `.completion`, `.total` | | ✅ | Prompt cache detail | `llm.token_count.prompt_details.cache_read`, `.cache_write` | | ✅ | Cost | `llm.cost.total` in USD, when the provider reports it | | ✅ | Invocation parameters and tools | `llm.invocation_parameters`, `llm.tools.N.tool.json_schema` | | ✅ | Input and output values (opt-in) | `input.value`, `output.value`, with `input.mime_type` and `output.mime_type` | | ✅ | Flattened messages (opt-in) | `llm.input_messages.N.message.*`, `llm.output_messages.N.message.*`, tool calls included | | ✅ | Tool spans | `tool.name`, `tool.description`, arguments and results as input and output values | | ✅ | Errors | Error span status with `exception` events | | ✅ | Phoenix out of the box | Point the OTLP endpoint at Phoenix, nothing else to configure | ## Everruns Attributes Spans also carry a few Everruns-specific attributes under their own namespace, so they never collide with either convention: | Attribute | Spans | Description | | ------------------------------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `everruns.turn.id`, `everruns.exec.id`, `everruns.input_message.id` | All | Correlation ids that match the [event stream](https://everruns.com/docs/features/events/) | | `everruns.phase` | `reason`, `act`, `thinking` | Which phase the span represents | | `everruns.turn.iterations`, `everruns.turn.tool_call_count`, `everruns.turn.llm_call_count`, `everruns.turn.status` | `invoke_agent` | Turn counters and outcome | | `everruns.turn.stop_reason` | `invoke_agent` | How the turn’s final model call ended (`stop`, `length`, …) | | `everruns.tool.status`, `everruns.tool.capability.id` | `execute_tool` | Tool outcome and the capability that provided it | | `everruns.tool.executed_arguments`, `everruns.tool.executed_arguments_truncated` (opt-in) | `execute_tool` | The arguments the tool actually ran with, present only when a pre-tool hook rewrote the call. Bounded, with credential values redacted; emitted only with content capture | | `everruns.usage.cost_usd` | `chat`, `invoke_agent` | Cost when known | | `everruns.llm.retry.attempts`, `everruns.llm.retry.total_wait_ms` | `chat` | Provider retries behind a single call | | `everruns.llm.finish_reason`, `everruns.llm.provider_finish_reason` | `chat` | Normalized finish reason as a scalar, and the provider’s own stop reason verbatim (`max_tokens`, `MAX_TOKENS`, …) | | `everruns.llm.tool_calls_dropped`, `everruns.llm.tool_calls_truncated_executed` | `chat` | Tool calls discarded because the response was cut off (or their arguments were not valid JSON), and complete calls run from a truncated response; present only when non-zero | | `everruns.llm.truncation_gate` | `chat` | `retried` or `failed` when the [output truncation](https://everruns.com/docs/capabilities/output-truncation/) policy acted on dropped calls | | `everruns.span.orphaned`, `everruns.span.unterminated` | Any | Diagnostics: a span rebuilt from a terminal event, or closed because its turn ended first | ## Choosing Conventions Both vocabularies are written by default. Narrow to one when a backend only reads one and you want smaller spans: ```bash # OpenTelemetry Gen-AI only (Tempo, Jaeger, Datadog, Langfuse) export EVERRUNS_TRACE_CONVENTIONS=gen_ai # OpenInference only (Arize Phoenix) export EVERRUNS_TRACE_CONVENTIONS=openinference ``` Span names, kinds, and hierarchy are the same either way; only the attributes differ. An unrecognized value falls back to writing both. ## Content Capture Prompts, completions, reasoning, and tool payloads are **not** exported by default. Turn them on with the standard OpenTelemetry variable: ```bash export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true ``` With capture on: * model call spans carry `gen_ai.system_instructions`, `gen_ai.input.messages`, `gen_ai.output.messages`, and `gen_ai.tool.definitions` in the conventions’ `{role, parts}` JSON, plus the OpenInference `input.value` and `output.value` and the flattened `llm.input_messages.N.message.*` keys * tool spans carry their arguments and results * the turn root carries the user’s message and the final answer * the thinking span carries the model’s reasoning text With capture off, error status descriptions and exception messages contain only the error classification. With capture on, detailed errors may include provider response bodies or tool output; treat them as sensitive content. Two details worth knowing. Everruns keeps the agent’s instructions separate from the conversation, so system messages are exported as `gen_ai.system_instructions` and left out of `gen_ai.input.messages`. Image bytes are never copied into a span; an image becomes a reference that names its media type only. Treat this as a data-retention decision. Everything captured leaves your deployment for whatever backend the OTLP endpoint points at. ## Troubleshooting ### No traces appear 1. Confirm `OTEL_EXPORTER_OTLP_ENDPOINT` is set and reachable from the server and worker processes; without it, tracing is off and startup logs say so 2. Confirm the endpoint speaks OTLP over **HTTP**, typically port `4318`, not the gRPC port `4317` 3. Check startup logs for `OpenTelemetry tracing enabled` with your endpoint, or a warning that the exporter failed to initialize 4. Confirm `OTEL_SDK_DISABLED` is not set to `true` ### Traces appear but spans look empty 1. Prompts and completions require `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true`; without it, spans carry structure and metrics only, which is the default 2. If your backend reads only one vocabulary, check `EVERRUNS_TRACE_CONVENTIONS` has not been narrowed to the other one ### Turns are split across traces Each turn is deliberately its own trace. Group by `gen_ai.conversation.id`, or `session.id` in Phoenix, to follow a whole session. ## Related * [Braintrust](https://everruns.com/docs/observability/braintrust/), LLM observability and evaluation with a dedicated exporter * [Events](https://everruns.com/docs/features/events/), the event stream every exporter is built on * [Environment Variables](https://everruns.com/docs/sre/environment-variables/), the full operator reference --- # Model Providers > Connect Everruns to OpenAI, Anthropic, Google Gemini, Meta, Mistral AI, AWS Bedrock, OpenRouter, Fireworks AI, Cloudflare and Vercel AI Gateway, and more. Source: A **provider** is an organization-scoped account on an AI model vendor, OpenAI, Anthropic, AWS Bedrock, OpenRouter, and others. You configure a provider once with credentials and connection settings, and it powers the models your agents run on. Everruns abstracts every vendor behind one uniform driver interface, so the same agent, prompt, and capabilities run unchanged whether the model is served by OpenAI, Claude, Gemini, or any OpenAI-compatible endpoint. ## Supported providers | Provider | Driver | Notes | | ------------------------------------------------------------------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | [OpenAI](https://everruns.com/docs/providers/openai/) | `openai`, `openai_completions` | Responses API (recommended) and Chat Completions. Also drives OpenAI-compatible endpoints via a base URL. | | [Azure OpenAI](https://everruns.com/docs/providers/azure-openai/) | `azure_openai` | OpenAI models deployed in your Azure OpenAI resource. A dedicated provider type. | | [Anthropic](https://everruns.com/docs/providers/anthropic/) | `anthropic` | Claude models via the Messages API, with extended thinking. | | [Google Gemini](https://everruns.com/docs/providers/gemini/) | `gemini` | Gemini 4 Hydrogen, Neon, Carbon, and Argon with long decode, reasoning, and implicit caching; explicit caching on supported Gemini models. | | [AWS Bedrock](https://everruns.com/docs/providers/bedrock/) | `bedrock` | Models hosted on Amazon Bedrock via the `ConverseStream` API. | | [OpenRouter](https://everruns.com/docs/providers/openrouter/) | `openrouter` | One key for a large multi-vendor catalog, with provider routing controls. | | [Microsoft MAI](https://everruns.com/docs/providers/mai/) | `mai` | Microsoft MAI models via Azure AI Foundry, with API-key or Entra ID (OAuth) auth. | | [Fireworks AI](https://everruns.com/docs/providers/fireworks/) | `fireworks` | Fast, low-cost inference for open models (Llama, Qwen, DeepSeek, Kimi, GLM, gpt-oss, …), with automatic model discovery. | | [Mistral AI](https://everruns.com/docs/providers/mistral/) | `mistral` | Mistral Large, Medium, Small and Codestral from La Plateforme, with reasoning and automatic model discovery. | | [Meta](https://everruns.com/docs/providers/meta/) | `meta` | Muse Wonder, Muse Spark and Muse Ember through Meta’s stateful, OpenAI-compatible Responses API. | | [Cloudflare AI Gateway](https://everruns.com/docs/providers/cloudflare/) | `cloudflare` | Many upstream vendors plus Cloudflare’s own Workers AI models behind one account token. | | [Vercel AI Gateway](https://everruns.com/docs/providers/vercel/) | `vercel` | Many upstream vendors behind one Vercel endpoint, over the Open Responses API. | Need a vendor that isn’t listed? Any OpenAI-compatible endpoint works through the [OpenAI](https://everruns.com/docs/providers/openai/) provider with a custom base URL (use the dedicated [Azure OpenAI](https://everruns.com/docs/providers/azure-openai/) provider for Azure deployments), and embedders can register additional drivers through the platform definition. ## Configure a provider Providers are managed by organization admins: 1. Go to **Settings** → **Providers**. 2. Click **Add provider** and choose the provider type. 3. Enter the credentials (API key, or the provider-specific fields described on each provider’s page). Credentials are validated before they are saved. 4. Save. Everruns discovers the provider’s available models and makes them selectable for agents and sessions. You can configure more than one provider for the same vendor, for example two Azure OpenAI regions, or a direct OpenAI key alongside an OpenRouter key. ## Providers vs. connections Providers and [connections](https://everruns.com/docs/integrations/) look similar but are deliberately separate: | | **Provider** | **Connection** | | ------------- | ------------------------------- | ------------------------------------------------------- | | Scope | Organization | User | | Purpose | Infrastructure that runs agents | A user’s identity on an external service, used by tools | | Configured in | Models → Providers | Settings → Connections | | Examples | OpenAI, Anthropic, Bedrock | Daytona, GitHub, Slack | Use a provider to decide **which model runs your agents**. Use a connection to give an agent access to an **external tool or service**. ## Models and switching providers Agents and sessions bind to a specific model on a specific provider. Because the driver interface is uniform, you can move an agent from one provider to another without rewriting prompts or capabilities. See [Migrate between providers](https://everruns.com/docs/how-to/migrate-providers/) for the model-resolution rules and the API calls to add a provider, switch an agent’s default model, or run an A/B comparison per session. ## Credential security * Credentials are encrypted at rest with AES-256-GCM envelope encryption. * Credential values are never returned by the API, only a “configured” flag is exposed. * Resolution is **fail-closed**: each organization resolves its own configured credentials. A turn with no configured provider fails with a clear error rather than running on another organization’s credentials. ## Organization research model Under **Models → Defaults**, the **Research model** row names the organization’s strongest model for hard reasoning and long research. Agents set to **Organization research model** in their model picker run on it, so moving every research agent to a new flagship is one change. Left on **Automatic**, it resolves when used: Anthropic’s recommended research model (Claude Fable 5.2) when an Anthropic provider is connected, else OpenAI’s (GPT-6.2 Astra), else another connected provider’s recommendation, else the default model. The row shows what Automatic picks today. Use `PATCH /v1/orgs/{org_id}` to set `research_model_id`, or `null` to return to Automatic. The response’s `effective_research_model_id` is the model it resolves to now. An agent follows it with `model_role: "research"`, which replaces `default_model_id`: ```bash everruns agents update agent_01h9 --name researcher --instructions "Research and cite sources" --model-role research ``` ## Organization coding model Under **Models → Defaults**, the **Coding model** row picks the model for agents on the Coding harness that set no model of their own. Left unset, they use the default model. Use `PATCH /v1/orgs/{org_id}` with `coding_model_id`, or `null` to clear it. ## Model presets A model preset is a named set of models, one for each job: Default, Chat, Coding, Research, Small and Decision. The organization defaults stay what every agent uses; a preset is an alternative set an agent can pick under **Models from** on its page. **Models → Presets** lists them: * **Automatic**: the best usable model for each job across your connected providers, following each provider’s recommended models. * **One preset per connected provider**, such as **OpenAI** or **Gemini**, filled from that provider’s recommended models. These are read only and follow new recommendations. If a recommended model is not enabled in your organization, the provider’s next recommended model is used and marked. * **Your own presets**: start blank or duplicate any preset, then change jobs one at a time. A job left as **Organization default** follows the Defaults tab. An agent’s own default model still wins for its turns. On a preset, a research agent uses the Research job and a Coding harness agent the Coding job; other agents use Default. **Copy to organization defaults** writes a preset’s models into the Defaults tab in one step. Presets work the same from the API, MCP and the CLI: ```bash everruns model-presets list everruns model-presets create --name "Cheap council" --from provider:gemini everruns agents update agent_01h9 --name reviewer --instructions "Review the diff" --model-preset provider:gemini everruns model-presets apply provider:gemini ``` ## Organization small-model default Under **Models → Defaults**, admins can select a **Small model** for lightweight work. This is a shared chat model on a specific provider, independent of the main chat and Decisions defaults. Personal providers and Decisions models cannot be selected here. [Automatic session titles](https://everruns.com/docs/capabilities/automatic-session-titles/) use this setting by default. Individual capabilities can select another model or always inherit the session model. Leaving or clearing Small model means title generation inherits the session model. Setting a default does not enable any capability. Use `PATCH /v1/orgs/{org_id}` to set `small_model_id` to a model’s public ID, or `null` to clear it. Omitted fields remain unchanged. A disabled or unavailable selection stays selected and skips generation without electing a replacement; deleting its model clears the selection. Requests use the selected provider’s organization credentials and count toward session usage and budgets. --- # Anthropic > Run Everruns agents on Anthropic Claude models via the Messages API, with streaming, tool use, and extended thinking. Source: Everruns runs agents on [Anthropic](https://www.anthropic.com/) Claude models through the Claude Messages API, mapping its provider-neutral messages, tools, and reasoning onto the Anthropic wire format. ## What you get * **Claude Messages API** streaming. * **Tool use** mapped to provider-neutral Everruns tools. * **Extended thinking**: adaptive thinking on recent Claude families and budget-based thinking on older ones, with the chain-of-thought signature preserved across multi-turn conversations. * **Prompt caching** via bounded `cache_control` breakpoints on stable, high-value sections of the request. * **Fast mode** on Claude Opus 5.5, Fable 5.2 and Mythos 5.2. ## Configure in Everruns 1. Go to **Settings** → **Providers** and click **Add provider**. 2. Choose **Anthropic**. 3. Paste your Anthropic API key. Get one from the [Anthropic Console](https://console.anthropic.com/). 4. Save. Everruns discovers available Claude models automatically. ### Claude Max and Team API credits Claude Max and Team plans include monthly Claude API credits. They land in the Anthropic Console organization you link to your plan, so any API key from that organization spends them first, before purchased credits. To run Everruns agents on those credits, create the key in the linked organization and add it as described above. Nothing else in Everruns changes. Everruns does not offer signing in with a Claude.ai account: Anthropic does not allow third-party products to use Claude.ai login or plan usage limits. See [API credits for Max and Team plans](https://platform.claude.com/docs/en/about-claude/api-credits-for-subscribers) for eligibility, amounts, and how to link the organization. ## Message threads (beta) Add the **Claude Message Threads** capability (`claude_message_threads`) to an agent or harness to opt in. It uses Anthropic’s [Messages API threads](https://platform.claude.com/docs/en/build-with-claude/message-threads) to send only the new messages after a completed response. Existing agents keep sending full history unless this capability is enabled. ```json { "ref": "claude_message_threads" } ``` In the Framework (with the `anthropic` feature): ```rust use everruns::{Agent, providers::anthropic::Anthropic}; fn main() -> Result<(), Box> { let _agent = Agent::builder() .provider(Anthropic::from_env()?) .model("claude-sonnet-5-5") .capability("claude_message_threads") .build()?; Ok(()) } ``` Everruns remains the source of truth for conversation history. A thread expires about five minutes after its last request. Missing or already-used thread state causes one replay of the full transcript in a new thread. A thread-specific unsupported-request error falls back to a normal Messages request. Other errors retain their normal handling. Continuation state is held only in a bounded process-local cache. Worker changes, restarts, cache eviction, edits, changed settings or credentials, and concurrent branches can start fresh threads. A partial or cancelled response never advances thread state. Tool results are supported; native compaction and opaque compacted prefixes use the existing full-history path. Batch requests stay unthreaded. Changes to a system prompt on every turn can prevent reuse. This is separate from [prompt caching](https://everruns.com/docs/capabilities/prompt-caching/): threads reduce uploaded request history, but do not change token pricing or rate limits. Keep prompt caching enabled independently when desired. **Data retention:** this beta is not eligible for zero data retention or HIPAA. Anthropic temporarily holds the conversation, system prompt, and tools, and states that it deletes thread state within one hour of last use. Enable the capability only when this retention is acceptable for your workload. Low-level driver callers can set `config.driver_options["anthropic/message_threads"] = serde_json::json!(true)`. Supply a stable, unique `config.metadata["session_id"]` and the complete transcript on every call, including assistant content and tool calls. Calls without a session scope stay unthreaded. Other provider drivers ignore this Anthropic option. ## Models Anthropic’s `/v1/models` endpoint returns capability metadata, which Everruns merges with its built-in model profiles. Hardcoded profiles take precedence for cost data; discovered data fills gaps for newer models. `max_tokens` is required on every Anthropic request, so Everruns always resolves a value from the model profile (falling back to a safe default) and will retry once with a lower limit if a stale profile causes the provider to reject it. Thinking counts toward `max_tokens`. When you set `max_tokens` yourself, Everruns preserves it as a hard limit on all generated tokens, including thinking. When the limit cannot accommodate thinking, the driver omits thinking rather than exceed the limit. On models that always think (Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.x), omitting it would run thinking at the provider’s default effort, so the driver keeps it and lowers the effort to `low` instead. A very small limit on those models can still be spent on thinking; give them room for the answer. Claude models that always think (Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.x) always get an explicit effort: the model’s default when you choose none, and `low` when you choose `none`. These and the other adaptive-thinking models reject assistant prefill, so a conversation must end with a user or tool message. ## Fast mode Claude Opus 5.5, Claude Fable 5.2 and Claude Mythos 5.2 offer a Fast speed next to Standard. Fast runs the same model with faster output at 2x the Standard price (Opus 5.5: $8 / $40 per million input / output tokens; Fable 5.2 and Mythos 5.2: $16 / $80). Choose it with the turn’s speed control (`fast`, or `priority`, which Everruns treats as the same tier); usage is priced at the speed Anthropic reports serving. Switching speed starts a new prompt cache. Fast mode is only on the first-party Anthropic provider. Batch requests always run at Standard speed. Opus 5 and Opus 4.8 fast mode is a research preview behind a beta flag, so Everruns does not offer it. ## Links * [Anthropic](https://www.anthropic.com/) * [Anthropic Console](https://console.anthropic.com/) * [API credits for Max and Team plans](https://platform.claude.com/docs/en/about-claude/api-credits-for-subscribers) * [`everruns-drivers` on crates.io](https://crates.io/crates/everruns-drivers), feature `anthropic` * [Migrate between providers](https://everruns.com/docs/how-to/migrate-providers/) --- # Azure OpenAI > Run Everruns agents on OpenAI models deployed in Azure OpenAI, using a dedicated provider type with your resource endpoint and key. Source: [Azure OpenAI](https://azure.microsoft.com/products/ai-services/openai-service) serves OpenAI models from your own Azure resource. Everruns ships a dedicated `azure_openai` provider type, distinct from the [OpenAI](https://everruns.com/docs/providers/openai/) provider, so Azure deployments resolve with the right endpoint and model behavior rather than being configured as a generic OpenAI base-URL override. ## What you get * **Azure OpenAI Responses API** through your Azure resource endpoint. * **Stateful continuation and context compaction**: Azure OpenAI hosts are recognized as stateful, like `api.openai.com`. * **Streaming, tool calls, and reasoning** mapped to provider-neutral Everruns types. ## Configure in Everruns 1. Go to **Settings** → **Providers** and click **Add provider**. 2. Choose **Azure OpenAI** (not plain OpenAI). 3. Set the **base URL** to your Azure OpenAI resource endpoint. 4. Paste the API key for your Azure OpenAI resource. 5. Save. Note that Azure model availability depends on the deployments you have created in your resource. ## Models Azure deployment names are operator-chosen, so a deployment whose name does not match a known model profile falls back to a minimal profile. Capability and cost metadata for recognized models come from Everruns’ built-in model profiles. ## Links * [Azure OpenAI Service](https://azure.microsoft.com/products/ai-services/openai-service) * [Azure AI Foundry](https://ai.azure.com/) * [Migrate between providers](https://everruns.com/docs/how-to/migrate-providers/) --- # AWS Bedrock > Run Everruns agents on models hosted in Amazon Bedrock via the ConverseStream API, with AWS credential and region resolution. Source: Everruns runs agents on models hosted in [Amazon Bedrock](https://aws.amazon.com/bedrock/) through the Bedrock Runtime `ConverseStream` API, mapping its provider-neutral messages, tools, and reasoning onto the Bedrock wire format. ## What you get * **Bedrock Runtime `ConverseStream`** streaming. * **Tool calls and reasoning** mapped to provider-neutral Everruns types. * **AWS credential and region** resolution from explicit fields. ## Configure in Everruns 1. Go to **Settings** → **Providers** and click **Add provider**. 2. Choose **AWS Bedrock**. 3. Enter your AWS credentials as separate fields: * **Access key ID** * **Secret access key** * **Region** (e.g. `us-east-1`) * **Session token** (optional, for temporary credentials) 4. Save. Make sure the models you want are enabled in your Bedrock account. Unlike most providers, Bedrock uses a multi-field credential rather than a single API key, so each field has its own input. ## Models Enable the model access you need in the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/) first. Everruns resolves Bedrock model ids to its built-in model profiles for capability and cost metadata. ## Links * [Amazon Bedrock](https://aws.amazon.com/bedrock/) * [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/) * [`everruns-drivers` on crates.io](https://crates.io/crates/everruns-drivers), feature `bedrock` * [Migrate between providers](https://everruns.com/docs/how-to/migrate-providers/) --- # Cloudflare AI Gateway > Run Everruns agents through Cloudflare's AI REST API, reaching many upstream providers and Cloudflare's own Workers AI models with one account token. Source: Everruns runs agents through [Cloudflare’s AI REST API](https://developers.cloudflare.com/ai-gateway/usage/rest-api/), which fronts many upstream model providers and Cloudflare’s own Workers AI models behind one account-scoped, OpenAI-compatible endpoint. Every call routes through an AI Gateway for caching, rate limiting, and logging. ## What you get * **Many vendors, one token**: OpenAI, Anthropic, Google, xAI and the rest of the catalog, plus Workers AI models, from a single Everruns provider. * **No upstream keys**: Cloudflare authenticates and bills the whole call against your account, so there are no per-vendor API keys to manage. * **Gateway controls**: response caching, rate limiting, retries, and per-request logging applied by the gateway the call routes through. * **Full chat capabilities**: streaming, tool/function calling, and structured output, through the same uniform driver as every other provider. * **Workers AI model discovery**: the `@cf/` catalog is synced with its advertised context windows and tool-calling support, so those ids appear in the model pickers without being typed by hand. ## Configure in Everruns 1. Create an API token with the **Account** → **Workers AI** → **Read** permission in the [Cloudflare dashboard](https://dash.cloudflare.com/profile/api-tokens). 2. Go to **Settings** → **Providers** and click **Add provider**. 3. Choose **Cloudflare AI Gateway**. 4. Enter: * **API Token** — the token from step 1. * **Account ID** — the account it belongs to. * **Gateway name** — optional. Calls route through the account’s default gateway when it is unset. 5. Save. Everruns derives the endpoint from the account id: ```plaintext https://api.cloudflare.com/client/v4/accounts//ai/v1 ``` Set a base URL only to route through a proxy in front of Cloudflare; it replaces the derived one. ## Models Model ids are namespaced and passed through unchanged: * Third-party: `openai/gpt-6-luna`, `anthropic/claude-opus-5` — see the [upstream providers AI Gateway supports](https://developers.cloudflare.com/ai-gateway/usage/providers/). * Workers AI: `@cf/meta/llama-3.3-70b-instruct-fp8-fast` — see the [Workers AI model catalog](https://developers.cloudflare.com/workers-ai/models/). Which third-party models a gateway can reach depends on the upstreams Cloudflare has enabled for your account, so verify an id with a real request rather than assuming the catalog. Third-party models are billed to your Cloudflare account and return `402` (“Insufficient balance”) until it is funded or you configure BYOK. Workers AI models draw on the account’s own allocation instead. Model sync covers the Workers AI half of the catalog: Everruns reads Cloudflare’s model search endpoint and keeps its text-generation models, which arrive with the context window and tool-calling support Cloudflare advertises. Third-party models are never listed — which ones an account can reach depends on what it can bill — so add those by id. Everruns matches a namespaced id against its model profile registry, so a model it recognizes still gets its capability and cost metadata. ## Why Chat Completions Cloudflare’s REST API offers four formats. Everruns uses `/ai/v1/chat/completions` because it is the only one that serves the whole catalog and streams: | Endpoint | Why not | | ------------------ | ----------------------------------------------------------------------------------- | | `/ai/v1/responses` | Rejects Workers AI models — they are not translated into the Responses shape | | `/ai/run` | Cannot stream: with `stream: true` it returns an empty JSON body rather than events | | `/ai/v1/messages` | Excludes Workers AI models | The older `gateway.ai.cloudflare.com/.../compat/chat/completions` endpoint is deprecated by Cloudflare for single-model calls and kept only for dynamic routes (`dynamic/{route}`), which this provider does not target. ## Links * [Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/) * [AI Gateway REST API](https://developers.cloudflare.com/ai-gateway/usage/rest-api/) * [Workers AI models](https://developers.cloudflare.com/workers-ai/models/) * [AI Gateway providers](https://developers.cloudflare.com/ai-gateway/usage/providers/) * [`everruns-drivers` on crates.io](https://crates.io/crates/everruns-drivers) * [Migrate between providers](https://everruns.com/docs/how-to/migrate-providers/) --- # Fireworks AI > Run Everruns agents on open models hosted by Fireworks AI (Llama, Qwen, DeepSeek, Kimi, GLM, gpt-oss), with automatic model discovery. Source: Everruns runs agents on [Fireworks AI](https://fireworks.ai/) through its OpenAI-compatible Chat Completions API. Fireworks serves frontier **open models**: Llama, Qwen, DeepSeek, Kimi, GLM, gpt-oss, and more, on a fast, cost-efficient inference platform, so the same Everruns agent, prompt, and capabilities run unchanged on open weights. ## What you get * **One key, many open models**: a single provider exposing Fireworks’ serverless model catalog. * **Automatic model discovery**: Fireworks’ `/models` endpoint advertises rich metadata (chat, tool calling, image input, context window), which Everruns parses into capability profiles on sync, so tool and vision support surface correctly per model. * **Full chat capabilities**: streaming, tool/function calling, vision, and structured output, through the same uniform driver as every other provider. * **Host-gated discovery**: model sync runs only against Fireworks’ own host, so a custom proxy base URL is never probed. ## Configure in Everruns 1. Go to **Settings** → **Providers** and click **Add provider**. 2. Choose **Fireworks AI**. 3. Paste your Fireworks API key. Create one from the [Fireworks API keys page](https://fireworks.ai/account/api-keys). 4. Save. Everruns discovers available models and their capability profiles automatically. You can optionally set a base URL to route through a proxy; leave it blank to use Fireworks’ hosted API (`https://api.fireworks.ai/inference/v1`). ## Models Fireworks model ids are namespaced, for example `accounts/fireworks/models/llama-v3p1-70b-instruct`. After a sync, models appear in the agent and session model pickers with their discovered capabilities. Only chat models are imported, image and other non-chat endpoints are filtered out. ## Links * [Fireworks AI](https://fireworks.ai/) * [Fireworks docs](https://docs.fireworks.ai/) * [`everruns-drivers` on crates.io](https://crates.io/crates/everruns-drivers), feature `fireworks` * [Migrate between providers](https://everruns.com/docs/how-to/migrate-providers/) ## Native Framework batches Enable the `fireworks` Cargo feature of `everruns` for direct offline model requests through [Batch Model Requests](https://everruns.com/docs/framework/batch-model-requests/). Fireworks uses native datasets and batch jobs; configure the account and trusted artifact origins explicitly. Cancellation is unsupported; it never substitutes deletion. The API is on `main`; published `0.49.0` does not include it. Use the guide’s Git dependency until a release includes this API. --- # Google Gemini > Run Everruns agents on Google Gemini models, including the Gemini 4 family, with streaming, tool calls, reasoning, context caching, and long decode. Source: Everruns runs agents on [Google Gemini](https://ai.google.dev/) models, implementing the provider-neutral driver contract over the Gemini API. ## What you get * **Interactions API** streaming, with the conversation kept on Google’s side between turns (see [Server-kept conversation](#server-kept-conversation)). * **Gemini 4 long decode** (Hydrogen, Neon, Carbon, Argon): one response can continue across requests with a shared output budget. * **Tool calls and reasoning** mapped to provider-neutral Everruns types. * **Native computer use** on Gemini 4: the [computer use](https://everruns.com/docs/capabilities/computer-use/) capability hands Gemini its built-in `computer_use` tool on Google’s own endpoint. * **Context caching**: explicit caching via `cachedContent` when a cached-content resource is supplied, otherwise Gemini’s default implicit caching on supported models. ## Configure in Everruns 1. Go to **Settings** → **Providers** and click **Add provider**. 2. Choose **Google Gemini**. 3. Paste your Gemini API key. Get one from [Google AI Studio](https://aistudio.google.com/apikey). 4. Save. Everruns discovers available Gemini models automatically. ## Models | Model | Best for | Thinking levels | Price per 1M tokens (input / output / cached) | | ------------------- | ----------------------------------------- | ------------------------ | -------------------------------------------------------------------- | | `gemini-4-hydrogen` | Everyday agent work; fastest and cheapest | low, medium, high, xhigh | $1.50 / $7.50 / $0.075 | | `gemini-4-neon` | Complex software engineering | low, medium, high, xhigh | $3.00 / $15.00 / $0.15 | | `gemini-4-carbon` | Hardest reasoning and research | low, medium, high | $2.00 / $10.00 / $0.10 until 30 November 2026, then $4 / $20 / $0.20 | | `gemini-4-argon` | The first Gemini 4 model | low, medium, high | $2.00 / $10.00 / $0.10 until 30 November 2026, then $4 / $20 / $0.20 | Gemini 4 Hydrogen, Neon, Carbon, and Argon are seeded and enabled; Hydrogen and Neon are favourites. New Gemini setups prefer Hydrogen when choosing an organisation default; existing defaults stay selected. The provider recommends Neon for coding agents and Carbon for research. Gemini models resolve to Everruns’ built-in model profiles for capability and cost metadata. Gemini 4 models default to 65,536 output tokens. Other Gemini models resolve their default from the model profile, falling back to a safe value. ## Server-kept conversation On Google’s own endpoint, agent turns use Gemini’s [Interactions API](https://ai.google.dev/gemini-api/docs/interactions), the interface Google recommends since June 2026. Google stores each interaction and Everruns keeps its id. The next model call sends that id and only what happened since the model last answered, such as tool results and new messages. The earlier transcript and its thought signatures are not sent again, so long tool loops send much less per call and Google’s implicit cache covers the stored prefix. The system prompt, tools and thinking settings travel with every call, so a change to the agent applies on the next call. When the stored interaction is gone (Google keeps it 55 days on paid projects and one day on the free tier, and you can delete it in AI Studio’s Logs), Everruns sends the whole transcript once and continues from the new interaction. Stored interactions appear in AI Studio’s Logs for the API key’s project. Calls that need a feature Interactions does not offer yet use `generateContent` and resend the transcript as before: batch requests, an explicit cached-content resource, long decode above 65,536 output tokens, and providers configured with a custom base URL. ## Long decode For any Gemini 4 model, set `max_tokens` above 65,536 to let a single response continue across multiple Gemini API requests. In an agent package, use the top-level `max_output_tokens`; the built-in Gemini 4 profiles permit up to 1,048,576 tokens. Input, thinking, and output share that window, so leave room for the prompt. The default remains 65,536. ```rust use everruns_contracts::{LlmCallConfig, ReasoningEffort}; let mut config = LlmCallConfig::new("gemini-4-neon"); config.max_tokens = Some(100_000); config.reasoning_effort = Some(ReasoningEffort::High); ``` Everruns follows continuation tokens automatically, streams text and reasoning across the hops, and returns one completion. Usage sums the final counts from each hop, including billed thinking and repeated input. Tool-use prompt tokens reported for provider-hosted tools count as additional uncached input; cached tokens remain a subset of the ordinary prompt. Repeated cumulative usage frames within a hop are counted once. Context-window pressure is estimated from the assembled messages, rather than those summed billing counts. With native Google Search enabled, citations retain the sources and supported answer spans from every hop, including when the final hop returns no grounding. Repeated search metadata within a hop is counted once; the same query in another hop counts as a separate search. Gemini 3 and later count queries for search usage, while Gemini 2.x counts grounded requests. Gemini 4 models take thinking levels rather than budgets; minimal maps to low. Hydrogen and Neon accept `xhigh`, so Extra High and Max map to it there; Carbon and Argon map every effort above medium to high. Sampling temperature is omitted. Gemini 4 models support implicit caching only; do not supply an explicit cached-content resource. Long-decode calls default to a 20-minute HTTP read and agent-loop stall timeout. Explicit host-level turn and stall limits still apply. A failed hop fails the call. A dropped stream resumes only when no output was exposed after its last checkpoint; otherwise it fails to prevent duplicate output. Cancelling or dropping the stream stops local continuation requests. See Google’s [long decode guide](https://ai.google.dev/gemini-api/docs/generate-content/long-decode) for provider limits and billing. ## Links * [Google AI for Developers](https://ai.google.dev/) * [Google AI Studio](https://aistudio.google.com/) * [`everruns-drivers` on crates.io](https://crates.io/crates/everruns-drivers), feature `gemini` * [Migrate between providers](https://everruns.com/docs/how-to/migrate-providers/) --- # Groq > Use Groq Chat Completions and native offline batches from Everruns Framework, with scoped resumable tickets and explicit provider configuration. Source: Groq is a first-class Framework driver for OpenAI-compatible Chat Completions. Enable `groq`, set `GROQ_API_KEY`, and select a model your account can use. The optional `GROQ_BASE_URL` overrides the API base. Model discovery runs only against `api.groq.com`; a custom endpoint must speak the corresponding protocol. This addition targets direct Framework applications. It does not add a Groq provider picker or credential storage integration to the Platform. The API is on `main`; published `0.49.0` does not include it. Use the Git dependency from [Batch Model Requests](https://everruns.com/docs/framework/batch-model-requests/) with `features = ["groq"]` until a release includes it. ```rust use everruns::{Model, providers::groq::Groq}; let reply = Model::new("llama-3.1-8b-instant", Groq::from_env()?) .completion().user("What is the capital of France?").max_tokens(64) .send().await?; println!("{}", reply.text); ``` For offline jobs, the same driver exposes the optional native batch capability. It uploads JSONL through Groq Files, creates a native batch, polls it, collects results by request ID, and explicitly cancels whole jobs. It uses a 24-hour window, one model per job, and a maximum of 50,000 requests / 200 MB including the upload envelope. Audio batches and Responses batching are outside this API. Persist tickets in access-controlled application storage. Reconstruct the same provider and tenant/account scope to collect later; ambiguous file upload or job creation requires reconciliation. See the [Groq native batch reference](https://console.groq.com/docs/batch) for current model eligibility, quotas and retention. --- # Microsoft MAI > Run Everruns agents on Microsoft MAI models served via Azure AI Foundry, authenticated with an API key or Microsoft Entra ID (OAuth). Source: Everruns runs agents on Microsoft MAI models (for example `MAI-Code-1-Flash`), which are served via [Azure AI Foundry](https://ai.azure.com) behind an OpenAI-compatible Chat Completions API. The MAI provider exists as its own driver mainly because of its authentication options. ## What you get * **OpenAI-compatible Chat Completions** streaming through Azure AI Foundry. * **Two authentication schemes**: an Azure AI Foundry API key, or Microsoft Entra ID (OAuth) service-principal credentials with bearer tokens minted and refreshed automatically. * **Model discovery** against Foundry’s `/models` endpoint where available, with capabilities supplied by Everruns’ built-in Microsoft model profiles. ## Configure in Everruns 1. Go to **Settings** → **Providers** and click **Add provider**. 2. Choose **Microsoft MAI**. 3. Set the **base URL** to your Azure AI Foundry resource (e.g. `https://.services.ai.azure.com`). 4. Provide credentials for one of the two methods, entered as discrete fields: * **API key**: your Azure AI Foundry resource key. * **Entra ID (OAuth)**: a client-credentials service principal: `tenant_id`, `client_id`, and `client_secret` (with optional `scope` and `authority`, which default to the Azure Cognitive Services scope and public Microsoft Entra authority). 5. Save. Authentication is fail-closed: a stored credential is always required, and OAuth tokens are refreshed transparently for both chat execution and model sync. ## Models Foundry’s `/models` listing is bare (ids only), so capabilities come from Everruns’ built-in Microsoft MAI model profiles, matched by id. Because Azure deployment names are operator-chosen, a deployment whose name does not match a known profile falls back to a minimal profile. ## Links * [Azure AI Foundry](https://ai.azure.com/) * [`everruns-drivers` on crates.io](https://crates.io/crates/everruns-drivers), feature `mai` * [Migrate between providers](https://everruns.com/docs/how-to/migrate-providers/) --- # Meta > Run Everruns agents on Muse Wonder, Muse Spark 1.3 and Muse Ember through Meta Model API, including the discounted Contributor tier. Source: Everruns runs Muse models through [Meta Model API](https://dev.meta.ai/). The dedicated `meta` driver uses Meta’s OpenAI-compatible Responses API at `https://api.meta.ai/v1`, including streaming, parallel tool calls, reasoning replay, message phases, hosted tool search, and server-managed response history. ## Configure in Everruns 1. Create an API key in the [Meta Model API dashboard](https://dev.meta.ai/). 2. Go to **Settings** → **Providers** and click **Add provider**. 3. Choose **Meta**, paste the key, and save. 4. Sync models to import the Muse models available to your team. The hosted endpoint is used by default. An optional base URL can point the driver at a compatible proxy; model discovery is disabled for non-Meta hosts. ## Muse Wonder Muse Wonder (`muse-wonder-1.0`, preview) is Meta’s most capable Muse model, for complex software engineering, multi-hour agent runs and sub-agent orchestration. It has the same 1,048,576-token context window and inputs as Muse Spark 1.3, and takes the same requests, so switching is a model ID change. | Model | Data use | Input / cached input / output per million tokens | | ----------------- | --------------------------------------------------------- | ------------------------------------------------ | | `muse-wonder-1.0` | Prompts and completions are not used to train Meta models | $4.00 / $0.20 / $20.00 | Muse Wonder has no Contributor tier on pay-as-you-go. Muse Wonder Full is only available inside Meta’s Muse Code, not through the API. ## Muse Ember Muse Ember (`muse-ember-1.0`) is Meta’s smallest and cheapest Muse model, built for bounded, high-volume work: sub-agent tasks, tool calls, routing, and running one task across many files or records. It has the same 1,048,576-token context and inputs as Muse Spark, answers up to 524,288 tokens, and is the Meta driver’s recommended small model. For hard single-shot coding or knowledge-heavy questions, Meta recommends Muse Spark or Muse Wonder instead. | Input tokens in the request | Input / cached input / output per million tokens | | --------------------------- | ------------------------------------------------ | | Up to 200K | $0.10 / $0.004 / $0.50 | | Over 200K | $0.30 / $0.012 / $1.50 | A request over 200K input tokens is billed entirely at the higher rates. Ember is Standard only: prompts and completions are not used to train Meta models. ## Muse Spark 1.3 tiers Muse Spark 1.3 is built for long-horizon coding and multi-step agentic work, with native tool calling and MCP support. Both 1.3 model IDs have a 1,048,576-token context window and accept text, images, audio, video, and PDFs while producing text. | Model | Data use | Input / cached input / output per million tokens | | ---------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------ | | `muse-spark-1.3` | Prompts and completions are not used to train Meta models | $1.25 / $0.15 / $4.25 | | `muse-spark-1.3-contributor` | Prompts and completions are used to train and improve Meta models; rate-limited by tokens | $0.10 / $0.002 / $0.20 | Choose the Contributor model only when the organization accepts its data-use terms. The distinction is part of the model ID, so changing tiers is an explicit model selection rather than a hidden provider setting. The previous `muse-spark-1.2` and `muse-spark-1.2-contributor` IDs remain available with the same tiers and pricing, and so does the original `muse-spark-1.1` (Standard tier only). ## Through OpenRouter and open weights The same Muse models are also reachable through [OpenRouter](https://everruns.com/docs/providers/openrouter/) as `meta/muse-ember`, `meta/muse-wonder`, `meta/muse-spark-1.3` and so on. Meta’s open-weight models, Muse Spark Open (`meta/muse-spark-open`) and Muse Glimmer 30B (`meta/muse-glimmer-30b`), are not on Meta Model API; reach them through OpenRouter or any OpenAI-compatible host that serves them. ## Reasoning effort Every Muse model lets you pick a reasoning effort per agent or per message: Minimal, Low, Medium, High, Extra High and, on Muse Wonder, Muse Ember and Muse Spark 1.3 (both tiers), Max. Muse Spark 1.1 and 1.2 stop at Extra High. No Muse model accepts `none`. Leave effort unset and Meta picks a level for the model. ## Links * [Muse Wonder model card](https://research.meta.ai/static/muse-wonder-model-card) * [Meta Model API documentation](https://dev.meta.ai/docs/overview/) * [Muse Ember model page](https://dev.meta.ai/docs/muse-ember) * [Muse Spark model page](https://developer.meta.com/ai/models/muse-spark/) * [Migrate between providers](https://everruns.com/docs/how-to/migrate-providers/) --- # Mistral AI > Run Everruns agents on Mistral models (Mistral Large 4, Medium, Small, Codestral) through La Plateforme, with reasoning and automatic model discovery. Source: Everruns runs agents on [Mistral AI](https://mistral.ai/) models through La Plateforme’s Chat Completions API: Mistral Large 4, Mistral Medium, Mistral Small, Ministral and Codestral, with the same agent, prompt, and capabilities you run on any other provider. ## What you get * **Mistral Large 4**: Mistral’s 1T-parameter multimodal model with a 512K context window, tool calling, image input, structured output, and reasoning. * **Reasoning on demand**: Mistral Large 4’s thinking is on or off. Set the agent’s reasoning effort to **On** (`high`) to stream its reasoning separately from the answer; the default, **Off**, answers directly. * **Automatic model discovery**: Mistral’s `/models` endpoint advertises chat, tool calling, vision and reasoning support per model, which Everruns turns into capability profiles on sync. Aliases are folded into one entry per model, and models Mistral has scheduled for retirement are skipped. * **Host-gated discovery**: model sync runs only against `api.mistral.ai`, so a custom proxy base URL is never probed. ## Configure in Everruns 1. Go to **Settings** → **Providers** and click **Add provider**. 2. Choose **Mistral AI**. 3. Paste your API key. Create one in [Mistral Studio](https://console.mistral.ai/api-keys). 4. Save. Everruns discovers the available models and their capabilities. You can optionally set a base URL to route through a proxy; leave it blank to use `https://api.mistral.ai/v1`. ## Models Use Mistral’s model ids, for example `mistral-large-4` (alias `mistral-large-4-0`), `mistral-medium-latest`, or `codestral-latest`. Mistral Large 4 is also reachable through [OpenRouter](https://everruns.com/docs/providers/openrouter/) as `mistralai/mistral-large-4-0`, with the same profile. Everruns ships profiles (context, pricing, reasoning toggle) for Mistral Large 4, Mistral Medium 3.5 (`mistral-medium-2604`, also `mistral-medium-latest`), and Mistral Small 4 (`mistral-small-2603`, also `mistral-small-latest`). ## Framework ```rust // Reads MISTRAL_API_KEY, and MISTRAL_BASE_URL when set. let provider = everruns::Mistral::from_env()?; ``` Enable the `mistral` feature of `everruns`. ## Responses API preview The existing Mistral provider can opt into Mistral’s stateless [Responses API](https://docs.mistral.ai/studio/conversations/responses) per connection. Chat Completions remains the default. Select Responses when constructing the provider connection (enable the `mistral` feature of `everruns`): ```rust use everruns::{Agent, Mistral, MistralApi}; let agent = Agent::builder() .provider(Mistral::from_env()?.api(MistralApi::Responses)) .model("mistral-large-4") .instructions("Be concise.") .build()?; ``` For a direct call, convert the same configuration into `everruns::Provider`: ```rust use everruns::{Mistral, MistralApi, Provider}; let provider: Provider = Mistral::from_env()? .api(MistralApi::Responses) .into(); ``` Use the same API key and `/v1` base URL. `MistralApi::ChatCompletions` selects `/v1/chat/completions`; `MistralApi::Responses` selects `/v1/responses`. Shared call configuration carries the model and generation settings, not the protocol. The runnable `mistral_responses` example uses this configuration: `cargo run -p everruns --features mistral --example mistral_responses`. Low-level hosts can use `everruns_drivers::mistral::provider_with_api(id, key, api)`. Hosted REST clients select the same API when creating or updating a provider: ```json { "name": "Mistral Responses", "provider_type": "mistral", "api": "responses" } ``` Configure credentials through the normal provider credential fields. `api` may be `responses`, `chat_completions`, or `default`. Omitting it on create preserves the existing default; omitting it on PATCH preserves the stored selection. PATCH `"api": "default"` restores the default. The server validates choices against the driver catalog. API reads return the stored selection, and `/v1/providers/config` returns supported choices in each driver’s `apis` field. Server and worker must both run a version supporting this field. The Settings UI has no selector yet. Responses supports streamed text and reasoning, client-executed function calls, parallel tool calls, JSON Schema output, token usage, prompt-cache routing, and HTTP retries. Pass the full message history on every call: Everruns replays messages, function calls and results, and Mistral plaintext reasoning. It sends `store: false` and ignores `previous_response_id` because Mistral stores no response chain. Reasoning from another provider is not replayed to Mistral. User messages and function results can contain image URLs/data URLs and files as HTTPS URLs or data URLs, subject to the selected model’s capabilities. Uploaded file IDs are not exposed by Everruns’ portable message contract. Audio and opaque provider content are rejected before sending a request. Non-streaming callers receive a collected SSE response; native Responses JSON transport is not implemented. Failed, incomplete, or prematurely closed streams fail the call rather than reporting a successful partial answer. Background responses, WebSockets, server-side compaction, hosted tools, token-counting, function namespaces, and forced tool selection are not exposed by this integration. OpenAI-only service-tier and verbosity settings are omitted. Model discovery behavior is unchanged. ## Links * [Mistral Large 4 announcement](https://mistral.ai/news/mistral-large-4/) * [Mistral API docs](https://docs.mistral.ai/) * [`everruns-drivers` on crates.io](https://crates.io/crates/everruns-drivers), feature `mistral` * [Migrate between providers](https://everruns.com/docs/how-to/migrate-providers/) ## Native Framework batches Enable the `mistral` Cargo feature of `everruns` for direct offline model requests through [Batch Model Requests](https://everruns.com/docs/framework/batch-model-requests/). Mistral uses native inline jobs with resumable tickets and explicit cancellation. The API is on `main`; published `0.49.0` does not include it. Use the guide’s Git dependency until a release includes this API. --- # OpenAI > Run Everruns agents on OpenAI models via the Responses API or Chat Completions, including Azure OpenAI and any OpenAI-compatible endpoint. Source: Everruns runs agents on [OpenAI](https://openai.com/) models through a uniform driver, mapping its provider-neutral messages, tools, and reasoning onto the OpenAI wire format. The same driver also powers any **OpenAI-compatible endpoint** through a custom base URL. For Azure deployments, use the dedicated [Azure OpenAI](https://everruns.com/docs/providers/azure-openai/) provider instead. ## What you get * **Responses API** (recommended), the default driver, with stateful continuation and server-side context compaction on `api.openai.com` and Azure OpenAI hosts. * **Chat Completions**: a compatibility driver (`openai_completions`) for legacy integrations and OpenAI-compatible gateways. * **Streaming, tool calls, and reasoning** mapped to provider-neutral Everruns types, including extended thinking on reasoning models. * **Prompt caching** via a deterministic cache key derived from the session (or agent, harness, organization) and model. * **Structured output**: a direct model call can require a reply that matches a JSON Schema, enforced by OpenAI (`text.format` on the Responses API, `response_format` on Chat Completions). * **Background mode** for `xhigh` and `max` reasoning on OpenAI and Azure: the response keeps running at OpenAI if the connection drops or the worker running the turn restarts, and Everruns picks the stream back up instead of paying for the call twice. A cancelled turn cancels the response. Background mode stores the response, so organizations with zero data retention fall back to a normal streaming call. * **WebSocket transport (opt-in)**: on `api.openai.com`, a call can stream over OpenAI’s Responses WebSocket mode instead of HTTP streaming, keeping one connection open across the turns of a tool loop. OpenAI recommends it for the `ultrafast` speed tier. It is off by default; see [WebSocket transport](#websocket-transport). ## Configure in Everruns 1. Go to **Settings** → **Providers** and click **Add provider**. 2. Choose **OpenAI** (Responses API) for new setups, or **OpenAI Completions** for Chat Completions compatibility. For Azure, choose the dedicated [Azure OpenAI](https://everruns.com/docs/providers/azure-openai/) provider instead. 3. Paste your OpenAI API key. Get one from the [OpenAI API keys page](https://platform.openai.com/api-keys). 4. (Optional) Set a **base URL** to target another OpenAI-compatible endpoint. 5. Save. Everruns discovers available models automatically. ## OpenAI-compatible endpoints The OpenAI driver works with any OpenAI-compatible API. Set the **base URL** to your endpoint. Self-hosted and proxy gateways are treated as stateless, so the driver replays the full transcript each turn instead of relying on server-side continuation. For Microsoft Azure deployments, use the dedicated [Azure OpenAI](https://everruns.com/docs/providers/azure-openai/) provider, which is recognized as a stateful host. ## WebSocket transport HTTP streaming (SSE) is the default. To use OpenAI’s [WebSocket mode](https://developers.openai.com/api/docs/guides/websocket-mode) instead, opt in per call with the `openai/websocket` driver option set to `true` (`false` opts a call out), or for a whole provider when you build it in code: ```rust use everruns_drivers::openai::OpenAIChatDriver; let driver = OpenAIChatDriver::new().with_websocket_transport(true); ``` Each turn of a tool loop continues on the connection the previous turn used, sending only the new tool results. The transport applies to `api.openai.com` only; Azure OpenAI and custom endpoints keep using HTTP streaming. If the socket cannot connect, or drops or reports an error before the response starts, the call is sent over HTTP streaming instead, so opting in never fails a call that HTTP would have served. Background-mode calls always use HTTP. ## Models Models are discovered when the provider is created and on each sync. OpenAI’s `/models` listing carries only identifiers, so capability and cost metadata come from Everruns’ built-in model profiles, matched by model id. ### GPT-6.2 Astra and Sol Use `gpt-6.2-sol` for the current balanced model or `gpt-6.2-astra` for the flagship. Explicit previous model IDs remain available; the budget default is still `gpt-6-luna`. Both GPT-6.2 models require the **Responses API for function tools**. Reasoning levels are `low`, `medium` (the default), `high`, `xhigh`, and `max`; `none` and `minimal` are rejected before sending. Standard, Fast (`fast` or `priority`), and Ultrafast are supported, but Flex is not. Ultrafast requires a US processing endpoint and costs 3x Standard through February 28, 2027, then 6x from March 1 Pacific time. Fast is 2x Standard. Keep prior conversation input and encrypted reasoning items unchanged. Append new instructions instead of rewriting earlier messages: GPT-6.2 may drop reasoning after prefix edits, model downgrades, or user/organization changes. See [OpenAI’s migration guide](https://developers.openai.com/api/docs/guides/latest-model). ## Links * [OpenAI Platform](https://platform.openai.com/) * [`everruns-drivers` on crates.io](https://crates.io/crates/everruns-drivers), feature `openai` * [Migrate between providers](https://everruns.com/docs/how-to/migrate-providers/) --- # OpenRouter > Run Everruns agents across OpenRouter's multi-vendor model catalog with one key, plus provider routing, fallbacks, and capacity controls. Source: Everruns runs agents on [OpenRouter](https://openrouter.ai/)’s model catalog through its OpenAI-compatible Responses API. One OpenRouter key gives you access to a large multi-vendor catalog, plus routing controls that decide which upstream provider actually serves each request. ## What you get * **One key, many models**: a single provider exposing OpenRouter’s full catalog. * **OAuth one-click connect**: authorize in the browser instead of copy-pasting an API key. See [Connecting](#connecting) below. * **Actual-cost reporting**: OpenRouter returns the real money spent per generation, which Everruns records as authoritative cost. See [Actual cost](#actual-cost) below. * **Built-in server tools**: let the model use OpenRouter-executed tools such as `web_search` and `web_fetch` without wiring up a separate integration. See [Server tools](#server-tools) below. * **Provider routing**: order, allow/deny lists, data-retention and zero-data-retention policies, and price/throughput sorting. * **Capacity strategy**: use OpenRouter’s shared capacity, prefer your own bring-your-own-key (BYOK) providers first, or require BYOK-only routing. * **Routing presets**: high-level intents such as cheapest-with-tools, lowest-latency, or reasoning-required that compile into the underlying routing flags. * **Capability profiling**: OpenRouter’s richer `/models` metadata is parsed into capability profiles, so reasoning support surfaces correctly even for models without a built-in profile. * **Session grouping & logs**: Everruns forwards its session id so all generations from one session group together in OpenRouter’s dashboard, where you can inspect traces and forward them to observability tools. See [Logs, traces, and observability](#logs-traces-and-observability) below. ## Connecting Providers are configured by organization admins under **Models** → **Providers** → **Connect provider** → **OpenRouter**. Under **How to connect**, pick one of two ways: ### OAuth (recommended) Choose **Sign in with OpenRouter**, click **Continue to OpenRouter** and authorize in the browser. OpenRouter’s one-click [PKCE](https://openrouter.ai/docs/use-cases/oauth-pkce) flow returns a user-controlled API key that Everruns stores org-wide, no key copy-pasting, and no app registration. The consent screen’s key label is preset to `Everruns `, which is also the name of the key OpenRouter creates. An admin authorizes once; everyone in the org then uses the models the provider serves against the single stored credential. The key is encrypted at rest and never returned by the API. > OpenRouter’s callback URL must be HTTPS on port 443 or 3000 for non-localhost deployments. ### API key Choose **Paste an API key** and paste a key from the [OpenRouter keys page](https://openrouter.ai/keys). To rotate the credential later, click the key button on the provider’s card. The same drawer shows the current credential and offers **Sign in again with OpenRouter** or **Paste a different API key**. Everruns syncs the catalog after browser sign-in or saving an API key. On a new provider, calibrated decision models are available in **Models → Defaults → Decisions**. Review the provider’s card to choose additional models. ## Routing controls OpenRouter-specific routing (model fallbacks, provider ordering, capacity strategy, and presets) is configured per agent and applied only to OpenRouter requests, direct OpenAI or other providers ignore these extensions. BYOK-only routing requires you to list at least one upstream provider, and fails closed if none is configured. ## Server tools OpenRouter can run **provider-executed server tools**: `web_search`, `web_fetch`, `datetime`, `image_generation`, and more, during a generation. OpenRouter executes them server-side and folds the results into the same answer, so your agent gets built-in web reach without a separate search [integration](https://everruns.com/docs/integrations/) or an extra round-trip through Everruns. Enable them per agent with the [OpenRouter Server Tools capability](https://everruns.com/docs/capabilities/openrouter-server-tools/). The capability is a harmless no-op on non-OpenRouter providers, so it is safe to leave on for agents that may switch providers. Because the model gains provider-executed web access, the capability is rated High risk, grant it only to agents you trust with outbound web access. ## Actual cost OpenRouter’s API reports the **real money spent** per generation, not just an estimate. Everruns records this as the generation’s authoritative `actual_cost_usd` (sourced from OpenRouter’s `usage.cost`, reconciled against the [generation endpoint](https://openrouter.ai/docs/api-reference/get-a-generation) when needed) alongside its own estimated cost. Budgets debit the actual cost when present and fall back to the estimate otherwise, so spend tracking and [budgeting](https://everruns.com/docs/capabilities/budgeting/) reflect what OpenRouter actually charged. ## Low balance When a request does not set a token limit, OpenRouter reserves the model’s full output limit against your credits and rejects the call with HTTP 402 (“can only afford N tokens”) if the balance cannot cover it. Set **Max output tokens** under **More** on the agent (`max_output_tokens` in the API, `--max-output-tokens` in the CLI) to a value below that number so each call fits. Everruns sends it as `max_tokens` and never asks for more than the model’s own output limit. ## Logs, traces, and observability Everruns forwards its session id to OpenRouter, so every generation from one Everruns session groups together in OpenRouter’s dashboard. OpenRouter’s own activity logs show each request’s trace, often enough to debug a run without leaving OpenRouter. When you need richer tracing, OpenRouter can forward your generations to external observability tools such as Braintrust or LangSmith; configure that on the OpenRouter side. This complements Everruns’ own [Framework context inspection](https://everruns.com/docs/framework/agents/#inspect-effective-context) rather than replacing it. ## Links * [OpenRouter](https://openrouter.ai/) * [OpenRouter docs](https://openrouter.ai/docs) * [OpenRouter Server Tools capability](https://everruns.com/docs/capabilities/openrouter-server-tools/) * [`everruns-drivers` on crates.io](https://crates.io/crates/everruns-drivers), feature `openrouter` * [Integrations overview](https://everruns.com/docs/integrations/) * [Migrate between providers](https://everruns.com/docs/how-to/migrate-providers/) --- # Vercel AI Gateway > Run Everruns agents through Vercel AI Gateway, reaching many upstream model providers over the Open Responses API with one key and automatic model discovery. Source: Everruns runs agents through [Vercel AI Gateway](https://vercel.com/docs/ai-gateway), which fronts many upstream model providers behind one endpoint. The gateway serves the [Open Responses](https://openresponses.org) specification, the same vendor-neutral standard Everruns prefers for new drivers, so this provider gets the richer surface rather than Chat Completions. ## What you get * **Many vendors, one key**: OpenAI, Anthropic, Google, and the rest of the gateway’s catalog from a single Everruns provider. * **Open Responses**: semantic streaming events, tool calling, structured output, and reasoning control over a spec Everruns implements natively. * **Automatic model discovery**: the gateway’s `/models` endpoint is synced, so the catalog appears in the agent and session model pickers. * **Host-gated discovery**: model sync runs only against Vercel’s own host, so a custom proxy base URL is never probed. ## Configure in Everruns 1. Create an AI Gateway API key in the [Vercel dashboard](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%2Fapi-keys). 2. Go to **Settings** → **Providers** and click **Add provider**. 3. Choose **Vercel AI Gateway**. 4. Paste the key. A Vercel OIDC token works in the same field — the gateway accepts either as a bearer token. 5. Save. Everruns discovers the available models automatically. You can optionally set a base URL to route through a proxy; leave it blank to use the hosted gateway (`https://ai-gateway.vercel.sh/v1`). ## Models Model ids are namespaced by upstream provider — `anthropic/claude-opus-5`, `openai/gpt-6.2-astra` — and are passed through to the gateway unchanged. The [AI Gateway model catalog](https://vercel.com/ai-gateway/models) lists what is available. After a sync they appear in the model pickers; Everruns matches a namespaced id against its model profile registry for capability and cost metadata. ## Links * [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) * [Open Responses on AI Gateway](https://vercel.com/docs/ai-gateway/sdks-and-apis/openresponses) * [AI Gateway models](https://vercel.com/ai-gateway/models) * [`everruns-drivers` on crates.io](https://crates.io/crates/everruns-drivers) * [Migrate between providers](https://everruns.com/docs/how-to/migrate-providers/)