mirror of https://github.com/dapr/docs.git
Merge branch 'v1.16' into workflow-architecture-update
This commit is contained in:
Josh van Leeuwen
GitHub
commit
a09769ee84
|
|
@ -5,7 +5,7 @@ linkTitle: "Scheduler"
|
|||
description: "Overview of the Dapr scheduler service"
|
||||
---
|
||||
|
||||
The Dapr Scheduler service is used to schedule different types of jobs, running in [self-hosted mode]({{% ref self-hosted %}}) or on [Kubernetes]({{% ref kubernetes %}}).
|
||||
The Dapr Scheduler service is used to schedule different types of jobs, running in [self-hosted mode]({{% ref self-hosted %}}) or on [Kubernetes]({{% ref kubernetes %}}).
|
||||
- Jobs created through the Jobs API
|
||||
- Actor reminder jobs (used by the actor reminders)
|
||||
- Actor reminder jobs created by the Workflow API (which uses actor reminders)
|
||||
|
|
@ -14,10 +14,13 @@ From Dapr v1.15, the Scheduler service is used by default to schedule actor remi
|
|||
|
||||
There is no concept of a leader Scheduler instance. All Scheduler service replicas are considered peers. All receive jobs to be scheduled for execution and the jobs are allocated between the available Scheduler service replicas for load balancing of the trigger events.
|
||||
|
||||
The diagram below shows how the Scheduler service is used via the jobs API when called from your application. All the jobs that are tracked by the Scheduler service are stored in an embedded etcd database.
|
||||
The diagram below shows how the Scheduler service is used via the jobs API when called from your application. All the jobs that are tracked by the Scheduler service are stored in the Etcd database.
|
||||
|
||||
<img src="/images/scheduler/scheduler-architecture.png" alt="Diagram showing the Scheduler control plane service and the jobs API">
|
||||
|
||||
By default, Etcd is embedded in the Scheduler service, which means that the Scheduler service runs its own instance of Etcd.
|
||||
See [Scheduler service flags]({{% ref "#flag-tuning" %}}) for more information on how to configure the Scheduler service.
|
||||
|
||||
## Actor Reminders
|
||||
|
||||
Prior to Dapr v1.15, [actor reminders]({{% ref "actors-timers-reminders#actor-reminders" %}}) were run using the Placement service. Now, by default, the [`SchedulerReminders` feature flag]({{% ref "support-preview-features#current-preview-features" %}}) is set to `true`, and all new actor reminders you create are run using the Scheduler service to make them more scalable.
|
||||
|
|
@ -73,6 +76,45 @@ The Scheduler service is deployed as part of `dapr init -k`, or via the Dapr Hel
|
|||
|
||||
When a Kubernetes namespace is deleted, all the Job and Actor Reminders corresponding to that namespace are deleted.
|
||||
|
||||
## Docker Compose Example
|
||||
|
||||
Here's how to expose the etcd ports in a Docker Compose configuration for standalone mode.
|
||||
When running in HA mode, you only need to expose the ports for one scheduler instance to perform backup operations.
|
||||
|
||||
```yaml
|
||||
version: "3.5"
|
||||
services:
|
||||
scheduler-0:
|
||||
image: "docker.io/daprio/scheduler:1.16.0"
|
||||
command:
|
||||
- "./scheduler"
|
||||
- "--etcd-data-dir=/var/run/dapr/scheduler"
|
||||
- "--id=scheduler-0"
|
||||
- "--etcd-initial-cluster=scheduler-0=http://scheduler-0:2380,scheduler-1=http://scheduler-1:2380,scheduler-2=http://scheduler-2:2380"
|
||||
ports:
|
||||
- 2379:2379
|
||||
volumes:
|
||||
- ./dapr_scheduler/0:/var/run/dapr/scheduler
|
||||
scheduler-1:
|
||||
image: "docker.io/daprio/scheduler:1.16.0"
|
||||
command:
|
||||
- "./scheduler"
|
||||
- "--etcd-data-dir=/var/run/dapr/scheduler"
|
||||
- "--id=scheduler-1"
|
||||
- "--etcd-initial-cluster=scheduler-0=http://scheduler-0:2380,scheduler-1=http://scheduler-1:2380,scheduler-2=http://scheduler-2:2380"
|
||||
volumes:
|
||||
- ./dapr_scheduler/1:/var/run/dapr/scheduler
|
||||
scheduler-2:
|
||||
image: "docker.io/daprio/scheduler:1.16.0"
|
||||
command:
|
||||
- "./scheduler"
|
||||
- "--etcd-data-dir=/var/run/dapr/scheduler"
|
||||
- "--id=scheduler-2"
|
||||
- "--etcd-initial-cluster=scheduler-0=http://scheduler-0:2380,scheduler-1=http://scheduler-1:2380,scheduler-2=http://scheduler-2:2380"
|
||||
volumes:
|
||||
- ./dapr_scheduler/2:/var/run/dapr/scheduler
|
||||
```
|
||||
|
||||
## Back Up and Restore Scheduler Data
|
||||
|
||||
In production environments, it's recommended to perform periodic backups of this data at an interval that aligns with your recovery point objectives.
|
||||
|
|
@ -89,32 +131,6 @@ Here's how to port forward and connect to the etcd instance:
|
|||
kubectl port-forward svc/dapr-scheduler-server 2379:2379 -n dapr-system
|
||||
```
|
||||
|
||||
#### Docker Compose Example
|
||||
|
||||
Here's how to expose the etcd ports in a Docker Compose configuration for standalone mode:
|
||||
|
||||
```yaml
|
||||
scheduler-1:
|
||||
image: "diagrid/dapr/scheduler:dev110-linux-arm64"
|
||||
command: ["./scheduler",
|
||||
"--etcd-data-dir", "/var/run/dapr/scheduler",
|
||||
"--replica-count", "3",
|
||||
"--id","scheduler-1",
|
||||
"--initial-cluster", "scheduler-1=http://scheduler-1:2380,scheduler-0=http://scheduler-0:2380,scheduler-2=http://scheduler-2:2380",
|
||||
"--etcd-client-ports", "scheduler-0=2379,scheduler-1=2379,scheduler-2=2379",
|
||||
"--etcd-client-http-ports", "scheduler-0=2330,scheduler-1=2330,scheduler-2=2330",
|
||||
"--log-level=debug"
|
||||
]
|
||||
ports:
|
||||
- 2379:2379
|
||||
volumes:
|
||||
- ./dapr_scheduler/1:/var/run/dapr/scheduler
|
||||
networks:
|
||||
- network
|
||||
```
|
||||
|
||||
When running in HA mode, you only need to expose the ports for one scheduler instance to perform backup operations.
|
||||
|
||||
### Performing Backup and Restore
|
||||
|
||||
Once you have access to the etcd ports, you can follow the [official etcd backup and restore documentation](https://etcd.io/docs/v3.5/op-guide/recovery/) to perform backup and restore operations. The process involves using standard etcd commands to create snapshots and restore from them.
|
||||
|
|
@ -135,6 +151,83 @@ If you are not using any features that require the Scheduler service (Jobs API,
|
|||
|
||||
For more information on running Dapr on Kubernetes, visit the [Kubernetes hosting page]({{% ref kubernetes %}}).
|
||||
|
||||
## Flag tuning
|
||||
|
||||
A number of Etcd flags are exposed on Scheduler which can be used to tune for your deployment use case.
|
||||
|
||||
### External Etcd database
|
||||
|
||||
Scheduler can be configured to use an external Etcd database instead of the embedded one inside the Scheduler service replicas.
|
||||
It may be interesting to decouple the storage volume from the Scheduler StatefulSet or container, because of how the cluster or environment is administered or what storage backend is being used.
|
||||
It can also be the case that moving the persistent storage outside of the scheduler runtime completely is desirable, or there is some existing Etcd cluster provider which will be reused.
|
||||
Externalising the Etcd database also means that the Scheduler replicas can be horizontally scaled at will, however note that during scale events, job triggering will be paused.
|
||||
Scheduler replica count does not need to match the [Etcd node count constraints](https://etcd.io/docs/v3.3/faq/#what-is-maximum-cluster-size).
|
||||
|
||||
To use an external Etcd cluster, set the `--etcd-embed` flag to `false` and provide the `--etcd-client-endpoints` flag with the endpoints of your Etcd cluster.
|
||||
Optionally also include `--etcd-client-username` and `--etcd-client-password` flags for authentication if the Etcd cluster requires it.
|
||||
|
||||
```
|
||||
--etcd-embed bool When enabled, the Etcd database is embedded in the scheduler server. If false, the scheduler connects to an external Etcd cluster using the --etcd-client-endpoints flag. (default true)
|
||||
--etcd-client-endpoints stringArray Comma-separated list of etcd client endpoints to connect to. Only used when --etcd-embed is false.
|
||||
--etcd-client-username string Username for etcd client authentication. Only used when --etcd-embed is false.
|
||||
--etcd-client-password string Password for etcd client authentication. Only used when --etcd-embed is false.
|
||||
```
|
||||
|
||||
Helm:
|
||||
|
||||
```yaml
|
||||
dapr_scheduler.etcdEmbed=true
|
||||
dapr_scheduler.etcdClientEndpoints=[]
|
||||
dapr_scheduler.etcdClientUsername=""
|
||||
dapr_scheduler.etcdClientPassword=""
|
||||
```
|
||||
|
||||
### Etcd leadership election tuning
|
||||
|
||||
To improve the speed of election leadership of rescue nodes in the event of a failure, the following flag may be used to speed up the election process.
|
||||
|
||||
```
|
||||
--etcd-initial-election-tick-advance Whether to fast-forward initial election ticks on boot for faster election. When it is true, then local member fast-forwards election ticks to speed up “initial” leader election trigger. This benefits the case of larger election ticks. Disabling this would slow down initial bootstrap process for cross datacenter deployments. Make your own tradeoffs by configuring this flag at the cost of slow initial bootstrap.
|
||||
```
|
||||
|
||||
Helm:
|
||||
|
||||
```yaml
|
||||
dapr_scheduler.etcdInitialElectionTickAdvance=true
|
||||
```
|
||||
|
||||
### Storage tuning
|
||||
|
||||
The following options can be used to tune the embedded Etcd storage to the needs of your deployment.
|
||||
A deeper understanding of what these flags do can be found in the [Etcd documentation](https://etcd.io/docs/v3.5/op-guide/configuration/).
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
Changing these flags can greatly change the performance and behaviour of the Scheduler, so caution is advised when modifying them from the default set by Dapr.
|
||||
Changing these settings should always been done first in a testing environment, and monitored closely before applying to production.
|
||||
{{% /alert %}}
|
||||
|
||||
```
|
||||
--etcd-backend-batch-interval string Maximum time before committing the backend transaction. (default "50ms")
|
||||
--etcd-backend-batch-limit int Maximum operations before committing the backend transaction. (default 5000)
|
||||
--etcd-compaction-mode string Compaction mode for etcd. Can be 'periodic' or 'revision' (default "periodic")
|
||||
--etcd-compaction-retention string Compaction retention for etcd. Can express time or number of revisions, depending on the value of 'etcd-compaction-mode' (default "10m")
|
||||
--etcd-experimental-bootstrap-defrag-threshold-megabytes uint Minimum number of megabytes needed to be freed for etcd to consider running defrag during bootstrap. Needs to be set to non-zero value to take effect. (default 100)
|
||||
--etcd-max-snapshots uint Maximum number of snapshot files to retain (0 is unlimited). (default 10)
|
||||
--etcd-max-wals uint Maximum number of write-ahead logs to retain (0 is unlimited). (default 10)
|
||||
--etcd-snapshot-count uint Number of committed transactions to trigger a snapshot to disk. (default 10000)
|
||||
```
|
||||
|
||||
Helm:
|
||||
|
||||
```yaml
|
||||
dapr_scheduler.etcdBackendBatchInterval="50ms"
|
||||
dapr_scheduler.etcdBackendBatchLimit=5000
|
||||
dapr_scheduler.etcdCompactionMode="periodic"
|
||||
dapr_scheduler.etcdCompactionRetention="10m"
|
||||
dapr_scheduler.etcdDefragThresholdMB=100
|
||||
dapr_scheduler.etcdMaxSnapshots=10
|
||||
```
|
||||
|
||||
## Related links
|
||||
|
||||
[Learn more about the Jobs API.]({{% ref jobs_api %}})
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -199,8 +199,6 @@ Messages are pulled by the application from Dapr. This means no endpoint is need
|
|||
Any number of pubsubs and topics can be subscribed to at once.
|
||||
As messages are sent to the given message handler code, there is no concept of routes or bulk subscriptions.
|
||||
|
||||
> **Note:** Only a single pubsub/topic pair per application may be subscribed at a time.
|
||||
|
||||
The example below shows the different ways to stream subscribe to a topic.
|
||||
|
||||
{{< tabpane text=true >}}
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ type: docs
|
|||
title: "Dapr Agents"
|
||||
linkTitle: "Dapr Agents"
|
||||
weight: 25
|
||||
description: "A framework for building production-grade resilient AI agent systems at scale"
|
||||
description: "A framework for building durable and resilient AI agent systems at scale"
|
||||
---
|
||||
|
||||
### What is Dapr Agents?
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
@ -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 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 environments requiring high levels of durability and resiliency.
|
||||
|
||||
## 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 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
|
||||
|
|
|
|||
|
|
@ -133,7 +133,6 @@ Create a `requirements.txt` file with the necessary dependencies:
|
|||
|
||||
```txt
|
||||
dapr-agents
|
||||
python-dotenv
|
||||
```
|
||||
|
||||
Create and activate a virtual environment, then install the dependencies:
|
||||
|
|
@ -163,7 +162,7 @@ This command starts a Dapr sidecar with the conversation component and launches
|
|||
|
||||
### 6. Enable Redis Insights (Optional)
|
||||
|
||||
Dapr uses [Redis]({{% ref setup-redis.md %}}) by default for state management and pub/sub messaging, which are fundamental to Dapr Agents's agentic workflows. 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. To run Redis Insights, run:
|
||||
Dapr uses [Redis]({{% ref setup-redis.md %}}) by default for state management and pub/sub messaging, which are fundamental to Dapr Agents's agentic workflows. To inspect the Redis instance, a great UI tool to use is Redis Insight, and you can use it to inspect the agent memory populated earlier. To run Redis Insights, run:
|
||||
|
||||
```bash
|
||||
docker run --rm -d --name redisinsight -p 5540:5540 redis/redisinsight:latest
|
||||
|
|
|
|||
|
|
@ -8,17 +8,17 @@ description: "Overview of Dapr Agents and its key features"
|
|||
|
||||
|
||||
|
||||
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 durable and 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
|
||||
|
||||
- **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,24 +64,24 @@ 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 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
|
||||
|
||||
Dapr Agents inherits Dapr's enterprise-grade operational capabilities, providing comprehensive support for production deployments of agentic systems.
|
||||
Dapr Agents inherits Dapr's enterprise-grade operational capabilities, providing comprehensive support for durable and reliable deployments of agentic systems.
|
||||
|
||||
### Built-in Operational Features
|
||||
|
||||
- **[Observability]({{% ref observability-concept.md %}})** - Distributed tracing, metrics collection, and logging for agent interactions and workflow execution
|
||||
- **[Security]({{% ref security-concept.md %}})** - mTLS encryption, access control, and secrets management for secure agent communication
|
||||
- **[Resiliency]({{% ref resiliency-concept.md %}})** - Automatic retries, circuit breakers, and timeout policies for fault-tolerant agent operations
|
||||
- **[Infrastructure Abstraction]({{% ref components-concept.md %}})** - Dapr components abstract LLM providers, memory stores, storage and messaging backends, enabling seamless transitions between development and production environments
|
||||
- **[Infrastructure Abstraction]({{% ref components-concept.md %}})** - Dapr components abstract LLM providers, memory stores, storage and messaging backends, enabling seamless transitions between different environments
|
||||
|
||||
These capabilities enable teams to monitor agent performance, secure multi-agent communications, and ensure reliable execution of complex agentic workflows in production environments.
|
||||
These capabilities enable teams to monitor agent performance, secure multi-agent communications, and ensure reliable execution of complex agentic workflows.
|
||||
|
||||
## Contributing
|
||||
|
||||
|
|
|
|||
|
|
@ -346,7 +346,7 @@ Enterprise applications often need durable execution and reliability that go bey
|
|||
|
||||
<img src="/images/dapr-agents/agents-stateful-llm.png" width=600 alt="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.
|
||||
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 environments where reliability and durability 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ description: "Get started with Dapr Agents through practical step-by-step exampl
|
|||
|
||||
#### Before you begin
|
||||
|
||||
- [Set up your local Dapr environment]({{% ref "install-dapr-cli.md" %}}).
|
||||
- [Set up your local Dapr environment]({{% ref install-dapr-cli.md %}}).
|
||||
|
||||
|
||||
## Quickstarts
|
||||
|
|
@ -21,8 +21,8 @@ description: "Get started with Dapr Agents through practical step-by-step exampl
|
|||
| [LLM Call with Dapr Chat Client](https://github.com/dapr/dapr-agents/tree/main/quickstarts/02_llm_call_dapr)<br>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 <br> - **Swapping LLM providers**: Switching LLM backends without application code change <br> - **Resilience**: Setting timeout, retry and circuit-breaking <br> - **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)<br>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 <br> - **Structured Outputs**: Converting LLM responses to Pydantic objects <br><br> *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)<br>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 <br> - **Agent Configuration**: Setting up agents with roles, goals, and tools <br> - **Function Calling**: Enabling LLMs to execute Python functions |
|
||||
| [Agentic Workflow](https://github.com/dapr/dapr-agents/tree/main/quickstarts/04-agentic-workflow)<br>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 <br> - **Task Chaining**: Creating resilient multi-step processes executing in sequence <br> - **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)<br>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 <br> - **Event-driven Architecture**: Implementing pub/sub messaging between agents <br> - **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)<br>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 <br> - **Container Orchestration**: Managing agent lifecycles with K8s <br> - **Service Communication**: Inter-agent communication in K8s |
|
||||
| [Agentic Workflow](https://github.com/dapr/dapr-agents/tree/main/quickstarts/04-llm-based-workflows)<br>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 <br> - **Task Chaining**: Creating resilient multi-step processes executing in sequence <br> - **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-workflows)<br>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 <br> - **Event-driven Architecture**: Implementing pub/sub messaging between agents <br> - **Workflow Orchestration**: Coordinating agents through different selection strategies|
|
||||
| [Multi-Agent Workflow on Kubernetes](https://github.com/dapr/dapr-agents/tree/main/quickstarts/05-multi-agent-workflow-k8s)<br>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 <br> - **Container Orchestration**: Managing agent lifecycles with K8s <br> - **Service Communication**: Inter-agent communication in K8s |
|
||||
| [Document Agent with Chainlit](https://github.com/dapr/dapr-agents/tree/main/quickstarts/06-document-agent-chainlit)<br>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 <br> - **Cloud Agnostic Storage**: Upload files to multiple storage providers <br> - **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)<br>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 <br> - **MCP Integration**: Connecting to databases without DB-specific code <br> - **Data Analysis**: Complex data analysis through conversation |
|
||||
|
|
|
|||
|
|
@ -6,8 +6,8 @@ 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 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.
|
||||
|
||||
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 agentic workflows powered by Dapr.
|
||||
|
||||
### Challenges with Existing Frameworks
|
||||
|
||||
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.
|
||||
|
|
@ -46,10 +46,10 @@ Dapr Agents places durability at the core of its architecture, leveraging [Dapr
|
|||
* **Durable Agent Execution**: DurableAgents are fundamentally workflow-backed, ensuring all LLM calls and tool executions remain durable, auditable, and resumable. Workflow checkpointing guarantees agents can recover from any point of failure while maintaining state consistency.
|
||||
* **Deterministic Multi-Agent Orchestration**: Workflows provide centralized control over task dependencies and coordination between multiple agents. Dapr's code-first workflow engine enables reliable orchestration of complex business processes while preserving agent autonomy where appropriate.
|
||||
|
||||
By integrating workflows as the foundational layer, Dapr Agents enables systems that combine the reliability of deterministic execution with the intelligence of LLM-powered agents, ensuring production-grade reliability and scalability.
|
||||
By integrating workflows as the foundational layer, Dapr Agents enables systems that combine the reliability of deterministic execution with the intelligence of LLM-powered agents, ensuring reliability and scalability.
|
||||
|
||||
{{% alert title="Note" color="info" %}}
|
||||
Workflows in Dapr Agents provide the foundation for building production-ready agentic systems that combine reliable execution with LLM-powered intelligence.
|
||||
Workflows in Dapr Agents provide the foundation for building durable agentic systems that combine reliable execution with LLM-powered intelligence.
|
||||
{{% /alert %}}
|
||||
|
||||
### Modular Component Model
|
||||
|
|
@ -61,7 +61,7 @@ Dapr Agents utilizes [Dapr's pluggable component framework]({{% ref components-c
|
|||
* **Seamless Transitions**: Develop locally with default configurations and deploy effortlessly to cloud environments by simply updating component definitions.
|
||||
|
||||
{{% alert title="Note" color="info" %}}
|
||||
Developers can easily switch between different components (e.g., Redis to DynamoDB, OpenAI, Anthropic) based on their deployment environment, ensuring portability and adaptability.
|
||||
Developers can easily switch between different components (e.g., Redis to DynamoDB, OpenAI to Anthropic) based on their deployment environment, ensuring portability and adaptability.
|
||||
{{% /alert %}}
|
||||
|
||||
### Message-Driven Communication
|
||||
|
|
|
|||
|
|
@ -85,17 +85,8 @@ Content-Length: 12
|
|||
|
||||
{{< /tabpane >}}
|
||||
|
||||
In this example, `My Message` is saved. It is not quoted because Dapr's API internally parse the JSON request
|
||||
object before saving it.
|
||||
|
||||
```JSON
|
||||
[
|
||||
{
|
||||
"key": "MyKey",
|
||||
"value": "My Message"
|
||||
}
|
||||
]
|
||||
```
|
||||
In this example, `My Message` is saved. It is not quoted because Dapr's API internally serializes the string before
|
||||
serving it.
|
||||
|
||||
## PubSub
|
||||
|
||||
|
|
@ -109,7 +100,9 @@ object before saving it.
|
|||
await client.PublishEventAsync("MyPubSubName", "TopicName", "My Message");
|
||||
```
|
||||
|
||||
The event is published and the content is serialized to `byte[]` and sent to Dapr sidecar. The subscriber receives it as a [CloudEvent](https://github.com/cloudevents/spec). Cloud event defines `data` as String. The Dapr SDK also provides a built-in deserializer for `CloudEvent` object.
|
||||
The event is published and the content is serialized to `byte[]` and sent to Dapr sidecar. The subscriber receives it
|
||||
as a [CloudEvent](https://github.com/cloudevents/spec). Cloud event defines `data` as string. The Dapr SDK also provides a built-in deserializer
|
||||
for the `CloudEvent` object.
|
||||
|
||||
```csharp
|
||||
public async Task<IActionResult> HandleMessage(string message)
|
||||
|
|
|
|||
|
|
@ -6,8 +6,8 @@ weight: 50000
|
|||
description: "Configure Scheduler to persist its database to make it resilient to restarts"
|
||||
---
|
||||
|
||||
The [Scheduler]({{% ref scheduler.md %}}) service is responsible for writing jobs to its embedded Etcd database and scheduling them for execution.
|
||||
By default, the Scheduler service database writes data to a Persistent Volume Claim volume of size `1Gb`, using the cluster's default [storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/).
|
||||
The [Scheduler]({{% ref scheduler.md %}}) service is responsible for writing jobs to its Etcd database and scheduling them for execution.
|
||||
By default, the Scheduler service database embeds Etcd and writes data to a Persistent Volume Claim volume of size `1Gb`, using the cluster's default [storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/).
|
||||
This means that there is no additional parameter required to run the scheduler service reliably on most Kubernetes deployments, although you will need [additional configuration](#storage-class) if a default StorageClass is not available or when running a production environment.
|
||||
|
||||
{{% alert title="Warning" color="warning" %}}
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ weight: 50000
|
|||
description: "Configure Scheduler to persist its database to make it resilient to restarts"
|
||||
---
|
||||
|
||||
The [Scheduler]({{% ref scheduler.md %}}) service is responsible for writing jobs to its embedded database and scheduling them for execution.
|
||||
The [Scheduler]({{% ref scheduler.md %}}) service is responsible for writing jobs to its Etcd database and scheduling them for execution.
|
||||
By default, the Scheduler service database writes this data to the local volume `dapr_scheduler`, meaning that **this data is persisted across restarts**.
|
||||
|
||||
The host file location for this local volume is typically located at either `/var/lib/docker/volumes/dapr_scheduler/_data` or `~/.local/share/containers/storage/volumes/dapr_scheduler/_data`, depending on your container runtime.
|
||||
|
|
|
|||
|
|
@ -134,6 +134,18 @@ In case you are invoking `mathService` on a different namespace, you can use the
|
|||
|
||||
In this URL, `testing` is the namespace that `mathService` is running in.
|
||||
|
||||
### Headers in Service Invocation Requests
|
||||
|
||||
When Dapr invokes a service, it automatically adds the following headers to the request:
|
||||
|
||||
| Header | Description | Example |
|
||||
|--------|-------------|---------|
|
||||
| `dapr-caller-app-id` | The ID of the calling application | `myapp` |
|
||||
| `dapr-caller-namespace` | The namespace of the calling application | `production` |
|
||||
| `dapr-callee-app-id` | The ID of the called application | `mathService` |
|
||||
|
||||
These headers are available in both HTTP and gRPC service invocation requests.
|
||||
|
||||
#### Non-Dapr Endpoint Example
|
||||
|
||||
If the `mathService` service was a non-Dapr application, then it could be invoked using service invocation via an `HTTPEndpoint`, as well as a Fully Qualified Domain Name (FQDN) URL.
|
||||
|
|
|
|||
|
|
@ -38,6 +38,8 @@ spec:
|
|||
value: "*****************"
|
||||
- name: direction
|
||||
value: "input, output"
|
||||
- name: endpoint
|
||||
value: "http://localhost:4566" # Optional: Custom endpoint (e.g. for LocalStack)
|
||||
```
|
||||
{{% alert title="Warning" color="warning" %}}
|
||||
The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described [here]({{% ref component-secrets.md %}}).
|
||||
|
|
@ -55,6 +57,8 @@ The above example uses secrets as plain strings. It is recommended to use a secr
|
|||
| `secretKey` | Y | Output | The AWS Secret Access Key to access this resource | `"secretAccessKey"` |
|
||||
| `sessionToken` | N | Output | The AWS session token to use | `"sessionToken"` |
|
||||
| `direction` | N | Input/Output | The direction of the binding | `"input"`, `"output"`, `"input, output"` |
|
||||
| `endpoint` | N | Input | Custom endpoint for Kinesis and DynamoDB (for example to enable AWS LocalStack support) | `"http://localhost:4566"` |
|
||||
|
||||
|
||||
{{% alert title="Important" color="warning" %}}
|
||||
When running the Dapr sidecar (daprd) with your application on EKS (AWS Kubernetes), if you're using a node/pod that has already been attached to an IAM policy defining access to AWS resources, you **must not** provide AWS access-key, secret-key, and tokens in the definition of the component spec you're using.
|
||||
|
|
|
|||
|
|
@ -34,6 +34,26 @@ The above example uses secrets as plain strings. It is recommended to use a secr
|
|||
| `model` | N | The Ollama LLM to use. Defaults to `llama3.2:latest`. | `phi4:latest` |
|
||||
| `cacheTTL` | N | A time-to-live value for a prompt cache to expire. Uses Golang duration format. | `10m` |
|
||||
|
||||
### OpenAI Compatibility
|
||||
|
||||
Ollama is compatible with [OpenAI's API](https://ollama.com/blog/openai-compatibility). You can use the OpenAI component with Ollama models with the following changes:
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: ollama-openai
|
||||
spec:
|
||||
type: conversation.openai # use the openai component type
|
||||
metadata:
|
||||
- name: key
|
||||
value: 'ollama' # just any non-empty string
|
||||
- name: model
|
||||
value: gpt-oss:20b # an ollama model (https://ollama.com/search) in this case openai open source model. See https://ollama.com/library/gpt-oss
|
||||
- name: endpoint
|
||||
value: 'http://localhost:11434/v1' # ollama endpoint
|
||||
```
|
||||
|
||||
## Related links
|
||||
|
||||
- [Conversation API overview]({{< ref conversation-overview.md >}})
|
||||
|
|
@ -86,6 +86,7 @@ The above example uses secrets as plain strings. It is recommended to use a secr
|
|||
| maxRetryBackoff | N | Maximum backoff between each retry. Defaults to `2` seconds; `"-1"` disables backoff. | `3000000000` |
|
||||
| failover | N | Enable failover configuration. Needs sentinelMasterName to be set. The redisHost should be the sentinel host address. See [Redis Sentinel Documentation](https://redis.io/docs/manual/sentinel/). Defaults to `"false"` | `"true"`, `"false"` |
|
||||
| sentinelMasterName | N | The sentinel master name. See [Redis Sentinel Documentation](https://redis.io/docs/manual/sentinel/) | `"mymaster"` |
|
||||
| sentinelPassword | N | Password for Redis Sentinel. No Default. Applicable only when “failover” is true, and Redis Sentinel has authentication enabled | `""`, `"KeFg23!"`
|
||||
| redeliverInterval | N | The interval between checking for pending messages for redelivery. Defaults to `"60s"`. `"0"` disables redelivery. | `"30s"` |
|
||||
| processingTimeout | N | The amount of time a message must be pending before attempting to redeliver it. Defaults to `"15s"`. `"0"` disables redelivery. | `"30s"` |
|
||||
| redisType | N | The type of redis. There are two valid values, one is `"node"` for single node mode, the other is `"cluster"` for redis cluster mode. Defaults to `"node"`. | `"cluster"` |
|
||||
|
|
@ -182,6 +183,19 @@ You can use [Helm](https://helm.sh/) to quickly create a Redis instance in our K
|
|||
{{< /tabpane >}}
|
||||
|
||||
|
||||
## Redis Sentinel behavior
|
||||
|
||||
Use `redisType: "node"` when connecting to Redis Sentinel. Additionally, set `failover` to `"true"` and `sentinelMasterName` to the name of the master node.
|
||||
|
||||
Failover characteristics:
|
||||
- Lock loss during failover: Locks may be lost during master failover if they weren't replicated to the promoted replica before the original master failed
|
||||
- Failover window: Brief server unavailability (typically seconds) during automatic master promotion
|
||||
- Consistency: All operations route to the current master, maintaining lock consistency
|
||||
|
||||
{{% alert title="Warning" color="warning" %}}
|
||||
Consider the trade-off of running Redis with high-availability and failover with the potential of lock loss during failover events. Your application should tolerate brief lock loss during failover scenarios.
|
||||
{{% /alert %}}
|
||||
|
||||
## Related links
|
||||
- [Basic schema for a Dapr component]({{% ref component-schema %}})
|
||||
- [Distributed lock building block]({{% ref distributed-lock-api-overview %}})
|
||||
|
|
|
|||
|
|
@ -36,6 +36,8 @@ spec:
|
|||
value: "authorization"
|
||||
- name: forceHTTPS
|
||||
value: "false"
|
||||
- name: pathFilter
|
||||
value: ".*/users/.*"
|
||||
```
|
||||
|
||||
{{% alert title="Warning" color="warning" %}}
|
||||
|
|
@ -54,6 +56,7 @@ The above example uses secrets as plain strings. It is recommended to use a secr
|
|||
| redirectURL | The URL of your web application that the authorization server should redirect to once the user has authenticated | `"https://myapp.com"`
|
||||
| authHeaderName | The authorization header name to forward to your application | `"authorization"`
|
||||
| forceHTTPS | If true, enforces the use of TLS/SSL | `"true"`,`"false"` |
|
||||
| pathFilter | Applies the middleware only to requests matching the given path pattern | `".*/users/.*"`
|
||||
|
||||
## Dapr configuration
|
||||
|
||||
|
|
@ -71,6 +74,67 @@ spec:
|
|||
type: middleware.http.oauth2
|
||||
```
|
||||
|
||||
## Request path filtering
|
||||
|
||||
The `pathFilter` field allows you to selectively apply OAuth2 authentication based on the HTTP request path using a regex pattern. This enables scenarios such as configuring multiple OAuth2 middlewares with different scopes for different API endpoints, implementing the least privilege principle by ensuring users only receive the minimum permissions necessary for their intended operation.
|
||||
|
||||
### Example: Separate read-only and admin user access
|
||||
In the following configuration:
|
||||
- Requests to `/api/users/*` endpoints receive tokens with a read-only user scopes
|
||||
- Requests to `/api/admin/*` endpoints receive tokens with full admin scopes
|
||||
|
||||
This reduces security risk by preventing unnecessary privilege access and limiting the blast radius of compromised tokens.
|
||||
```yaml
|
||||
# User with read-only access scope
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: oauth2-users
|
||||
spec:
|
||||
type: middleware.http.oauth2
|
||||
version: v1
|
||||
metadata:
|
||||
- name: clientId
|
||||
value: "<your client ID>"
|
||||
- name: clientSecret
|
||||
value: "<your client secret>"
|
||||
- name: scopes
|
||||
value: "user:read profile:read"
|
||||
- name: authURL
|
||||
value: "https://accounts.google.com/o/oauth2/v2/auth"
|
||||
- name: tokenURL
|
||||
value: "https://accounts.google.com/o/oauth2/token"
|
||||
- name: redirectURL
|
||||
value: "http://myapp.com/callback"
|
||||
- name: pathFilter
|
||||
value: "^/api/users/.*"
|
||||
---
|
||||
# User with full admin access scope
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: oauth2-admin
|
||||
spec:
|
||||
type: middleware.http.oauth2
|
||||
version: v1
|
||||
metadata:
|
||||
- name: clientId
|
||||
value: "<your client ID>"
|
||||
- name: clientSecret
|
||||
value: "<your client secret>"
|
||||
- name: scopes
|
||||
value: "admin:read admin:write user:read user:write"
|
||||
- name: authURL
|
||||
value: "https://accounts.google.com/o/oauth2/v2/auth"
|
||||
- name: tokenURL
|
||||
value: "https://accounts.google.com/o/oauth2/token"
|
||||
- name: redirectURL
|
||||
value: "http://myapp.com/callback"
|
||||
- name: pathFilter
|
||||
value: "^/api/admin/.*"
|
||||
```
|
||||
|
||||
|
||||
## Related links
|
||||
|
||||
- [Configure API authorization with OAuth]({{% ref oauth %}})
|
||||
|
|
|
|||
|
|
@ -30,6 +30,8 @@ spec:
|
|||
value: "https://accounts.google.com/o/oauth2/token"
|
||||
- name: headerName
|
||||
value: "authorization"
|
||||
- name: pathFilter
|
||||
value: ".*/users/.*"
|
||||
```
|
||||
|
||||
{{% alert title="Warning" color="warning" %}}
|
||||
|
|
@ -47,6 +49,7 @@ The above example uses secrets as plain strings. It is recommended to use a secr
|
|||
| headerName | The authorization header name to forward to your application | `"authorization"`
|
||||
| endpointParamsQuery | Specifies additional parameters for requests to the token endpoint | `true`
|
||||
| authStyle | Optionally specifies how the endpoint wants the client ID & client secret sent. See the table of possible values below | `0`
|
||||
| pathFilter | Applies the middleware only to requests matching the given path pattern | `".*/users/.*"`
|
||||
|
||||
### Possible values for `authStyle`
|
||||
|
||||
|
|
@ -72,6 +75,63 @@ spec:
|
|||
type: middleware.http.oauth2clientcredentials
|
||||
```
|
||||
|
||||
## Request path filtering
|
||||
|
||||
The `pathFilter` field allows you to selectively apply OAuth2 authentication based on the HTTP request path using a regex pattern. This enables scenarios such as configuring multiple OAuth2 middlewares with different scopes for different API endpoints, implementing the least privilege principle by ensuring users only receive the minimum permissions necessary for their intended operation.
|
||||
|
||||
### Example: Separate read-only and admin user access
|
||||
|
||||
In the following configuration:
|
||||
- Requests to `/api/users/*` endpoints receive tokens with a read-only user scopes
|
||||
- Requests to `/api/admin/*` endpoints receive tokens with full admin scopes
|
||||
This reduces security risk by preventing unnecessary privilege access and limiting the blast radius of compromised tokens.
|
||||
```yaml
|
||||
# User with read-only access scope
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: oauth2clientcredentials-users
|
||||
spec:
|
||||
type: middleware.http.oauth2clientcredentials
|
||||
version: v1
|
||||
metadata:
|
||||
- name: clientId
|
||||
value: "<your client ID>"
|
||||
- name: clientSecret
|
||||
value: "<your client secret>"
|
||||
- name: scopes
|
||||
value: "user:read profile:read"
|
||||
- name: tokenURL
|
||||
value: "https://accounts.google.com/o/oauth2/token"
|
||||
- name: headerName
|
||||
value: "authorization"
|
||||
- name: pathFilter
|
||||
value: "^/api/users/.*"
|
||||
---
|
||||
# User with full admin access scope
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: oauth2clientcredentials-admin
|
||||
spec:
|
||||
type: middleware.http.oauth2clientcredentials
|
||||
version: v1
|
||||
metadata:
|
||||
- name: clientId
|
||||
value: "<your client ID>"
|
||||
- name: clientSecret
|
||||
value: "<your client secret>"
|
||||
- name: scopes
|
||||
value: "admin:read admin:write user:read user:write"
|
||||
- name: tokenURL
|
||||
value: "https://accounts.google.com/o/oauth2/token"
|
||||
- name: headerName
|
||||
value: "authorization"
|
||||
- name: pathFilter
|
||||
value: "^/api/admin/.*"
|
||||
```
|
||||
|
||||
|
||||
## Related links
|
||||
- [Middleware]({{% ref middleware.md %}})
|
||||
- [Configuration concept]({{% ref configuration-concept.md %}})
|
||||
|
|
|
|||
|
|
@ -129,6 +129,7 @@ spec:
|
|||
| sessionTimeout | N | The timeout used to detect client failures when using Kafka’s group management facility. If the broker fails to receive any heartbeats from the consumer before the expiration of this session timeout, then the consumer is removed and initiates a rebalance. Defaults to "10s". | `"20s"` |
|
||||
| consumerGroupRebalanceStrategy | N | The strategy to use for consumer group rebalancing. Supported values: `range`, `sticky`, `roundrobin`. Default is `range` | `"sticky"` |
|
||||
| escapeHeaders | N | Enables URL escaping of the message header values received by the consumer. Allows receiving content with special characters that are usually not allowed in HTTP headers. Default is `false`. | `true` |
|
||||
| excludeHeaderMetaRegex | N | A regular expression to exclude keys from being converted from headers to metadata when consuming messages and from metadata to headers when publishing messages. This capability avoids unwanted downstream side effects for topic consumers. | '"^valueSchemaType$"`
|
||||
|
||||
The `secretKeyRef` above is referencing a [kubernetes secrets store]({{% ref kubernetes-secret-store.md %}}) to access the tls information. Visit [here]({{% ref setup-secret-store.md %}}) to learn more about how to configure a secret store component.
|
||||
|
||||
|
|
@ -677,11 +678,36 @@ def my_topic_subscriber(event_data=Body()):
|
|||
app.include_router(router)
|
||||
|
||||
```
|
||||
|
||||
{{% /tab %}}
|
||||
|
||||
{{< /tabpane >}}
|
||||
|
||||
### Avoiding downstream side effects when publishing messages requiring custom metadata
|
||||
Dapr allows customizing the publishing behavior by setting custom publish metadata.
|
||||
|
||||
For instance, to publish in avro format, it is required to set the `valueSchemaType=Avro` metadata.
|
||||
|
||||
However, by default these metadata items get converted to Kafka headers and published along with the message. This default behavior is very helpful for instance to forward tracing headers across a chain of publishers/consumers.
|
||||
|
||||
In certain scenario, however, it has unwanted side effects.
|
||||
Let's assume you consume an Avro message using Dapr with the headers above.If this message cannot be consumed successfully and configured to be sent to a dead letter topic, `valueSchemaType=Avro` will be automatically carried forward when publishing to the dead letter topic, requiring the set up of a schema associated with this topic. In many scenarios, it is preferable to publish dead letter messages in JSON only, as complying to a determined schema is not possible.
|
||||
|
||||
To avoid this behavior, the kafka-pubsub component can be configured to exclude certain metadata keys from being converted to/from headers.
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: kafka-pubsub-exclude-metadata
|
||||
type: pubsub.kafka
|
||||
version: v1
|
||||
metadata:
|
||||
- name: brokers # Required. Kafka broker connection setting
|
||||
value: "dapr-kafka.myapp.svc.cluster.local:9092"
|
||||
- name: authType # Required.
|
||||
value: "none"
|
||||
- name: excludeMetaHeaderRegex
|
||||
value: "^valueSchemaType$" # Optional. Excludes `valueSchemaType` header from being published to headers and converted to metadata
|
||||
```
|
||||
|
||||
### Overriding default consumer group rebalancing
|
||||
In Kafka, rebalancing strategies determine how partitions are assigned to consumers within a consumer group. The default strategy is "range", but "roundrobin" and "sticky" are also available.
|
||||
- `Range`:
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ spec:
|
|||
metadata:
|
||||
- name: region
|
||||
value: "[huaweicloud_region]"
|
||||
- name: accessKey
|
||||
- name: accessKey
|
||||
value: "[huaweicloud_access_key]"
|
||||
- name: secretAccessKey
|
||||
value: "[huaweicloud_secret_access_key]"
|
||||
|
|
|
|||
|
|
@ -0,0 +1,66 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Tencent Cloud Secrets Manager (SSM)"
|
||||
linkTitle: "Tencent Cloud Secrets Manager (SSM)"
|
||||
description: Detailed information on the Tencent Cloud Secrets Manager (SSM) - secret store component
|
||||
aliases:
|
||||
- "/operations/components/setup-secret-store/supported-secret-stores/tencentcloud-ssm/"
|
||||
---
|
||||
|
||||
## Component format
|
||||
|
||||
To setup Tencent Cloud Secrets Manager (SSM) secret store create a component of type `secretstores.tencentcloud.ssm`.
|
||||
See [this guide]({{% ref "setup-secret-store.md#apply-the-configuration" %}}) on how to create and apply a secretstore configuration.
|
||||
See this guide on [referencing secrets]({{% ref component-secrets.md %}}) to retrieve and use the secret with Dapr components.
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: tencentcloudssm
|
||||
spec:
|
||||
type: secretstores.tencentcloud.ssm
|
||||
version: v1
|
||||
metadata:
|
||||
- name: region
|
||||
value: "[tencentcloud_region]"
|
||||
- name: secretId
|
||||
value: "[tencentcloud_secret_id]"
|
||||
- name: secretKey
|
||||
value: "[tencentcloud_secret_key]"
|
||||
- name: token
|
||||
value: "[tencentcloud_secret_token]"
|
||||
```
|
||||
|
||||
{{% alert title="Warning" color="warning" %}}
|
||||
The above example uses secrets as plain strings.
|
||||
It is recommended to use a local secret store such as [Kubernetes secret store]({{% ref kubernetes-secret-store.md %}}) or a [local file]({{% ref file-secret-store.md %}}) to bootstrap secure key storage.
|
||||
{{% /alert %}}
|
||||
|
||||
## Spec metadata fields
|
||||
|
||||
| Field | Required | Details | Example |
|
||||
| --------------- | :------: | ---------------------------------------------------------------- | ------------------- |
|
||||
| region | Y | The specific region the Tencent SSM instance is deployed in | `"ap-beijing-3"` |
|
||||
| secretId | Y | The SecretId of the Tencent Cloud account | `"xyz"` |
|
||||
| secretKey | Y | The SecretKey of the Tencent Cloud account | `"xyz"` |
|
||||
| token | N | The Token of the Tencent Cloud account. This is required only if using temporary credentials | `""` |
|
||||
|
||||
## Optional per-request metadata properties
|
||||
|
||||
The following [optional query parameters]({{% ref "secrets_api#query-parameters" %}}) can be provided when retrieving secrets from this secret store:
|
||||
|
||||
Query Parameter | Description
|
||||
--------- | -----------
|
||||
`metadata.version_id` | Version for the given secret key.
|
||||
|
||||
## Setup Tencent Cloud Secrets Manager (SSM)
|
||||
|
||||
Setup Tencent Cloud Secrets Manager (SSM) using the Tencent Cloud documentation: https://www.tencentcloud.com/products/ssm
|
||||
|
||||
## Related links
|
||||
|
||||
- [Secrets building block]({{% ref secrets %}})
|
||||
- [How-To: Retrieve a secret]({{% ref "howto-secrets.md" %}})
|
||||
- [How-To: Reference secrets in Dapr components]({{% ref component-secrets.md %}})
|
||||
- [Secrets API reference]({{% ref secrets_api.md %}})
|
||||
|
|
@ -150,7 +150,7 @@
|
|||
features:
|
||||
input: false
|
||||
output: true
|
||||
- component: Twilio
|
||||
- component: Twilio SMS
|
||||
link: twilio
|
||||
state: Alpha
|
||||
version: v1
|
||||
|
|
@ -158,7 +158,7 @@
|
|||
features:
|
||||
input: false
|
||||
output: true
|
||||
- component: SendGrid
|
||||
- component: Twillio SendGrid
|
||||
link: sendgrid
|
||||
state: Alpha
|
||||
version: v1
|
||||
|
|
|
|||
|
|
@ -0,0 +1,5 @@
|
|||
- component: HuaweiCloud Cloud Secret Management Service (CSMS)
|
||||
link: huaweicloud-csms
|
||||
state: Alpha
|
||||
version: v1
|
||||
since: "1.8"
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
- component: Tencent Cloud Secrets Manager (SSM)
|
||||
link: tencentcloud-ssm
|
||||
state: Alpha
|
||||
version: v1
|
||||
since: "1.9"
|
||||
|
|
@ -1,9 +1,11 @@
|
|||
{{- $groups := dict
|
||||
" Generic" $.Site.Data.components.secret_stores.generic
|
||||
"Generic" $.Site.Data.components.secret_stores.generic
|
||||
"Microsoft Azure" $.Site.Data.components.secret_stores.azure
|
||||
"Alibaba Cloud" $.Site.Data.components.secret_stores.alibaba
|
||||
"Google Cloud Platform (GCP)" $.Site.Data.components.secret_stores.gcp
|
||||
"Amazon Web Services (AWS)" $.Site.Data.components.secret_stores.aws
|
||||
"Tencent Cloud" $.Site.Data.components.secret_stores.tencentcloud
|
||||
"HuaweiCloud Cloud" $.Site.Data.components.secret_stores.huaweicloud
|
||||
}}
|
||||
|
||||
<style>
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 78 KiB |
Loading…
Reference in New Issue