# Quickstart: Multi-Agent Orchestrator

This quickstart shows how to run an LLM-driven orchestrator agent that dynamically coordinates a triage agent and an expert agent using [Dapr Agents](https://github.com/dapr/dapr-agents) and [Catalyst Cloud](https://docs.diagrid.io/operate/hosting/catalyst-cloud). Unlike the [multi-agent workflow quickstart](https://docs.diagrid.io/develop/agents/dapr-agents/multi-agent-workflow-quickstart) where the agent sequence is hardcoded, here an LLM-powered orchestrator reasons about which agent to call next.

You will learn how to:

- Provision a Catalyst project and related resources using the Diagrid CLI.
- Run an LLM-driven orchestrator agent that delegates to specialist agents via Dapr pub/sub.
- Use a shared agent registry for dynamic agent discovery.
- Monitor orchestrated multi-agent execution in the Catalyst web console.

## 1. Prerequisites

Before you proceed, ensure you have the following prerequisites installed:

- [Diagrid Catalyst account](https://catalyst.diagrid.io/)
- [Diagrid CLI](https://docs.diagrid.io/references/catalyst/catalyst-cli-intro)
- [Git](https://git-scm.com/downloads)
- [Python 3.11, 3.12, or 3.13](https://www.python.org/downloads/) & [uv](https://docs.astral.sh/uv/#installation)
- [An OpenAI API key](https://platform.openai.com/api-keys)

## 2. Log in to Catalyst

Authenticate to Diagrid Catalyst using the following command:

```bash
diagrid login
```

This command opens a new browser window where you log into Catalyst.
Once logged in, you'll be shown a confirmation code (matching the code in your terminal) that you need to confirm.

Confirm your user details are correct using the following command:

```bash
diagrid whoami
```

The expected output contains the name of the organization, your user name, and the Catalyst API endpoint.

## 3. Clone Quickstart Code

Clone the quickstart code from GitHub:

```bash
git clone https://github.com/diagridio/catalyst-quickstarts.git
```

Navigate to the quickstart directory:

**macOS/Linux**

```bash
cd catalyst-quickstarts/dapr-agents/multi-agent-orchestrator
```

**Windows**

```powershell
cd catalyst-quickstarts\dapr-agents\multi-agent-orchestrator
```

## 4. Configure OpenAI API Key

Add your OpenAI API key to `resources/agent-llm-provider.yaml`:

```yaml
metadata:
  - name: key
    value: "YOUR_OPENAI_API_KEY"
  - name: model
    value: gpt-4.1-2025-04-14
```

## 5. Install Dependencies

Install dependencies with `uv`:

```bash
uv sync
```

## 6. Run with Catalyst Cloud

The `diagrid dev run` command creates your Catalyst Cloud project (if needed), provisions resources (agents, Components, managed state stores and pubsub), configures environment variables, and sets up the connection between your local environment and Catalyst Cloud.

```bash
diagrid dev run -f dapr.yaml --project multi-agent-orchestrator-quickstart --approve
```

This starts three apps:

- `support-agent-orchestrator` on port 8001 — LLM-powered coordinator that decides which agent to delegate to
- `triage-agent` on port 8002 — checks customer entitlement and assesses urgency
- `expert-agent` on port 8003 — retrieves environment info and proposes a resolution

:::tip
Wait for the log output to confirm all three apps are running and registered before proceeding.
:::

```mermaid
---
title: Orchestrator Agent connected to Catalyst
---
flowchart LR
  ORCH(Orchestrator Agent)
  TRIAGE(Triage Agent)
  EXPERT(Expert Agent)
  subgraph Catalyst
    WF(Workflow Engine)
    STATE[(State Stores)]
    PUBSUB((PubSub))
    REGISTRY[(Agent Registry)]
    CONV(Conversation Component)
  end
  OPENAI(OpenAI)

  ORCH<-->WF
  TRIAGE<-->WF
  EXPERT<-->WF
  ORCH<-->PUBSUB
  TRIAGE<-->PUBSUB
  EXPERT<-->PUBSUB
  ORCH<-->REGISTRY
  TRIAGE<-->REGISTRY
  EXPERT<-->REGISTRY
  WF<-->STATE
  ORCH<-->CONV
  TRIAGE<-->CONV
  EXPERT<-->CONV
  CONV-->OPENAI
```

## 7. Trigger the Orchestrator

Open a new terminal and trigger the orchestrator agent via REST API:

**macOS/Linux**

```bash
curl -i -X POST http://localhost:8001/agent/run \
  -H "Content-Type: application/json" \
  -d '{"task": "Customer: Alice. Issue: My Dapr system fails to start in production."}'
```

**Windows**

```powershell
Invoke-RestMethod -Method Post -Uri "http://localhost:8001/agent/run" -ContentType "application/json" -Body '{"task": "Customer: Alice. Issue: My Dapr system fails to start in production."}'
```

The orchestrator agent will:

1. Reason about the task and decide to delegate to the **Triage Agent** via pub/sub.
2. Receive the triage result (entitlement and urgency) and decide whether to delegate to the **Expert Agent**.
3. Receive the expert's proposed resolution and synthesize a customer-friendly response.

```mermaid
---
title: LLM-driven orchestrator dynamically delegates to specialist agents
---
flowchart TD
  START((Start)):::startNode
  TASK(Receive Task)
  REASON(Orchestrator LLM:
  which agent next?)
  TRIAGE(Triage Agent)
  EXPERT(Expert Agent)
  SYNTH(Orchestrator LLM:
  synthesize response)
  END((End)):::endNode

  START-->TASK
  TASK-->REASON
  REASON-- delegate -->TRIAGE
  TRIAGE-->REASON
  REASON-- delegate -->EXPERT
  EXPERT-->REASON
  REASON-- done -->SYNTH
  SYNTH-->END

  classDef startNode stroke:#22613f,stroke-width:3px
  classDef endNode stroke:#8b1a1a,stroke-width:3px
```

### How this differs from the Multi-Agent Workflow quickstart

In the [multi-agent workflow quickstart](https://docs.diagrid.io/develop/agents/dapr-agents/multi-agent-workflow-quickstart), the sequence triage → expert is hardcoded in a workflow definition. Here, the orchestrator agent uses an LLM to decide which agents to call and in what order. This makes the system more flexible — the orchestrator can skip agents, call them in different orders, or retry based on results — at the cost of being non-deterministic.

## 8. View in the Catalyst web console

Open the Workflow viewer in the [Catalyst Cloud web console](https://catalyst.diagrid.io/workflows/executions) and navigate to the **Workflows** section. Select the workflow instance that corresponds to your orchestrator run.

The workflow visualizer shows how the orchestrator reasons about the task and delegates to each agent. Inspect every step to see the LLM prompts, responses, and pub/sub messages exchanged between agents.

## 9. Clean Up

Stop the running application by pressing `Ctrl+C` in the terminal where `diagrid dev run` is running.

Delete the Catalyst Cloud project to clean up all provisioned resources:

```bash
diagrid project delete multi-agent-orchestrator-quickstart
```

## Summary

In this quickstart, you:

- Ran an LLM-driven orchestrator agent built with Dapr Agents, connected to Catalyst Cloud for durable execution.
- Observed the orchestrator dynamically delegating to specialist agents via pub/sub and a shared agent registry.
- Inspected orchestrated multi-agent executions in the Catalyst web console.

## Next steps

- Compare with the [Multi-Agent Workflow quickstart](https://docs.diagrid.io/develop/agents/dapr-agents/multi-agent-workflow-quickstart) to see the same triage and expert agents coordinated by a deterministic workflow instead.
- Explore the [Dapr Agents documentation](https://github.com/dapr/dapr-agents) for more agent development patterns.
- Browse available [conversation components](https://docs.diagrid.io/references/catalyst/components-reference/conversation/openai) for different LLM providers.