diff --git a/python/samples/01-get-started/02_add_tools.py b/python/samples/01-get-started/02_add_tools.py index 7b558abeaec..9d38ea71206 100644 --- a/python/samples/01-get-started/02_add_tools.py +++ b/python/samples/01-get-started/02_add_tools.py @@ -20,6 +20,11 @@ # # 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, +# 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( 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..68a290a37ac 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. + +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. +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..330c21e361c 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 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`. +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..e0d8dbd4e65 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 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 34eb44c2931..fdfd871ba7c 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. + +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. +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