Single agent.

One model, one chat thread, one unified tool registry. The default — and right for almost everything.

The flow

Open the agent panel (the chat icon in the activity bar). Press Cmd+L to jump focus into the chat input. Type a request. The agent inspects the notebook context, decides what tools to call, and walks through the work step by step in the chat. Proposed cells land in the notebook with a review banner.

Conversations stay scoped to the current notebook. Switching notebooks starts a new thread; you can pin earlier threads from the panel header to come back to them later.

A single agent thread with a multi-step plan, tool calls, and a proposed chart cell at the bottom./docs-images/agents/single-thread.png

One thread, one model. The full plan visible in the chat.

What it can do

The single agent has access to the full tool set:

Run SQL against any of your connections (read-only by default).
Execute Python in the project kernel, sharing state with cells you wrote.
Read project files; propose edits to existing files and cells.
Run shell commands (git, ls, cat, etc.) inside the project workspace.
Create and modify .orchid notebooks, .orchid-dashboard dashboards, and documents.

See Tools for the full list and Approvals for what triggers an explicit prompt.

Free-tier Gemini, BYO key for premium

Out of the box, single-agent mode runs on Google Gemini. No setup, no rate-limit surprises during normal use. The free model is capable for most analyst work — SQL drafting, basic analysis, chart selection.

For longer chains or harder reasoning, plug in Anthropic Claude or OpenAI GPT-4o from Settings → Models. Bring your own key; Orchid uses it directly, no proxying.

// settings.local.json (anonymized)
{
  "agents": {
    "mode": "single",
    "model": "claude-sonnet-4-7",
    "byo_keys": {
      "anthropic": "sk-ant-..."
    }
  }
}

Tip

You can swap models mid-conversation — the previous turns stay in the thread and the new model picks up from there. Useful when a small model gets stuck and you want a larger one to finish.

When to switch to multi-agent

Single agent is faster, cheaper, and simpler. Start there. Reach for multi-agent mode when you want clearer separation of concerns — "pull the data" vs. "analyze it" vs. "write the readout" — or when a thread is long enough that role labels make the log easier to scan.

Tips for the single agent

Anchor with cell ids. Reference the cell you want changed — "in cell q1, switch to median" is faster than re-explaining the whole context.
Ask before you accept. If a proposed change looks off, ask the agent to revise in chat. It edits the proposal in place.
Don't overload the prompt. One outcome per request. Long multi-step asks turn into long multi-step plans that are hard to review.

More on prompt habits in Prompting tips. Back to the Agents overview.