Add observability quickstarts

quickstarts/01-hello-world-observability/01_agent_zipkin.py

@@ -0,0 +1,58 @@
+import asyncio
+from dapr_agents import tool, Agent
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+@tool
+def my_weather_func() -> str:
+    """Get current weather."""
+    return "It's 72°F and sunny"
+
+
+async def main():
+    weather_agent = Agent(
+        name="WeatherAgent",
+        role="Weather Assistant",
+        instructions=["Help users with weather information"],
+        tools=[my_weather_func],
+    )
+
+    from opentelemetry import trace
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+    from opentelemetry.exporter.zipkin.json import ZipkinExporter
+    from opentelemetry.sdk.resources import Resource
+    from dapr_agents.observability import DaprAgentsInstrumentor
+
+    # Define the service name using a Resource
+    resource = Resource(attributes={"service.name": "dapr-weather-agents"})
+
+    # Set up the OpenTelemetry TracerProvider with the resource
+    tracer_provider = TracerProvider(resource=resource)
+
+    # Configure the Zipkin exporter (no service_name argument here)
+    zipkin_exporter = ZipkinExporter(
+        endpoint="http://localhost:9411/api/v2/spans"  # default Zipkin endpoint
+    )
+
+    # Attach the exporter to the tracer provider
+    span_processor = BatchSpanProcessor(zipkin_exporter)
+    tracer_provider.add_span_processor(span_processor)
+
+    # Register the tracer provider globally
+    trace.set_tracer_provider(tracer_provider)
+
+    # Instrument Dapr Agents
+    instrumentor = DaprAgentsInstrumentor()
+    instrumentor.instrument(tracer_provider=tracer_provider, skip_dep_check=True)
+
+    # Run the agent
+    await weather_agent.run(
+        "What is the weather in Virginia, New York and Washington DC?"
+    )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

quickstarts/01-hello-world-observability/02_agent_otel.py

@@ -0,0 +1,56 @@
+import asyncio
+from dapr_agents import tool, Agent
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+@tool
+def my_weather_func() -> str:
+    """Get current weather."""
+    return "It's 72°F and sunny"
+
+
+async def main():
+    weather_agent = Agent(
+        name="WeatherAgent",
+        role="Weather Assistant",
+        instructions=["Help users with weather information"],
+        tools=[my_weather_func],
+    )
+
+    from opentelemetry import trace
+    from opentelemetry.sdk.resources import Resource
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+    from dapr_agents.observability import DaprAgentsInstrumentor
+
+    # Define the service name in the resource
+    resource = Resource(attributes={"service.name": "dapr-weather-agents"})
+
+    # Set up TracerProvider with resource
+    tracer_provider = TracerProvider(resource=resource)
+
+    # Set up OTLP exporter (in this example working with HTTP to send traces to Jaeger)
+    otlp_exporter = OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
+
+    # Set up span processor and add to tracer provider
+    span_processor = BatchSpanProcessor(otlp_exporter)
+    tracer_provider.add_span_processor(span_processor)
+
+    # Register tracer provider globally
+    trace.set_tracer_provider(tracer_provider)
+
+    # Instrument Dapr Agents
+    instrumentor = DaprAgentsInstrumentor()
+    instrumentor.instrument(tracer_provider=tracer_provider, skip_dep_check=True)
+
+    # Run the agent
+    await weather_agent.run(
+        "What is the weather in Virginia, New York and Washington DC?"
+    )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

quickstarts/01-hello-world-observability/README.md

@@ -0,0 +1,123 @@
+# Hello World with Dapr Agents and Tracing
+
+This quickstart provides a hands-on introduction to setting up full end-to-end tracing with Dapr Agents.
+
+## Prerequisites
+
+- Python 3.10 (recommended)
+- pip package manager
+- OpenAI API key
+- Zipkin
+- Jaeger
+
+## Environment Setup
+
+### Option 1: Using pip (Recommended)
+
+```bash
+# Create a virtual environment
+python3.10 -m venv .venv
+
+# Activate the virtual environment 
+# On Windows:
+.venv\Scripts\activate
+# On macOS/Linux:
+source .venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+```
+
+### Option 2: Using uv 
+
+```bash
+# Create and activate virtual environment
+uv venv .venv
+source .venv/bin/activate
+
+# Install core dependencies
+uv pip install -r requirements.txt
+```
+
+## Configuration
+
+Create a `.env` file in the project root:
+
+```env
+OPENAI_API_KEY=your_api_key_here
+```
+
+Replace `your_api_key_here` with your actual OpenAI API key.
+
+## Examples
+
+### 1. Simple Agent with Zipkin tracing
+
+In this example, we'll run a simple agent that uses Zipkin for distributed tracing.
+
+Run Zipkin locally:
+
+```bash
+docker run --rm -d -p 9411:9411 --name zipkin openzipkin/zipkin
+```
+
+Run the agent example to see how to create an agent with custom tools:
+
+<!-- STEP
+name: Run simple agent with tools example
+expected_stdout_lines:
+  - "user:"
+  - "What's the weather?"
+  - "assistant:"
+  - "Function name: MyWeatherFunc"
+  - "MyWeatherFunc(tool)"
+  - "It's 72°F and sunny"
+  - "assistant:"
+  - "The current weather is 72°F and sunny."
+timeout_seconds: 30
+output_match_mode: substring
+-->
+```bash
+python 01_agent_zipkin.py
+```
+<!-- END_STEP -->
+
+**Expected output:** Visit `http://localhost:9411` in your browser and view the traces.
+
+### 2. Simple Agent with OpenTelemetry tracing (Jaeger)
+
+In this example, we'll use Jaeger as the tracing backend with an HTTP `OTLPSpanExporter` generic span exporter.
+
+Run Jaeger locally:
+
+```bash
+docker run -d -e COLLECTOR_OTLP_ENABLED=true -p 4318:4318 -p 16686:16686 jaegertracing/all-in-one:latest
+```
+
+Run the agent example to see how to create an agent with custom tools:
+
+<!-- STEP
+name: Run simple agent with tools example
+expected_stdout_lines:
+  - "user:"
+  - "What's the weather?"
+  - "assistant:"
+  - "Function name: MyWeatherFunc"
+  - "MyWeatherFunc(tool)"
+  - "It's 72°F and sunny"
+  - "assistant:"
+  - "The current weather is 72°F and sunny."
+timeout_seconds: 30
+output_match_mode: substring
+-->
+```bash
+python 02_agent_otel.py
+```
+<!-- END_STEP -->
+
+**Expected output:** Visit `http://localhost:16686` in your browser and view the traces.
+
+## Next Steps
+
+After completing these examples, move on to the [LLM Call quickstart](../02_llm_call_open_ai/README.md) to learn more about structured outputs from LLMs.

