Address PR review comments

- Fix docstring in workflow_hitl_tool_approval.py to match implementation
- Replace json.dumps with Jsonb adapter in workflow_hitl_checkpoint_pg.py
- Move WorkflowCheckpoint to public import path
- Translate tool docstrings to Spanish in spanish/ examples
- Translate 'goodbye' termination to Spanish in workflow_hitl_handoff.py
- Fix run command filename in workflow_hitl_requests.py
- Remove misleading 'exit' from prompts in workflow_hitl_requests_structured.py
- Update AGENTS.md to clarify @tool docstring translation rule

Author: pamelafox

AGENTS.md

@@ -32,10 +32,11 @@ Each example .py file should have a corresponding file with the same name under
 * 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
+* @tool function names: English
+* @tool parameter descriptions (Field(description=...)): English
+* @tool docstrings: Spanish
 * HITL control words: bilingual (approve/aprobar, exit/salir)
 * Agent and workflow names: English ("TravelPlannerAgent" should be the same in both versions, not "AgentePlanificadorDeViajes")
 

examples/spanish/agent_tool_approval.py

@@ -62,7 +62,7 @@
 def lookup_receipt(
     receipt_id: Annotated[str, "The receipt ID to look up"],
 ) -> dict[str, str]:
-    """Look up a receipt by ID and return its details."""
+    """Busca un recibo por ID y devuelve sus detalles."""
     return receipts_db.get(receipt_id, {"error": f"Recibo {receipt_id} no encontrado"})
 
 
@@ -72,7 +72,7 @@ def submit_expense_report(
     total_amount: Annotated[str, "Total amount to reimburse"],
     receipt_ids: Annotated[str, "Comma-separated receipt IDs included"],
 ) -> str:
-    """Submit an expense report for reimbursement. Requires manager approval."""
+    """Envía un reporte de gastos para reembolso. Requiere aprobación del gerente."""
     report = {"description": description, "total_amount": total_amount, "receipt_ids": receipt_ids}
     submitted_reports.append(report)
     return f"Reporte de gastos enviado: {description} por {total_amount} (recibos: {receipt_ids})"

examples/spanish/workflow_hitl_checkpoint_pg.py

@@ -9,12 +9,12 @@
 """
 
 import asyncio
-import json
 import os
 from dataclasses import dataclass
 from typing import Any
 
 import psycopg
+from psycopg.types.json import Jsonb
 from agent_framework import (
     Agent,
     AgentExecutor,
@@ -28,7 +28,10 @@
     handler,
     response_handler,
 )
-from agent_framework._workflows._checkpoint import WorkflowCheckpoint
+from agent_framework import WorkflowCheckpoint
+
+# Importación privada — aún no hay API pública para la codificación de checkpoints.
+# Ver: https://github.com/microsoft/agent-framework/issues/4428
 from agent_framework._workflows._checkpoint_encoding import decode_checkpoint_value, encode_checkpoint_value
 from agent_framework.exceptions import WorkflowCheckpointException
 from agent_framework.openai import OpenAIChatClient
@@ -79,7 +82,7 @@ async def save(self, checkpoint: WorkflowCheckpoint) -> str:
                    VALUES (%s, %s, %s, %s)
                    ON CONFLICT (id) DO UPDATE SET data = EXCLUDED.data""",
                 (checkpoint.checkpoint_id, checkpoint.workflow_name,
-                 checkpoint.timestamp, json.dumps(encoded)),
+                 checkpoint.timestamp, Jsonb(encoded)),
             )
         return checkpoint.checkpoint_id
 

examples/spanish/workflow_hitl_handoff.py

@@ -55,8 +55,8 @@ def process_return(
     order_number: Annotated[str, "The 3-digit order number"],
     return_type: Annotated[str, "Either 'refund' or 'replacement'"],
 ) -> str:
-    """Process a product return for the given order."""
-    return f"Return processed for order {order_number}: {return_type} approved. Confirmation email sent."
+    """Procesa una devolución de producto para el pedido indicado."""
+    return f"Devolución procesada para el pedido {order_number}: {return_type} aprobado. Correo de confirmación enviado."
 
 
 # --- Agentes ---
@@ -107,7 +107,8 @@ def process_return(
         name="customer_support",
         participants=[triage_agent, order_agent, return_agent],
         termination_condition=lambda conversation: (
-            len(conversation) > 0 and "goodbye" in conversation[-1].text.lower()
+            len(conversation) > 0
+            and any(word in conversation[-1].text.lower() for word in ("adiós", "adios", "chao"))
         ),
     )
     .with_start_agent(triage_agent)

examples/spanish/workflow_hitl_requests_structured.py

@@ -187,7 +187,7 @@ async def main() -> None:
 
         for request_id, request in pending.items():
             print(f"\n⏸️  El agente pregunta: {request.message}")
-            answer = input("💬 Tu respuesta (o 'exit/salir'): ")
+            answer = input("💬 Tu respuesta: ")
             pending[request_id] = answer
 
         stream = workflow.run(stream=True, responses=pending)

