chore: import upstream snapshot with attribution

python/samples/02-agents/skills/script_approval/README.md

@@ -0,0 +1,60 @@
+# Skill Tool Approval — Human-in-the-Loop for Skill Tools
+
+This sample demonstrates the **manual human-in-the-loop** approval pattern for
+skill tools. Every tool exposed by `SkillsProvider` (`load_skill`,
+`read_skill_resource`, and `run_skill_script`) requires host approval by
+default, so the agent pauses and returns approval requests that your
+application approves or rejects.
+
+## How It Works
+
+By default, skill tools require approval. The agent pauses before running any of
+them and returns approval requests instead:
+
+1. The agent tries to call a skill tool (e.g. `load_skill` or `run_skill_script`) — execution is paused
+2. `result.user_input_requests` contains approval request(s) with function name and arguments
+3. The application inspects each request and decides to approve or reject
+4. `request.to_function_approval_response(approved=True|False)` creates the response
+5. The response is sent back via `agent.run(approval_response, session=session)`
+6. If approved, the tool runs; if rejected, the agent receives an error
+
+## Key Components
+
+- **Approval-by-default** — All skill tools require host approval; no extra configuration is needed
+- **`result.user_input_requests`** — Contains pending approval requests after `agent.run()`
+- **`request.to_function_approval_response()`** — Creates an approval or rejection response
+
+To approve skill tools automatically instead of prompting for each one, use
+`ToolApprovalMiddleware` with one of the static auto-approval rules — see the
+[Skills Auto-Approval Sample](../skills_auto_approval/).
+
+## Running the Sample
+
+### Prerequisites
+- An [Azure AI Foundry](https://ai.azure.com/) project with a deployed model (e.g. `gpt-4o-mini`)
+
+### Environment Variables
+
+Set the required environment variables in a `.env` file (see `python/.env.example`):
+
+- `FOUNDRY_PROJECT_ENDPOINT`: Your Azure AI Foundry project endpoint
+- `FOUNDRY_MODEL`: The name of your model deployment (defaults to `gpt-4o-mini`)
+
+### Authentication
+
+This sample uses `AzureCliCredential` for authentication. Run `az login` in your terminal before running the sample.
+
+### Run
+
+```bash
+cd python
+uv run samples/02-agents/skills/script_approval/script_approval.py
+```
+
+## Learn More
+
+- [Skills Auto-Approval Sample](../skills_auto_approval/)
+- [File-Based Skills Sample](../file_based_skill/)
+- [Code-Defined Skills Sample](../code_defined_skill/)
+- [Mixed Skills Sample](../mixed_skills/)
+- [Agent Skills Specification](https://agentskills.io/)

python/samples/02-agents/skills/script_approval/script_approval.py

@@ -0,0 +1,141 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from textwrap import dedent
+
+from agent_framework import Agent, Content, InlineSkill, Message, SkillFrontmatter, SkillsProvider
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+"""
+Skill Tool Approval — Require human approval before running skill tools
+
+Every tool exposed by :class:`SkillsProvider` (``load_skill``,
+``read_skill_resource``, and ``run_skill_script``) requires host approval by
+default. This sample shows the manual human-in-the-loop pattern: the agent
+pauses and returns approval requests, and the application approves or rejects
+each one before the agent continues.
+
+How it works:
+1. A code-defined skill with a script is registered via SkillsProvider.
+2. Because skill tools require approval by default, the agent pauses and returns
+   approval requests in ``result.user_input_requests`` instead of executing
+   tools immediately.
+3. The application inspects each request and calls
+   ``request.to_function_approval_response(approved=True|False)`` to approve
+   or reject.
+4. The approval response is sent back via ``agent.run(approval_response, session=session)``
+   and the agent continues — running the tool if approved, or receiving an
+   error if rejected.
+
+To approve skill tools automatically instead of prompting, use
+``ToolApprovalMiddleware`` with one of the static auto-approval rules — see
+``samples/02-agents/skills/skills_auto_approval/skills_auto_approval.py``.
+
+Prerequisites:
+- FOUNDRY_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- FOUNDRY_MODEL (defaults to "gpt-4o-mini").
+"""
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Define a code skill with a script that performs a sensitive operation
+deployment_skill = InlineSkill(
+    frontmatter=SkillFrontmatter(
+        name="deployment", description="Tools for deploying application versions to production"
+    ),
+    instructions=dedent("""\
+        Use this skill when the user asks to deploy an application.
+
+        1. Run the deploy script with the version and environment parameters.
+    """),
+)
+
+
+@deployment_skill.script
+def deploy(version: str, environment: str = "staging") -> str:
+    """Deploy the application to the specified environment."""
+    return f"Deployed version {version} to {environment}"
+
+
+async def main() -> None:
+    """Run the skill script approval demo."""
+    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
+    deployment = os.environ.get("FOUNDRY_MODEL", "gpt-4o-mini")
+
+    client = FoundryChatClient(
+        project_endpoint=endpoint,
+        model=deployment,
+        credential=AzureCliCredential(),
+    )
+
+    # Create the skills provider. All skill tools require approval by default.
+    skills_provider = SkillsProvider(
+        source=[deployment_skill],
+    )
+
+    async with Agent(
+        client=client,
+        instructions="You are a deployment assistant. Use the deployment skill to deploy applications.",
+        context_providers=[skills_provider],
+    ) as agent:
+        session = agent.create_session()
+
+        print("Starting agent with skill tool approval (the default)...")
+        print("-" * 60)
+
+        # Step 1: Send the user request — the agent will try to call the script
+        query = "Deploy the latest application version 2.5.0 to the production environment"
+        print(f"User: {query}")
+        result = await agent.run(query, session=session)
+
+        # Step 2: Handle approval requests (with sessions, context is
+        # maintained automatically). Collect a response for every request and
+        # send them in one run so the loop always makes progress.
+        while result.user_input_requests:
+            approval_responses: list[Content] = []
+            for request in result.user_input_requests:
+                if request.function_call is None:
+                    # Not a function-approval request; reject it so the run can proceed.
+                    approval_responses.append(request.to_function_approval_response(approved=False))
+                    continue
+                print("\nApproval needed:")
+                print(f"  Function: {request.function_call.name}")
+                print(f"  Arguments: {request.function_call.arguments}")
+
+                # In a real application, prompt the user here
+                approved = True  # Change to False to see rejection
+                print(f"  Decision: {'Approved' if approved else 'Rejected'}")
+                approval_responses.append(request.to_function_approval_response(approved=approved))
+
+            # Send the approval responses — session preserves conversation history
+            result = await agent.run(Message(role="user", contents=approval_responses), session=session)
+
+        print(f"\nAgent: {result}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+"""
+Sample output:
+
+Starting agent with skill tool approval (the default)...
+------------------------------------------------------------
+User: Deploy the latest application version 2.5.0 to the production environment
+
+Approval needed:
+  Function: load_skill
+  Arguments: {"skill_name": "deployment"}
+  Decision: Approved
+
+Approval needed:
+  Function: run_skill_script
+  Arguments: {"skill_name": "deployment", "script_name": "deploy", ...}
+  Decision: Approved
+
+Agent: Successfully deployed version 2.5.0 to production.
+"""