AI Agents
SAM supports six AI coding agents. You connect the ones you want to use, then choose which to run for a given chat by selecting an agent profile.
Supported Agents
Section titled “Supported Agents”Claude Code
Section titled “Claude Code”| Property | Value |
|---|---|
| Provider | Anthropic |
| API Key | ANTHROPIC_API_KEY |
| OAuth Support | Yes (Claude Max/Pro subscriptions) |
| Get a Key | Anthropic Console |
Claude Code supports two authentication methods: an API key (pay-per-use) or your Claude Max/Pro subscription. To use a subscription, choose Connect with Claude Code for the guided sign-in — SAM opens a Claude sign-in page, then you paste Claude’s browser-displayed code#state value back into SAM, so you never run claude setup-token or paste a token by hand. Pasting a claude setup-token value manually is still available as a fallback.
OpenAI Codex
Section titled “OpenAI Codex”| Property | Value |
|---|---|
| Provider | OpenAI |
| API Key | OPENAI_API_KEY |
| OAuth Support | Yes (via ~/.codex/auth.json) |
| Get a Key | OpenAI Platform |
For a ChatGPT subscription, choose Connect with Codex for the guided
sign-in. SAM opens an OpenAI
sign-in page and shows a copyable one-time code; no terminal interaction or
manual ~/.codex/auth.json paste is required. Pasting auth.json manually is
still available as a fallback.
Gemini CLI
Section titled “Gemini CLI”| Property | Value |
|---|---|
| Provider | |
| API Key | GEMINI_API_KEY |
| Get a Key | Google AI Studio |
Mistral Vibe
Section titled “Mistral Vibe”| Property | Value |
|---|---|
| Provider | Mistral |
| API Key | MISTRAL_API_KEY |
| Get a Key | Mistral Console |
Mistral Vibe is installed via uv (Python package manager) and requires Python 3.12.
OpenCode
Section titled “OpenCode”| Property | Value |
|---|---|
| Provider | OpenCode (SST) |
| Default Inference Provider | OpenCode Zen |
| Advanced Inference Providers | OpenCode Go, SAM Platform (Workers AI), Scaleway, Google Vertex, OpenAI-compatible, Anthropic, custom |
| API Key | OPENCODE_API_KEY for OpenCode Zen and OpenCode Go |
| Get a Key | OpenCode auth |
OpenCode defaults to OpenCode Zen. SAM loads the Zen and Go model dropdowns from Models.dev through its authenticated model-catalog API, with a static fallback if that upstream catalog is unavailable. Select OpenCode Go in agent settings to use Go-only models such as opencode-go/glm-5.2. Advanced configurations can use SAM Platform inference without a user API key, or another user-selected inference provider. If you explicitly select Scaleway and already have a Scaleway cloud provider credential configured, OpenCode can reuse that credential — no separate API key required.
| Property | Value |
|---|---|
| Provider | Sourcegraph |
| API Key | AMP_API_KEY |
| OAuth Support | No |
| Get a Key | Amp settings |
Amp requires an Amp API key and may require paid Amp credits.
Connecting Agent Credentials
Section titled “Connecting Agent Credentials”- Go to Settings → Connections in the SAM web UI
- Start the Connect flow for the agent you want to use
- Provide your API key (or OAuth token). Your credentials are encrypted at rest.
You can connect multiple agents and switch between them per chat by choosing a different profile.
Connecting a subscription with guided sign-in
Section titled “Connecting a subscription with guided sign-in”If you pay for Claude Max/Pro or a ChatGPT plan, you can connect that subscription instead of an API key — without leaving the browser or touching a terminal. This is the recommended way to use Claude Code or OpenAI Codex on a subscription.
- Go to Settings → Connections (or Settings → Agents) and start the connect flow for Claude Code or OpenAI Codex.
- Choose the OAuth / subscription authentication method (rather than API key), then click Connect with Claude Code or Connect with Codex.
- Click the Open sign-in link and approve access on the provider’s page. For Codex, enter the short code SAM displays when the provider asks. For Claude Code, copy the
code#statevalue Claude displays, return to SAM, paste the complete value into the dialog, and click Continue sign-in. - Leave the SAM window open — it updates on its own. When the provider confirms, the panel shows Connected and your subscription credential is saved, encrypted at rest.
A few things worth knowing:
- No terminal, no file paste. The old flow asked you to run
claude setup-tokenor paste~/.codex/auth.json. Those still work as a manual fallback (in the same panel), but the guided flow removes them from the happy path. - User-scoped. Guided sign-in saves the credential for your account, so it applies across your projects. To set a subscription credential for a single shared project, use the manual paste fallback in that project’s connections.
- Availability. Guided sign-in is available on the hosted platform and on self-hosted deployments running on Cloudflare Containers (SAM’s default runtime). If the button isn’t shown, use the manual API key or token fields in the same panel.
AI Provider Modes
Section titled “AI Provider Modes”Each agent runs in one of three provider modes, which control where LLM traffic goes and who pays for it:
| Mode | What it uses |
|---|---|
| API key | Your own provider API key (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.) |
| OAuth | A token from your provider subscription (for example Claude Max/Pro) |
| SAM | The platform’s managed AI proxy, with billing and budget handled by SAM (opt-in) |
You pick the mode when you connect an agent. The SAM platform proxy is never selected automatically — you have to opt in.
Agent Profiles
Section titled “Agent Profiles”An agent profile bundles a connected agent, a model, and settings into a reusable configuration. Profiles are how you choose what runs: pick a profile from the chat input when you start a session, or attach one to a trigger for automated work. Create and manage profiles under a project’s Profiles page.
In a shared project, agent profiles (and skills, environment variables, secrets, and files) are project-scoped resources — any member can use profiles another member created. LLM cost still follows the running user’s own key unless a shared project credential is attached.
When work starts, the agent is resolved in this order:
- The profile you selected (or the trigger’s profile)
- The project’s default profile
- The platform default (
DEFAULT_TASK_AGENT_TYPE,opencodein the checked-in Worker config)
Workspace Profiles
Section titled “Workspace Profiles”When you start a chat you can also choose how much environment to bring:
- Full (default) — builds your project’s
.devcontainerso the agent can run your stack, tests, and services. Best when the work depends on your real environment. - Lightweight — starts faster with a minimal environment. Best for quick questions, planning, and code exploration.
Agent Session Features
Section titled “Agent Session Features”Real-Time Streaming
Section titled “Real-Time Streaming”Agent output streams to your browser in real-time via WebSocket. You see code being written, commands being executed, and decisions being made as they happen.
Conversation Forking
Section titled “Conversation Forking”You can fork a conversation from any message to explore an alternative approach:
- Hover over a message in the chat
- Click the Fork button
- SAM generates an AI context summary of the conversation up to that point
- A new session starts with the context and awareness of the previous conversation
Fork depth is limited to 10 levels (configurable via ACP_SESSION_MAX_FORK_DEPTH).
Voice Input
Section titled “Voice Input”Speak your message or follow-up prompts using the microphone button. SAM transcribes audio using Whisper (via Workers AI) and submits the text.
Text-to-Speech Playback
Section titled “Text-to-Speech Playback”Agent responses can be played back as audio using Deepgram Aura 2 (via Workers AI). TTS audio is cached in R2 for subsequent playback.
Session Lifecycle
Section titled “Session Lifecycle”Each agent session follows this state machine:
pending → assigned → running → completed/failed/interrupted- Pending: Session created, waiting for workspace assignment
- Assigned: Workspace ready, agent starting up
- Running: Agent actively executing
- Completed: Agent finished successfully
- Failed: Agent encountered an error
- Interrupted: Connection to the agent was lost
SAM now backs chat sessions with task records across more runtime paths. In practice, that means forking, archive/complete controls, lineage, and status reporting behave consistently whether the work started as an idea execution, a full task, or an instant chat.
MCP Tools
Section titled “MCP Tools”Running agents have access to project-aware MCP tools:
| Tool | Description |
|---|---|
dispatch_task | Spawn follow-up work using the selected profile runtime, or an explicit runtime override |
create_idea | Create a new idea |
update_idea | Update an idea’s title, content, priority, or status |
list_ideas | View project ideas |
get_idea | Read idea details |
search_ideas | Search ideas by keyword |
link_idea | Link an idea to a chat session |
unlink_idea | Remove an idea-session link |
find_related_ideas | Find ideas related to a session |
list_linked_ideas | List ideas linked to a session |
list_sessions | View chat sessions |
get_session_messages | Read conversation history (consecutive streaming tokens are concatenated into logical messages) |
search_messages | Search messages by keyword — uses FTS5 full-text search for completed sessions; keyword matching for active sessions |
list_triggers | List this project’s automation triggers, optionally filtered by status or source type |
update_task_status | Report progress |
get_task_details | Inspect task state, persisted output fields, PR/error details, session id, and bounded recent assistant diagnostics |
complete_task | Mark current work as done, optionally with structured completion evidence |
request_human_input | Record a user decision request and notify the user; the tool call itself is non-blocking |
get_task_details keeps outputSummary and completionEvidence as the canonical persisted completion fields. When a task has a linked chat session, it can also include a bounded recentAssistantMessages array with up to five recent assistant messages, each capped to 2,000 characters, so orchestrators can recover useful final output when the persisted summary is sparse. The SAM session (Anthropic tool) variant returns a single finalAssistantMessage (the latest assistant message, content capped to 2,000 characters) instead of the full array. If session diagnostics are unavailable, task details still return and the diagnostic fields are empty/null.
Claude Code and Codex get these tools on both the VM and Instant runtimes. If a Codex session is handed an MCP server without a usable token, it fails to start with an explicit error rather than launching a tool-less agent.
An agent that reports it has no SAM tools is worth reporting — it is not expected behavior on either runtime.