Merge pull request #7 from pamelafox/context-examples

Add context/memory examples and migrate to latest agent-framework API

Author: pamelafox

.devcontainer/Dockerfile

@@ -1,5 +1,8 @@
 FROM mcr.microsoft.com/devcontainers/python:3.12-bookworm
 
+# Required for cloning agent-framework from GitHub (it uses Git LFS)
+RUN apt-get update && apt-get install -y git-lfs && git lfs install && rm -rf /var/lib/apt/lists/*
+
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
 
 COPY pyproject.toml uv.lock /tmp/uv-tmp/

.devcontainer/devcontainer.json

@@ -2,9 +2,12 @@
     "name": "python-agentframework-demos",
     "dockerComposeFile": "docker-compose.yml",
     "service": "app",
-    "workspaceFolder": "/workspaces/python-agentframework-demos",
+    "workspaceFolder": "/workspace",
+    "forwardPorts": [5432, 6379, 18888],
     "features": {
-        "ghcr.io/azure/azure-dev/azd:latest": {}
+        "ghcr.io/azure/azure-dev/azd:latest": {},
+        "ghcr.io/devcontainers/features/azure-cli:latest": {},
+        "ghcr.io/devcontainers/features/github-cli:1": {}
     },
     "customizations": {
         "vscode": {

.devcontainer/docker-compose.yml

@@ -4,14 +4,38 @@ services:
       context: ..
       dockerfile: .devcontainer/Dockerfile
     volumes:
-      - ..:/workspaces/python-agentframework-demos:cached
+      - ..:/workspace:cached
     command: sleep infinity
     environment:
       - OTEL_EXPORTER_OTLP_ENDPOINT=http://aspire-dashboard:18889
+      - OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+      - REDIS_URL=redis://redis:6379
+      - POSTGRES_URL=postgresql://admin:LocalPasswordOnly@db:5432/postgres
+
+  db:
+    image: pgvector/pgvector:pg17
+    restart: unless-stopped
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    environment:
+      POSTGRES_DB: postgres
+      POSTGRES_USER: admin
+      POSTGRES_PASSWORD: LocalPasswordOnly
+    ports:
+      - "5433:5432"
+
+  redis:
+    image: redis/redis-stack-server:latest
+    restart: unless-stopped
+    ports:
+      - '6380:6379'
 
   aspire-dashboard:
     image: mcr.microsoft.com/dotnet/aspire-dashboard:latest
     ports:
       - "18888:18888"
     environment:
       - DASHBOARD__FRONTEND__AUTHMODE=Unsecured
+
+volumes:
+  postgres-data:

.env.sample

@@ -9,8 +9,16 @@ OPENAI_MODEL=gpt-3.5-turbo
 # Configure for GitHub models: (GITHUB_TOKEN already exists inside Codespaces)
 GITHUB_MODEL=gpt-5-mini
 GITHUB_TOKEN=YOUR-GITHUB-PERSONAL-ACCESS-TOKEN
+# Configure for Redis (used by agent_history_redis.py, defaults to dev container Redis):
+REDIS_URL=redis://localhost:6379
 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+# Or use console exporters instead of OTLP:
+# ENABLE_CONSOLE_EXPORTERS=true
 # Optional: Set to export telemetry to Azure Application Insights
 APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=YOUR-KEY;IngestionEndpoint=https://YOUR-REGION.in.applicationinsights.azure.com/
+# Configure for Azure AI Search (used by agent_knowledge_aisearch.py):
+AZURE_SEARCH_ENDPOINT=https://YOUR-SEARCH-SERVICE.search.windows.net
+AZURE_SEARCH_KNOWLEDGE_BASE_NAME=YOUR-KB-NAME
 # Optional: Set to log evaluation results to Azure AI Foundry for rich visualization
 AZURE_AI_PROJECT=https://YOUR-ACCOUNT.services.ai.azure.com/api/projects/YOUR-PROJECT

.github/prompts/review_slides.prompt.md

@@ -0,0 +1,10 @@
+---
+name: review_slides
+description: Use this to review slides for accuracy
+---
+Review the given slides for consistency with the code samples in the repository.
+
+Use the markitdown skill to convert the PDF to markdown first.
+
+Point out any errors, inconsistencies, or areas that may need clarification. Provide specific feedback on how to improve the slides to better align with the code and concepts presented in the repository.
+Make sure all URLs/filenames are valid.

.github/prompts/update_translations.prompt.md

@@ -0,0 +1,7 @@
+---
+name: update_translations
+description: Use this prompt to update the Spanish translations in the repo.
+model: GPT-5.2 (copilot)
+---
+
+Update the Spanish translations in the repo according to the guidelines in AGENTS.md. Ensure there are spanish equivalents of each english example. Make sure to keep the translations consistent with the original content and maintain the technical accuracy of the code.

.github/skills/pdf-to-markdown/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: pdf-to-markdown
+description: Converts PDF files to Markdown using Microsoft's markitdown package. Use this skill when the user asks to convert a PDF to Markdown, extract text from a PDF, or read/parse PDF content.
+argument-hint: "[path to file]"
+---
+
+# PDF to Markdown Conversion
+
+This skill converts PDF files to Markdown format using [Microsoft's markitdown](https://github.com/microsoft/markitdown) package.
+
+## When to use
+
+- User asks to convert a PDF to Markdown
+- User wants to extract text content from a PDF
+- User needs to read or parse a PDF document
+- User asks to summarize or analyze a PDF file
+
+## How to use
+
+Use `uvx` to run markitdown directly. Pick the dependency group matching the file type:
+
+| File type | Dependency group |
+|-----------|-----------------|
+| PDF       | `pdf`           |
+| PowerPoint | `pptx`         |
+| Word      | `docx`          |
+| Excel (.xlsx) | `xlsx`      |
+| Excel (.xls)  | `xls`       |
+
+```bash
+uvx 'markitdown[pdf]' <path-to-file> -o output.md
+```
+
+Or install all optional dependencies at once:
+
+```bash
+uvx 'markitdown[all]' <path-to-file> -o output.md
+```
+
+## Examples
+
+```bash
+uvx 'markitdown[pdf]' report.pdf -o report.md
+uvx 'markitdown[pptx]' slides.pptx -o slides.md
+uvx 'markitdown[docx]' document.docx -o document.md
+```
+
+## Output
+
+- If you were asked to save the output to a specific file, save it to the requested file using `-o`.
+- If no output file was specified, use the source filename with a `.md` suffix.

.gitignore

@@ -147,3 +147,8 @@ node_modules
 static/
 
 .DS_Store
+*.sqlite3
+
+# Red team scan results (may contain sensitive/graphic content)
+redteam_results.json/
+.scan_*/

