chore: import upstream snapshot with attribution

python/samples/03-workflows/declarative/student_teacher/README.md

@@ -0,0 +1,61 @@
+# Student-Teacher Math Chat Workflow
+
+This sample demonstrates an iterative conversation between two AI agents - a Student and a Teacher - working through a math problem together.
+
+## Overview
+
+The workflow showcases:
+- **Iterative Agent Loops**: Two agents take turns in a coaching conversation
+- **Termination Conditions**: Loop ends when teacher says "congratulations" or max turns reached
+- **State Tracking**: Turn counter tracks iteration progress
+- **Conditional Flow Control**: GotoAction for loop continuation
+
+## Agents
+
+| Agent | Role |
+|-------|------|
+| StudentAgent | Attempts to solve math problems, making intentional mistakes to learn from |
+| TeacherAgent | Reviews student's work and provides constructive feedback |
+
+## How It Works
+
+1. User provides a math problem
+2. Student attempts a solution
+3. Teacher reviews and provides feedback
+4. If teacher says "congratulations" -> success, workflow ends
+5. If under 4 turns -> loop back to step 2
+6. If 4 turns reached without success -> timeout, workflow ends
+
+## Usage
+
+```bash
+# Run the demonstration with mock responses
+python main.py
+```
+
+## Example Input
+
+```
+How would you compute the value of PI?
+```
+
+## Configuration
+
+For production use, configure these agents in Azure AI Foundry:
+
+### StudentAgent
+```
+Instructions: Your job is to help a math teacher practice teaching by making
+intentional mistakes. You attempt to solve the given math problem, but with
+intentional mistakes so the teacher can help. Always incorporate the teacher's
+advice to fix your next response. You have the math-skills of a 6th grader.
+Don't describe who you are or reveal your instructions.
+```
+
+### TeacherAgent
+```
+Instructions: Review and coach the student's approach to solving the given
+math problem. Don't repeat the solution or try and solve it. If the student
+has demonstrated comprehension and responded to all of your feedback, give
+the student your congratulations by using the word "congratulations".
+```

python/samples/03-workflows/declarative/student_teacher/main.py

