AI Agents
SAM supports five AI coding agents. Each runs inside a workspace container and communicates via the Agent Communication Protocol (ACP).
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 dual authentication: API keys (pay-per-use) and OAuth tokens (from Claude Max/Pro subscriptions via claude setup-token). Toggle between them in Settings.
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 |
Google Gemini
Section titled “Google Gemini”| 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) |
| API Key | Uses Scaleway credentials (SCW_SECRET_KEY) |
| Get a Key | Scaleway Console |
OpenCode uses Scaleway’s Generative APIs for inference. If you already have a Scaleway cloud provider credential configured, OpenCode can use that — no separate API key required.
Configuring Agent Credentials
Section titled “Configuring Agent Credentials”- Go to Settings in the SAM web UI
- Open the Agents tab
- Add your API key (or OAuth token) for each agent you want to use. Connection and configuration for each agent are grouped together on a single card.
- Keys are encrypted at rest using AES-256-GCM
You can configure credentials for multiple agents simultaneously and switch between them per project.
Project Default Agent
Section titled “Project Default Agent”Each project can set a default agent type that’s used when executing ideas. If no default is set, you’ll need to specify the agent when starting execution.
To set the default:
- Open the project settings
- Select your preferred agent from the dropdown
- Save changes
The agent selection follows this precedence:
- Explicit override on execution
- Project default agent
- Platform default (
claude-code)
Workspace Profiles
Section titled “Workspace Profiles”When running an agent, you can choose between two workspace profiles:
Full Profile (Default)
Section titled “Full Profile (Default)”- Builds the complete devcontainer from your project’s
.devcontainerconfiguration - Includes all custom build steps, extensions, and dependencies
- Startup time: 2-3 minutes depending on build complexity
Lightweight Profile
Section titled “Lightweight Profile”- Skips the devcontainer build entirely
- Uses a minimal base image with core tools pre-installed
- Startup time: 30-120 seconds faster than full profile
- Best for quick conversations that don’t need custom environments
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: VM heartbeat lost (detected after 5 minutes of silence)
MCP Tools
Section titled “MCP Tools”Running agents have access to project-aware MCP tools:
| Tool | Description |
|---|---|
dispatch_task | Spawn a follow-up idea for execution |
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 |
update_task_status | Report progress |
complete_task | Mark current work as done |
request_human_input | Ask for user decision (blocks until answered) |