Skip to main content

Quickstart: Durable Agent

This quickstart showcases how to build and run a durable agent using Dapr Agents. The agent acts as a travel assistant that can search for flights and hotels, maintain conversation memory, and execution state across restarts. Catalyst hosts the workflow execution engine, manages the agent state, performs LLM calls, with the application containing the agent code.

durable agent overview

Prerequisites​

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

Log in to Catalyst​

Authenticate to Diagrid Catalyst using the following command:

diagrid login

Confirm your organization and user details are correct:

diagrid whoami

Clone quickstart code​

Clone the quickstart code from the Diagrid Labs GitHub repository and navigate to the appropriate directory:

diagrid dev quickstart --type durable-agent --language python

Configure OpenAI API Key​

Navigate to the resources folder and update the openai.yaml file with your OpenAI API key:

metadata:
  - name: key
    value: "YOUR_OPENAI_API_KEY"

Install python dependencies in a virtual environment​

note

This quickstart uses the venv module to create the virtual environment. Please feel free to adapt if you prefer to use conda, pipenv, or another alternative.

python -m venv .venv

If you are using MacOS, start the virtual environment with the following command:

source .venv/bin/activate
tip

Don't forget to close your virtual environment with deactivate when done with the quickstart

Install the python app requirements:

pip install -r requirements.txt

Run quickstart application​

To run the quickstart locally, use the diagrid dev run command. This command uses the dapr multi-app run file in the root of the code directory to:

  • Create a Catalyst project: If the project does not exist, the command will create a new project
  • Create resources: Creates the necessary resources on Catalyst such as App IDs, Components, and Diagrid managed services including multiple state stores (execution state, memory state, and registry state) and pubsub.
  • Inject environment variables: Configures the Dapr client to talk to Catalyst
  • Launch the quickstart application: Locates the code directory and launches the application using the app command input

For additional details on the Catalyst local development experience, read Develop Locally with Catalyst APIs.

Run the application using the following command:

diagrid dev run -f dev-python-durable-agent.yaml --project dev-python-durable-agent

Interact with Durable Agent​

With the quickstart application running, it's time to test the Durable Agent. Use the curl command below or take advantage of the REST Client extension using Visual Studio Code with the test.rest file in the root folder of the repo.

Start agent workflow​

Open a new terminal and execute the following curl command to start a new agent workflow:

curl -i -X POST http://localhost:5001/start-workflow \
  -H "Content-Type: application/json" \
  -d '{"task": "Find me flights and hotels to London and Amsterdam"}'

This command will block until the agent completes the workflow that has been started. The agent will:

  1. Process your travel request using natural language understanding
  2. Execute the search_flights tool in parallel for both cities with simulated external API calls
  3. If flights are found, call the search_hotels tool in parallel for the same destinations
  4. Return available flight and hotel options with pricing information
  5. Persist all execution state, conversation memory, and agent registry data in Catalyst’s managed key-value stores

Monitor in Catalyst Dashboard​

Navigate to the Catalyst web console to explore and monitor your agent execution.

  1. View Workflow Execution

Use the Workflows section to observe the real-time progress of your agent workflow. You can examine each action taken, along with its input and output, and the time it took to complete or fail.

The diagram below shows an example workflow executed by the travel assistant agent. It starts by invoking the LLM, performs two parallel flight searches, and then summarizes the results.

workflow viewer

The structure of the workflow may vary depending on the prompt and LLM provider.

  1. Examine State Storage

Catalyst automatically maintains three state stores that persist agent context and execution data:

  • statestore Workflow execution state and retry information
  • memory-state Conversation history and context
  • registry-state Agent registry and metadata

You can inspect the key/value data using the Diagrid KV Store data explorer.

durable agent state

  1. View Application Map

The Application Map visualizes how the travel-assistant service interacts with Catalyst-managed components and dependencies. It helps identify relationships between the agent, its tools, and external resources.

You can experiment with different types of travel queries. For example, ask the agent to find flights and hotels for a single destination, or search for flights only. The agent will automatically adapt and build a suitable workflow based on your input.

The following example triggers only parallel flight searches:

curl -i -X POST http://localhost:5001/start-workflow \
  -H "Content-Type: application/json" \
  -d '{"task": "Find me only flights to Paris and Barcelona"}'

You can watch the workflow execution live in the Catalyst workflow visualizer. The workflow structure may differ based on the query and model response.

Clean up resources​

If you are not going to continue to use this application, you can delete the resources using the following commands:

diagrid appid delete travel-assistant-agent

If you want to delete the entire Catalyst project, including the managed infrastructure resources, run the diagrid project delete command.