# Quickstart: Durable Agent

This quickstart shows how to run a durable agent built using [Dapr Agents](https://github.com/dapr/dapr-agents) and [Catalyst Cloud](https://docs.diagrid.io/operate/hosting/catalyst-cloud). The agent acts as a travel assistant that can search for flights and hotels, maintain conversation memory, and persist execution state across restarts.

You will learn how to:

- Provision a Catalyst project and related resources using the Diagrid CLI.
- Run a durable AI agent with tool-calling capabilities using Dapr Agents with Catalyst Cloud
- Monitor parallel tool 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/durable-agent
```

**Windows**

```powershell
cd catalyst-quickstarts\dapr-agents\durable-agent
```

## 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"
```

Optionally, to use [Anthropic](https://docs.diagrid.io/references/catalyst/components-reference/conversation/anthropic) instead of OpenAI, update `resources/agent-llm-provider.yaml` with:

```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: anthropic
spec:
  type: conversation.anthropic
  version: v1
  metadata:
  - name: key
    value: "YOUR_ANTHROPIC_API_KEY"
  - name: model
    value: claude-opus-5
```

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

:::tip
Wait for the following log output to confirm the agent is running before proceeding:
:::

```text
Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)
== APP - travel-assistant-agent == Travel Assistant Agent is running
```

```mermaid
---
title: Travel Assistant Agent connected to Catalyst
---
flowchart LR
  APP(Travel Assistant Agent)
  subgraph Catalyst
    APPID(ID: travel-assistant-
    agent)
    WF(Workflow Engine)
    STATE[(State Store)]
    CONV(Conversation Component)
  end
  OPENAI(OpenAI)

  APP<-->APPID
  APPID<-->WF
  WF<-->STATE
  APPID<-->CONV
  CONV-->OPENAI
```

## 7. Interact with the Agent

Test the Durable Agent using the terminal or the [REST Client extension](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) with the `test.rest` file.

### 7.1 Example 1: Multi-city flights and hotels

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

**macOS/Linux**

```bash
curl -i -X POST http://localhost:8001/agent/run \
  -H "Content-Type: application/json" \
  -d '{"task": "Find me flights and hotels to London and Amsterdam"}'
```

**Windows**

```powershell
Invoke-RestMethod -Method Post -Uri "http://localhost:8001/agent/run" -ContentType "application/json" -Body '{"task": "Find me flights and hotels to London and Amsterdam"}'
```

At a high-level, the agent will:

1. Process your flight and hotels request
2. Execute the `search_flights` tool in parallel for both cities
3. Return flight options with pricing to the LLM and plan next steps
4. Execute the `search_hotels` tool in parallel for both cities
5. At every step, persist execution state and conversation history to Catalyst
6. Return flight and hotel options

```mermaid
---
title: Durable Agent workflow with parallel tool execution
---
flowchart TD
  START((Start)):::startNode
  TASK(Receive Task)
  LLM1(LLM: Plan Tool Calls)
  SF1(search_flights: City 1)
  SF2(search_flights: City 2)
  LLM2(LLM: Evaluate Flight Results)
  SH1(search_hotels: City 1)
  SH2(search_hotels: City 2)
  LLM3(LLM: Compile Response)
  END((End)):::endNode

  START-->TASK
  TASK-->LLM1
  LLM1-->SF1
  LLM1-->SF2
  SF1-->LLM2
  SF2-->LLM2
  LLM2-->SH1
  LLM2-->SH2
  SH1-->LLM3
  SH2-->LLM3
  LLM3-->END

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

The response will include flight and hotel search results for both London and Amsterdam with pricing details.

### 7.2 Example 2: Single destination

The agent adapts its workflow based on your input. You can search for flights only, hotels only, or both. For example, search for a flight and a hotel to a single destination:

**macOS/Linux**

```bash
curl -i -X POST http://localhost:8001/agent/run \
  -H "Content-Type: application/json" \
  -d '{"task": "Find me flights and hotels to London"}'
```

**Windows**

```powershell
Invoke-RestMethod -Method Post -Uri "http://localhost:8001/agent/run" -ContentType "application/json" -Body '{"task": "Find me flights and hotels to London"}'
```

## 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 agent execution.

The Catalyst workflow visualizer shows each step the agent takes during execution. You can inspect every step with its inputs and outputs — including inputs to the LLM, generated responses, and tool call parameters — making it easy to understand and debug agent behavior.

![workflow viewer](https://docs.diagrid.io/img/catalyst/durable-agent-wf-qs.png)

## 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 durable-agent-quickstart
```

## Summary

In this quickstart, you:

- Ran a durable AI agent based on Dapr Agents and connected to Catalyst Cloud for agent durability
- Observed parallel tool execution and workflow visualization in the Catalyst web console

## Next steps

- Explore the [Dapr Agents documentation](https://docs.dapr.io/developing-applications/dapr-agents/) for more agent development patterns.
- Try the [Multi-Agent Workflow quickstart](https://docs.diagrid.io/develop/agents/multi-agent-quickstart) to orchestrate multiple cooperating agents.
- Browse available [conversation components](https://docs.diagrid.io/references/catalyst/components-reference/conversation/openai) for different LLM providers.