# Quickstart: Multi-Agent Orchestration

This quickstart shows how to run a multi-agent orchestration system where nine specialist agents — each built with a different AI framework — coordinate through Dapr pub/sub to plan events end-to-end. An orchestrator agent discovers available specialists via a shared registry and delegates tasks to plan a complete event.

You will learn how to:

- Run nine agents built with different AI frameworks (Google ADK, CrewAI, Dapr Agents, LangGraph, OpenAI Agents, Pydantic AI, Strands, and Claude Agents) in a single orchestration
- Use Dapr pub/sub for inter-agent communication and task delegation
- Use a shared agent registry for dynamic agent discovery
- Monitor multi-agent execution in the Catalyst web console

```mermaid
---
title: Event Planning Orchestration connected to Catalyst
---
flowchart LR
  ORCH(Event Coordinator)
  subgraph Specialists
    ADK(Entertainment Planner - ADK)
    CREW(Venue Scout - CrewAI)
    DAPR(Invitations Manager - Dapr Agents)
    LANG(Schedule Planner - LangGraph)
    OPENAI(Catering Coordinator - OpenAI Agents)
    PYAI(Decoration Planner - Pydantic AI)
    STRANDS(Budget Analyst - Strands)
    CLAUDE(Photography Planner - Claude Agents)
  end
  subgraph Catalyst
    PUBSUB(Pub/Sub Broker)
    STATE[(State Store)]
    REGISTRY[(Agent Registry)]
    WF(Workflow Engine)
  end

  ORCH<-->PUBSUB
  PUBSUB<-->ADK
  PUBSUB<-->CREW
  PUBSUB<-->DAPR
  PUBSUB<-->LANG
  PUBSUB<-->OPENAI
  PUBSUB<-->PYAI
  PUBSUB<-->STRANDS
  PUBSUB<-->CLAUDE
  ORCH<-->WF
  WF<-->STATE
  ORCH<-->REGISTRY
```

## 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.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)
- [An Anthropic API key](https://console.anthropic.com/settings/keys) (for the Claude Agents photography planner)

## 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/agents/dapr-agents/orchestrator
```

**Windows**

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

## 4. Configure API Keys

Export `OPENAI_API_KEY` for the ADK, CrewAI, LangGraph, OpenAI Agents, Pydantic AI and Strands
agents and the orchestrator, and `ANTHROPIC_API_KEY` for the Claude Agents photography planner:

**macOS/Linux**

```bash
export OPENAI_API_KEY=""
export ANTHROPIC_API_KEY=""
```

**Windows**

```powershell
$env:OPENAI_API_KEY = ""
$env:ANTHROPIC_API_KEY = ""
```

Also update `resources/llm-provider.yaml` with your OpenAI API key for the Dapr Agents conversation component:

```yaml
metadata:
  - name: key
    value: "YOUR_OPENAI_API_KEY"
```

## 5. Install Dependencies

Each agent declares its dependencies in its own `pyproject.toml`, and `uv` creates and manages the virtual environment for you:

```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
uv run diagrid dev run -f dev-multi-agent-orchestration.yaml
```

:::tip
Wait for all nine agents to start. You should see log output for each agent confirming it is running before proceeding.
:::

This starts all agents on ports 8001-8009:

| Port | ID | Agent | Framework |
|------|--------|-------|-----------|
| 8001 | `entertainment-planner` | Entertainment Planner | Google ADK |
| 8002 | `venue-scout` | Venue Scout | CrewAI |
| 8003 | `invitations-manager` | Invitations Manager | Dapr Agents |
| 8004 | `event-coordinator` | Event Coordinator | Dapr Agents |
| 8005 | `schedule-planner` | Schedule Planner | LangGraph |
| 8006 | `catering-coordinator` | Catering Coordinator | OpenAI Agents |
| 8007 | `decoration-planner` | Decoration Planner | Pydantic AI |
| 8008 | `budget-planner` | Budget Analyst | Strands |
| 8009 | `photography-planner` | Photography Planner | Claude Agents |

## 7. Trigger an Orchestration

Once all agents are running, send an event planning request to the orchestrator:

**macOS/Linux**

```bash
curl -i -X POST http://localhost:8004/agent/run \
  -H "Content-Type: application/json" \
  -d '{"task": "Plan a corporate gala in San Francisco for 200 guests on March 15, 2026"}'
```

**Windows**

```powershell
Invoke-RestMethod -Method Post -Uri "http://localhost:8004/agent/run" -ContentType "application/json" -Body '{"task": "Plan a corporate gala in San Francisco for 200 guests on March 15, 2026"}'
```

The orchestrator will:

1. Discover all registered agents in the shared registry
2. Create an execution plan with tasks for each specialist
3. Delegate entertainment to the Entertainment Planner (ADK)
4. Delegate venue search to the Venue Scout (CrewAI)
5. Delegate invitations to the Invitations Manager (Dapr Agents)
6. Delegate scheduling to the Schedule Planner (LangGraph)
7. Delegate catering to the Catering Coordinator (OpenAI Agents)
8. Delegate decorations to the Decoration Planner (Pydantic AI)
9. Delegate budgeting to the Budget Analyst (Strands)
10. Synthesize all results into a comprehensive event plan

The response will include a complete event plan with venue, catering, entertainment, decorations, scheduling, budget, and invitation details.

## 8. View in the Catalyst web console

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

The Catalyst workflow visualizer shows the orchestrator delegating tasks to specialist agents. You can inspect every step with its inputs and outputs — including the LLM's delegation decisions, agent responses, and the final synthesized event plan.

## 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 <your-project-name>
```

## Summary

In this quickstart, you:

- Ran 8 specialist agents built with 7 different AI frameworks in a single orchestration
- Used Dapr pub/sub for inter-agent communication and a shared registry for agent discovery
- Observed multi-agent orchestration and workflow visualization in the Catalyst console

## Next steps

- Try the [Durable Agent quickstart](https://docs.diagrid.io/develop/agents/dapr-agents/durable-agent-quickstart) to build a single durable agent with tool-calling capabilities.
- Explore the [Dapr Agents documentation](https://docs.dapr.io/developing-applications/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.