AGENTS.md

@@ -0,0 +1,92 @@
+# Instructions for coding agents
+
+This repository contains many examples of using the Microsoft Agent Framework in Python (agent-framework), sometimes abbreviated as MAF.
+
+The agent-framework GitHub repo is here:
+https://github.com/microsoft/agent-framework
+It contains both Python and .NET agent framework code, but we are only using the Python packages in this repo.
+
+MAF is changing rapidly still, so we sometimes need to check the repo changelog and issues to see if there are any breaking changes that might affect our code. 
+The Python changelog is here:
+https://github.com/microsoft/agent-framework/blob/main/python/CHANGELOG.md
+
+MAF documentation is available on Microsoft Learn here:
+https://learn.microsoft.com/agent-framework/
+When available, the MS Learn MCP server can be used to explore the documentation, ask questions, and get code examples.
+
+## Package management
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management. Use `uv` commands instead of `pip`:
+
+```bash
+uv add <package>
+uv sync
+```
+
+## Spanish translations
+
+There are Spanish equivalents of each example in /examples/spanish.
+
+Each example .py file should have a corresponding file with the same name under /examples/spanish/ that is the translation of the original, but with the same code. Here's a guide on what should be translated vs. what should be left in English:
+
+* Comments: Spanish
+* Docstrings: Spanish
+* System prompts (agent instructions): Spanish
+* Tool descriptions (metadata like description=): English
+* Parameter descriptions (Field(description=...)): English
+* Identifiers (functions/classes/vars): English
+* User-facing output/data (e.g., example responses, sample values): Spanish
+* HITL control words: bilingual (approve/aprobar, exit/salir)
+
+Use informal (tuteo) LATAM Spanish, tu not usted, puedes not podes, etc. The content is technical so if a word is best kept in English, then do so.
+
+The /examples/spanish/README.md corresponds to the root README.md and should be kept in sync with it, but translated to Spanish.
+
+## Debugging Azure Python SDK HTTP requests
+
+When debugging HTTP interactions between Azure Python SDKs (like `azure-ai-evaluation`) and Azure services, there are three levels of logging you can enable:
+
+### 1. Azure SDK logger (request headers and URLs)
+
+Set the Azure SDK loggers to DEBUG level to see request URLs, headers, and status codes:
+
+```python
+import logging
+
+logging.basicConfig(level=logging.WARNING)
+logging.getLogger("azure").setLevel(logging.DEBUG)
+logging.getLogger("azure.core.pipeline.policies.http_logging_policy").setLevel(logging.DEBUG)
+```
+
+### 2. Raw HTTP wire data (request/response headers)
+
+Enable `http.client` debug logging to see the raw HTTP wire protocol, including request and response headers:
+
+```python
+import http.client
+http.client.HTTPConnection.debuglevel = 1
+```
+
+Note: Response bodies will typically not be visible at this level because Azure SDKs use gzip compression, and `http.client` logs the raw compressed bytes.
+
+### 3. Decompressed response bodies
+
+To see actual response bodies, monkey-patch the Azure SDK's `HttpLoggingPolicy.on_response` method. This works because `response.http_response.body()` returns the decompressed content:
+
+```python
+from azure.core.pipeline.policies import HttpLoggingPolicy
+
+_original_on_response = HttpLoggingPolicy.on_response
+
+def _on_response_with_body(self, request, response):
+    _original_on_response(self, request, response)
+    try:
+        body = response.http_response.body()
+        if body:
+            _logger = logging.getLogger("azure.core.pipeline.policies.http_logging_policy")
+            _logger.debug("Response body: %s", body[:4096].decode("utf-8", errors="replace"))
+    except Exception:
+        pass
+
+HttpLoggingPolicy.on_response = _on_response_with_body
+```

