From 66077b2da661e4acfce58cca59fbb6c6b29e5fa4 Mon Sep 17 00:00:00 2001 From: Bilgin Ibryam Date: Wed, 23 Jul 2025 08:30:31 +0100 Subject: [PATCH] Improve docs Signed-off-by: Bilgin Ibryam --- .../dapr-agents/_index.md | 2 +- .../dapr-agents-getting-started.md | 23 +++++++----- .../dapr-agents/dapr-agents-introduction.md | 19 +++++----- .../dapr-agents/dapr-agents-patterns.md | 2 +- .../dapr-agents/dapr-agents-why.md | 37 +++++++++---------- 5 files changed, 43 insertions(+), 40 deletions(-) diff --git a/daprdocs/content/en/developing-applications/dapr-agents/_index.md b/daprdocs/content/en/developing-applications/dapr-agents/_index.md index c32b6de37..2f4719098 100644 --- a/daprdocs/content/en/developing-applications/dapr-agents/_index.md +++ b/daprdocs/content/en/developing-applications/dapr-agents/_index.md @@ -8,5 +8,5 @@ description: "A framework for building production-grade resilient AI agent syste ### What is Dapr Agents? -Dapr Agents is a framework for building LLM-powered autonomous agentic applications using Dapr's distributed systems capabilities. It provides tools for creating agents that can execute tasks, make decisions, and collaborate through workflows, while leveraging Dapr's state management, messaging, and observability features for reliable execution at scale. +Dapr Agents is a framework for building LLM-powered autonomous agentic applications using Dapr's distributed systems capabilities. It provides tools for creating AI agents that can execute tasks, make decisions, and collaborate through workflows, while leveraging Dapr's state management, messaging, and observability features for reliable execution at scale. \ No newline at end of file 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 bb5961422..2e04d2ec6 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,7 +3,7 @@ type: docs title: "Getting Started" linkTitle: "Getting Started" weight: 20 -description: "How to install and run Dapr Agents" +description: "How to install Dapr Agents and run your first agent" --- {{% alert title="Dapr Agents Concepts" color="primary" %}} @@ -69,6 +69,8 @@ Create a `.env` file with your OpenAI API key: OPENAI_API_KEY=your_api_key_here ``` +This API key is essential for agents to communicate with the LLM, as the default LLM client in the agent uses OpenAI's services. If you don't have an API key, you can [create one here](https://platform.openai.com/api-keys). + ### 2. Create the Dapr component Create a `components` directory and add `historystore.yaml`: @@ -88,6 +90,8 @@ spec: value: "" ``` +This component will be used to store the conversation history, as LLMs are stateless and every chat interaction needs to send all the previous conversations to maintain context. + ### 3. Create the agent with weather tool Create `weather_agent.py`: @@ -126,7 +130,8 @@ async def main(): if __name__ == "__main__": asyncio.run(main()) ``` - + +This code creates an agent with a single weather tool and uses Dapr for memory persistence. Notice how in the agent's responses, it remembers the user's name from the first chat interaction, demonstrating the conversation memory in action. ### 4. Run with Dapr @@ -134,26 +139,25 @@ if __name__ == "__main__": 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. +This command starts a Dapr sidecar with the conversation component and launches the agent that communicates with the sidecar for state persistence. -## Enable Redis Insights (Optional) +### 5. 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: * Viewing Pub/Sub Messages: Monitor and inspect messages exchanged between agents in event-driven workflows. -* Inspecting State Information: Access and analyze shared state data among agents. +* Inspecting State Information: Access and analyze workflow state, conversation state, and other shared 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 for debugging purposes. +To inspect the Redis instance, a great tool to use is Redis Insight, and you can use it to inspect the agent memory populated earlier. ```bash docker run --rm -d --name redisinsight -p 5540:5540 redis/redisinsight:latest ``` Once running, access the Redis Insight interface at `http://localhost:5540/` - -### Connection Configuration +Inside Redis Insight, you can connect to a Redis instance, so let's connect to the one used by the agent: * Port: 6379 * Host (Linux): 172.17.0.1 @@ -163,7 +167,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) - +Here you can browse the state store used in the agent and explore its data. + ## Next Steps 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. 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 0a0631c71..b806bb832 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 @@ -8,7 +8,7 @@ description: "Overview of Dapr Agents and its key features" ![Agent Overview](/images/dapr-agents/concepts-agents-overview.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. +[Dapr Agents](https://github.com/dapr/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. ## Core Capabilities @@ -18,7 +18,7 @@ Dapr Agents is a developer framework for building production-grade, resilient AI - **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. - **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. +- **Platform-Ready**: 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 @@ -30,20 +30,21 @@ Dapr Agents provides specialized modules designed for creating intelligent, auto |----------------------------------------------------------------------------------------------|-------------| | [**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. +| [**Tool Selection**]({{< ref "dapr-agents-integrations.md#tool-selection" >}}) | Dynamic tool selection based on requirements, best action, and execution through [Function Calling](https://platform.openai.com/docs/guides/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. +| [**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](https://docs.dapr.io/developing-applications/building-blocks/state-management/state-management-overview/) for scalable, persistent memory. | [**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. +| [**Headless Agents**]({{< 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. +| [**Event-Driven Communication**]({{< ref "dapr-agents-core-concepts.md#messaging" >}}) | Enable agent collaboration through [Pub/Sub messaging](https://docs.dapr.io/developing-applications/building-blocks/pubsub/pubsub-overview/) 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](https://docs.dapr.io/developing-applications/building-blocks/workflow/workflow-overview/) 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. +Dapr Agents enables a comprehensive set of patterns that represent different approaches to building intelligent systems. -Each pattern addresses specific use cases and offers different trade-offs between determenisstic outcomes and autonomy: + +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 deterministic outcomes and autonomy: | Pattern | Description | |----------------------------------------------------------------------------------------|-------------| 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 index a000df321..566173e38 100644 --- a/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-patterns.md +++ b/daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-patterns.md @@ -344,7 +344,7 @@ Moving to the far end of the agentic spectrum, the Durable Agent pattern represe 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 +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. 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 d379de041..d234136a8 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 @@ -6,38 +6,37 @@ weight: 30 description: "Understanding the benefits and use cases for Dapr Agents" --- -Dapr Agents is an open-source framework for building and orchestrating LLM-based autonomous agents, designed to simplify the complexity of creating scalable agentic workflows and microservices. Inspired by the growing need for frameworks that integrate seamlessly with distributed systems, Dapr Agents enables developers to focus on designing intelligent agents without getting bogged down by infrastructure concerns. - +Dapr Agents is an open-source framework for building and orchestrating LLM-based autonomous agents that leverages Dapr's proven distributed systems foundation. Unlike other agentic frameworks that require developers to build infrastructure from scratch, Dapr Agents enables teams to focus on agent intelligence by providing enterprise-grade scalability, state management, and messaging capabilities out of the box. This approach eliminates the complexity of recreating distributed system fundamentals while delivering production-ready agentic workflows.RetryClaude can make mistakes. Please double-check responses. + ### The Problem -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 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 steep learning curves, 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. +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 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, 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. +Dapr Agents takes a different 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. +By integrating with Dapr's runtime and modular components, Dapr Agents empowers developers to build and deploy agents that work as collaborative services within larger systems. Whether experimenting with a single agent or orchestrating workflows involving multiple agents, Dapr Agents allows teams to concentrate on the intelligence and behavior of LLM-powered agents while leveraging a proven framework for scalability and reliability. ## Dapr Agents Benefits -### Scalable Workflows as a First Class Citizen +### Scalable Workflows as First-Class Citizens -Dapr Agents uses a [durable-execution workflow engine](https://docs.dapr.io/developing-applications/building-blocks/workflow/workflow-overview/) that guarantees each agent task executes to completion in the face of network interruptions, node crashes and other types of disruptive failures. Developers do not need to know about the underlying concepts of the workflow engine - simply write an agent that performs any number of tasks and these will get automatically distributed across the cluster. If any task fails, it will be retried and recover its state from where it left off. +Dapr Agents uses a [durable-execution workflow engine](https://docs.dapr.io/developing-applications/building-blocks/workflow/workflow-overview/) that guarantees each agent task executes to completion despite network interruptions, node crashes, and other disruptive failures. Developers do not need to understand the underlying workflow engine concepts—simply write an agent that performs any number of tasks and these will be automatically distributed across the cluster. If any task fails, it will be retried and recover its state from where it left off. ### Cost-Effective AI Adoption -Dapr Agents builds on top of Dapr's Workflow API, which under the hood represents each agent as an actor, a single unit of compute and state that is thread-safe and natively distributed, lending itself well to an agentic Scale-To-Zero architecture. This minimizes infrastructure costs, making AI adoption accessible to everyone. The underlying virtual actor model allows thousands of agents to run on demand on a single core machine with double-digit millisecond latency when scaling from zero. When unused, the agents are reclaimed by the system but retain their state until the next time they are needed. With this design, there's no trade-off between performance and resource efficiency. +Dapr Agents builds on Dapr's Workflow API, which represents each agent as an actor, a single unit of compute and state that is thread-safe and natively distributed. This design enables a scale-to-zero architecture that minimizes infrastructure costs, making AI adoption accessible to organizations of all sizes. The underlying virtual actor model allows thousands of agents to run on demand on a single machine with low latency when scaling from zero. When unused, agents are reclaimed by the system but retain their state until needed again. This design eliminates the trade-off between performance and resource efficiency. ### 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-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. +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 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 numerous data sources for agent data ingestion. ### 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: - +Dapr Agents provides AI features that give developers a complete API surface to tackle common problems, including: - Flexible prompting - Structured outputs @@ -49,18 +48,16 @@ Dapr Agents provides a set of AI features that give developers a complete API su ### 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](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. +By building on Dapr, platform and infrastructure teams can apply Dapr's [resiliency policies](https://docs.dapr.io/operations/resiliency/policies/) to the database and message broker components used by Dapr Agents. These policies include timeouts, retry/backoff strategies, and circuit breakers. For [security](https://docs.dapr.io/concepts/security-concept/), Dapr provides options to scope access to specific databases or message brokers to one or more agentic app deployments. Additionally, Dapr Agents uses mTLS to encrypt communication between its underlying components. ### Built-in Messaging and State Infrastructure - - **Service-to-Service Invocation**: Facilitates direct communication between agents with built-in service discovery, error handling, and distributed tracing. Agents can leverage this for synchronous messaging in multi-agent workflows. -- **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. +- **Service-to-Service Invocation**: Enables direct communication between agents with built-in service discovery, error handling, and distributed tracing. Agents can use this for synchronous messaging in multi-agent workflows. +- **Publish and Subscribe**: Supports loosely coupled collaboration between agents through a shared message bus. This enables real-time, event-driven interactions 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. - **State Management**: Provides a flexible key-value store for agents to retain context across interactions, ensuring continuity and adaptability during workflows. -- **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. +- **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, and provides native clients for other LLM integrations such as embeddings and audio processing. ### Vendor-Neutral and Open Source -As a part of **CNCF**, Dapr Agents is vendor-neutral, eliminating concerns about lock-in, intellectual property risks, or proprietary restrictions. Organizations gain full flexibility and control over their AI applications using open-source software they can audit and contribute to. - - \ No newline at end of file +As part of the **CNCF**, Dapr Agents is vendor-neutral, eliminating concerns about lock-in, intellectual property risks, or proprietary restrictions. Organizations gain full flexibility and control over their AI applications using open-source software they can audit and contribute to. \ No newline at end of file