Get Started

Design and Run Agent Workflows

Create a reusable team of agents, connect their handoffs, validate drafts, and run the workflow from AI Chat with an execution report you can inspect.

Updated: July 4, 2026

What you need

  • Multi Agents: open the designer to create and edit flows.
  • AI Chat provider: connect a provider and model for LLM Instruction agents.
  • Saved tools: configure MCP tools before assigning a Tool Runner agent.
  • Professional license: required for workflow creation, commit, and advanced tool usage.

Quick links

Quick Start Designer Runtime Skill Executor Fixes Next Steps

Quick start in 5 steps

  1. Open Multi Agents and choose Add Multi-Agent Flow or New Flow.
  2. Name the flow, add a practical Goal, and keep the starting Coordinator and Specialist agents.
  3. Select each agent on the canvas, set a clear Role, write a direct Instruction, and leave Execution on LLM Instruction for the first test.
  4. Connect agents with readable links such as Delegation, Handoff, or Review, then save with Save or Command-S.
  5. Open AI Chat, click Select Multi-Agent Workflow, choose the flow, send a request, and review the generated execution report.
Start with two or three agents. Add more only when the new agent has a different responsibility, output, or review standard.

Shape the flow in the Agent Workflow Designer

The designer has three working areas: the saved flow list, the canvas, and the Inspector. Use the list to find workflows by name, goal, summary, or pattern. Use the canvas to arrange agents and links. Use the Inspector to edit the selected workflow, agent, or link.

Choose the workflow pattern

  • Coordinator: one root agent delegates work and gathers results.
  • Hierarchical: agents follow a chain of responsibility.
  • Peer Review: one or more agents check another agent's result.
  • Pipeline: each agent handles one step and passes output forward.
  • Parallel Debate: agents explore different positions before synthesis.

Give every agent one job

Use roles as readable labels: Root Coordinator, Planner, Specialist, Reviewer, Tool Runner, or Synthesizer. The instruction is still the source of behavior, so include the responsibility, expected output, and boundaries.

Review the specialist result. Find correctness risks,
missing checks, and unclear assumptions. Return concise
findings and a final go/no-go recommendation.

Use properties for values that change

Agent properties can hold strings, numbers, booleans, or JSON. Use them for review standards, acceptance criteria, fixed tool arguments, thresholds, or shared state names.

Understand the Agent Workflow Runtime

When AI Chat runs a workflow, MCP Studio snapshots the saved flow, finds agents whose dependencies are ready, and executes ready batches asynchronously. Independent agents can run in parallel; agents with incoming links wait for upstream results.

  • LLM Instruction: sends the agent instruction to the active chat session or a specific provider and model.
  • MCP Tool: runs one selected MCP tool and passes workflow context, incoming agent results, and agent properties as input context.
  • Root Coordinator pass-through: a coordinator with delegation links can release downstream agents without spending a model call.
  • Execution report: captures workflow runtime, per-agent status, provider or model, output, errors, and notes about slow agents or dependency failures.
If an upstream agent fails, dependent agents may be skipped. Fix the first failed agent before tuning downstream instructions.

Create workflows with the Agent Workflow Skill

The agent_workflow_creator skill turns a goal into a draft-first workflow. It creates a normalized preview, validates it, explains warnings, and commits only when the draft is valid and the user intent is clear.

  1. Describe the outcome, domain, review step, and completion criteria.
  2. Let the skill create a draft with create_multi_agent_workflow_draft.
  3. Validate the preview with validate_multi_agent_workflow_draft.
  4. Review names, roles, instructions, properties, and connections.
  5. Commit the valid draft with commit_multi_agent_workflow_draft when you are ready to save it.
{
  "name": "Small Task Review",
  "pattern": "coordinator",
  "agents": ["Coordinator", "Specialist", "Reviewer"],
  "connections": ["Delegate task", "Review result"]
}

Run saved flows with the Agent Workflow Executor

The executor exposes saved workflows as a callable MCP Studio tool. Use agent_workflow_run when a task should be handled by the runtime instead of manually simulating multiple agents.

  • user_prompt: the task or question passed into the workflow.
  • workflow_id: the preferred stable identifier from the workflow catalog.
  • workflow_name: a fallback when the ID is not available.
  • execution_report: the markdown report returned after the run.
Use workflow IDs for repeatable automations. Use workflow names only while testing or when you are selecting a flow by hand.

Common problems and quick fixes

  • No workflow appears in AI Chat: open Multi Agents, save the flow, then reopen the workflow picker.
  • Wrong model is used: check the agent's Execution section. Active Session uses the current AI Chat provider and model; a specific provider uses the saved model.
  • Missing model or token: open the provider settings and verify base URL, API token if required, and model availability.
  • Tool Runner fails: switch the agent to MCP Tool mode, select a tool, and confirm the license requirement for BuiltinTool, ScriptTool, or CustomTool.
  • Workflow stalls or skips agents: inspect the first failed upstream agent and check for broken links or dependency cycles.
  • Output feels random: lower Temperature for review and verification agents.
  • Workflow takes too long: reduce agent count, lower Max Turns, or choose faster providers and models.
In the sandboxed app, shell scripts or programs outside granted folders may not execute. Use the non-sandboxed MCP Studio build when a workflow must call build tools such as xcrun or xcodebuild.

Next steps