README.md

@@ -58,6 +58,8 @@ A related option is VS Code Dev Containers, which will open the project in your
 3. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window.
 4. Continue with the steps to run the examples
 
+The dev container includes a Redis server, which is used by the `agent_history_redis.py` example.
+
 ### Local environment
 
 1. Make sure the following tools are installed:
@@ -79,6 +81,18 @@ A related option is VS Code Dev Containers, which will open the project in your
     uv sync
     ```
 
+4. *Optional:* To run the `agent_history_redis.py` example, you need a Redis server running locally:
+
+    ```shell
+    docker run -d -p 6379:6379 redis:7-alpine
+    ```
+
+5. *Optional:* To run the PostgreSQL examples (`agent_knowledge_postgres.py`, `agent_knowledge_pg.py`, `agent_knowledge_pg_rewrite.py`), you need PostgreSQL with pgvector running locally:
+
+    ```shell
+    docker run -d -p 5432:5432 -e POSTGRES_USER=admin -e POSTGRES_PASSWORD=LocalPasswordOnly pgvector/pgvector:pg17
+    ```
+
 ## Configuring model providers
 
 These examples can be run with Azure AI Foundry, OpenAI.com, or GitHub Models, depending on the environment variables you set. All the scripts reference the environment variables from a `.env` file, and an example `.env.sample` file is provided. Host-specific instructions are below.
@@ -125,6 +139,12 @@ This project includes infrastructure as code (IaC) to provision Azure OpenAI dep
     azd auth login --use-device-code
     ```
 
