Skip to main content

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 and Catalyst Cloud. Unlike the 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:

2. Log in to Catalyst​

Authenticate to Diagrid Catalyst using the following command:

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:

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:

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

Navigate to the quickstart directory:

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

4. Configure OpenAI API Key​

Add your OpenAI API key to resources/agent-llm-provider.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:

uv sync

6. Run with Catalyst Cloud​

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

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.

7. Trigger the Orchestrator​

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

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."}'

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.

How this differs from the Multi-Agent Workflow quickstart​

In the 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 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:

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​

Last updated on