diff --git a/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-core-concepts.md b/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-core-concepts.md index 20f77aada..9680eb5e6 100644 --- a/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-core-concepts.md +++ b/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-core-concepts.md @@ -2,17 +2,13 @@ type: docs title: "Core Concepts" linkTitle: "Core Concepts" -weight: 30 +weight: 40 description: "Learn about the core concepts and principles of Dapr Agents" --- -# Core Concepts +## Principles -## Core Principles - -![Agent Overview](/images/dapr-agents/concepts-agents-overview.png) - -### 1. Agent-Centric Design +### Agent-Centric Design Dapr Agents is designed to place agents, powered by LLMs, at the core of task execution and workflow orchestration. This principle emphasizes: @@ -26,7 +22,7 @@ While Dapr Agents centers around agents, it also recognizes the versatility of u Agents are not standalone; they are building blocks in larger, orchestrated workflows. {{% /alert %}} -### 2. Decoupled Infrastructure Design +### Decoupled Infrastructure Design Dapr Agents ensures a clean separation between agents and the underlying infrastructure, emphasizing simplicity, scalability, and adaptability: @@ -39,7 +35,7 @@ Decoupling infrastructure keeps agents focused on tasks while enabling seamless ![Decoupled Principles](/images/dapr-agents/home_concepts_principles_decoupled.png) -### 3. Modular Component Model +### Modular Component Model Dapr Agents utilizes [Dapr's pluggable component framework](https://docs.dapr.io/concepts/components-concept/) and building blocks to simplify development and enhance flexibility: @@ -54,22 +50,7 @@ Developers can easily switch between different components (e.g., Redis to Dynamo ![Modular Principles](/images/dapr-agents/home_concepts_principles_modular.png) -### 4. Actor-Based Model for Agents - -Dapr Agents leverages [Dapr's Virtual Actor model](https://docs.dapr.io/developing-applications/building-blocks/actors/actors-overview/) to enable agents to function efficiently and flexibly within distributed environments. Each agent in Dapr Agents is instantiated as an instance of a class, wrapped and managed by a virtual actor. This design offers: - -* **Stateful Agents**: Virtual actors allow agents to store and recall information across tasks, maintaining context and continuity for workflows. -* **Dynamic Lifecycle Management**: Virtual actors are automatically instantiated when invoked and deactivated when idle. This eliminates the need for explicit creation or cleanup, ensuring resource efficiency and simplicity. -* **Location Transparency**: Agents can be accessed and operate seamlessly, regardless of where they are located in the system. The underlying runtime handles their mobility, enabling fault-tolerance and dynamic load balancing. -* **Scalable Execution**: Agents process one task at a time, avoiding concurrency issues, and scale dynamically across nodes to meet workload demands. - -This model ensures agents remain focused on their core logic, while the infrastructure abstracts complexities like state management, fault recovery, and resource optimization. - -{{% alert title="Note" color="info" %}} -Dapr Agents' use of virtual actors makes agents always addressable and highly scalable, enabling them to operate reliably and efficiently in distributed, high-demand environments. -{{% /alert %}} - -### 5. Message-Driven Communication +### Message-Driven Communication Dapr Agents emphasizes the use of Pub/Sub messaging for event-driven communication between agents. This principle ensures: @@ -83,7 +64,7 @@ Pub/Sub messaging serves as the backbone for Dapr Agents' event-driven workflows ![Message Principles](/images/dapr-agents/home_concepts_principles_message.png) -### 6. Workflow-Oriented Design +### Workflow-Oriented Design Dapr Agents embraces workflows as a foundational concept, integrating [Dapr Workflows](https://docs.dapr.io/developing-applications/building-blocks/workflow/workflow-overview/) to support both deterministic and event-driven task orchestration. This dual approach enables robust and adaptive systems: diff --git a/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-getting-started.md b/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-getting-started.md index a17c62e11..bb5961422 100644 --- a/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-getting-started.md +++ b/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-getting-started.md @@ -3,26 +3,17 @@ type: docs title: "Getting Started" linkTitle: "Getting Started" weight: 20 -description: "How to install and set up Dapr Agents" +description: "How to install and run Dapr Agents" --- - - -## Install Dapr Agents - -{{% alert title="Note" color="info" %}} -Make sure you have Python already installed. `Python >=3.10` +{{% alert title="Dapr Agents Concepts" color="primary" %}} +If you are looking for an introductory overview of Dapr Agents and want to learn more about basic Dapr Agents terminology, we recommend starting with the [introduction](dapr-agents-introduction.md) and [concepts](dapr-agents-core-concepts.md) sections. {{% /alert %}} -### As a Python package using Pip - -```bash -pip install dapr-agents -``` - ## Install Dapr CLI -Install the Dapr CLI to manage Dapr-related tasks like running applications with sidecars, viewing logs, and launching the Dapr dashboard. It works seamlessly with both self-hosted and Kubernetes environments. For a complete step-by-step guide, visit the official [Dapr CLI installation page](https://docs.dapr.io/getting-started/install-dapr-cli/). +While simple examples in Dapr Agents can be used without the sidecar, the recommended mode is with the Dapr sidecar. To benefit from the full power of Dapr Agents, install the Dapr CLI for running Dapr locally or on Kubernetes for development purposes. For a complete step-by-step guide, follow the [Dapr CLI installation page](https://docs.dapr.io/getting-started/install-dapr-cli/). + Verify the CLI is installed by restarting your terminal/command prompt and running the following: @@ -33,7 +24,7 @@ dapr -h ## Initialize Dapr in Local Mode {{% alert title="Note" color="info" %}} -Make sure you have [Docker](https://docs.docker.com/get-started/get-docker/) already installed. I use [Docker Desktop](https://www.docker.com/products/docker-desktop/). +Make sure you have [Docker](https://docs.docker.com/get-started/get-docker/) already installed. {{% /alert %}} Initialize Dapr locally to set up a self-hosted environment for development. This process fetches and installs the Dapr sidecar binaries, runs essential services as Docker containers, and prepares a default components folder for your application. For detailed steps, see the official [guide on initializing Dapr locally](https://docs.dapr.io/getting-started/install-dapr-selfhost/). @@ -52,7 +43,101 @@ Verify you have container instances with `daprio/dapr`, `openzipkin/zipkin`, and docker ps ``` -## Enable Redis Insights +## Install Python + +{{% alert title="Note" color="info" %}} +Make sure you have Python already installed. `Python >=3.10`. For installation instructions, visit the official [Python installation guide](https://www.python.org/downloads/). +{{% /alert %}} + +## Install Dapr Agents + +Install the Dapr Agents Python package using pip. For the latest version, check the [PyPI page](https://pypi.org/project/dapr-agents/). + +```bash +pip install dapr-agents +``` + +## Create Your First Dapr Agent + +Let's create a weather assistant agent that demonstrates tool calling with Dapr state management used for conversation memory. + +### 1. Create the environment file + +Create a `.env` file with your OpenAI API key: + +```env +OPENAI_API_KEY=your_api_key_here +``` + +### 2. Create the Dapr component + +Create a `components` directory and add `historystore.yaml`: + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: historystore +spec: + type: state.redis + version: v1 + metadata: + - name: redisHost + value: localhost:6379 + - name: redisPassword + value: "" +``` + +### 3. Create the agent with weather tool + +Create `weather_agent.py`: + +```python +import asyncio +from dapr_agents import tool, Agent +from dapr_agents.memory import ConversationDaprStateMemory +from dotenv import load_dotenv + +load_dotenv() + +@tool +def get_weather() -> str: + """Get current weather.""" + return "It's 72°F and sunny" + +async def main(): + agent = Agent( + name="WeatherAgent", + role="Weather Assistant", + instructions=["Help users with weather information"], + memory=ConversationDaprStateMemory(store_name="historystore", session_id="hello-world"), + tools=[get_weather], + ) + + # First interaction + response1 = await agent.run("Hi! My name is John. What's the weather?") + print(f"Agent: {response1}") + + # Second interaction - agent should remember the name + response2 = await agent.run("What's my name?") + print(f"Agent: {response2}") + + +if __name__ == "__main__": + asyncio.run(main()) +``` + + +### 4. Run with Dapr + +```bash +dapr run --app-id weatheragent --resources-path ./components -- python weather_agent.py +``` + +This example demonstrates an agent that uses tools to fetch weather information while persisting conversation history through Dapr's state management. + + +## Enable Redis Insights (Optional) Dapr uses [Redis](https://docs.dapr.io/reference/components-reference/supported-state-stores/setup-redis/) by default for state management and pub/sub messaging, which are fundamental to Dapr Agents's agentic workflows. These capabilities enable the following: @@ -60,7 +145,7 @@ Dapr uses [Redis](https://docs.dapr.io/reference/components-reference/supported- * Inspecting State Information: Access and analyze shared state data among agents. * Debugging and Monitoring Events: Track workflow events in real time to ensure smooth operations and identify issues. -To make these insights more accessible, you can leverage Redis Insight. +To make these insights more accessible, you can leverage Redis Insight for debugging purposes. ```bash docker run --rm -d --name redisinsight -p 5540:5540 redis/redisinsight:latest @@ -78,56 +163,8 @@ Redis Insight makes it easy to visualize and manage the data powering your agent ![Redis Dashboard](/images/dapr-agents/home_installation_redis_dashboard.png) -## Using custom endpoints -### Azure hosted OpenAI endpoint +## Next Steps -In order to use Azure OpenAI for the model you'll need the following `.env` file: - -```env -AZURE_OPENAI_API_KEY=your_custom_key -AZURE_OPENAI_ENDPOINT=your_custom_endpoint -AZURE_OPENAI_DEPLOYMENT=your_custom_model -AZURE_OPENAI_API_VERSION="azure_openai_api_version" -``` - -**NB!** the `AZURE_OPENAI_DEPLOYMENT` refers to the _model_, e.g., `gpt-4o`. `AZURE_OPENAI_API_VERSION` has been tested to work against `2024-08-01-preview`. - -Then instantiate the agent(s) as well as the orchestrator as follows: - -```python -from dapr_agents import DurableAgent, OpenAIChatClient -from dotenv import load_dotenv -import asyncio -import logging -import os - -async def main(): - llm = OpenAIChatClient( - api_key=os.getenv("AZURE_OPENAI_API_KEY"), - azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"), - azure_deployment=os.getenv("AZURE_OPENAI_DEPLOYMENT"), - api_version=os.getenv("AZURE_OPENAI_API_VERSION") - ) - - try: - elf_service = DurableAgent( - name="Legolas", role="Elf", - goal="Act as a scout, marksman, and protector, using keen senses and deadly accuracy to ensure the success of the journey.", - instructions=[ - "Speak like Legolas, with grace, wisdom, and keen observation.", - "Be swift, silent, and precise, moving effortlessly across any terrain.", - "Use superior vision and heightened senses to scout ahead and detect threats.", - "Excel in ranged combat, delivering pinpoint arrow strikes from great distances.", - "Respond concisely, accurately, and relevantly, ensuring clarity and strict alignment with the task."], - llm=llm, # Note the explicit reference to the above OpenAIChatClient - message_bus_name="messagepubsub", - state_store_name="workflowstatestore", - state_key="workflow_state", - agents_registry_store_name="agentstatestore", - agents_registry_key="agents_registry", - ) -... -``` - -The above is taken from [multi-agent quick starter](https://github.com/dapr/dapr-agents/blob/main/quickstarts/05-multi-agent-workflow-dapr-workflows/services/elf/app.py#L1-L23). \ No newline at end of file +Now that you have Dapr Agents installed and running, explore more advanced examples and patterns in the [quickstarts](dapr-agents-quickstarts.md) section to learn about multi-agent workflows, durable agents, and integration with Dapr's powerful distributed capabilities. + \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-tools.md b/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-integrations.md similarity index 88% rename from daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-tools.md rename to daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-integrations.md index 8edfb1917..d6ea7644e 100644 --- a/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-tools.md +++ b/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-integrations.md @@ -1,16 +1,30 @@ --- type: docs -title: "Tools" -linkTitle: "Tools" -weight: 50 -description: "Various tools and integrations available in Dapr Agents" +title: "Integrations" +linkTitle: "Integrations" +weight: 60 +description: "Various integrations available in Dapr Agents" --- -# Tools +# Integrations + + +Dapr Agents integrates with popular Python frameworks and tools. + +| Framework | Integration | Description | +|-----------|-------------|-------------| +| [**FastAPI**]({{< ref "dapr-agents-getting-started.md#fastapi-integration" >}}) | Native | Expose agents as REST APIs with automatic documentation and validation +| [**Chainlit**]({{< ref "dapr-agents-quickstarts.md#chainlit-integration" >}}) | Supported | Build conversational UIs for agent interactions with file upload and chat capabilities +| [**Pydantic**]({{< ref "dapr-agents-core-concepts.md#pydantic-integration" >}}) | Built-in | Type-safe configuration and structured outputs for agents and tools + + + +# Out-of-the-box Tools + ## Text Splitter -The Text Splitter module is a foundational tool in `Dapr Agents` designed to preprocess documents for use in [Retrieval-Augmented Generation (RAG)](https://en.wikipedia.org/wiki/Retrieval-augmented_generation) workflows and other `in-context learning` applications. Its primary purpose is to break large documents into smaller, meaningful chunks that can be embedded, indexed, and efficiently retrieved based on user queries. +The Text Splitter module is a foundational integration in `Dapr Agents` designed to preprocess documents for use in [Retrieval-Augmented Generation (RAG)](https://en.wikipedia.org/wiki/Retrieval-augmented_generation) workflows and other `in-context learning` applications. Its primary purpose is to break large documents into smaller, meaningful chunks that can be embedded, indexed, and efficiently retrieved based on user queries. By focusing on manageable chunk sizes and preserving contextual integrity through overlaps, the Text Splitter ensures documents are processed in a way that supports downstream tasks like question answering, summarization, and document retrieval. @@ -311,6 +325,6 @@ The Arxiv Fetcher enables various use cases for researchers and developers: While the Arxiv Fetcher provides robust functionality for retrieving and processing research papers, its output can be integrated into advanced workflows: -* **Building a Searchable Knowledge Base**: Combine fetched papers with tools like text splitting and vector embeddings for advanced search capabilities. +* **Building a Searchable Knowledge Base**: Combine fetched papers with integrations like text splitting and vector embeddings for advanced search capabilities. * **Retrieval-Augmented Generation (RAG)**: Use processed papers as inputs for RAG pipelines to power question-answering systems. * **Automated Literature Surveys**: Generate summaries or insights based on the fetched and processed research. \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-introduction.md b/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-introduction.md index 76199a5e7..0a0631c71 100644 --- a/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-introduction.md +++ b/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-introduction.md @@ -6,16 +6,83 @@ weight: 10 description: "Overview of Dapr Agents and its key features" --- -Dapr Agents is a developer framework designed to build production-grade resilient AI agent systems that operate at scale. Built on top of the battle-tested Dapr project, it enables software developers to create AI agents that reason, act, and collaborate using Large Language Models (LLMs), while leveraging built-in observability and stateful workflow execution to guarantee agentic workflows complete successfully, no matter how complex. +![Agent Overview](/images/dapr-agents/concepts-agents-overview.png) -![Dapr Agents Logo](/images/dapr-agents/logo-workflows.png) +Dapr Agents is a developer framework for building production-grade, resilient AI agent systems powered by Large Language Models (LLMs). Built on the battle-tested Dapr project, it enables developers to create autonomous systems that reason through problems, make dynamic decisions, and collaborate seamlessly. It includes built-in observability and stateful workflow execution to ensure agentic workflows complete successfully, regardless of complexity. Whether you're developing single-agent applications or complex multi-agent workflows, Dapr Agents provides the infrastructure for intelligent, adaptive systems that scale across environments. -## Key Features + +## Core Capabilities - **Scale and Efficiency**: Run thousands of agents efficiently on a single core. Dapr distributes single and multi-agent apps transparently across fleets of machines and handles their lifecycle. - **Workflow Resilience**: Automatically retries agentic workflows and ensures task completion. -- **Kubernetes-Native**: Easily deploy and manage agents in Kubernetes environments. - **Data-Driven Agents**: Directly integrate with databases, documents, and unstructured data by connecting to dozens of different data sources. - **Multi-Agent Systems**: Secure and observable by default, enabling collaboration between agents. -- **Vendor-Neutral & Open Source**: Avoid vendor lock-in and gain flexibility across cloud and on-premises deployments. +- **Kubernetes-Native**: Easily deploy and manage agents in Kubernetes environments. - **Platform-Ready**: Built-in RBAC, access scopes and declarative resources enable platform teams to integrate Dapr agents into their systems. +- **Vendor-Neutral & Open Source**: Avoid vendor lock-in and gain flexibility across cloud and on-premises deployments. + +## Key Features + +Dapr Agents provides specialized modules designed for creating intelligent, autonomous systems. Each module is designed to work independently, allowing you to use any combination that fits your application needs. + + +| Building Block | Description | +|----------------------------------------------------------------------------------------------|-------------| +| [**LLM Integration**]({{< ref "dapr-agents-core-concepts.md#llm-integration" >}}) | Uses Dapr [Conversation API](https://docs.dapr.io/developing-applications/building-blocks/conversation/conversation-overview/) to abstract LLM inference APIs for chat completion, or provides native clients for other LLM integrations such as embeddings, audio, etc. +| [**Structured Outputs**]({{< ref "dapr-agents-core-concepts.md#structured-outputs" >}}) | Leverage capabilities like OpenAI's Function Calling to generate predictable, reliable results following JSON Schema and OpenAPI standards for tool integration. +| [**Tool Selection**]({{< ref "dapr-agents-integrations.md#tool-selection" >}}) | Dynamic tool selection based on requirements, best action, and execution through Function Calling capabilities. +| [**MCP Support**]({{< ref "dapr-agents-integrations.md#mcp-support" >}}) | Built-in support for [Model Context Protocol](https://modelcontextprotocol.io/) enabling agents to dynamically discover and invoke external tools through standardized interfaces. +| [**Memory Management**]({{< ref "dapr-agents-core-concepts.md#memory-management" >}}) | Retain context across interactions with options from simple in-memory lists to vector databases, integrating with Dapr state stores for scalable, persistent memory. +| [**Headless Mode**]({{< ref "dapr-agents-core-concepts.md#agent-services" >}}) | Expose agents over REST for long-running tasks, enabling programmatic access and integration without requiring user interfaces or human intervention. +| [**Durable Agents**]({{< ref "dapr-agents-core-concepts.md#durable-agents" >}}) | Workflow-backed agents that provide fault-tolerant execution with persistent state management and automatic retry mechanisms for long-running processes. +| [**Event-Driven Communication**]({{< ref "dapr-agents-core-concepts.md#messaging" >}}) | Enable agent collaboration through Pub/Sub messaging for event-driven communication, task distribution, and real-time coordination in distributed systems. +| [**Agent Orchestration**]({{< ref "dapr-agents-core-concepts.md#workflow-orchestration" >}}) | Deterministic agent orchestration using Dapr Workflows with higher-level tasks that interact with LLMs for complex multi-step processes. + + +## Agentic Patterns +Dapr Agents enables a comprehensive set of patterns that represent different approaches to building intelligent systems. These patterns exist along a spectrum of autonomy, from predictable workflow-based approaches to fully autonomous agents that can dynamically plan and execute their own strategies. + + +Each pattern addresses specific use cases and offers different trade-offs between determenisstic outcomes and autonomy: + +| Pattern | Description | +|----------------------------------------------------------------------------------------|-------------| +| [**Augmented LLM**]({{< ref "dapr-agents-patterns.md#augmented-llm" >}}) | Enhances a language model with external capabilities like memory and tools, providing a foundation for AI-driven applications. +| [**Prompt Chaining**]({{< ref "dapr-agents-patterns.md#prompt-chaining" >}}) | Decomposes complex tasks into a sequence of steps where each LLM call processes the output of the previous one. +| [**Routing**]({{< ref "dapr-agents-patterns.md#routing" >}}) | Classifies inputs and directs them to specialized follow-up tasks, enabling separation of concerns and expert specialization. +| [**Parallelization**]({{< ref "dapr-agents-patterns.md#parallelization" >}}) | Processes multiple dimensions of a problem simultaneously with outputs aggregated programmatically for improved efficiency. +| [**Orchestrator-Workers**]({{< ref "dapr-agents-patterns.md#orchestrator-workers" >}}) | Features a central orchestrator LLM that dynamically breaks down tasks, delegates them to worker LLMs, and synthesizes results. +| [**Evaluator-Optimizer**]({{< ref "dapr-agents-patterns.md#evaluator-optimizer" >}}) | Implements a dual-LLM process where one model generates responses while another provides evaluation and feedback in an iterative loop. +| [**Durable Agent**]({{< ref "dapr-agents-patterns.md#durable-agent" >}}) | Extends the Augmented LLM by adding durability and persistence to agent interactions using Dapr's state stores. + + +## Developer Experience + +Dapr Agents is a Python framework built on top of the [Python Dapr SDK](https://docs.dapr.io/developing-applications/sdks/python/), providing a comprehensive development experience for building agentic systems. + +### Getting Started + +Get started with Dapr Agents by following the [installation guide]({{< ref "dapr-agents-getting-started.md" >}}). + +### Framework Integrations + +Dapr Agents integrates with popular Python frameworks and tools. For detailed integration guides and examples, see the [integrations guide]({{< ref "dapr-agents-integrations.md" >}}). + +## Operational Support + +Dapr Agents inherits Dapr's enterprise-grade operational capabilities, providing comprehensive support for production deployments of agentic systems. + +### Built-in Operational Features + +- **[Observability](https://docs.dapr.io/concepts/observability-concept/)** - Distributed tracing, metrics collection, and logging for agent interactions and workflow execution +- **[Security](https://docs.dapr.io/concepts/security-concept/)** - mTLS encryption, access control, and secrets management for secure agent communication +- **[Resiliency](https://docs.dapr.io/concepts/resiliency-concept/)** - Automatic retries, circuit breakers, and timeout policies for fault-tolerant agent operations +- **[Infrastructure Isolation](https://docs.dapr.io/concepts/components-concept/)** - Dapr components abstract LLM providers, memory stores, storage and messaging backends, enabling seamless transitions between development and production environments + +These capabilities enable teams to monitor agent performance, secure multi-agent communications, and ensure reliable execution of complex agentic workflows in production environments. + +## Contributing + +Whether you're interested in enhancing the framework, adding new integrations, or improving documentation, we welcome contributions from the community. + +For development setup and guidelines, see our [Development Guide](https://docs.dapr.io/contributing/dapr-agents/). \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-patterns.md b/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-patterns.md new file mode 100644 index 000000000..a000df321 --- /dev/null +++ b/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-patterns.md @@ -0,0 +1,400 @@ +--- +type: docs +title: "Agentic Patterns" +linkTitle: "Agentic Patterns" +weight: 50 +description: "Common design patterns and use cases for building agentic systems" +--- + +Dapr Agents simplify the implementation of agentic systems, from simple augmented LLMs to fully autonomous agents in enterprise environments. The following sections describe several application patterns that can benefit from Dapr Agents. + +## Overview + +Agentic systems use design patterns such as reflection, tool use, planning, and multi-agent collaboration to achieve better results than simple single-prompt interactions. Rather than thinking of "agent" as a binary classification, it's more useful to think of systems as being agentic to different degrees. + +This ranges from simple workflows that prompt a model once, to sophisticated systems that can carry out multiple iterative steps with greater autonomy. +There are two fundamental architectural approaches: + +* **Workflows**: Systems where LLMs and tools are orchestrated through predefined code paths (more prescriptive) +* **Agents**: Systems where LLMs dynamically direct their own processes and tool usage (more autonomous) + +On one end, we have predictable workflows with well-defined decision paths and deterministic outcomes. On the other end, we have AI agents that can dynamically direct their own strategies. While fully autonomous agents might seem appealing, workflows often provide better predictability and consistency for well-defined tasks. This aligns with enterprise requirements where reliability and maintainability are crucial. + + + +The patterns in this documentation start with the Augmented LLM, then progress through workflow-based approaches that offer predictability and control, before moving toward more autonomous patterns. Each addresses specific use cases and offers different trade-offs between deterministic outcomes and autonomy. + +## Augmented LLM + +The Augmented LLM pattern is the foundational building block for any kind of agentic system. It enhances a language model with external capabilities like memory and tools, providing a basic but powerful foundation for AI-driven applications. + +Diagram showing how the augmented LLM pattern works + +This pattern is ideal for scenarios where you need an LLM with enhanced capabilities but don't require complex orchestration or autonomous decision-making. The augmented LLM can access external tools, maintain conversation history, and provide consistent responses across interactions. + +**Use Cases:** +- Personal assistants that remember user preferences +- Customer support agents that access product information +- Research tools that retrieve and analyze information + +**Implementation with Dapr Agents:** + +```python +from dapr_agents import Agent, tool + +@tool +def search_flights(destination: str) -> List[FlightOption]: + """Search for flights to the specified destination.""" + # Mock flight data (would be an external API call in a real app) + return [ + FlightOption(airline="SkyHighAir", price=450.00), + FlightOption(airline="GlobalWings", price=375.50) + ] + +# Create agent with memory and tools +travel_planner = Agent( + name="TravelBuddy", + role="Travel Planner Assistant", + instructions=["Remember destinations and help find flights"], + tools=[search_flights], +) +``` + +Dapr Agents automatically handles: +- **Agent configuration** - Simple configuration with role and instructions guides the LLM behavior +- **Memory persistence** - The agent manages conversation memory +- **Tool integration** - The `@tool` decorator handles input validation, type conversion, and output formatting + +The foundational building block of any agentic system is the Augmented LLM - a language model enhanced with external capabilities like memory, tools, and retrieval. In Dapr Agents, this is represented by the `Agent` class. However, while this provides essential capabilities, it alone is often not sufficient for complex enterprise scenarios. This is why it's typically combined with workflow orchestration that provides structure, reliability, and coordination for multi-step processes. + +## Prompt Chaining + +The Prompt Chaining pattern addresses complex requirements by decomposing tasks into a sequence of steps, where each LLM call processes the output of the previous one. This pattern allows for better control of the overall process, validation between steps, and specialization of each step. + +Diagram showing how the prompt chaining pattern works + +**Use Cases:** +- Content generation (creating outlines first, then expanding, then reviewing) +- Multi-stage analysis (performing complex analysis into sequential steps) +- Quality assurance workflows (adding validation between processing steps) + +**Implementation with Dapr Agents:** + +```python +from dapr_agents import DaprWorkflowContext, workflow + +@workflow(name='travel_planning_workflow') +def travel_planning_workflow(ctx: DaprWorkflowContext, user_input: str): + # Step 1: Extract destination using a simple prompt (no agent) + destination_text = yield ctx.call_activity(extract_destination, input=user_input) + + # Gate: Check if destination is valid + if "paris" not in destination_text.lower(): + return "Unable to create itinerary: Destination not recognized or supported." + + # Step 2: Generate outline with planning agent (has tools) + travel_outline = yield ctx.call_activity(create_travel_outline, input=destination_text) + + # Step 3: Expand into detailed plan with itinerary agent (no tools) + detailed_itinerary = yield ctx.call_activity(expand_itinerary, input=travel_outline) + + return detailed_itinerary +``` + +The implementation showcases three different approaches: +- **Basic prompt-based task** (no agent) +- **Agent-based task** without tools +- **Agent-based task** with tools + +Dapr Agents' workflow orchestration provides: +- **Workflow as Code** - Tasks are defined in developer-friendly ways +- **Workflow Persistence** - Long-running chained tasks survive process restarts +- **Hybrid Execution** - Easily mix prompts, agent calls, and tool-equipped agents + +## Routing Pattern + +The Routing pattern addresses diverse request types by classifying inputs and directing them to specialized follow-up tasks. This allows for separation of concerns and creates specialized experts for different types of queries. + +Diagram showing how the routing pattern works + +**Use Cases:** +- Resource optimization (sending simple queries to smaller models) +- Multi-lingual support (routing queries to language-specific handlers) +- Customer support (directing different query types to specialized handlers) +- Content creation (routing writing tasks to topic specialists) +- Hybrid LLM systems (using different models for different tasks) + +**Implementation with Dapr Agents:** + +```python +@workflow(name="travel_assistant_workflow") +def travel_assistant_workflow(ctx: DaprWorkflowContext, input_params: dict): + user_query = input_params.get("query") + + # Classify the query type using an LLM + query_type = yield ctx.call_activity(classify_query, input={"query": user_query}) + + # Route to the appropriate specialized handler + if query_type == QueryType.ATTRACTIONS: + response = yield ctx.call_activity( + handle_attractions_query, + input={"query": user_query} + ) + elif query_type == QueryType.ACCOMMODATIONS: + response = yield ctx.call_activity( + handle_accommodations_query, + input={"query": user_query} + ) + elif query_type == QueryType.TRANSPORTATION: + response = yield ctx.call_activity( + handle_transportation_query, + input={"query": user_query} + ) + else: + response = "I'm not sure how to help with that specific travel question." + + return response +``` + +The advantages of Dapr's approach include: +- **Familiar Control Flow** - Uses standard programming if-else constructs for routing +- **Extensibility** - The control flow can be extended for future requirements easily +- **LLM-Powered Classification** - Uses an LLM to categorize queries dynamically + +## Parallelization + +The Parallelization pattern enables processing multiple dimensions of a problem simultaneously, with outputs aggregated programmatically. This pattern improves efficiency for complex tasks with independent subtasks that can be processed concurrently. + +Diagram showing how the parallelization pattern works + +**Use Cases:** +- Complex research (processing different aspects of a topic in parallel) +- Multi-faceted planning (creating various elements of a plan concurrently) +- Product analysis (analyzing different aspects of a product in parallel) +- Content creation (generating multiple sections of a document simultaneously) + +**Implementation with Dapr Agents:** + +```python +@workflow(name="travel_planning_workflow") +def travel_planning_workflow(ctx: DaprWorkflowContext, input_params: dict): + destination = input_params.get("destination") + preferences = input_params.get("preferences") + days = input_params.get("days") + + # Process three aspects of the travel plan in parallel + parallel_tasks = [ + ctx.call_activity(research_attractions, input={ + "destination": destination, + "preferences": preferences, + "days": days + }), + ctx.call_activity(recommend_accommodations, input={ + "destination": destination, + "preferences": preferences, + "days": days + }), + ctx.call_activity(suggest_transportation, input={ + "destination": destination, + "preferences": preferences, + "days": days + }) + ] + + # Wait for all parallel tasks to complete + results = yield wfapp.when_all(parallel_tasks) + + # Aggregate results into final plan + final_plan = yield ctx.call_activity(create_final_plan, input={"results": results}) + + return final_plan +``` + +The benefits of using Dapr for parallelization include: +- **Simplified Concurrency** - Handles the complex orchestration of parallel tasks +- **Automatic Synchronization** - Waits for all parallel tasks to complete +- **Workflow Durability** - The entire parallel process is durable and recoverable + +## Orchestrator-Workers + +For highly complex tasks where the number and nature of subtasks can't be known in advance, the Orchestrator-Workers pattern offers a powerful solution. This pattern features a central orchestrator LLM that dynamically breaks down tasks, delegates them to worker LLMs, and synthesizes their results. + +Diagram showing how the orchestrator-workers pattern works + +Unlike previous patterns where workflows are predefined, the orchestrator determines the workflow dynamically based on the specific input. + +**Use Cases:** +- Software development tasks spanning multiple files +- Research gathering information from multiple sources +- Business analysis evaluating different facets of a complex problem +- Content creation combining specialized content from various domains + +**Implementation with Dapr Agents:** + +```python +@workflow(name="orchestrator_travel_planner") +def orchestrator_travel_planner(ctx: DaprWorkflowContext, input_params: dict): + travel_request = input_params.get("request") + + # Step 1: Orchestrator analyzes request and determines required tasks + plan_result = yield ctx.call_activity( + create_travel_plan, + input={"request": travel_request} + ) + + tasks = plan_result.get("tasks", []) + + # Step 2: Execute each task with a worker LLM + worker_results = [] + for task in tasks: + task_result = yield ctx.call_activity( + execute_travel_task, + input={"task": task} + ) + worker_results.append({ + "task_id": task["task_id"], + "result": task_result + }) + + # Step 3: Synthesize the results into a cohesive travel plan + final_plan = yield ctx.call_activity( + synthesize_travel_plan, + input={ + "request": travel_request, + "results": worker_results + } + ) + + return final_plan +``` + +The advantages of Dapr for the Orchestrator-Workers pattern include: +- **Dynamic Planning** - The orchestrator can dynamically create subtasks based on input +- **Worker Isolation** - Each worker focuses on solving one specific aspect of the problem +- **Simplified Synthesis** - The final synthesis step combines results into a coherent output + +## Evaluator-Optimizer + +Quality is often achieved through iteration and refinement. The Evaluator-Optimizer pattern implements a dual-LLM process where one model generates responses while another provides evaluation and feedback in an iterative loop. + +Diagram showing how the evaluator-optimizer pattern works + +**Use Cases:** +- Content creation requiring adherence to specific style guidelines +- Translation needing nuanced understanding and expression +- Code generation meeting specific requirements and handling edge cases +- Complex search requiring multiple rounds of information gathering and refinement + +**Implementation with Dapr Agents:** + +```python +@workflow(name="evaluator_optimizer_travel_planner") +def evaluator_optimizer_travel_planner(ctx: DaprWorkflowContext, input_params: dict): + travel_request = input_params.get("request") + max_iterations = input_params.get("max_iterations", 3) + + # Generate initial travel plan + current_plan = yield ctx.call_activity( + generate_travel_plan, + input={"request": travel_request, "feedback": None} + ) + + # Evaluation loop + iteration = 1 + meets_criteria = False + + while iteration <= max_iterations and not meets_criteria: + # Evaluate the current plan + evaluation = yield ctx.call_activity( + evaluate_travel_plan, + input={"request": travel_request, "plan": current_plan} + ) + + score = evaluation.get("score", 0) + feedback = evaluation.get("feedback", []) + meets_criteria = evaluation.get("meets_criteria", False) + + # Stop if we meet criteria or reached max iterations + if meets_criteria or iteration >= max_iterations: + break + + # Optimize the plan based on feedback + current_plan = yield ctx.call_activity( + generate_travel_plan, + input={"request": travel_request, "feedback": feedback} + ) + + iteration += 1 + + return { + "final_plan": current_plan, + "iterations": iteration, + "final_score": score + } +``` + +The benefits of using Dapr for this pattern include: +- **Iterative Improvement Loop** - Manages the feedback cycle between generation and evaluation +- **Quality Criteria** - Enables clear definition of what constitutes acceptable output +- **Maximum Iteration Control** - Prevents infinite loops by enforcing iteration limits + +## Durable Agent + +Moving to the far end of the agentic spectrum, the Durable Agent pattern represents a shift from workflow-based approaches. Instead of predefined steps, we have an autonomous agent that can plan its own steps and execute them based on its understanding of the goal. + +Enterprise applications often need durable execution and reliability that go beyond in-memory capabilities. Dapr's `DurableAgent` class helps you implement autonomous agents with the reliability of workflows, as these agents are backed by Dapr workflows behind the scenes. The `DurableAgent` extends the basic `Agent` class by adding durability to agent execution. + +Diagram showing how the durable agent pattern works + +This pattern doesn't just persist message history – it dynamically creates workflows with durable activities for each interaction, where LLM calls and tool executions are stored reliably in Dapr's state stores. This makes it ideal for production environments where reliability is critical. + +The Durable Agent also enables the "headless agents" approach where autonomous systems that operate without direct user interaction. Dapr's Durable Agent exposes REST and Pub/Sub APIs, making it ideal for long-running operations that are triggered by other applications or external events. + + +**Use Cases:** +- Long-running tasks that may take minutes or days to complete +- Distributed systems running across multiple services +- Customer support handling complex multi-session tickets +- Business processes with LLM intelligence at each step +- Personal assistants handling scheduling and information lookup +- Autonomous background processes triggered by external systems + +**Implementation with Dapr Agents:** + +```python +from dapr_agents import DurableAgent + +travel_planner = DurableAgent( + name="TravelBuddy", + role="Travel Planner", + goal="Help users find flights and remember preferences", + instructions=[ + "Find flights to destinations", + "Remember user preferences", + "Provide clear flight info" + ], + tools=[search_flights], + message_bus_name="messagepubsub", + state_store_name="workflowstatestore", + state_key="workflow_state", + agents_registry_store_name="workflowstatestore", + agents_registry_key="agents_registry", +) +``` +The implementation follows Dapr's sidecar architecture model, where all infrastructure concerns are handled by the Dapr runtime: +- **Persistent Memory** - Agent state is stored in Dapr's state store, surviving process crashes +- **Workflow Orchestration** - All agent interactions managed through Dapr's workflow system +- **Service Exposure** - REST endpoints for workflow management come out of the box +- **Pub/Sub Input/Output** - Event-driven messaging through Dapr's pub/sub system for seamless integration + +The Durable Agent enables the concept of "headless agents" - autonomous systems that operate without direct user interaction. Dapr's Durable Agent exposes both REST and Pub/Sub APIs, making it ideal for long-running operations that are triggered by other applications or external events. This allows agents to run in the background, processing requests asynchronously and integrating seamlessly into larger distributed systems. + + +## Choosing the Right Pattern + +The journey from simple agentic workflows to fully autonomous agents represents a spectrum of approaches for integrating LLMs into your applications. Different use cases call for different levels of agency and control: + +- **Start with simpler patterns** like Augmented LLM and Prompt Chaining for well-defined tasks where predictability is crucial +- **Progress to more dynamic patterns** like Parallelization and Orchestrator-Workers as your needs grow more complex +- **Consider fully autonomous agents** only for open-ended tasks where the benefits of flexibility outweigh the need for strict control + \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-quickstarts.md b/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-quickstarts.md index a11db7518..2fec29e71 100644 --- a/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-quickstarts.md +++ b/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-quickstarts.md @@ -2,226 +2,27 @@ type: docs title: "Quickstarts" linkTitle: "Quickstarts" -weight: 55 -description: "Get started with Dapr Agents through practical examples and tutorials" +weight: 70 +description: "Get started with Dapr Agents through practical step-by-step examples" --- -# Dapr Agents Quickstarts +[Dapr Agents Quickstarts](https://github.com/dapr/dapr-agents/tree/main/quickstarts) demonstrate how to use Dapr Agents to build applications with LLM-powered autonomous agents and event-driven workflows. Each quickstart builds upon the previous one, introducing new concepts incrementally. -[Quickstarts](https://github.com/dapr/dapr-agents/tree/main/quickstarts) demonstrate how to use Dapr Agents to build applications with LLM-powered autonomous agents and event-driven workflows. Each quickstart builds upon the previous one, introducing new concepts incrementally. +#### Before you begin -{{% alert title="Note" color="info" %}} -Not all quickstarts require Docker, but it is recommended to have your [local Dapr environment set up]({{< ref "/developing-applications/dapr-agents/dapr-agents-getting-started.md" >}}) with Docker for the best development experience and to follow the steps in this guide seamlessly. -{{% /alert %}} +- [Set up your local Dapr environment]({{< ref "install-dapr-cli.md" >}}). -## Available Quickstarts -| Scenario | What You'll Learn | -|----------|-------------------| -| [Hello World](https://github.com/dapr/dapr-agents/tree/main/quickstarts/01-hello-world)
A rapid introduction that demonstrates core Dapr Agents concepts through simple, practical examples. | - **Basic LLM Usage**: Simple text generation with OpenAI models
- **Creating Agents**: Building agents with custom tools in under 20 lines of code
- **ReAct Pattern**: Implementing reasoning and action cycles in agents
- **Simple Workflows**: Setting up multi-step LLM processes | -| [LLM Call with Dapr Chat Client](https://github.com/dapr/dapr-agents/tree/main/quickstarts/02_llm_call_dapr)
Explore interaction with Language Models through Dapr Agents' `DaprChatClient`, featuring basic text generation with plain text prompts and templates. | - **Text Completion**: Generating responses to prompts
- **Swapping LLM providers**: Switching LLM backends without application code change
- **Resilience**: Setting timeout, retry and circuit-breaking
- **PII Obfuscation**: Automatically detect and mask sensitive user information | -| [LLM Call with OpenAI Client](https://github.com/dapr/dapr-agents/tree/main/quickstarts/02_llm_call_open_ai)
Discover how to leverage native LLM client libraries with Dapr Agents using the OpenAI Client for chat completion, audio processing, and embeddings. | - **Text Completion**: Generating responses to prompts
- **Structured Outputs**: Converting LLM responses to Pydantic objects

*Note: Other quickstarts for specific clients are available for [Elevenlabs](https://github.com/dapr/dapr-agents/tree/main/quickstarts/02_llm_call_elevenlabs), [Hugging Face](https://github.com/dapr/dapr-agents/tree/main/quickstarts/02_llm_call_hugging_face), and [Nvidia](https://github.com/dapr/dapr-agents/tree/main/quickstarts/02_llm_call_nvidia).* | -| [Agent Tool Call](https://github.com/dapr/dapr-agents/tree/main/quickstarts/03-agent-tool-call)
Build your first AI agent with custom tools by creating a practical weather assistant that fetches information and performs actions. | - **Tool Definition**: Creating reusable tools with the `@tool` decorator
- **Agent Configuration**: Setting up agents with roles, goals, and tools
- **Function Calling**: Enabling LLMs to execute Python functions | -| [Agentic Workflow](https://github.com/dapr/dapr-agents/tree/main/quickstarts/04-agentic-workflow)
Dive into stateful workflows with Dapr Agents by orchestrating sequential and parallel tasks through powerful workflow capabilities. | - **LLM-powered Tasks**: Using language models in workflows
- **Task Chaining**: Creating resilient multi-step processes executing in sequence
- **Fan-out/Fan-in**: Executing activities in parallel; then synchronizing these activities until all preceding activities have completed | -| [Multi-Agent Workflows](https://github.com/dapr/dapr-agents/tree/main/quickstarts/05-multi-agent-workflow-dapr-workflows)
Explore advanced event-driven workflows featuring a Lord of the Rings themed multi-agent system where autonomous agents collaborate to solve problems. | - **Multi-agent Systems**: Creating a network of specialized agents
- **Event-driven Architecture**: Implementing pub/sub messaging between agents
- **Actor Model**: Using Dapr Actors for stateful agent management
- **Workflow Orchestration**: Coordinating agents through different selection strategies

*Note: To see Actor-based workflow see [Multi-Agent Actors](https://github.com/dapr/dapr-agents/tree/main/quickstarts/05-multi-agent-workflow-actors).* | -| [Multi-Agent Workflow on Kubernetes](https://github.com/dapr/dapr-agents/tree/main/quickstarts/07-k8s-multi-agent-workflow)
Run multi-agent workflows in Kubernetes, demonstrating deployment and orchestration of event-driven agent systems in a containerized environment. | - **Kubernetes Deployment**: Running agents on Kubernetes
- **Container Orchestration**: Managing agent lifecycles with K8s
- **Service Communication**: Inter-agent communication in K8s | -| [Document Agent with Chainlit](https://github.com/dapr/dapr-agents/tree/main/quickstarts/06-document-agent-chainlit)
Create a conversational agent with an operational UI that can upload, and learn unstructured documents while retaining long-term memory. | - **Conversational Document Agent**: Upload and converse over unstructured documents
- **Cloud Agnostic Storage**: Upload files to multiple storage providers
- **Conversation Memory Storage**: Persists conversation history using external storage. | -| [Data Agent with MCP and Chainlit](https://github.com/dapr/dapr-agents/tree/main/quickstarts/08-data-agent-mcp-chainlit)
Build a conversational agent over a Postgres database using Model Composition Protocol (MCP) with a ChatGPT-like interface. | - **Database Querying**: Natural language queries to relational databases
- **MCP Integration**: Connecting to databases without DB-specific code
- **Data Analysis**: Complex data analysis through conversation | +## Quickstarts -## Agentic Workflows - -{{% alert title="Note" color="info" %}} -This quickstart requires `Dapr CLI` and `Docker`. You must have your [local Dapr environment set up]({{< ref "/developing-applications/dapr-agents/dapr-agents-getting-started.md" >}}). -{{% /alert %}} - -Traditional workflows follow fixed, step-by-step processes, while autonomous agents make real-time decisions based on reasoning and available data. Agentic workflows combine the best of both approaches, integrating structured execution with reasoning loops to enable more adaptive decision-making. - -This allows systems to analyze information, adjust to new conditions, and refine actions dynamically rather than strictly following a predefined sequence. By incorporating planning, feedback loops, and model-driven adjustments, agentic workflows provide both scalability and predictability while still allowing for autonomous adaptation. - -In `Dapr Agents`, agentic workflows leverage LLM-based tasks, reasoning loop patterns, and an event-driven system powered by pub/sub messaging and a shared message bus. Agents operate autonomously, responding to events in real time, making decisions, and collaborating dynamically. This makes the system highly adaptable—agents can communicate, share tasks, and adjust based on new information, ensuring fluid coordination across distributed environments. - -{{% alert title="Tip" color="primary" %}} -We will demonstrate this concept using the [Multi-Agent Workflow Guide](https://github.com/dapr/dapr-agents/tree/main/cookbook/workflows/multi_agents/basic_lotr_agents_as_workflows) from our Cookbook, which outlines a step-by-step guide to implementing a basic agentic workflow. -{{% /alert %}} - -### Agents as Services: Dapr Workflows - -In `Dapr Agents`, agents can be implemented using [Dapr Workflows](https://docs.dapr.io/developing-applications/building-blocks/workflow/workflow-overview/), both of which are exposed as microservices via [FastAPI servers](https://docs.dapr.io/developing-applications/sdks/python/python-sdk-extensions/python-fastapi/). - -#### Agents as Dapr Workflows (Orchestration, Complex Execution) - -[Dapr Workflows](https://docs.dapr.io/developing-applications/building-blocks/workflow/workflow-overview/) define the structured execution of agent behaviors, reasoning loops, and tool selection. Workflows allow agents to: - -✅ Define complex execution sequences instead of just reacting to events. -✅ Integrate with message buses to listen and act on real-time inputs. -✅ Orchestrate multi-step reasoning, retrieval-augmented generation (RAG), and tool use. -✅ Best suited for goal-driven, structured, and iterative decision-making workflows. - -🚀 Dapr agents uses Dapr Workflows for orchestration and complex multi-agent collaboration. - -**Example: An Agent as a Dapr Workflow** - -```python -from dapr_agents import DurableAgent -from dotenv import load_dotenv -import asyncio -import logging - -async def main(): - try: - # Define Agent - wizard_service = DurableAgent( - name="Gandalf", - role="Wizard", - goal="Guide the Fellowship with wisdom and strategy, using magic and insight to ensure the downfall of Sauron.", - instructions=[ - "Speak like Gandalf, with wisdom, patience, and a touch of mystery.", - "Provide strategic counsel, always considering the long-term consequences of actions.", - "Use magic sparingly, applying it when necessary to guide or protect.", - "Encourage allies to find strength within themselves rather than relying solely on your power.", - "Respond concisely, accurately, and relevantly, ensuring clarity and strict alignment with the task." - ], - message_bus_name="messagepubsub", - state_store_name="agenticworkflowstate", - state_key="workflow_state", - agents_registry_store_name="agentsregistrystore", - agents_registry_key="agents_registry", - ) - - await wizard_service.start() - except Exception as e: - print(f"Error starting service: {e}") - -if __name__ == "__main__": - load_dotenv() - logging.basicConfig(level=logging.INFO) - asyncio.run(main()) -``` - -Here, `Gandalf` is an `DurableAgent` implemented as a workflow, meaning it executes structured reasoning, plans actions, and integrates tools within a managed workflow execution loop. - -#### How We Use Dapr Workflows for Orchestration - -In dapr agents, the orchestrator itself is a Dapr Workflow, which: - -✅ Coordinates execution of agentic workflows (LLM-driven or rule-based). -✅ Delegates tasks to agents implemented as either other workflows. -✅ Manages reasoning loops, plan adaptation, and error handling dynamically. - -🚀 The LLM default orchestrator is a Dapr Workflow that interacts with agent workflows. - -**Example: The Orchestrator as a Dapr Workflow** - -```python -from dapr_agents import LLMOrchestrator -from dotenv import load_dotenv -import asyncio -import logging - -async def main(): - try: - agentic_orchestrator = LLMOrchestrator( - name="Orchestrator", - message_bus_name="messagepubsub", - state_store_name="agenticworkflowstate", - state_key="workflow_state", - agents_registry_store_name="agentsregistrystore", - agents_registry_key="agents_registry", - max_iterations=25 - ).as_service(port=8009) - - await agentic_orchestrator.start() - except Exception as e: - print(f"Error starting service: {e}") - -if __name__ == "__main__": - load_dotenv() - logging.basicConfig(level=logging.INFO) - asyncio.run(main()) -``` - -This orchestrator acts as a central controller, ensuring that agentic workflows communicate effectively, execute tasks in order, and handle iterative reasoning loops. - -### Structuring A Multi-Agent Project - -The way to structure such a project is straightforward. We organize our services into a directory that contains individual folders for each agent, along with a `components` directory for Dapr resources configurations. Each agent service includes its own app.py file, where the FastAPI server and the agent logic are defined. - -``` -dapr.yaml # Dapr main config file -components/ # Dapr resource files -├── statestore.yaml # State store configuration -├── pubsub.yaml # Pub/Sub configuration -└── ... # Other Dapr components -services/ # Directory for agent services -├── agent1/ # First agent's service -│ ├── app.py # FastAPI app for agent1 -│ └── ... # Additional agent1 files -│── agent2/ # Second agent's service -│ ├── app.py # FastAPI app for agent2 -│ └── ... # Additional agent2 files -└── ... # More agents -``` - -### Set Up an Environment Variables File - -This example uses our default `LLM Orchestrator`. Therefore, you have to create an `.env` file to securely store your Inference Service (i.e. OpenAI) API keys and other sensitive information. For example: - -``` -OPENAI_API_KEY="your-api-key" -OPENAI_BASE_URL="https://api.openai.com/v1" -``` - -### Define Your First Agent Service - -Let's start by defining a `Hobbit` service with a specific `name`, `role`, `goal` and `instructions`. - -``` -services/ # Directory for agent services -├── hobbit/ # Hobbit Service -│ ├── app.py # Dapr Enabled FastAPI app for Hobbit -``` - -Create the `app.py` script and provide the following information. - -```python -from dapr_agents import DurableAgent -from dotenv import load_dotenv -import asyncio -import logging - -async def main(): - try: - # Define Agent and expose it as a service - hobbit_agent = DurableAgent( - role="Hobbit", - name="Frodo", - goal="Carry the One Ring to Mount Doom, resisting its corruptive power while navigating danger and uncertainty.", - instructions=[ - "Speak like Frodo, with humility, determination, and a growing sense of resolve.", - "Endure hardships and temptations, staying true to the mission even when faced with doubt.", - "Seek guidance and trust allies, but bear the ultimate burden alone when necessary.", - "Move carefully through enemy-infested lands, avoiding unnecessary risks.", - "Respond concisely, accurately, and relevantly, ensuring clarity and strict alignment with the task." - ], - message_bus_name="messagepubsub", - agents_registry_store_name="agentsregistrystore", - agents_registry_key="agents_registry", - ).as_service(8001) - - await hobbit_service.start() - except Exception as e: - print(f"Error starting service: {e}") - -if __name__ == "__main__": - load_dotenv() - logging.basicConfig(level=logging.INFO) - asyncio.run(main()) -``` - -Now, you can define multiple services following this format, but it's essential to pay attention to key areas to ensure everything runs smoothly. Specifically, focus on correctly configuring the components (e.g., `statestore` and `pubsub` names) and incrementing the ports for each service. - -**Key Considerations:** - -* Ensure the `message_bus_name` matches the `pub/sub` component name in your `pubsub.yaml` file. -* Verify the `agents_registry_store_name` matches the state store component defined in your `agentstate.yaml` file. -* Increment the `service_port` for each new agent service (e.g., 8001, 8002, 8003). \ No newline at end of file +| Scenario | What You'll Learn | +|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------| +| [Hello World](https://github.com/dapr/dapr-agents/tree/main/quickstarts/01-hello-world)
A rapid introduction that demonstrates core Dapr Agents concepts through simple, practical examples. | - **Basic LLM Usage**: Simple text generation with OpenAI models
- **Creating Agents**: Building agents with custom tools in under 20 lines of code

- **Simple Workflows**: Setting up multi-step LLM processes | +| [LLM Call with Dapr Chat Client](https://github.com/dapr/dapr-agents/tree/main/quickstarts/02_llm_call_dapr)
Explore interaction with Language Models through Dapr Agents' `DaprChatClient`, featuring basic text generation with plain text prompts and templates. | - **Text Completion**: Generating responses to prompts
- **Swapping LLM providers**: Switching LLM backends without application code change
- **Resilience**: Setting timeout, retry and circuit-breaking
- **PII Obfuscation**: Automatically detect and mask sensitive user information | +| [LLM Call with OpenAI Client](https://github.com/dapr/dapr-agents/tree/main/quickstarts/02_llm_call_open_ai)
Leverage native LLM client libraries with Dapr Agents using the OpenAI Client for chat completion, audio processing, and embeddings. | - **Text Completion**: Generating responses to prompts
- **Structured Outputs**: Converting LLM responses to Pydantic objects

*Note: Other quickstarts for specific clients are available for [Elevenlabs](https://github.com/dapr/dapr-agents/tree/main/quickstarts/02_llm_call_elevenlabs), [Hugging Face](https://github.com/dapr/dapr-agents/tree/main/quickstarts/02_llm_call_hugging_face), and [Nvidia](https://github.com/dapr/dapr-agents/tree/main/quickstarts/02_llm_call_nvidia).* | +| [Agent Tool Call](https://github.com/dapr/dapr-agents/tree/main/quickstarts/03-agent-tool-call)
Build your first AI agent with custom tools by creating a practical weather assistant that fetches information and performs actions. | - **Tool Definition**: Creating reusable tools with the `@tool` decorator
- **Agent Configuration**: Setting up agents with roles, goals, and tools
- **Function Calling**: Enabling LLMs to execute Python functions | +| [Agentic Workflow](https://github.com/dapr/dapr-agents/tree/main/quickstarts/04-agentic-workflow)
Dive into stateful workflows with Dapr Agents by orchestrating sequential and parallel tasks through powerful workflow capabilities. | - **LLM-powered Tasks**: Using language models in workflows
- **Task Chaining**: Creating resilient multi-step processes executing in sequence
- **Fan-out/Fan-in**: Executing activities in parallel; then synchronizing these activities until all preceding activities have completed | +| [Multi-Agent Workflows](https://github.com/dapr/dapr-agents/tree/main/quickstarts/05-multi-agent-workflow-dapr-workflows)
Explore advanced event-driven workflows featuring a Lord of the Rings themed multi-agent system where autonomous agents collaborate to solve problems. | - **Multi-agent Systems**: Creating a network of specialized agents
- **Event-driven Architecture**: Implementing pub/sub messaging between agents
- **Workflow Orchestration**: Coordinating agents through different selection strategies| +| [Multi-Agent Workflow on Kubernetes](https://github.com/dapr/dapr-agents/tree/main/quickstarts/07-k8s-multi-agent-workflow)
Run multi-agent workflows in Kubernetes, demonstrating deployment and orchestration of event-driven agent systems in a containerized environment. | - **Kubernetes Deployment**: Running agents on Kubernetes
- **Container Orchestration**: Managing agent lifecycles with K8s
- **Service Communication**: Inter-agent communication in K8s | +| [Document Agent with Chainlit](https://github.com/dapr/dapr-agents/tree/main/quickstarts/06-document-agent-chainlit)
Create a conversational agent with an operational UI that can upload, and learn unstructured documents while retaining long-term memory. | - **Conversational Document Agent**: Upload and converse over unstructured documents
- **Cloud Agnostic Storage**: Upload files to multiple storage providers
- **Conversation Memory Storage**: Persists conversation history using external storage. | +| [Data Agent with MCP and Chainlit](https://github.com/dapr/dapr-agents/tree/main/quickstarts/08-data-agent-mcp-chainlit)
Build a conversational agent over a Postgres database using Model Composition Protocol (MCP) with a ChatGPT-like interface. | - **Database Querying**: Natural language queries to relational databases
- **MCP Integration**: Connecting to databases without DB-specific code
- **Data Analysis**: Complex data analysis through conversation | diff --git a/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-why.md b/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-why.md index 6a6d3b3a4..d379de041 100644 --- a/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-why.md +++ b/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-why.md @@ -2,7 +2,7 @@ type: docs title: "Why Dapr Agents" linkTitle: "Why Dapr Agents" -weight: 25 +weight: 30 description: "Understanding the benefits and use cases for Dapr Agents" --- @@ -10,21 +10,15 @@ Dapr Agents is an open-source framework for building and orchestrating LLM-based ### The Problem -Many agentic frameworks today attempt to redefine how microservices are built and orchestrated by developing their own platforms for workflows, Pub/Sub messaging, state management, and service communication. While these efforts showcase innovation, they often lead to a steep learning curve, fragmented systems, and unnecessary complexity when scaling or adapting to new environments. +Many agentic frameworks today attempt to redefine how microservices are built and orchestrated by developing their own platforms for core distributed system capabilities. While these efforts showcase innovation, they often lead to a steep learning curve, fragmented systems, and unnecessary complexity when scaling or adapting to new environments. Many of these frameworks require developers to adopt entirely new paradigms or recreate foundational infrastructure, rather than building on existing solutions that are proven to handle these challenges at scale. This added complexity often diverts focus from the primary goal: designing and implementing intelligent, effective agents. ### Dapr Agents' Approach -Dapr Agents takes a distinct approach by building on [Dapr](https://dapr.io/), a portable and event-driven runtime optimized for distributed systems. Dapr offers built-in APIs and patterns such as state management, Pub/Sub messaging, service invocation, and virtual actors—that eliminate the need to recreate foundational components from scratch. By integrating seamlessly with Dapr, Dapr Agents empowers developers to focus on the intelligence and behavior of LLM-powered agents while leveraging a proven framework for scalability and reliability. - -Rather than reinventing microservices, Dapr Agents enables developers to design, test, and deploy agents that seamlessly integrate as collaborative services within larger systems. Whether experimenting with a single agent or orchestrating workflows involving multiple agents, Dapr Agents simplifies the exploration and implementation of scalable agentic workflows. - -[//]: # (### Conclusion) - -[//]: # () -[//]: # (Dapr Agents provides a unified framework for designing, deploying, and orchestrating LLM-powered agents. By leveraging Dapr’s runtime and modular components, Dapr Agents allows developers to focus on building intelligent systems without worrying about the complexities of distributed infrastructure. Whether you're creating standalone agents or orchestrating multi-agent workflows, Dapr Agents empowers you to explore the future of intelligent, scalable, and collaborative systems.) +Dapr Agents takes a distinct approach by building on Dapr, leveraging its proven APIs and patterns including [workflows](https://docs.dapr.io/developing-applications/building-blocks/workflow/workflow-overview/), [Pub/Sub messaging](https://docs.dapr.io/developing-applications/building-blocks/pubsub/pubsub-overview/), [state management](https://docs.dapr.io/developing-applications/building-blocks/state-management/state-management-overview/), and [service communication](https://docs.dapr.io/developing-applications/building-blocks/service-invocation/service-invocation-overview/). This integration eliminates the need to recreate foundational components from scratch. +By integrating seamlessly with Dapr's runtime and modular components, Dapr Agents empowers developers to build and deploy agents that integrate as collaborative services within larger systems. Whether experimenting with a single agent or orchestrating workflows involving multiple agents, Dapr Agents' approach allows teams to concentrate on the intelligence and behavior of LLM-powered agents while leveraging a proven framework for scalability and reliability, rather than reinventing distributed systems capabilities. ## Dapr Agents Benefits @@ -38,23 +32,24 @@ Dapr Agents builds on top of Dapr's Workflow API, which under the hood represent ### Data-Centric AI Agents -With built-in connectivity to over 50 enterprise data sources, Dapr Agents efficiently handles structured and unstructured data. From basic [PDF extraction]({{< ref "/developing-applications/dapr-agents/dapr-agents-tools.md" >}}) to large-scale database interactions, it enables seamless data-driven AI workflows with minimal code changes. Dapr's [bindings](https://docs.dapr.io/reference/components-reference/supported-bindings/) and [state stores](https://docs.dapr.io/reference/components-reference/supported-state-stores/), along with [MCP](https://modelcontextprotocol.io/) support, provide access to a large number of data sources that can be used to ingest data to an agent. +With built-in connectivity to over 50 enterprise data sources, Dapr Agents efficiently handles structured and unstructured data. From basic [PDF extraction]({{< ref "/developing-applications/dapr-agents/dapr-agents-integrations.md" >}}) to large-scale database interactions, it enables seamless data-driven AI workflows with minimal code changes. Dapr's [bindings](https://docs.dapr.io/developing-applications/building-blocks/bindings/bindings-overview/) and [state stores](https://docs.dapr.io/reference/components-reference/supported-state-stores/), along with MCP support, provide access to a large number of data sources that can be used to ingest data to an agent. ### Accelerated Development Dapr Agents provides a set of AI features that give developers a complete API surface to tackle common problems. Some of these include: -- Multi-agent communications + +- Flexible prompting - Structured outputs - Multiple LLM providers - Contextual memory -- Flexible prompting - Intelligent tool selection - [MCP integration](https://docs.anthropic.com/en/docs/agents-and-tools/mcp) +- Multi-agent communications ### Integrated Security and Reliability -By building on top of Dapr, platform and infrastructure teams can apply Dapr's [resiliency policies](https://docs.dapr.io/operations/resiliency/policies/) to the database and/or message broker of their choice that are used by Dapr Agents. These policies include timeouts, retry/backoffs and circuit breakers. When it comes to security, Dapr provides the option to scope access to a given database or message broker to one or more agentic app deployments. In addition, Dapr Agents uses mTLS to encrypt the communication layer of its underlying components. +By building on top of Dapr, platform and infrastructure teams can apply Dapr's [resiliency policies](https://docs.dapr.io/operations/resiliency/policies/) to the database and/or message broker of their choice that are used by Dapr Agents. These policies include timeouts, retry/backoffs and circuit breakers. When it comes to [security](https://docs.dapr.io/concepts/security-concept/), Dapr provides the option to scope access to a given database or message broker to one or more agentic app deployments. In addition, Dapr Agents uses mTLS to encrypt the communication layer of its underlying components. ### Built-in Messaging and State Infrastructure @@ -62,7 +57,7 @@ By building on top of Dapr, platform and infrastructure teams can apply Dapr's [ - **Publish and Subscribe**: Supports loosely coupled collaboration between agents through a shared message bus. This enables real-time, event-driven interactions critical for task distribution and coordination. - **Durable Workflow**: Defines long-running, persistent workflows that combine deterministic processes with LLM-based decision-making. Dapr Agents uses this to orchestrate complex multi-step agentic workflows seamlessly. - **State Management**: Provides a flexible key-value store for agents to retain context across interactions, ensuring continuity and adaptability during workflows. -- **Actors**: Implements the Virtual Actor pattern, allowing agents to operate as self-contained, stateful units that handle messages sequentially. This eliminates concurrency concerns and enhances scalability in agentic systems. +- **LLM Integration**: Uses Dapr [Conversation API](https://docs.dapr.io/developing-applications/building-blocks/conversation/conversation-overview/) to abstract LLM inference APIs for chat completion, or provides native clients for other LLM integrations such as embeddings, audio, etc. ### Vendor-Neutral and Open Source diff --git a/daprdocs/static/images/dapr-agents/agents-augmented-llm.png b/daprdocs/static/images/dapr-agents/agents-augmented-llm.png new file mode 100644 index 000000000..16e63ab1e Binary files /dev/null and b/daprdocs/static/images/dapr-agents/agents-augmented-llm.png differ diff --git a/daprdocs/static/images/dapr-agents/agents-autonomous.png b/daprdocs/static/images/dapr-agents/agents-autonomous.png new file mode 100644 index 000000000..501326897 Binary files /dev/null and b/daprdocs/static/images/dapr-agents/agents-autonomous.png differ diff --git a/daprdocs/static/images/dapr-agents/agents-evaluator-optimizer.png b/daprdocs/static/images/dapr-agents/agents-evaluator-optimizer.png new file mode 100644 index 000000000..67bdaf221 Binary files /dev/null and b/daprdocs/static/images/dapr-agents/agents-evaluator-optimizer.png differ diff --git a/daprdocs/static/images/dapr-agents/agents-orchestrator-workers.png b/daprdocs/static/images/dapr-agents/agents-orchestrator-workers.png new file mode 100644 index 000000000..1a5cad1f1 Binary files /dev/null and b/daprdocs/static/images/dapr-agents/agents-orchestrator-workers.png differ diff --git a/daprdocs/static/images/dapr-agents/agents-parallelization.png b/daprdocs/static/images/dapr-agents/agents-parallelization.png new file mode 100644 index 000000000..4c709827e Binary files /dev/null and b/daprdocs/static/images/dapr-agents/agents-parallelization.png differ diff --git a/daprdocs/static/images/dapr-agents/agents-patterns-overview.png b/daprdocs/static/images/dapr-agents/agents-patterns-overview.png new file mode 100644 index 000000000..4c231bce2 Binary files /dev/null and b/daprdocs/static/images/dapr-agents/agents-patterns-overview.png differ diff --git a/daprdocs/static/images/dapr-agents/agents-prompt-chaining.png b/daprdocs/static/images/dapr-agents/agents-prompt-chaining.png new file mode 100644 index 000000000..bfdd9c7ff Binary files /dev/null and b/daprdocs/static/images/dapr-agents/agents-prompt-chaining.png differ diff --git a/daprdocs/static/images/dapr-agents/agents-routing.png b/daprdocs/static/images/dapr-agents/agents-routing.png new file mode 100644 index 000000000..2ebc36b44 Binary files /dev/null and b/daprdocs/static/images/dapr-agents/agents-routing.png differ diff --git a/daprdocs/static/images/dapr-agents/agents-stateful-llm.png b/daprdocs/static/images/dapr-agents/agents-stateful-llm.png new file mode 100644 index 000000000..a65ea6f33 Binary files /dev/null and b/daprdocs/static/images/dapr-agents/agents-stateful-llm.png differ