How dapr/dapr-agents works
Project Type and Purpose
• Dapr Agents is a framework rather than a traditional full-stack application. It is built to enable production-grade AI agent systems using the distributed capabilities of Dapr.
• The objective is to support scalable, durable agent workflows by abstracting actor-based interactions, messaging, state management, and integrations with various LLM providers as well as data sources.
File Structure
• Multiple top-level directories indicate modularity:
• The “dapr_agents” directory contains the core framework code. Within it, subdirectories such as agent, document, llm, memory, prompt, service, storage, tool, types, and workflow represent distinct modules.
• The “cookbook” directory holds notebooks and quick demos for different usage scenarios like agent patterns, multi-agent workflows, vectorstores, and more. This shows how the framework is applied in practice.
• The “quickstarts” directory includes sample projects demonstrating specific use cases (LLM calls, tool calling, agentic workflows, etc.), which is very useful for illustrating integration and data flows.
• Other directories (e.g., docs, .github) support documentation, continuous integration, and developer tooling.
Key Components
• Core Framework Modules:
• Agent Module: Represents the building blocks for creating AI agents. This includes actor patterns, interfaces for different agent types (react, toolcall, openapi, etc.).
• LLM & Prompt Modules: Integrate with multiple LLM providers (OpenAI, Azure, HuggingFace, Nvidia, Elevenlabs) and handle the various text and prompt processing capabilities.
• Workflow & State Management: Modules under workflow and memory implement durable workflows and stateful actor patterns using Dapr’s workflow engine and state stores.
• Document and Data Integration: Components for fetching, reading, splitting, and embedding documents enable data-driven agents.
• Storage/Graphstore/Vectorstore: These components connect to external databases and vector databases, reinforcing the data-driven aspect of the agents.
• Service Layer: Contains FastAPI integrations to allow external REST calls and service invocations with Dapr.
• Infrastructure Components:
• Dapr Sidecars: Since the system is built on Dapr, incorporate Dapr’s service invocation, pub/sub, state management, and bindings. These may be represented by Dapr APIs, state stores, and message brokers.
• External Systems: Show LLM providers (e.g., OpenAI, Azure, Nvidia, etc.), databases, document sources, and any external APIs integrated via bindings.
• Deployment & Operational Components:
• Kubernetes: Represent the possibility of running the system in a Kubernetes-native environment. Indicate how Dapr distributes agents and handles scaling.
• Resiliency & Observability: Include elements such as mTLS for secure communication, resiliency policies (timeouts, retries, circuit breakers), and observability components like logging and distributed tracing.
Relationships and Interactions
• From client or trigger input to the service layer (for initiating agent tasks).
• From service layer to the Dapr workflow orchestrator and agent actors.
• Between agents communicating via pub/sub and direct service invocations.
• Data flowing from agents to external systems (LLM APIs, document fetchers, etc.) and then responses back to agents.
• Interactions with state management, where agents persist intermediate state and retrieve it as needed.
Architectural Patterns to Emphasize
• Microservice Decomposition: Separation of concerns across different modules (agent behaviors, LLM interactions, storage, etc.).
• Actor Model: Highlight the agent implementation as self-contained actors that handle sequential messages.
• Durable & Resilient Workflow: Use a component to show the durable workflow engine which ensures reliable task execution.
• Event-Driven Communication: Illustrate the pub/sub messaging that enables loosely coupled multi-agent coordination.
• Extensibility: Point out modules for document processing, tool integrations, and optional components (e.g., MCP integration) as part of the extensibility of the framework.