Setting Up Your Studio
Three steps take you from a blank studio to running your first AI agent.
Quick start: You can complete all three steps in under 10 minutes. The studio guides you through each one — follow the progress banner on the Model Config and Agent Config pages.
Step 1 — Add a Provider & API Key (Model Config)
Navigate to Studio → Model Config. The page shows a four-step setup banner at the top.
- Click Add Provider and choose your vendor (OpenAI, Anthropic, GitHub Models, Azure OpenAI).
- Paste your API key into the key field and click Apply Key. A ● Key stored badge confirms the key was saved (it is never shown in plain text again).
- Click Test Connection to verify the key works. A green ✓ Connected badge confirms success.
- Click 🔄 Fetch Models List to pull the provider’s current model catalogue. Apply, Test & Fetch Models does all three steps in one click.
Choosing a Provider
| Provider | Best for | Notes |
|---|---|---|
| OpenAI | General-purpose, broad capability | Requires an OpenAI account; models fetched from your account |
| Anthropic | Long context, safety-focused tasks | Requires an Anthropic account; Claude models fetched from your key |
| GitHub Models | Teams already on GitHub Copilot | Uses your GitHub token; no extra billing |
| Azure OpenAI | Enterprise data-residency requirements | Requires an Azure deployment endpoint |
Don't see your model? The dropdown shows exactly what the provider's API returns for your key — nothing is curated or hardcoded, so new models appear as soon as your account can call them. If one you expect is missing, re-run Fetch Models List (the list is cached until you refresh it) and check your account has access to it. You can always use ➕ Add other model ID to enter an ID by hand.
Step 2 — Select a Model per Provider (Model Config)
After fetching the model list, select the model your agents will use from the Model dropdown. The list comes straight from the provider, so it reflects their current line-up rather than a version baked into Productivity Workbench. Mark one model ⭐ Default per provider — that is the model agents use unless a specific agent overrides it.
- You can configure more than one provider and select different models for each.
- The Sync from providers button on the Allow-list automatically adds all selected models to the safe list.
- Click Next: Configure Agents → when all providers show a selected model.
Step 3 — Assign Models to Agents (Agent Config)
Navigate to Studio → Agent Config. Each agent card shows a Model selector and a Max Cost Per Run (USD) field.
- Select a model from the dropdown (populated from your configured providers). Assigning a model automatically enables the agent.
- Set a per-run cost limit. Recommended starting values:
Agent Recommended budget Rationale Composer $1.00 – $2.00 Short context, frequent use Coder $1.00 – $3.00 Medium context, code generation Tester $0.50 – $1.00 Low context, assertion generation Reviewer $0.50 – $1.50 Moderate context per PR Planner $2.00 – $5.00 Large context, strategic analysis - Use Apply to All to set the same model and budget across every agent in one click.
- Click Save Config, then open the Intent Pad.
Budget increments: The budget field accepts values in $0.10 increments (minimum $0.10). You can type any value — the field is not capped at $5; $5 is just the UI recommendation for most use cases.
After Setup — Using AI Features
Once all three steps are complete, any AI-powered page will activate. The most common starting points are:
- Intent page — open an Intent, draft its brief, and let AI break it into workstreams and Work Packages
- Intent Pad — capture raw problem statements and trigger agent classification
- Agent Runs — view run history, review agent output, and apply results to your workspace
Troubleshooting Setup Errors
| Error / symptom | Cause | Fix |
|---|---|---|
| "No model assigned — agent will not run" | Agent Config: agent has no model selected | Agent Config → select a model in the agent's Model dropdown |
| "Configure a provider in Model Config first" | Agent Config: no providers with API keys configured | Model Config → add provider → apply API key → test |
| Test connection returns ✗ Failed | Invalid or expired API key, wrong provider endpoint | Re-paste the API key; confirm the correct provider type is selected |
| Intent page: "AI not set up" banner | Studio provider or agent config incomplete | Follow the three-item checklist in the banner; each item links directly to the relevant config page |
| Model dropdown is empty in Agent Config | No provider has a defaultModel set yet | Model Config → choose a model for each provider → save |
| Cost exceeds budget error during run | Run context size exceeded the per-run cap | Agent Config → increase Max Cost Per Run for that agent type, or reduce the number of files per run |