Upgrade all examples to MAF 1.0.0

Mechanical fixes across 102 English + Spanish example files:
- model_id= → model= in all OpenAIChatClient constructors
- Message(text=...) → Message(contents=[...])
- BaseContextProvider → ContextProvider
- BaseHistoryProvider → HistoryProvider

Additional fix for history provider examples:
- Removed tools from agent_history_redis.py and agent_history_sqlite.py
  to work around Responses API duplicate item ID issue with history
  providers (microsoft/agent-framework#3295)

Added manual test plan to AGENTS.md.

All examples verified with live LLM calls against Azure OpenAI.
Ran pre-commit (ruff lint + format).

Author: pamelafox

.github/prompts/update_translations.prompt.md

@@ -4,4 +4,4 @@ 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.
+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.

AGENTS.md

@@ -6,7 +6,7 @@ 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. 
+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
 
@@ -92,3 +92,94 @@ def _on_response_with_body(self, request, response):
 
 HttpLoggingPolicy.on_response = _on_response_with_body
 ```
+
+## Manual test plan
+
+After upgrading dependencies or making changes across examples, use this plan to verify everything works. Run each example with `uv run python examples/<file>.py`.
+
+### No extra setup (Azure OpenAI only)
+
+These work with just `API_HOST=azure` and the standard `.env` from `azd up`:
+
+| Examples | Notes |
+|----------|-------|
+| `agent_basic.py` | Interactive chat loop |
+| `agent_tool.py`, `agent_tools.py` | Tool calling |
+| `agent_session.py` | Session persistence |
+| `agent_with_subagent.py`, `agent_without_subagent.py` | Sub-agent patterns |
+| `agent_supervisor.py` | Supervisor pattern |
+| `agent_middleware.py` | Middleware pipeline |
+| `agent_summarization.py` | Summarization middleware |
+| `agent_tool_approval.py` | Tool approval |
+| `workflow_agents.py`, `workflow_agents_sequential.py`, `workflow_agents_concurrent.py`, `workflow_agents_streaming.py` | Basic workflows |
+| `workflow_conditional.py`, `workflow_conditional_state.py`, `workflow_conditional_state_isolated.py`, `workflow_conditional_structured.py` | Conditional workflows |
+| `workflow_switch_case.py` | Switch/case workflow |
+| `workflow_converge.py`, `workflow_fan_out_fan_in_edges.py` | Converge / fan-out patterns |
+| `workflow_aggregator_ranked.py`, `workflow_aggregator_structured.py`, `workflow_aggregator_summary.py`, `workflow_aggregator_voting.py` | Aggregator workflows |
+| `workflow_multi_selection_edge_group.py` | Multi-selection edges |
+| `workflow_handoffbuilder.py`, `workflow_handoffbuilder_rules.py` | Handoff builder |
+| `workflow_hitl_handoff.py`, `workflow_hitl_requests.py`, `workflow_hitl_requests_structured.py`, `workflow_hitl_tool_approval.py` | HITL workflows |
+| `workflow_hitl_checkpoint.py` | HITL with file-based checkpoints |
+| `agent_knowledge_sqlite.py` | SQLite knowledge provider |
+| `agent_history_sqlite.py` | SQLite history provider (no tools — see [agent-framework#3295](https://github.com/microsoft/agent-framework/issues/3295)) |
+| `agent_memory_mem0.py` | Mem0 memory provider |
+
+### Requires Redis (dev container)
+
+Redis runs automatically in the dev container at `redis://redis:6379`.
+
+| Examples | Notes |
+|----------|-------|
+| `agent_history_redis.py` | Redis history provider (no tools — see [agent-framework#3295](https://github.com/microsoft/agent-framework/issues/3295)) |
+| `agent_memory_redis.py` | Redis memory provider |
+
+### Requires PostgreSQL (dev container)
+
+PostgreSQL runs automatically in the dev container at `postgresql://admin:LocalPasswordOnly@db:5432/postgres`.
+
+| Examples | Notes |
+|----------|-------|
+| `agent_knowledge_pg.py` | PG + pgvector knowledge |
+| `agent_knowledge_pg_rewrite.py` | PG knowledge with query rewrite |
+| `agent_knowledge_postgres.py` | PG knowledge (alternative) |
+| `workflow_hitl_checkpoint_pg.py` | HITL with PG-backed checkpoints |
+
+### Requires Azure AI Search
+
+Needs `AZURE_SEARCH_ENDPOINT` and `AZURE_SEARCH_KNOWLEDGE_BASE_NAME` in `.env`.
+
+| Examples | Notes |
+|----------|-------|
+| `agent_knowledge_aisearch.py` | Azure AI Search knowledge base (agentic mode) |
+
+### Requires MCP server
+
+Start the MCP server first: `uv run python examples/mcp_server.py`
+
+| Examples | Notes |
+|----------|-------|
+| `agent_mcp_local.py` | Local MCP server (stdio) |
+| `agent_mcp_remote.py` | Remote MCP server (SSE) |
+
+### Requires OTel / Aspire
+
+| Examples | Notes |
+|----------|-------|
+| `agent_otel_aspire.py` | Aspire dashboard (runs in dev container at `http://aspire-dashboard:18888`) |
+| `agent_otel_appinsights.py` | Needs `APPLICATIONINSIGHTS_CONNECTION_STRING` in `.env` |
+
+### Slow-running examples (⏱ 2–10 minutes)
+
+These take significantly longer than other examples:
+
+| Examples | Notes |
+|----------|-------|
+| `agent_evaluation.py` | Runs agent + evaluators inline. ~2–3 min. |
+| `agent_evaluation_generate.py` | Generates eval data JSONL. ~2 min. |
+| `agent_evaluation_batch.py` | Batch evaluators on JSONL. ~3–5 min. Needs `eval_data.jsonl` from `agent_evaluation_generate.py`. |
+| `agent_redteam.py` | Red team attack simulation. ~5–10 min. |
+| `workflow_magenticone.py` | Multi-agent MagenticOne orchestration. ~2–5 min. |
+
+### Spanish examples
+
+Spanish files under `examples/spanish/` mirror the English examples exactly (same code, translated strings). After changes, spot-check 3–5 Spanish files to confirm they run correctly.

examples/agent_evaluation.py

@@ -298,9 +298,7 @@ async def main():
 
     intent_result = intent_evaluator(query=eval_query, response=eval_response, tool_definitions=tool_definitions)
     completeness_result = completeness_evaluator(response=response.text, ground_truth=ground_truth)
-    adherence_result = adherence_evaluator(
-        query=eval_query, response=eval_response, tool_definitions=tool_definitions
-    )
+    adherence_result = adherence_evaluator(query=eval_query, response=eval_response, tool_definitions=tool_definitions)
     tool_accuracy_result = tool_accuracy_evaluator(
         query=eval_query, response=eval_response, tool_definitions=tool_definitions
     )

examples/agent_evaluation_batch.py

@@ -13,6 +13,7 @@
 import os
 from pathlib import Path
 
+import rich
 from azure.ai.evaluation import (
     AzureOpenAIModelConfiguration,
     IntentResolutionEvaluator,
@@ -23,7 +24,6 @@
     evaluate,
 )
 from dotenv import load_dotenv
-import rich
 from rich.logging import RichHandler
 from rich.table import Table
 

examples/agent_evaluation_generate.py

@@ -16,7 +16,6 @@
 
 from agent_framework import Agent, tool
 from agent_framework.openai import OpenAIChatClient
-from azure.ai.evaluation import AzureOpenAIModelConfiguration, OpenAIModelConfiguration
 from azure.identity.aio import DefaultAzureCredential, get_bearer_token_provider
 from dotenv import load_dotenv
 from pydantic import Field

examples/agent_history_redis.py

@@ -99,8 +99,7 @@ async def main() -> None:
     except Exception as e:
         logger.error(f"Cannot connect to Redis at {REDIS_URL}: {e}")
         logger.error(
-            "Ensure Redis is running (e.g. via the dev container"
-            " or 'docker run -p 6379:6379 redis:7-alpine')."
+            "Ensure Redis is running (e.g. via the dev container" " or 'docker run -p 6379:6379 redis:7-alpine')."
         )
         return
     finally:

examples/agent_knowledge_aisearch.py

@@ -106,6 +106,7 @@
     context_providers=[search_provider],
 )
 
+
 async def main() -> None:
     """Demonstrate Azure AI Search RAG in a multi-turn conversation."""
     async with search_provider:

examples/agent_knowledge_pg.py

@@ -32,15 +32,14 @@
 from typing import Any
 
 import psycopg
-from openai import OpenAI
-from pgvector.psycopg import register_vector
-
 from agent_framework import Agent, AgentSession, ContextProvider, Message, SessionContext, SupportsAgentRun
 from agent_framework.openai import OpenAIChatClient
 from azure.identity import DefaultAzureCredential as SyncDefaultAzureCredential
 from azure.identity import get_bearer_token_provider as sync_get_bearer_token_provider
 from azure.identity.aio import DefaultAzureCredential, get_bearer_token_provider
 from dotenv import load_dotenv
+from openai import OpenAI
+from pgvector.psycopg import register_vector
 from rich import print
 from rich.logging import RichHandler
 
@@ -63,7 +62,9 @@
     async_token_provider = get_bearer_token_provider(async_credential, "https://cognitiveservices.azure.com/.default")
     # Sync credential for the OpenAI SDK embed client
     sync_credential = SyncDefaultAzureCredential()
-    sync_token_provider = sync_get_bearer_token_provider(sync_credential, "https://cognitiveservices.azure.com/.default")
+    sync_token_provider = sync_get_bearer_token_provider(
+        sync_credential, "https://cognitiveservices.azure.com/.default"
+    )
     chat_client = OpenAIChatClient(
         base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT']}/openai/v1/",
         api_key=async_token_provider,
@@ -196,9 +197,7 @@ def create_knowledge_db(conn: psycopg.Connection) -> None:
         """
     )
     # GIN index for full-text search on name + description
-    conn.execute(
-        "CREATE INDEX ON products USING GIN (to_tsvector('english', name || ' ' || description))"
-    )
+    conn.execute("CREATE INDEX ON products USING GIN (to_tsvector('english', name || ' ' || description))")
 
     logger.info("[📚 Knowledge] Generating embeddings for %d products...", len(PRODUCTS))
     for product in PRODUCTS:

examples/agent_knowledge_pg_rewrite.py

@@ -36,15 +36,14 @@
 from typing import Any
 
 import psycopg
-from openai import OpenAI
-from pgvector.psycopg import register_vector
-
 from agent_framework import Agent, AgentSession, ContextProvider, Message, SessionContext, SupportsAgentRun
 from agent_framework.openai import OpenAIChatClient
 from azure.identity import DefaultAzureCredential as SyncDefaultAzureCredential
 from azure.identity import get_bearer_token_provider as sync_get_bearer_token_provider
 from azure.identity.aio import DefaultAzureCredential, get_bearer_token_provider
 from dotenv import load_dotenv
+from openai import OpenAI
+from pgvector.psycopg import register_vector
 from rich import print
 from rich.logging import RichHandler
 
@@ -65,7 +64,9 @@
     async_credential = DefaultAzureCredential()
     async_token_provider = get_bearer_token_provider(async_credential, "https://cognitiveservices.azure.com/.default")
     sync_credential = SyncDefaultAzureCredential()
-    sync_token_provider = sync_get_bearer_token_provider(sync_credential, "https://cognitiveservices.azure.com/.default")
+    sync_token_provider = sync_get_bearer_token_provider(
+        sync_credential, "https://cognitiveservices.azure.com/.default"
+    )
     chat_client = OpenAIChatClient(
         base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT']}/openai/v1/",
         api_key=async_token_provider,
@@ -197,9 +198,7 @@ def create_knowledge_db(conn: psycopg.Connection) -> None:
         )
         """
     )
-    conn.execute(
-        "CREATE INDEX ON products USING GIN (to_tsvector('english', name || ' ' || description))"
-    )
+    conn.execute("CREATE INDEX ON products USING GIN (to_tsvector('english', name || ' ' || description))")
 
     logger.info("[📚 Knowledge] Generating embeddings for %d products...", len(PRODUCTS))
     for product in PRODUCTS:
@@ -290,9 +289,7 @@ async def _rewrite_query(self, conversation_messages: list[Message]) -> str:
             A concise, self-contained search query.
         """
         # Format conversation for the rewriter
-        conversation_text = "\n".join(
-            f"{msg.role}: {msg.text}" for msg in conversation_messages if msg.text
-        )
+        conversation_text = "\n".join(f"{msg.role}: {msg.text}" for msg in conversation_messages if msg.text)
 
         rewrite_messages = [
             Message(role="system", contents=[QUERY_REWRITE_PROMPT]),

examples/agent_knowledge_postgres.py

@@ -32,15 +32,14 @@
 from typing import Any
 
 import psycopg
-from openai import OpenAI
-from pgvector.psycopg import register_vector
-
 from agent_framework import Agent, AgentSession, ContextProvider, Message, SessionContext, SupportsAgentRun
 from agent_framework.openai import OpenAIChatClient
 from azure.identity import DefaultAzureCredential as SyncDefaultAzureCredential
 from azure.identity import get_bearer_token_provider as sync_get_bearer_token_provider
 from azure.identity.aio import DefaultAzureCredential, get_bearer_token_provider
 from dotenv import load_dotenv
+from openai import OpenAI
+from pgvector.psycopg import register_vector
 from rich import print
 from rich.logging import RichHandler
 
@@ -63,7 +62,9 @@
     async_token_provider = get_bearer_token_provider(async_credential, "https://cognitiveservices.azure.com/.default")
     # Sync credential for the OpenAI SDK embed client
     sync_credential = SyncDefaultAzureCredential()
-    sync_token_provider = sync_get_bearer_token_provider(sync_credential, "https://cognitiveservices.azure.com/.default")
+    sync_token_provider = sync_get_bearer_token_provider(
+        sync_credential, "https://cognitiveservices.azure.com/.default"
+    )
     chat_client = OpenAIChatClient(
         base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT']}/openai/v1/",
         api_key=async_token_provider,
@@ -196,9 +197,7 @@ def create_knowledge_db(conn: psycopg.Connection) -> None:
         """
     )
     # GIN index for full-text search on name + description
-    conn.execute(
-        "CREATE INDEX ON products USING GIN (to_tsvector('english', name || ' ' || description))"
-    )
+    conn.execute("CREATE INDEX ON products USING GIN (to_tsvector('english', name || ' ' || description))")
 
     logger.info("[📚 Knowledge] Generating embeddings for %d products...", len(PRODUCTS))
     for product in PRODUCTS:
@@ -297,7 +296,9 @@ async def before_run(
         state: dict[str, Any],
     ) -> None:
         """Search the knowledge base with the user's latest message and inject results."""
-        user_text = next((msg.text for msg in reversed(context.input_messages) if msg.role == "user" and msg.text), None)
+        user_text = next(
+            (msg.text for msg in reversed(context.input_messages) if msg.role == "user" and msg.text), None
+        )
         if not user_text:
             return