+    If you are using a tenant besides the default tenant, you may need to also login with Azure CLI to that tenant:
+
+    ```shell
+    az login --tenant your-tenant-id
+    ```
+
 3. Provision the OpenAI account:
 
     ```shell
@@ -165,17 +185,22 @@ You can run the examples in this repository by executing the scripts in the `exa
 | [agent_basic.py](examples/agent_basic.py) | A basic informational agent. |
 | [agent_tool.py](examples/agent_tool.py) | An agent with a single weather tool. |
 | [agent_tools.py](examples/agent_tools.py) | A weekend planning agent with multiple tools. |
+| [agent_session.py](examples/agent_session.py) | In-memory sessions for multi-turn conversations with memory across messages. |
+| [agent_history_redis.py](examples/agent_history_redis.py) | Persistent chat history with Redis for conversation history that survives restarts. |
 | [agent_supervisor.py](examples/agent_supervisor.py) | A supervisor orchestrating activity and recipe sub-agents. |
 | [workflow_magenticone.py](examples/workflow_magenticone.py) | A MagenticOne multi-agent workflow. |
 | [workflow_hitl.py](examples/workflow_hitl.py) | Human-in-the-loop (HITL) for tool-enabled agents with human feedback. |
 | [agent_middleware.py](examples/agent_middleware.py) | Agent, chat, and function middleware for logging, timing, and blocking. |
+| [agent_knowledge_sqlite.py](examples/agent_knowledge_sqlite.py) | Knowledge retrieval (RAG) using a custom context provider with SQLite FTS5. |
+| [agent_knowledge_postgres.py](examples/agent_knowledge_postgres.py) | Knowledge retrieval (RAG) with PostgreSQL hybrid search (pgvector + full-text) using Reciprocal Rank Fusion. |
 | [agent_mcp_remote.py](examples/agent_mcp_remote.py) | An agent using a remote MCP server (Microsoft Learn) for documentation search. |
 | [agent_mcp_local.py](examples/agent_mcp_local.py) | An agent connected to a local MCP server (e.g. for expense logging). |
 | [openai_tool_calling.py](examples/openai_tool_calling.py) | Tool calling with the low-level OpenAI SDK, showing manual tool dispatch. |
 | [workflow_basic.py](examples/workflow_basic.py) | A workflow-based agent. |
 | [agent_otel_aspire.py](examples/agent_otel_aspire.py) | An agent with OpenTelemetry tracing, metrics, and structured logs exported to the [Aspire Dashboard](https://aspire.dev/dashboard/standalone/). |
 | [agent_otel_appinsights.py](examples/agent_otel_appinsights.py) | An agent with OpenTelemetry tracing, metrics, and structured logs exported to [Azure Application Insights](https://learn.microsoft.com/azure/azure-monitor/app/app-insights-overview). Requires Azure provisioning via `azd provision`. |
 | [agent_evaluation.py](examples/agent_evaluation.py) | Evaluate a travel planner agent using [Azure AI Evaluation](https://learn.microsoft.com/azure/ai-foundry/concepts/evaluation-evaluators/agent-evaluators) agent evaluators (IntentResolution, ToolCallAccuracy, TaskAdherence, ResponseCompleteness). Optionally set `AZURE_AI_PROJECT` in `.env` to log results to [Azure AI Foundry](https://learn.microsoft.com/azure/ai-foundry/how-to/develop/agent-evaluate-sdk). |
+| [agent_redteam.py](examples/agent_redteam.py) | Red-team a financial advisor agent using [Azure AI Evaluation](https://learn.microsoft.com/azure/ai-foundry/how-to/develop/red-teaming-agent) to test resilience against adversarial attacks across risk categories (Violence, HateUnfairness, Sexual, SelfHarm). Requires `AZURE_AI_PROJECT` in `.env`. |
 
 ## Using the Aspire Dashboard for telemetry
 
@@ -190,7 +215,7 @@ The Aspire Dashboard runs automatically as a service alongside the dev container
 2. Run the example:
 
     ```sh
-    uv run agent_otel_aspire.py
+    uv run examples/agent_otel_aspire.py
     ```
 
 3. Open the dashboard at <http://localhost:18888> and explore: