From 04ae12186ea93e951fa6be1f1c515f607ab283ae Mon Sep 17 00:00:00 2001 From: Samantha Coyle Date: Tue, 29 Jul 2025 15:12:27 -0500 Subject: [PATCH] fix: correct links, capitalization, content corrections, etc Signed-off-by: Samantha Coyle --- .../content/en/contributing/dapr-agents.md | 10 ++--- .../dapr-agents/dapr-agents-core-concepts.md | 26 ++++++------ .../dapr-agents/dapr-agents-introduction.md | 41 ++++++++++--------- 3 files changed, 39 insertions(+), 38 deletions(-) diff --git a/daprdocs/content/en/contributing/dapr-agents.md b/daprdocs/content/en/contributing/dapr-agents.md index 48a1c6fba..696c8cff2 100644 --- a/daprdocs/content/en/contributing/dapr-agents.md +++ b/daprdocs/content/en/contributing/dapr-agents.md @@ -1,16 +1,16 @@ --- type: docs -title: "Contributing to Dapr agents" -linkTitle: "Dapr agents" +title: "Contributing to Dapr Agents" +linkTitle: "Dapr Agents" weight: 85 -description: Guidelines for contributing to Dapr agents +description: Guidelines for contributing to Dapr Agents --- -When contributing to Dapr agents, the following rules and best-practices should be followed. +When contributing to Dapr Agents, the following rules and best-practices should be followed. ## Examples -The examples directory contains code samples for users to run to try out specific functionality of the various Dapr agents packages and extensions. When writing new and updated samples keep in mind: +The examples directory contains code samples for users to run to try out specific functionality of the various Dapr Agents packages and extensions. When writing new and updated samples keep in mind: - All examples should be runnable on Windows, Linux, and MacOS. While Python code is consistent among operating systems, any pre/post example commands should provide options through [codetabs]({{< ref "contributing-docs.md#tabbed-content" >}}) - Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine. 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 9c9d747f6..a5fe4996a 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 @@ -6,7 +6,7 @@ weight: 40 description: "Learn about the core concepts of Dapr Agents" --- -Dapr Agents provides a structured way to build and orchestrate applications that use LLMs without getting bogged down in infrastructure details. The primary goal is to make AI development by abstracting away the complexities of working with LLMs, tools, memory management, and distributed systems, allowing developers to focus on the business logic of their AI applications. Agents in this framework are the fundamental building blocks. +Dapr Agents provides a structured way to build and orchestrate applications that use LLMs without getting bogged down in infrastructure details. The primary goal is to enable AI development by abstracting away the complexities of working with LLMs, tools, memory management, and distributed systems, allowing developers to focus on the business logic of their AI applications. Agents in this framework are the fundamental building blocks. ## Agents @@ -89,12 +89,12 @@ In Summary: | Agent Type | Memory Type | Execution | Interaction Mode | |-----------------|-------------------------|---------------------------|------------------------------| | `Agent` | In-memory or Persistent | Ephemeral | Synchronous / Conversational | -| `Durable Agent` | In-memory or Persistent | Durable (Workflow-backed) | Asynchronous / Headless | +| `Durable Agent` | In-memory or Persistent | Durable (Workflow-backed) | Synchronous / Asynchronous / Headless | -- Regular `Agent`: Interaction is synchronous—you send conversational prompts and receive responses immediately. The conversation can be stored in memory or persisted, but the execution is ephemeral and does not survive restarts. +- Regular `Agent`: Interaction is synchronous — you send conversational prompts and receive responses immediately. The conversation can be stored in memory or persisted, but the execution is ephemeral and does not survive restarts. -- `DurableAgent` (Workflow-backed): Interaction is asynchronous—you trigger the agent once, and it runs autonomously in the background until completion. The conversation state can also be in memory or persisted, but the execution is durable and can resume across failures or restarts. +- `DurableAgent` (Workflow-backed): Interaction is synchronous or asynchronous — you can trigger the agent once, and it runs autonomously in the background until completion. The conversation state can also be in memory or persisted, but the execution is durable and can resume across failures or restarts. ## Core Agent Features @@ -104,15 +104,15 @@ An agentic system is a distributed system that requires a variety of behaviors a Dapr Agents provides a unified interface to connect with LLM inference APIs. This abstraction allows developers to seamlessly integrate their agents with cutting-edge language models for reasoning and decision-making. The framework includes multiple LLM clients for different providers and modalities: +- `DaprChatClient`: Unified API for LLM interactions via Dapr's Conversation API with built-in security (scopes, secrets, PII obfuscation), resiliency (timeouts, retries, circuit breakers), and observability via OpenTelemetry & Prometheus - `OpenAIChatClient`: Full spectrum support for OpenAI models including chat, embeddings, and audio - `HFHubChatClient`: For Hugging Face models supporting both chat and embeddings - `NVIDIAChatClient`: For NVIDIA AI Foundation models supporting local inference and chat - `ElevenLabs`: Support for speech and voice capabilities -- `DaprChatClient`: Unified API for LLM interactions via Dapr's Conversation API with built-in security (scopes, secrets, PII obfuscation), resiliency (timeouts, retries, circuit breakers), and observability via OpenTelemetry & Prometheus ### Prompt Flexibility -Dapr Agents supports flexible prompt templates to shape agent behavior and reasoning. Users can define placeholders within prompts, enabling dynamic input of context for inference calls. By leveraging prompt formatting with [Jinja templates](https://jinja.palletsprojects.com/en/stable/templates/), users can include loops, conditions, and variables, providing precise control over the structure and content of prompts. This flexibility ensures that LLM responses are tailored to the task at hand, offering modularity and adaptability for diverse use cases. +Dapr Agents supports flexible prompt templates to shape agent behavior and reasoning. Users can define placeholders within prompts, enabling dynamic input of context for inference calls. By leveraging prompt formatting with [Jinja templates](https://jinja.palletsprojects.com/en/stable/templates/) and Python f-string formatting, users can include loops, conditions, and variables, providing precise control over the structure and content of prompts. This flexibility ensures that LLM responses are tailored to the task at hand, offering modularity and adaptability for diverse use cases. ### Structured Outputs @@ -165,7 +165,7 @@ This is supported directly through LLM parametric knowledge and enhanced by [Fun ### MCP Support -Dapr Agents includes built-in support for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), enabling agents to dynamically discover and invoke external tools through a standardized interface. Using the provided MCPClient, agents can connect to MCP servers via two transport options: stdio for local development and sse for remote or distributed environments. +Dapr Agents includes built-in support for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), enabling agents to dynamically discover and invoke external tools through a standardized interface. Using the provided MCPClient, agents can connect to MCP servers via three transport options: stdio for local development, sse for remote or distributed environments, and via streamable HTTP transport. ```python client = MCPClient() @@ -229,7 +229,7 @@ curl -i -X POST http://localhost:8001/start-workflow \ -H "Content-Type: application/json" \ -d '{"task": "I want to find flights to Paris"}' ``` -Unlike conversational agents that provide immediate synchronous responses, durable agents operate as headless services that are triggered asynchronously. You trigger it, receive a workflow instance ID, and can track progress over time. This enables long-running, fault-tolerant operations that can span multiple systems and survive restarts, making them ideal for complex multi-step processes in production environments. +Unlike conversational agents that provide immediate synchronous responses, durable agents can operate as headless services that are triggered asynchronously. You trigger it, receive a workflow instance ID, and can track progress over time. This enables long-running, fault-tolerant operations that can span multiple systems and survive restarts, making them ideal for complex multi-step processes in production environments. ## Multi-agent Systems (MAS) @@ -298,7 +298,7 @@ Agent tasks enable workflows to leverage specialized agents with their own tools ### Workflow Patterns -Workflows enable the implementation of various agentic patterns through structured orchestration, including Prompt Chaining, Routing, Parallelization, Orchestrator-Workers, Evaluator-Optimizer, Human-in-the-loop, and others. For detailed implementations and examples of these patterns, see the [Patterns documentation]({{< ref "dapr-agents-patterns.md" >}}). +Workflows enable the implementation of various agentic patterns through structured orchestration, including Prompt Chaining, Routing, Parallelization, Orchestrator-Workers, Evaluator-Optimizer, Human-in-the-loop, and others. For detailed implementations and examples of these patterns, see the [Patterns documentation]({{< ref "developing-applications/dapr-agents/dapr-agents-patterns.md" >}}). ### Workflows vs. Durable Agents @@ -309,14 +309,14 @@ Both DurableAgent and workflow-based agent orchestration use Dapr workflows behi | Control | Developer-defined process flow | Agent determines next steps | | Predictability | Higher | Lower | | Flexibility | Fixed overall structure, flexible within steps | Completely flexible | -| Reliability | Very high (workflow engine guarantees) | Depends on agent implementation | -| Complexity | Simpler to reason about | Harder to debug and understand | +| Reliability | Very high (workflow engine guarantees) | Very high (underlying agent implementation guarantees) | +| Complexity | Structured workflow patterns | Dynamic, flexible execution paths | | Use Cases | Business processes, regulated domains | Open-ended research, creative tasks | -The key difference lies in control flow determination: with DurableAgent, the workflow is created dynamically by the LLM's planning decisions, executing entirely within a single agent context. In contrast, with deterministic workflows, the developer explicitly defines the coordination between one or more LLM interactions, providing structured orchestration across multiple tasks or agents. +The key difference lies in control flow determination: with DurableAgent, the underlying workflow is created dynamically by the LLM's planning decisions, executing entirely within a single agent context. In contrast, with deterministic workflows, the developer explicitly defines the coordination between one or more LLM interactions, providing structured orchestration across multiple tasks or agents. -## Event-driven Orchestration +## Event-Driven Orchestration Event-driven agent orchestration enables multiple specialized agents to collaborate through asynchronous [Pub/Sub messaging](https://docs.dapr.io/developing-applications/building-blocks/pubsub/pubsub-overview/). This approach provides powerful collaborative problem-solving, parallel processing, and division of responsibilities among specialized agents through independent scaling, resilience via service isolation, and clear separation of responsibilities. ### Core Participants 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 17af8e70b..0e82a91a3 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,17 +8,17 @@ 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 is a developer framework for building production-grade, durable 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 - **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. +- **Workflow Resilience**: Automatically retry agentic workflows and to ensure task completion. - **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**: 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 @@ -26,17 +26,17 @@ Dapr Agents is a developer framework for building production-grade, resilient AI 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 | +| Feature | Description | |----------------------------------------------------------------------------------------------|-------------| -| [**LLM Integration**]({{% ref "dapr-agents-core-concepts.md#1-llm-integration" %}}) | Uses Dapr [Conversation API]({{% ref conversation-overview.md %}}) 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#2-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-core-concepts.md#3-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-core-concepts.md#4-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#5-memory" %}}) | Retain context across interactions with options from simple in-memory lists to vector databases, integrating with [Dapr state stores]({{% ref state-management-overview.md %}}) for scalable, persistent memory. -| [**Durable Agents**]({{% ref "dapr-agents-core-concepts.md#durableagent" %}}) | Workflow-backed agents that provide fault-tolerant execution with persistent state management and automatic retry mechanisms for long-running processes. -| [**Headless Agents**]({{% ref "dapr-agents-core-concepts.md#7-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#8-message-driven-communication" %}}) | Enable agent collaboration through [Pub/Sub messaging]({{% ref pubsub-overview.md %}}) for event-driven communication, task distribution, and real-time coordination in distributed systems. -| [**Agent Orchestration**]({{% ref "dapr-agents-core-concepts.md#9-workflow-orchestration" %}}) | Deterministic agent orchestration using [Dapr Workflows]({{% ref workflow-overview.md %}}) with higher-level tasks that interact with LLMs for complex multi-step processes. +| [**LLM Integration**]({{% ref "dapr-agents-core-concepts.md#llm-integration" %}}) | Uses Dapr [Conversation API]({{% ref conversation-overview.md %}}) 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-core-concepts.md#tool-calling" %}}) | 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-core-concepts.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" %}}) | Retain context across interactions with options from simple in-memory lists to vector databases, integrating with [Dapr state stores]({{% ref state-management-overview.md %}}) 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. +| [**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#event-driven-orchestration" %}}) | Enable agent collaboration through [Pub/Sub messaging]({{% ref pubsub-overview.md %}}) for event-driven communication, task distribution, and real-time coordination in distributed systems. +| [**Agent Orchestration**]({{% ref "dapr-agents-core-concepts.md#deterministic-workflows" %}}) | Deterministic agent orchestration using [Dapr Workflows]({{% ref workflow-overview.md %}}) with higher-level tasks that interact with LLMs for complex multi-step processes. ## Agentic Patterns @@ -49,12 +49,13 @@ These patterns exist along a spectrum of autonomy, from predictable workflow-bas | 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. +| [**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. +| [**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. +| [**Parallelization**]({{% ref "dapr-agents-patterns.md#parallelization" %}}) | Processes multiple dimensions of a problem simultaneously with outputs aggregated programmatically for improved efficiency. +| [**Routing**]({{% ref "dapr-agents-patterns.md#routing" %}}) | Classifies inputs and directs them to specialized follow-up tasks, enabling separation of concerns and expert specialization. +| [**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. + ## Developer Experience @@ -63,11 +64,11 @@ Dapr Agents is a Python framework built on top of the [Python Dapr SDK]({{% ref ### Getting Started -Get started with Dapr Agents by following the instructions on the [Getting Started page]({{% ref "dapr-agents-getting-started.md" %}}). +Get started with Dapr Agents by following the instructions on the [Getting Started page]({{% ref "developing-applications/dapr-agents/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 page]({{% ref "dapr-agents-integrations.md" %}}). +Dapr Agents integrates with popular Python frameworks and tools. For detailed integration guides and examples, see the [integrations page]({{% ref "developing-applications/dapr-agents/dapr-agents-integrations.md" %}}). ## Operational Support