Add dapr agents to 0 1.16

daprdocs/content/en/contributing/dapr-agents.md

@@ -0,0 +1,115 @@
+---
+type: docs
+title: "Contributing to Dapr agents"
+linkTitle: "Dapr agents"
+weight: 85
+description: Guidelines for contributing to Dapr agents
+---
+
+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:
+
+- 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.
+
+## Dependencies
+
+This project uses modern Python packaging with `pyproject.toml`. Dependencies are managed as follows:
+
+- Main dependencies are in `[project.dependencies]`
+- Test dependencies are in `[project.optional-dependencies.test]`
+- Development dependencies are in `[project.optional-dependencies.dev]`
+
+### Generating Requirements Files
+
+If you need to generate requirements files (e.g., for deployment or specific environments):
+
+```bash
+# Generate requirements.txt
+pip-compile pyproject.toml
+
+# Generate dev-requirements.txt
+pip-compile pyproject.toml --extra dev
+```
+
+### Installing Dependencies
+
+```bash
+# Install main package with test dependencies
+pip install -e ".[test]"
+
+# Install main package with development dependencies
+pip install -e ".[dev]"
+
+# Install main package with all optional dependencies
+pip install -e ".[test,dev]"
+```
+
+## Testing
+
+The project uses pytest for testing. To run tests:
+
+```bash
+# Run all tests
+tox -e pytest
+
+# Run specific test file
+tox -e pytest tests/test_random_orchestrator.py
+
+# Run tests with coverage
+tox -e pytest --cov=dapr_agents
+```
+
+## Code Quality
+
+The project uses several tools to maintain code quality:
+
+```bash
+# Run linting
+tox -e flake8
+
+# Run code formatting
+tox -e ruff
+
+# Run type checking
+tox -e type
+```
+
+## Development Workflow
+
+1. Install development dependencies:
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+2. Run tests before making changes:
+   ```bash
+   tox -e pytest
+   ```
+
+3. Make your changes
+
+4. Run code quality checks:
+   ```bash
+   tox -e flake8
+   tox -e ruff
+   tox -e type
+   ```
+
+5. Run tests again:
+   ```bash
+   tox -e pytest
+   ```
+
+6. Submit your changes
+
+## GitHub Dapr Bot Commands
+
+Checkout the [daprbot documentation]({{< ref "daprbot.md" >}}) for GitHub commands you can run in this repo for common tasks. For example, you can run the `/assign` (as a comment on an issue) to assign issues to a user or group of users.
+
+## Feedback
+
+Was this page helpful?

daprdocs/content/en/developing-applications/dapr-agents/_index.md

@@ -1 +1,12 @@
-# Dapr Agents
+---
+type: docs
+title: "Dapr Agents"
+linkTitle: "Dapr Agents"
+weight: 25
+description: "A framework for building production-grade resilient AI agent systems at scale"
+---
+
+###  What is Dapr Agents?
+
+Dapr Agents is a framework for building LLM-powered autonomous agentic applications using Dapr's distributed systems capabilities. It provides tools for creating AI agents that can execute tasks, make decisions, and collaborate through workflows, while leveraging Dapr's state management, messaging, and observability features for reliable execution at scale.
+

daprdocs/content/en/developing-applications/dapr-agents/dapr-agents-getting-started.md

