# Quickstart: Multi-Agent Workflow

This quickstart shows how to run a customer support system built with [Dapr Agents](https://github.com/dapr/dapr-agents) and [Catalyst Cloud](https://docs.diagrid.io/operate/hosting/catalyst-cloud). A Dapr Workflow orchestrates two durable agents — a triage agent and an expert agent — as child workflows to handle support tickets end-to-end.

You will learn how to:

- Provision a Catalyst project and related resources using the Diagrid CLI.
- Run a deterministic multi-agent workflow that calls durable agents as child workflows.
- Monitor sequential 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-workflow
```

**Windows**

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

## 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-workflow-quickstart --approve
```

This starts three apps:

- `customer-support-system` on port 8001 — the workflow app that exposes the REST endpoint
- `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 before proceeding.
:::

```mermaid
---
title: Multi-Agent Workflow connected to Catalyst
---
flowchart LR
  APP(Customer Support System)
  TRIAGE(Triage Agent)
  EXPERT(Expert Agent)
  subgraph Catalyst
    WF(Workflow Engine)
    STATE[(State Stores)]
    CONV(Conversation Component)
  end
  OPENAI(OpenAI)

  APP<-->WF
  TRIAGE<-->WF
  EXPERT<-->WF
  WF<-->STATE
  TRIAGE<-->CONV
  EXPERT<-->CONV
  CONV-->OPENAI
```

## 7. Trigger the Workflow

Open a new terminal and trigger the workflow via REST API:

**macOS/Linux**

```bash
curl -i -X POST http://localhost:8001/workflow/start \
  -H "Content-Type: application/json" \
  -d '{"customer": "Alice", "issue": "My Dapr system fails to start in production."}'
```

**Windows**

```powershell
Invoke-RestMethod -Method Post -Uri "http://localhost:8001/workflow/start" -ContentType "application/json" -Body '{"customer": "Alice", "issue": "My Dapr system fails to start in production."}'
```

The workflow will:

1. Call the **Triage Agent** as a child workflow to check Alice's entitlement and assess urgency.
2. If Alice is entitled, call the **Expert Agent** as a child workflow to retrieve environment info and generate a resolution.
3. Return a customer-ready response with the proposed fix.

```mermaid
---
title: Deterministic multi-agent workflow
---
flowchart TD
  START((Start)):::startNode
  REQ(Receive Support Request)
  TRIAGE(Triage Agent:
  check entitlement and urgency)
  DECISION{Entitled?}:::decision
  REJECT(Return: rejected)
  EXPERT(Expert Agent:
  retrieve environment and
  propose resolution)
  RESP(Return: customer response)
  END((End)):::endNode

  START-->REQ
  REQ-->TRIAGE
  TRIAGE-->DECISION
  DECISION-- No -->REJECT
  DECISION-- Yes -->EXPERT
  EXPERT-->RESP
  REJECT-->END
  RESP-->END

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

Try a customer other than Alice to see the entitlement check reject the request:

```bash
curl -i -X POST http://localhost:8001/workflow/start \
  -H "Content-Type: application/json" \
  -d '{"customer": "Bob", "issue": "Same production outage."}'
```

## 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 request.

The workflow visualizer shows the parent workflow and the child agent workflows, with inputs and outputs at each step — including LLM prompts, generated responses, and tool call parameters.

## 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-workflow-quickstart
```

## Summary

In this quickstart, you:

- Ran a multi-agent workflow based on Dapr Agents and Dapr Workflows, connected to Catalyst Cloud for durable execution.
- Observed a workflow orchestrating two durable agents as child workflows with a deterministic triage-then-expert sequence.
- Inspected parent and child workflow executions in the Catalyst web console.

## Next steps

- Try the [Multi-Agent Orchestrator quickstart](https://docs.diagrid.io/develop/agents/dapr-agents/multi-agent-orchestrator-quickstart) to see an LLM-driven orchestrator delegate to the same triage and expert agents dynamically.
- 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.