quickstarts/01-hello-world-observability/requirements.txt

@@ -0,0 +1,7 @@
+dapr-agents>=0.8.0
+python-dotenv
+opentelemetry-sdk>=1.25.0
+opentelemetry-exporter-zipkin-json
+opentelemetry-exporter-otlp>=1.25.0
+opentelemetry-proto>=1.25.0
+protobuf>=4.22

quickstarts/01-hello-world/requirements.txt

@@ -1,2 +1,2 @@
-dapr-agents>=0.7.1
+dapr-agents>=0.8.0
 python-dotenv

quickstarts/02_llm_call_dapr/requirements.txt

@@ -1,2 +1,2 @@
-dapr-agents>=0.7.1
+dapr-agents>=0.8.0
 python-dotenv

quickstarts/02_llm_call_elevenlabs/requirements.txt

@@ -1,3 +1,3 @@
-dapr-agents>=0.7.1
+dapr-agents>=0.8.0
 python-dotenv
 elevenlabs

quickstarts/02_llm_call_hugging_face/requirements.txt

@@ -1 +1 @@
-dapr-agents>=0.7.1
+dapr-agents>=0.8.0

quickstarts/02_llm_call_nvidia/requirements.txt

@@ -1,3 +1,3 @@
-dapr-agents>=0.7.1
+dapr-agents>=0.8.0
 python-dotenv
 tiktoken

quickstarts/02_llm_call_open_ai/requirements.txt

@@ -1,3 +1,3 @@
-dapr-agents>=0.7.1
+dapr-agents>=0.8.0
 python-dotenv
 tiktoken

quickstarts/03-agent-tool-call/requirements.txt

@@ -1,4 +1,4 @@
-dapr-agents[observability]>=0.7.1
+dapr-agents[observability]>=0.8.0
 python-dotenv
 arize-phoenix
 arize-phoenix-otel

quickstarts/03-durable-agent-tool-call/requirements.txt

@@ -1,3 +1,3 @@
-dapr-agents>=0.7.1
+dapr-agents>=0.8.0
 python-dotenv
 arize-phoenix-otel

quickstarts/04-llm-based-workflows/requirements.txt

@@ -1,2 +1,2 @@
-dapr-agents>=0.7.1
+dapr-agents>=0.8.0
 python-dotenv

quickstarts/05-multi-agent-workflows/requirements.txt

@@ -1,2 +1,2 @@
-dapr-agents>=0.7.1
+dapr-agents>=0.8.0
 python-dotenv

quickstarts/06-document-agent-chainlit/requirements.txt

@@ -1,4 +1,4 @@
-dapr-agents>=0.7.1
+dapr-agents>=0.8.0
 python-dotenv
 requests
 chainlit

quickstarts/07-agent-mcp-client-sse/requirements.txt

@@ -1,4 +1,4 @@
-dapr-agents>=0.7.1
+dapr-agents>=0.8.0
 python-dotenv
 mcp
 starlette

quickstarts/07-agent-mcp-client-stdio/requirements.txt

@@ -1,3 +1,3 @@
-dapr-agents>=0.7.1
+dapr-agents>=0.8.0
 python-dotenv
 mcp 

quickstarts/07-agent-mcp-client-streamablehttp/requirements.txt

@@ -1,3 +1,3 @@
-dapr-agents>=0.7.1
+dapr-agents>=0.8.0
 python-dotenv
 mcp 

quickstarts/08-data-agent-mcp-chainlit/requirements.txt

@@ -1,4 +1,4 @@
-dapr-agents>=0.7.1
+dapr-agents>=0.8.0
 python-dotenv
 chainlit
 psycopg

quickstarts/09-agents-as-tasks-in-workflows/requirements.txt

@@ -1,3 +1,3 @@
-dapr-agents>=0.7.1
+dapr-agents>=0.8.0
 python-dotenv
 arize-phoenix