examples/spanish/workflow_hitl_tool_approval.py

@@ -1,7 +1,8 @@
 """Workflow de agente de correo con aprobación de herramientas para operaciones sensibles.
 
-Demuestra: @tool(approval_mode="always_require"), FunctionApprovalRequestContent,
-to_function_approval_response(), y un bucle de eventos que maneja solicitudes de aprobación.
+Demuestra: @tool(approval_mode="always_require"), verificación de tipo Content
+con data.type == "function_approval_request", to_function_approval_response(),
+y un bucle de eventos que maneja solicitudes de aprobación via get_request_info_events().
 
 Un agente de redacción de correos procesa correos entrantes y usa herramientas para
 buscar contexto y enviar respuestas. Herramientas como send_email y read_historical_email_data
@@ -65,13 +66,13 @@
 
 @tool(approval_mode="never_require")
 def get_current_date() -> str:
-    """Get the current date in YYYY-MM-DD format."""
+    """Obtiene la fecha actual en formato YYYY-MM-DD."""
     return "2026-03-05"
 
 
 @tool(approval_mode="never_require")
 def get_team_members_email_addresses() -> list[dict[str, str]]:
-    """Get the email addresses of team members."""
+    """Obtiene las direcciones de correo de los miembros del equipo."""
     return [
         {"name": "Alice", "email": "alice@contoso.com", "position": "Ingeniera de Software"},
         {"name": "Bob", "email": "bob@contoso.com", "position": "Gerente de Producto"},
@@ -85,7 +86,7 @@ async def read_historical_email_data(
     start_date: Annotated[str, "The start date in YYYY-MM-DD format"],
     end_date: Annotated[str, "The end date in YYYY-MM-DD format"],
 ) -> list[dict[str, str]]:
-    """Read historical email data for a given email address and date range."""
+    """Lee datos históricos de correo para una dirección y rango de fechas."""
     historical_data = {
         "alice@contoso.com": [
             {
@@ -119,7 +120,7 @@ async def send_email(
     subject: Annotated[str, "The email subject"],
     body: Annotated[str, "The email body"],
 ) -> str:
-    """Send an email."""
+    """Envía un correo electrónico."""
     await asyncio.sleep(0.5)  # Simula el envío
     return "Correo enviado exitosamente."
 

examples/workflow_hitl_checkpoint_pg.py

@@ -9,12 +9,12 @@
 """
 
 import asyncio
-import json
 import os
 from dataclasses import dataclass
 from typing import Any
 
 import psycopg
+from psycopg.types.json import Jsonb
 from agent_framework import (
     Agent,
     AgentExecutor,
@@ -28,7 +28,10 @@
     handler,
     response_handler,
 )
-from agent_framework._workflows._checkpoint import WorkflowCheckpoint
+from agent_framework import WorkflowCheckpoint
+
+# Private import — no public API for checkpoint encoding yet.
+# See: https://github.com/microsoft/agent-framework/issues/4428
 from agent_framework._workflows._checkpoint_encoding import decode_checkpoint_value, encode_checkpoint_value
 from agent_framework.exceptions import WorkflowCheckpointException
 from agent_framework.openai import OpenAIChatClient
@@ -79,7 +82,7 @@ async def save(self, checkpoint: WorkflowCheckpoint) -> str:
                    VALUES (%s, %s, %s, %s)
                    ON CONFLICT (id) DO UPDATE SET data = EXCLUDED.data""",
                 (checkpoint.checkpoint_id, checkpoint.workflow_name,
-                 checkpoint.timestamp, json.dumps(encoded)),
+                 checkpoint.timestamp, Jsonb(encoded)),
             )
         return checkpoint.checkpoint_id
 

examples/workflow_hitl_requests.py

@@ -8,7 +8,7 @@
 This is the minimal HITL pattern — every agent response triggers a human turn.
 
 Run:
-    uv run examples/workflow_hitl_chat.py
+    uv run examples/workflow_hitl_requests.py
 """
 
 import asyncio

examples/workflow_hitl_requests_structured.py

@@ -187,7 +187,7 @@ async def main() -> None:
 
         for request_id, request in pending.items():
             print(f"\n⏸️  Agent asks: {request.message}")
-            answer = input("💬 Your answer (or 'exit'): ")
+            answer = input("💬 Your answer: ")
             pending[request_id] = answer
 
         stream = workflow.run(stream=True, responses=pending)

examples/workflow_hitl_tool_approval.py

@@ -1,7 +1,8 @@
 """Email agent workflow with tool approval for sensitive operations.
 
-Demonstrates: @tool(approval_mode="always_require"), FunctionApprovalRequestContent,
-to_function_approval_response(), and an event loop that handles approval requests.
+Demonstrates: @tool(approval_mode="always_require"), Content type checking
+with data.type == "function_approval_request", to_function_approval_response(),
+and an event loop that handles approval requests via get_request_info_events().
 
 An email-writing agent processes incoming emails and uses tools to look up
 context and send replies. Tools like send_email and read_historical_email_data