# Studio tour

> The Studio window, providers, the Loop, agent configuration, settings, multimodal input and shortcuts.

Source: https://github.com/christianbalevski/adf/blob/v0.7.4/docs/ADF_STUDIO_DOCS.md (adf v0.7.4)

ADF Studio is the desktop application for creating, configuring, and operating ADF agents. It is the visual IDE for the [Agent Document Format](https://github.com/christianbalevski/adf/blob/v0.7.4/README.md) — where you author an agent, follow its turns, configure its tools, and run it on the mesh.

This document covers the **Studio application itself**: its interface, settings, and day-to-day workflows. For the underlying format, runtime, and tool concepts, see the [documentation index](https://agentdocumentformat.org/guides), which links every guide. For the headless runtime, see the [Daemon documentation](https://agentdocumentformat.org/cli/daemon).

> **Looking for a specific concept?** Start at [docs/index.md](https://agentdocumentformat.org/guides). This page is the app tour, not the full reference — it links into the guides rather than duplicating them.

![The ADF Studio window with a fleet of agents in the sidebar, a markdown document open in the center editor, and the Loop panel on the right showing a conversation with tool calls, reasoning blocks, and token counts.](https://agentdocumentformat.org/docs-assets/assets/screenshots/studio-agent-loop.png)

---

## Installation and Prerequisites

Before you begin you need:

1. **ADF Studio** installed on your machine (macOS or Windows).
2. **At least one LLM provider** — Studio supports Anthropic, OpenAI, OpenAI-compatible endpoints, and ChatGPT Subscription (OAuth).

On first launch Studio creates its application data directory (`~/.adf-studio/`), which holds settings, the shared sandbox-package store, and per-agent compute state.

---

## Setting Up a Provider

You must configure a provider before an agent can run.

1. Open **Settings** (gear icon in the sidebar, or `Cmd/Ctrl + ,`).
2. Go to the **Providers** section.
3. Click **Add provider**. A catalog opens with one tile per service, grouped as:
   - **Subscriptions** — ChatGPT Plus/Pro and SuperGrok/X Premium, via OAuth sign-in (flat-rate, no API key).
   - **APIs** — Anthropic, OpenAI, OpenRouter, Gemini, xAI, Mistral, Groq and the other hosted endpoints (API key).
   - **Local** — LM Studio, Ollama, vLLM, llama.cpp and friends, with the usual localhost base URL prefilled.
   - **Other** — any endpoint that speaks the OpenAI API, with a base URL you enter.
4. Click a tile. The provider is created and its configure modal opens: enter the key or complete the OAuth sign-in, optionally set a default model, and **Save**.

![Settings → Providers listing the connected providers, each row with the service logo, name, and default model.](https://agentdocumentformat.org/docs-assets/assets/screenshots/settings-add-provider.png)

Provider keys are application-level and are **never** exposed to agent code execution — only server-side model invocation can use them. See [Settings](https://agentdocumentformat.org/studio/settings) for the full provider reference.

---

## Anatomy of the Interface

The Studio window is organized into a few persistent areas:

- **Sidebar** (left) — your open agents and their live status, plus quick actions (**New .adf**, open, Settings). Selecting an agent loads it into the main panel.
- **Main panel** (center) — the active tab for the selected agent.
- **Right panel** (collapsible) — additional context and configuration where applicable.

### Per-agent tabs

| Tab | What it shows |
|-----|---------------|
| **Loop** | The conversation/transcript: your messages, the agent's reasoning, tool calls and results. This is where you chat with the agent. |
| **Inbox** | Messages received from other agents over the mesh. |
| **Files** | The agent's files (`adf_files`): `README.md`, `mind.md`, `soul.md`, and any uploaded or agent-written files. |
| **Agent** | The configuration panel, with sub-sections for Identity, Model, Instructions, Tools, Triggers, Messaging, Serving, Timers, and the raw Config. (`mind.md` and `soul.md` are edited as files in the editor, not here.) |

### The Home view

When no agent is selected, Studio shows a **Home** dashboard: a compact header plus a grid of status tiles (agents, messaging, compute/containers, and more) that load progressively and deep-link into the relevant **Settings** section when clicked. A **Networking** panel surfaces LAN discovery state. Container-backed tiles refresh on a short interval so they settle as services finish booting.

![The Home dashboard with an "All systems go" banner, status tiles for Providers, MCP Servers, Channels, Packages, Containers, Host Access, Agents, and Running counts, a Networking panel with Mesh, LAN Discovery, LAN Peers, and Tailnet tiles, and the tracked directories list.](https://agentdocumentformat.org/docs-assets/assets/screenshots/home-dashboard.png)

### The fleet map

The **Age of Agents** button in the toolbar opens the fleet map — an RTS-style command surface where every agent is a tile on a hex-territory map, grouped by directory. From there you can select one or many agents, command them with hotkeys, rearrange the map's geography, and handle pending approvals. See the [Fleet Map guide](https://agentdocumentformat.org/studio/fleet-map).

![The fleet map showing two agent districts named squad and ops on a dark hex-tile map, floating status chips over each district, an internet gateway station, a terrain legend in the top-right corner, and a minimap in the bottom-right corner.](https://agentdocumentformat.org/docs-assets/assets/screenshots/fleet-map-overview.png)

---

## Creating Your First Agent

1. Click **New .adf** in the sidebar.
2. Choose a filename — this becomes the agent's default name.
3. Studio creates the `.adf` file in your tracked directory from an [agent template](https://agentdocumentformat.org/guides/agent-templates).

A new agent gets everything in its template except the template's identity and history, including its start state, files and tool set. It gets a new 12-character config `id` and its own identity. Fields the template does not set take the [new-file defaults](https://agentdocumentformat.org/spec#141-new-file-defaults).

See [Creating and Configuring Agents](https://agentdocumentformat.org/guides/creating-agents) for every configuration field.

---

## Talking to Your Agent

1. Select the agent in the sidebar and open the **Loop** tab.
2. Type a message in the input at the bottom and press **Enter**.

Sending a message drives the lifecycle:

1. The agent transitions from **idle** to **active**.
2. Its model processes your message alongside its instructions, document, and available tools.
3. It responds, possibly calling tools along the way — each call and result is shown inline in the Loop.
4. It returns to **idle**.

![The Loop tab showing a conversation: a collapsed Context Injected block, a user message bubble, an expandable amber Thinking block with a token count, assistant text, and inline msg_send and fs_write tool-call chips with their JSON arguments.](https://agentdocumentformat.org/docs-assets/assets/screenshots/agent-loop-conversation.png)

See [Agent States and Lifecycle](https://agentdocumentformat.org/guides/agent-states) for the full state model (active, idle, hibernate, suspended, off) and [Memory Management](https://agentdocumentformat.org/guides/memory-management) for how the Loop is compacted and archived over time.

---

## Configuring an Agent

Open the **Agent** tab to configure the selected agent. The main areas:

- **Identity** — name, description, icon, and the agent ID/DID.
- **Model** — provider, model ID, temperature, max tokens, thinking budget, and provider parameters.
- **Instructions** — the system prompt (immutable by the agent itself).
- **Tools** — which built-in tools are enabled and visible, and which are restricted/locked. See [Tools](https://agentdocumentformat.org/guides/tools).
- **Triggers** — what events wake the agent. See [Triggers](https://agentdocumentformat.org/guides/triggers).
- **Messaging** — channels and inter-agent routing. See [Messaging](https://agentdocumentformat.org/guides/messaging).
- **Serving** — HTTP routes, shared files, and WebSocket endpoints. See [HTTP Serving](https://agentdocumentformat.org/guides/serving).

![The Agent → Config panel showing the Identity section (name, description, icon, start-in-state, autostart, autonomous) and the Model section (provider, model ID, temperature, max tokens, and reasoning effort selector).](https://agentdocumentformat.org/docs-assets/assets/screenshots/agent-config-model.png)

Every field is documented in [Creating and Configuring Agents](https://agentdocumentformat.org/guides/creating-agents).

---

## Settings

Settings (gear icon, or `Cmd/Ctrl + ,`) holds application-wide and instance-wide configuration:

- **Providers** — LLM provider accounts and default models.
- **Packages** — runtime sandbox packages available to *every* agent on this instance, installed to the shared store at `~/.adf-studio/sandbox-packages/`. Agents can also promote their own packages here via **Make Runtime**. See [Code Execution](https://agentdocumentformat.org/guides/code-execution).
- **MCP** — the MCP Status Dashboard for registered tool servers and their credentials. See [MCP Integration](https://agentdocumentformat.org/guides/mcp-integration).
- **Computer tab** — each desktop-enabled isolated agent has a small standard Linux desktop (Openbox, tint2, PCManFM) with one ADF-managed Chromium session that opens on demand. Studio streams it through noVNC, browser MCP automation controls Chromium through CDP, and `xdotool`/`scrot` give agents generic computer use. See [Computer](https://agentdocumentformat.org/guides/browser).
- **Networking** — LAN discovery (mDNS) state and discovered runtimes. See [LAN Discovery](https://agentdocumentformat.org/guides/lan-discovery).
- **Web** — settings for serving agent content over HTTP. See [HTTP Serving](https://agentdocumentformat.org/guides/serving).
- **About / Updates** — version and update information.

The complete reference is in [Settings](https://agentdocumentformat.org/studio/settings).

---

## Multimodal

Studio agents can perceive images, audio, and video when the matching modality is enabled in the agent's `model.multimodal` configuration. When enabled, media returned by `fs_read` or MCP tools is sent to the model as a native content block (rather than just a path reference); when disabled, the file is still saved to `adf_files` and the tool result includes a path reference, but no content block is created.

| Modality | Config flag | Content block | Supported formats | Default size limit (`limits.*`) |
|----------|-------------|---------------|-------------------|--------------------------------|
| **Image** | `multimodal.image` | `image_url` | PNG, JPEG, GIF, WEBP | `max_image_size_bytes` (5 MB) |
| **Audio** | `multimodal.audio` | `input_audio` | WAV, MP3, OGG, FLAC, AAC, AIFF, M4A, WebM | `max_audio_size_bytes` (10 MB) |
| **Video** | `multimodal.video` | `video_url` | MP4, MPEG, QuickTime, WebM | `max_video_size_bytes` (20 MB) |

Notes:

- **Image** replaces the legacy `model.vision` toggle.
- **Audio** — the AI SDK natively supports only WAV and MP3; other formats are coerced to WAV for the SDK's validator while actual codec negotiation happens provider-side.
- **Video** — the AI SDK has no native video support, so the runtime injects raw OpenAI-format `video_url` parts directly into the request body. This works for providers that accept the OpenAI chat-completions format (OpenRouter, Gemini, etc.).
- Media content blocks are **ephemeral** — they are not persisted to `adf_loop`.
- **In code/shell execution**, the full structured JSON (with raw base64 data) is always returned regardless of these settings, so agents can parse, transform, save (`fs_write`), or forward media programmatically. See [The adf Proxy Object](https://agentdocumentformat.org/guides/adf-object) and [Tools](https://agentdocumentformat.org/guides/tools#filesystem-tools).

---

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Cmd/Ctrl + ,` | Open Settings |
| `Cmd/Ctrl + S` | Save the current editor tab |
| `Cmd/Ctrl + W` | Close the active editor tab |

---

## Where to Go Next

- [Getting Started](https://agentdocumentformat.org/studio/getting-started) — create your first agent and start a conversation.
- [Core Concepts](https://agentdocumentformat.org/guides/core-concepts) — one file, one agent; the access boundary; the ADF stack.
- [Documentation index](https://agentdocumentformat.org/guides) — the full list of guides for the format, runtime, tools, messaging, security, and more.
- [Daemon documentation](https://agentdocumentformat.org/cli/daemon) — run the same `.adf` agents headlessly via the API runtime.