@@ -0,0 +1,175 @@
+---
+type: docs
+title: "Getting Started"
+linkTitle: "Getting Started"
+weight: 20
+description: "How to install Dapr Agents and run your first agent"
+---
+
+{{% alert title="Dapr Agents Concepts" color="primary" %}}
+If you are looking for an introductory overview of Dapr Agents and want to learn more about basic Dapr Agents terminology, we recommend starting with the [introduction](dapr-agents-introduction.md) and [concepts](dapr-agents-core-concepts.md) sections.
+{{% /alert %}}
+
+## Install Dapr CLI
+
+While simple examples in Dapr Agents can be used without the sidecar, the recommended mode is with the Dapr sidecar. To benefit from the full power of Dapr Agents, install the Dapr CLI for running Dapr locally or on Kubernetes for development purposes. For a complete step-by-step guide, follow the  [Dapr CLI installation page](https://docs.dapr.io/getting-started/install-dapr-cli/).
+
+
+Verify the CLI is installed by restarting your terminal/command prompt and running the following:
+
+```bash
+dapr -h
+```
+
+## Initialize Dapr in Local Mode
+
+{{% alert title="Note" color="info" %}}
+Make sure you have [Docker](https://docs.docker.com/get-started/get-docker/) already installed.
+{{% /alert %}}
+
+Initialize Dapr locally to set up a self-hosted environment for development. This process fetches and installs the Dapr sidecar binaries, runs essential services as Docker containers, and prepares a default components folder for your application. For detailed steps, see the official [guide on initializing Dapr locally](https://docs.dapr.io/getting-started/install-dapr-selfhost/).
+
+![Dapr Initialization](/images/dapr-agents/home_installation_init.png)
+
+To initialize the Dapr control plane containers and create a default configuration file, run:
+
+```bash
+dapr init
+```
+
+Verify you have container instances with `daprio/dapr`, `openzipkin/zipkin`, and `redis` images running:
+
+```bash
+docker ps
+```
+
+## Install Python
+
+{{% alert title="Note" color="info" %}}
+Make sure you have Python already installed. `Python >=3.10`. For installation instructions, visit the official [Python installation guide](https://www.python.org/downloads/).
+{{% /alert %}}
+
+## Install Dapr Agents
+
+Install the Dapr Agents Python package using pip. For the latest version, check the [PyPI page](https://pypi.org/project/dapr-agents/).
+
+```bash
+pip install dapr-agents
+```
+
+## Create Your First Dapr Agent
+
+Let's create a weather assistant agent that demonstrates tool calling with Dapr state management used for conversation memory.
+
+### 1. Create the environment file
+
+Create a `.env` file with your OpenAI API key:
+
+```env
+OPENAI_API_KEY=your_api_key_here
+```
+
+This API key is essential for agents to communicate with the LLM, as the default LLM client in the agent uses OpenAI's services. If you don't have an API key, you can [create one here](https://platform.openai.com/api-keys).
+
+### 2. Create the Dapr component
+
+Create a `components` directory and add `historystore.yaml`:
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+  name: historystore
+spec:
+  type: state.redis
+  version: v1
+  metadata:
+  - name: redisHost
+    value: localhost:6379
+  - name: redisPassword
+    value: ""
+```
+
+This component will be used to store the conversation history, as LLMs are stateless and every chat interaction needs to send all the previous conversations to maintain context.
+
+### 3. Create the agent with weather tool
+
+Create `weather_agent.py`:
+
+```python
+import asyncio
+from dapr_agents import tool, Agent
+from dapr_agents.memory import ConversationDaprStateMemory
+from dotenv import load_dotenv
+
+load_dotenv()
+
+@tool
+def get_weather() -> str:
+    """Get current weather."""
+    return "It's 72°F and sunny"
+
+async def main():
+    agent = Agent(
+        name="WeatherAgent",
+        role="Weather Assistant",
+        instructions=["Help users with weather information"],
+        memory=ConversationDaprStateMemory(store_name="historystore", session_id="hello-world"),
+        tools=[get_weather],
+    )
+
+    # First interaction
+    response1 = await agent.run("Hi! My name is John. What's the weather?")
+    print(f"Agent: {response1}")
+
+    # Second interaction - agent should remember the name
+    response2 = await agent.run("What's my name?")
+    print(f"Agent: {response2}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+This code creates an agent with a single weather tool and uses Dapr for memory persistence. Notice how in the agent's responses, it remembers the user's name from the first chat interaction, demonstrating the conversation memory in action.
+
+### 4. Run with Dapr
+
+```bash
+dapr run --app-id weatheragent --resources-path ./components -- python weather_agent.py
+```
+
+This command starts a Dapr sidecar with the conversation component and launches the agent that communicates with the sidecar for state persistence.
+
+
+### 5. Enable Redis Insights (Optional)
+
+Dapr uses [Redis](https://docs.dapr.io/reference/components-reference/supported-state-stores/setup-redis/) by default for state management and pub/sub messaging, which are fundamental to Dapr Agents's agentic workflows. These capabilities enable the following:
+
+* Viewing Pub/Sub Messages: Monitor and inspect messages exchanged between agents in event-driven workflows.
+* Inspecting State Information: Access and analyze workflow state, conversation state, and other shared data among agents.
+* Debugging and Monitoring Events: Track workflow events in real time to ensure smooth operations and identify issues.
+
+To inspect the Redis instance, a great tool to use is Redis Insight, and you can use it to inspect the agent memory populated earlier.
+
+```bash
+docker run --rm -d --name redisinsight -p 5540:5540 redis/redisinsight:latest
+```
+
+Once running, access the Redis Insight interface at `http://localhost:5540/`
+Inside Redis Insight, you can connect to a Redis instance, so let's connect to the one used by the agent:
+
+* Port: 6379
+* Host (Linux): 172.17.0.1
+* Host (Windows/Mac): host.docker.internal (example `host.docker.internal:6379`)
+
+Redis Insight makes it easy to visualize and manage the data powering your agentic workflows, ensuring efficient debugging, monitoring, and optimization.
+
+![Redis Dashboard](/images/dapr-agents/home_installation_redis_dashboard.png)
+
+Here you can browse the state store used in the agent and explore its data.
+
+## Next Steps
+
+Now that you have Dapr Agents installed and running, explore more advanced examples and patterns in the [quickstarts](dapr-agents-quickstarts.md) section to learn about multi-agent workflows, durable agents, and integration with Dapr's powerful distributed capabilities.
+