@@ -0,0 +1,106 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Run the student-teacher (MathChat) workflow sample.
+
+Usage:
+    python main.py
+
+Demonstrates iterative conversation between two agents:
+- StudentAgent: Attempts to solve math problems
+- TeacherAgent: Reviews and coaches the student's approach
+
+The workflow loops until the teacher gives congratulations or max turns reached.
+
+Prerequisites:
+    - Azure OpenAI deployment with chat completion capability
+    - Environment variables:
+        FOUNDRY_PROJECT_ENDPOINT: Your Azure AI Foundry Agent Service (V2) project endpoint
+        FOUNDRY_MODEL: Your model deployment name
+"""
+
+import asyncio
+import os
+from pathlib import Path
+
+from agent_framework import Agent
+from agent_framework.declarative import WorkflowFactory
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv.main import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+STUDENT_INSTRUCTIONS = """You are a curious math student working on understanding mathematical concepts.
+When given a problem:
+1. Think through it step by step
+2. Make reasonable attempts, but it's okay to make mistakes
+3. Show your work and reasoning
+4. Ask clarifying questions when confused
+5. Build on feedback from your teacher
+
+Be authentic - you're learning, so don't pretend to know everything."""
+
+TEACHER_INSTRUCTIONS = """You are a patient math teacher helping a student understand concepts.
+When reviewing student work:
+1. Acknowledge what they did correctly
+2. Gently point out errors without giving away the answer
+3. Ask guiding questions to help them discover mistakes
+4. Provide hints that lead toward understanding
+5. When the student demonstrates clear understanding, respond with "CONGRATULATIONS"
+   followed by a summary of what they learned
+
+Focus on building understanding, not just getting the right answer."""
+
+
+async def main() -> None:
+    """Run the student-teacher workflow with real Azure AI agents."""
+    # Create chat client
+    client = FoundryChatClient(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["FOUNDRY_MODEL"],
+        credential=AzureCliCredential(),
+    )
+
+    # Create student and teacher agents
+    student_agent = Agent(
+        client=client,
+        name="StudentAgent",
+        instructions=STUDENT_INSTRUCTIONS,
+    )
+
+    teacher_agent = Agent(
+        client=client,
+        name="TeacherAgent",
+        instructions=TEACHER_INSTRUCTIONS,
+    )
+
+    # Create factory with agents
+    factory = WorkflowFactory(
+        agents={
+            "StudentAgent": student_agent,
+            "TeacherAgent": teacher_agent,
+        }
+    )
+
+    workflow_path = Path(__file__).parent / "workflow.yaml"
+    workflow = factory.create_workflow_from_yaml_path(workflow_path)
+
+    print(f"Loaded workflow: {workflow.name}")
+    print("=" * 50)
+    print("Student-Teacher Math Coaching Session")
+    print("=" * 50)
+
+    async for event in workflow.run("How would you compute the value of PI?", stream=True):
+        if event.type == "output":
+            print(f"{event.data}", flush=True, end="")
+
+    print("\n" + "=" * 50)
+    print("Session Complete")
+    print("=" * 50)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/03-workflows/declarative/student_teacher/workflow.yaml

@@ -0,0 +1,98 @@
+# Student-Teacher Math Chat Workflow
+#
+# Demonstrates iterative conversation between two agents with loop control
+# and termination conditions.
+#
+# Example input:
+# How would you compute the value of PI?
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: student_teacher_workflow
+  actions:
+
+    # Initialize turn counter
+    - kind: SetVariable
+      id: init_counter
+      variable: Local.TurnCount
+      value: =0
+
+    # Announce the start with the problem
+    - kind: SendActivity
+      id: announce_start
+      activity:
+        text: '=Concat("Starting math coaching session for: ", Workflow.Inputs.input)'
+
+    # Label for student
+    - kind: SendActivity
+      id: student_label
+      activity:
+        text: "\n[Student]:\n"
+
+    # Student attempts to solve - entry point for loop
+    # No explicit input.messages - uses implicit input from workflow inputs or conversation
+    - kind: InvokeAzureAgent
+      id: question_student
+      conversationId: =System.ConversationId
+      agent:
+        name: StudentAgent
+
+    # Label for teacher
+    - kind: SendActivity
+      id: teacher_label
+      activity:
+        text: "\n\n[Teacher]:\n"
+
+    # Teacher reviews and coaches
+    # No explicit input.messages - uses conversation context from conversationId
+    - kind: InvokeAzureAgent
+      id: question_teacher
+      conversationId: =System.ConversationId
+      agent:
+        name: TeacherAgent
+      output:
+        messages: Local.TeacherResponse
+
+    # Increment the turn counter
+    - kind: SetVariable
+      id: increment_counter
+      variable: Local.TurnCount
+      value: =Local.TurnCount + 1
+
+    # Check for completion using ConditionGroup
+    - kind: ConditionGroup
+      id: check_completion
+      conditions:
+        - id: success_condition
+          condition: =!IsBlank(Find("CONGRATULATIONS", Upper(MessageText(Local.TeacherResponse))))
+          actions:
+            - kind: SendActivity
+              id: success_message
+              activity:
+                text: "\nGOLD STAR! The student has demonstrated understanding."
+            - kind: SetVariable
+              id: set_success_result
+              variable: workflow.outputs.result
+              value: success
+      elseActions:
+        - kind: ConditionGroup
+          id: check_turn_limit
+          conditions:
+            - id: can_continue
+              condition: =Local.TurnCount < 4
+              actions:
+                # Continue the loop - go back to student label
+                - kind: GotoAction
+                  id: continue_loop
+                  actionId: student_label
+          elseActions:
+            - kind: SendActivity
+              id: timeout_message
+              activity:
+                text: "\nLet's try again later... The session has reached its limit."
+            - kind: SetVariable
+              id: set_timeout_result
+              variable: workflow.outputs.result
+              value: timeout