From 00519d9d761d3d9187970ba6e9344e7edea8a926 Mon Sep 17 00:00:00 2001 From: Manohar Paturi <186662190+ManoharPaturi@users.noreply.github.com> Date: Thu, 24 Sep 2026 18:16:51 +0530 Subject: [PATCH 1/2] docs(samples): link get-started and provider samples to security patterns Link introductory getting-started guides, provider READMEs, and hosting documentation to the production security samples under 02-agents/security. While introductory samples intentionally keep code minimal for quick onboarding, production agents interacting with external content require prompt injection defense and policy enforcement. Cross-referencing SecureAgentConfig, quarantined_llm, and MCP proxy patterns directly from getting started, tools, and provider guides makes these safeguards readily discoverable. Signed-off-by: Manohar Paturi <186662190+ManoharPaturi@users.noreply.github.com> --- python/samples/01-get-started/02_add_tools.py | 3 +++ python/samples/01-get-started/README.md | 11 +++++++++++ python/samples/02-agents/providers/README.md | 9 +++++++++ python/samples/04-hosting/README.md | 5 +++++ python/samples/README.md | 14 +++++++++++++- 5 files changed, 41 insertions(+), 1 deletion(-) diff --git a/python/samples/01-get-started/02_add_tools.py b/python/samples/01-get-started/02_add_tools.py index 7b558abeaec..dcfb766f66b 100644 --- a/python/samples/01-get-started/02_add_tools.py +++ b/python/samples/01-get-started/02_add_tools.py @@ -20,6 +20,9 @@ # # NOTE: approval_mode="never_require" is for sample brevity. # Use "always_require" in production for user confirmation before tool execution. +# For tools processing untrusted external data or performing privileged operations, +# see samples/02-agents/security/email_security_example.py for SecureAgentConfig +# and quarantined_llm defense patterns. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/01-get-started/README.md b/python/samples/01-get-started/README.md index c4180b85fab..fcbf0ac3105 100644 --- a/python/samples/01-get-started/README.md +++ b/python/samples/01-get-started/README.md @@ -32,6 +32,17 @@ export FOUNDRY_MODEL="gpt-4o" # optional, defaults to gpt-4o To host agents and workflows with Durable Task or Azure Functions, continue with the [Durable Agent Framework extension samples](https://github.com/microsoft/agent-framework-durable-extension/tree/main/python/samples). +## Security in Production + +Introductory tutorials in this directory demonstrate core agent mechanics with minimal wiring. When building agents for production that handle untrusted external content (emails, user attachments, web browsing, third-party APIs) or execute privileged actions, incorporate security controls against indirect prompt injection and data exfiltration. + +See [`samples/02-agents/security/`](../02-agents/security/) for production-ready security patterns: + +1. [`email_security_example.py`](../02-agents/security/email_security_example.py): Demonstrates `SecureAgentConfig`, isolated execution using `quarantined_llm`, and approval gating before invoking sensitive tools. +2. [`repo_confidentiality_example.py`](../02-agents/security/repo_confidentiality_example.py): Demonstrates tracking data confidentiality to prevent sensitive data leaks. +3. [`github_mcp_example.py`](../02-agents/security/github_mcp_example.py): Demonstrates `SecureMCPToolProxy` wrapping remote MCP endpoints with local policy enforcement. +4. [FIDES Developer Guide](../02-agents/security/FIDES_DEVELOPER_GUIDE.md): Architecture reference and security middleware documentation. + Run any sample with: ```bash diff --git a/python/samples/02-agents/providers/README.md b/python/samples/02-agents/providers/README.md index 4f0946a2864..f006b3775f1 100644 --- a/python/samples/02-agents/providers/README.md +++ b/python/samples/02-agents/providers/README.md @@ -17,3 +17,12 @@ This directory groups provider-specific samples for Agent Framework. | [`openai/`](openai/) | OpenAI provider samples for Chat and Chat Completion clients, including tools, structured output, sessions, MCP, web search, and multimodal tasks. | Each folder has its own README with setup requirements and file-by-file details. + +## Security & Untrusted Data + +When configuring providers with function tools or external data access, review [`../security/`](../security/) for production security controls: + +1. [`email_security_example.py`](../security/email_security_example.py): Prompt injection defense with `SecureAgentConfig` and `quarantined_llm`. +2. [`github_mcp_example.py`](../security/github_mcp_example.py): Securing external MCP tools with `SecureMCPToolProxy`. +3. [`repo_confidentiality_example.py`](../security/repo_confidentiality_example.py): Preventing confidential data exfiltration across tool invocations. +4. [FIDES Developer Guide](../security/FIDES_DEVELOPER_GUIDE.md): Architecture reference and security middleware documentation. diff --git a/python/samples/04-hosting/README.md b/python/samples/04-hosting/README.md index 0563298f55b..aee66dd8573 100644 --- a/python/samples/04-hosting/README.md +++ b/python/samples/04-hosting/README.md @@ -33,3 +33,8 @@ Most hosting samples share a small set of prerequisites: 1. Pick the hosting approach that matches your scenario. 2. Open the corresponding README for setup and run instructions. 3. Follow that sample's environment, dependency, and execution steps. + +## Security in Hosted Environments + +Hosted agents that accept remote requests or execute tools with external effects should implement defense-in-depth controls. Review [`../02-agents/security/`](../02-agents/security/) for patterns covering `SecureAgentConfig`, policy enforcement middleware, and isolated processing of untrusted content. + diff --git a/python/samples/README.md b/python/samples/README.md index 34eb44c2931..52d0be1e6f5 100644 --- a/python/samples/README.md +++ b/python/samples/README.md @@ -7,7 +7,7 @@ This directory contains samples demonstrating the capabilities of Microsoft Agen | Folder | Description | |--------|-------------| | [`01-get-started/`](./01-get-started/) | Progressive tutorial: hello agent → graph workflows | -| [`02-agents/`](./02-agents/) | Deep-dive by concept: tools, middleware, providers, orchestrations | +| [`02-agents/`](./02-agents/) | Deep-dive by concept: tools, middleware, providers, orchestrations, security | | [`03-workflows/`](./03-workflows/) | Workflow patterns: sequential, concurrent, state, declarative, explicit output designation | | [`04-hosting/`](./04-hosting/) | Deployment: A2A, self-hosted protocol helpers, and Foundry hosted agents | | [`05-end-to-end/`](./05-end-to-end/) | Full applications, evaluation, demos, including the [AG-UI single-agent demo](./05-end-to-end/ag_ui_single_agent/) using `FoundryChatClient` | @@ -26,6 +26,18 @@ Start with `01-get-started/` and work through the numbered files: Durable Task and Azure Functions samples have moved to the [Durable Agent Framework extension](https://github.com/microsoft/agent-framework-durable-extension/tree/main/python/samples). +## Production Security & Prompt Injection Defense + +While getting-started tutorials demonstrate core mechanics with minimal boilerplate, real-world agents processing external or untrusted data (emails, web content, user-uploaded files, external APIs) require security controls against indirect prompt injection and data exfiltration. + +Review the production security patterns in [`02-agents/security/`](./02-agents/security/): + +1. **Prompt Injection Defense**: [`email_security_example.py`](./02-agents/security/email_security_example.py) shows `SecureAgentConfig`, quarantined processing with `quarantined_llm`, and approval gating for privileged tools. +2. **Data Confidentiality & Exfiltration Prevention**: [`repo_confidentiality_example.py`](./02-agents/security/repo_confidentiality_example.py) demonstrates information flow tracking and preventing sensitive data exfiltration to public destinations. +3. **MCP Tool Protection**: [`github_mcp_example.py`](./02-agents/security/github_mcp_example.py) demonstrates `SecureMCPToolProxy` wrapping remote MCP endpoints with local policy enforcement. +4. **Principal-Bound Identity**: [`user_identity_security_example.py`](./02-agents/security/user_identity_security_example.py) shows principal binding and tenant isolation. +5. **Architecture Reference**: Consult the [FIDES Developer Guide](./02-agents/security/FIDES_DEVELOPER_GUIDE.md) for full details on security middleware, labels, and auto-hiding behavior. + ## Prerequisites ```bash From fffdf9b8f1a948f4b2388f3d09620dce8990f4e9 Mon Sep 17 00:00:00 2001 From: Manohar Paturi <186662190+ManoharPaturi@users.noreply.github.com> Date: Thu, 24 Sep 2026 20:58:56 +0530 Subject: [PATCH 2/2] docs(samples): add Learn Agent Safety doc as primary security guidance source --- python/samples/01-get-started/02_add_tools.py | 4 +++- python/samples/01-get-started/README.md | 2 +- python/samples/02-agents/providers/README.md | 2 +- python/samples/04-hosting/README.md | 2 +- python/samples/README.md | 2 +- 5 files changed, 7 insertions(+), 5 deletions(-) diff --git a/python/samples/01-get-started/02_add_tools.py b/python/samples/01-get-started/02_add_tools.py index dcfb766f66b..9d38ea71206 100644 --- a/python/samples/01-get-started/02_add_tools.py +++ b/python/samples/01-get-started/02_add_tools.py @@ -21,7 +21,9 @@ # NOTE: approval_mode="never_require" is for sample brevity. # Use "always_require" in production for user confirmation before tool execution. # For tools processing untrusted external data or performing privileged operations, -# see samples/02-agents/security/email_security_example.py for SecureAgentConfig +# review the Agent Safety guidance at +# https://learn.microsoft.com/en-us/agent-framework/concepts/agents/safety +# and see samples/02-agents/security/email_security_example.py for SecureAgentConfig # and quarantined_llm defense patterns. @tool(approval_mode="never_require") def get_weather( diff --git a/python/samples/01-get-started/README.md b/python/samples/01-get-started/README.md index fcbf0ac3105..68a290a37ac 100644 --- a/python/samples/01-get-started/README.md +++ b/python/samples/01-get-started/README.md @@ -36,7 +36,7 @@ To host agents and workflows with Durable Task or Azure Functions, continue with Introductory tutorials in this directory demonstrate core agent mechanics with minimal wiring. When building agents for production that handle untrusted external content (emails, user attachments, web browsing, third-party APIs) or execute privileged actions, incorporate security controls against indirect prompt injection and data exfiltration. -See [`samples/02-agents/security/`](../02-agents/security/) for production-ready security patterns: +For the official security guidance, see [Agent Safety](https://learn.microsoft.com/en-us/agent-framework/concepts/agents/safety) on Microsoft Learn. Then see [`samples/02-agents/security/`](../02-agents/security/) for production-ready security patterns: 1. [`email_security_example.py`](../02-agents/security/email_security_example.py): Demonstrates `SecureAgentConfig`, isolated execution using `quarantined_llm`, and approval gating before invoking sensitive tools. 2. [`repo_confidentiality_example.py`](../02-agents/security/repo_confidentiality_example.py): Demonstrates tracking data confidentiality to prevent sensitive data leaks. diff --git a/python/samples/02-agents/providers/README.md b/python/samples/02-agents/providers/README.md index f006b3775f1..330c21e361c 100644 --- a/python/samples/02-agents/providers/README.md +++ b/python/samples/02-agents/providers/README.md @@ -20,7 +20,7 @@ Each folder has its own README with setup requirements and file-by-file details. ## Security & Untrusted Data -When configuring providers with function tools or external data access, review [`../security/`](../security/) for production security controls: +When configuring providers with function tools or external data access, review the [Agent Safety](https://learn.microsoft.com/en-us/agent-framework/concepts/agents/safety) guidance on Microsoft Learn, then [`../security/`](../security/) for production security controls: 1. [`email_security_example.py`](../security/email_security_example.py): Prompt injection defense with `SecureAgentConfig` and `quarantined_llm`. 2. [`github_mcp_example.py`](../security/github_mcp_example.py): Securing external MCP tools with `SecureMCPToolProxy`. diff --git a/python/samples/04-hosting/README.md b/python/samples/04-hosting/README.md index aee66dd8573..e0d8dbd4e65 100644 --- a/python/samples/04-hosting/README.md +++ b/python/samples/04-hosting/README.md @@ -36,5 +36,5 @@ Most hosting samples share a small set of prerequisites: ## Security in Hosted Environments -Hosted agents that accept remote requests or execute tools with external effects should implement defense-in-depth controls. Review [`../02-agents/security/`](../02-agents/security/) for patterns covering `SecureAgentConfig`, policy enforcement middleware, and isolated processing of untrusted content. +Hosted agents that accept remote requests or execute tools with external effects should implement defense-in-depth controls. Review the [Agent Safety](https://learn.microsoft.com/en-us/agent-framework/concepts/agents/safety) guidance on Microsoft Learn, then [`../02-agents/security/`](../02-agents/security/) for patterns covering `SecureAgentConfig`, policy enforcement middleware, and isolated processing of untrusted content. diff --git a/python/samples/README.md b/python/samples/README.md index 52d0be1e6f5..fdfd871ba7c 100644 --- a/python/samples/README.md +++ b/python/samples/README.md @@ -30,7 +30,7 @@ Durable Task and Azure Functions samples have moved to the [Durable Agent Framew While getting-started tutorials demonstrate core mechanics with minimal boilerplate, real-world agents processing external or untrusted data (emails, web content, user-uploaded files, external APIs) require security controls against indirect prompt injection and data exfiltration. -Review the production security patterns in [`02-agents/security/`](./02-agents/security/): +For the official security guidance, see [Agent Safety](https://learn.microsoft.com/en-us/agent-framework/concepts/agents/safety) on Microsoft Learn. The production security patterns in [`02-agents/security/`](./02-agents/security/) implement these practices end to end: 1. **Prompt Injection Defense**: [`email_security_example.py`](./02-agents/security/email_security_example.py) shows `SecureAgentConfig`, quarantined processing with `quarantined_llm`, and approval gating for privileged tools. 2. **Data Confidentiality & Exfiltration Prevention**: [`repo_confidentiality_example.py`](./02-agents/security/repo_confidentiality_example.py) demonstrates information flow tracking and preventing sensitive data exfiltration to public destinations.