mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00

Files

T

Evan Mattson e56e6dad4d Python: Remove bespoke Foundry toolbox helpers; standardize on MCP for toolbox consumption (#5671 )

* Remove Foundry toolbox helpers; standardize on MCP for toolbox consumption

- Remove RawFoundryChatClient.get_toolbox() and its fetch_toolbox import
- Remove fetch_toolbox, select_toolbox_tools, get_toolbox_tool_name,
  get_toolbox_tool_type, FoundryHostedToolType, ToolboxToolSelectionInput
  from agent_framework_foundry._tools
- Remove ExperimentalFeature.TOOLBOXES from _feature_stage.py (no consumers)
- Drop toolbox re-exports from agent_framework_foundry/__init__.py and
  agent_framework.foundry namespace
- Update _sanitize_foundry_response_tool docstring to remove toolbox framing;
  sanitization logic itself is unchanged
- Update _agent.py docstring: 'toolbox-fetched MCP' → 'hosted MCP'
- Delete tests/test_toolbox.py (all tests covered removed helpers)
- Update test_foundry_chat_client.py: rename/redoc tests that mentioned
  toolbox but test sanitization that remains
- Delete foundry_chat_client_with_toolbox.py (bespoke toolbox API sample)
- Delete foundry_toolbox_context_provider.py (relied on select_toolbox_tools)
- Rename foundry_chat_client_with_toolbox_mcp.py →
  foundry_chat_client_with_toolbox.py (canonical MCP pattern)
- Rewrite 04_foundry_toolbox/main.py to use MCPStreamableHTTPTool
- Update provider/README, context_providers/README, 04_foundry_toolbox/README

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(samples): update 06_files sample to consume toolbox via MCP (#5670)

Replace removed get_toolbox/select_toolbox_tools APIs with
MCPStreamableHTTPTool, using allowed_tools=["code_interpreter"] to
select only the code interpreter from the toolbox endpoint.

Update .env.example and README to use FOUNDRY_TOOLBOX_ENDPOINT
instead of TOOLBOX_NAME.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(foundry): remove non-existent toolbox helper APIs from README (#5670)

Remove the 'fetch, optionally filter, and pass tools directly' pattern
from the FoundryChatClient toolbox documentation, as select_toolbox_tools
and get_toolbox were removed. Only the MCP endpoint pattern is documented.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(foundry): remove residual toolbox docstring references and reproduction report

Remove REPRODUCTION_REPORT.md (workflow artifact that should not be committed),
and update two remaining docstring references that still said 'toolbox reads'
/'toolbox definition' after the toolbox helpers were removed.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Python: Remove bespoke Foundry toolbox helpers; standardize on MCP for toolbox consumption

Fixes #5670

* fix(#5670): resolve toolbox endpoint from TOOLBOX_NAME fallback; add namespace regression tests

- Add _resolve_toolbox_endpoint() helper in 04_foundry_toolbox/main.py and
  06_files/main.py that prefers FOUNDRY_TOOLBOX_ENDPOINT but falls back to
  deriving the MCP URL from FOUNDRY_PROJECT_ENDPOINT + TOOLBOX_NAME — fixing
  the startup KeyError when agents are deployed via azd provision (which injects
  TOOLBOX_NAME, not FOUNDRY_TOOLBOX_ENDPOINT).
- Update 04_foundry_toolbox/.env.example to use FOUNDRY_TOOLBOX_ENDPOINT
  (consistent with 06_files).
- Add TOOLBOX_NAME env var to 06_files/agent.yaml so deployed agents have it
  available for the fallback derivation.
- Update both READMEs to document the two ways to supply the toolbox endpoint.
- Add test_foundry_namespace_no_longer_exposes_toolbox_helpers() with negative
  assertions for FoundryHostedToolType, get_toolbox_tool_name,
  get_toolbox_tool_type, and select_toolbox_tools — guarding against accidental
  re-introduction of removed symbols.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(samples): fail fast on empty FOUNDRY_TOOLBOX_ENDPOINT; add unit tests

Addresses review feedback for #5670:

- In _resolve_toolbox_endpoint() (04_foundry_toolbox/main.py and
  06_files/main.py) change the walrus-operator check from a truthy
  test to an explicit 'is not None' guard.  An explicitly set empty
  string now raises ValueError immediately with a clear message
  instead of silently falling through to the fallback URL
  construction.

- Add tests/samples/hosting/test_toolbox_endpoint.py covering both
  sample modules:
    (a) FOUNDRY_TOOLBOX_ENDPOINT set → returned as-is
    (b) FOUNDRY_TOOLBOX_ENDPOINT set to empty string → ValueError
    (c) fallback constructs URL from FOUNDRY_PROJECT_ENDPOINT + TOOLBOX_NAME,
        stripping trailing slashes
    (d) neither variable group set → KeyError

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address review feedback: remove extraneous test and docstring content

- Remove test_foundry_namespace_no_longer_exposes_toolbox_helpers (no longer warranted)
- Remove docstring from _agent.py _prepare_tools_for_openai (extraneous)
- Trim _chat_client.py _prepare_tools_for_openai docstring to one-liner (toolbox references no longer relevant)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: remove remaining extraneous docstring from RawFoundryChatClient._prepare_tools_for_openai

Address review comment on PR #5671: reviewer noted the description
isn't warranted now that toolbox helpers have been removed. Matches
the pattern in RawFoundryAgentChatClient which has no docstring.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

e56e6dad4d · 2026-05-06 23:56:16 +00:00

History

01-get-started

Python: Add requirements.txt and .env.example to the a2a/ sample for pip-based setup (#5510 )

2026-04-27 22:22:07 +00:00

02-agents

Python: Remove bespoke Foundry toolbox helpers; standardize on MCP for toolbox consumption (#5671 )

2026-05-06 23:56:16 +00:00

03-workflows

Python: Add Python parity for InvokeMcpTool in declarative workflow (#5630 )

2026-05-05 20:16:03 +00:00

04-hosting

Python: Remove bespoke Foundry toolbox helpers; standardize on MCP for toolbox consumption (#5671 )

2026-05-06 23:56:16 +00:00

05-end-to-end

Python: Update package dependencies (#5555 )

2026-04-29 06:18:03 +00:00

autogen-migration

Fix handoff workflow context management and improve AG-UI demo (#5136 )

2026-04-08 04:08:24 +00:00

semantic-kernel-migration

Fix handoff workflow context management and improve AG-UI demo (#5136 )

2026-04-08 04:08:24 +00:00

shared

Python: Phase 2: Embedding clients for Ollama, Bedrock, and Azure AI Inference (#4207 )

2026-02-25 17:45:08 +00:00

__init__.py

Python telemetry (#223 )

2025-07-28 07:33:42 +00:00

AGENTS.md

Python: [BREAKING] update to v1.0.0 (#5062 )

2026-04-02 15:26:30 +00:00

README.md

Python: (core): Add functional workflow API (#4238 )

2026-04-24 09:41:20 +00:00

SAMPLE_GUIDELINES.md

Python: [BREAKING] Python: Provider-leading client design & OpenAI package extraction (#4818 )

2026-03-25 09:56:29 +00:00

README.md

Python Samples

This directory contains samples demonstrating the capabilities of Microsoft Agent Framework for Python.

Structure

Folder	Description
`01-get-started/`	Progressive tutorial: hello agent → hosting
`02-agents/`	Deep-dive by concept: tools, middleware, providers, orchestrations
`03-workflows/`	Workflow patterns: sequential, concurrent, state, declarative
`04-hosting/`	Deployment: Azure Functions, Durable Tasks, A2A
`05-end-to-end/`	Full applications, evaluation, demos

Getting Started

Start with 01-get-started/ and work through the numbered files:

01_hello_agent.py — Create and run your first agent
02_add_tools.py — Add function tools with @tool
03_multi_turn.py — Multi-turn conversations with AgentSession
04_memory.py — Agent memory with ContextProvider
05_functional_workflow_with_agents.py — Call agents inside a functional workflow
06_functional_workflow_basics.py — Write a workflow as a plain async function
07_first_graph_workflow.py — Build a workflow with executors and edges
08_host_your_agent.py — Host your agent via Azure Functions

Prerequisites

pip install agent-framework

Environment Variables

Samples call load_dotenv() to automatically load environment variables from a .env file in the python/ directory. This is a convenience for local development and testing.

For local development, set up your environment using any of these methods:

Option 1: Using a .env file (recommended for local development):

Copy .env.example to .env in the python/ directory:
```
cp .env.example .env
```
Edit .env and set your values (API keys, endpoints, etc.)

Option 2: Export environment variables directly:

export FOUNDRY_PROJECT_ENDPOINT="your-foundry-project-endpoint"
export FOUNDRY_MODEL="gpt-4o"

Option 3: Using env_file_path parameter (for per-client configuration):

All client classes (e.g., OpenAIChatClient, OpenAIChatCompletionClient) support an env_file_path parameter to load environment variables from a specific file:

from agent_framework.openai import OpenAIChatClient

# Load from a custom .env file
client = OpenAIChatClient(env_file_path="path/to/custom.env")

This allows different clients to use different configuration files if needed.

For the generic OpenAI clients (OpenAIChatClient and OpenAIChatCompletionClient), routing precedence is:

Explicit Azure inputs such as credential, azure_endpoint, or api_version
OPENAI_API_KEY / explicit OpenAI API-key parameters
Azure environment fallback such as AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_API_KEY

If you keep both OpenAI and Azure variables in your shell, the generic clients stay on OpenAI until you pass an explicit Azure input.

For the getting-started samples, you'll need at minimum:

FOUNDRY_PROJECT_ENDPOINT="your-foundry-project-endpoint"
FOUNDRY_MODEL="gpt-4o"

Consolidated sample env inventory

This is the single source of truth for package-level environment variables read by packages included by agent-framework-core[all]. It intentionally excludes variables that are only read by standalone samples, package sample folders, or tests. When package code adds, removes, or renames an environment variable, update this table in the same change.

Example values below are illustrative. For entries not backed by a single public class, the class column names the closest public surface, helper, or package-level initialization point that reads the variable.

package	class	env var	example value
`agent-framework-anthropic`	`AnthropicClient`	`ANTHROPIC_API_KEY`	`sk-ant-api03-...`
`agent-framework-anthropic`	`AnthropicClient`	`ANTHROPIC_CHAT_MODEL`	`claude-sonnet-4-5-20250929`
`agent-framework-foundry`	`FoundryEmbeddingClient`	`FOUNDRY_MODELS_ENDPOINT`	`https://my-endpoint.inference.ai.azure.com`
`agent-framework-foundry`	`FoundryEmbeddingClient`	`FOUNDRY_MODELS_API_KEY`	`env-key`
`agent-framework-foundry`	`FoundryEmbeddingClient`	`FOUNDRY_EMBEDDING_MODEL`	`text-embedding-3-small`
`agent-framework-foundry`	`FoundryEmbeddingClient`	`FOUNDRY_IMAGE_EMBEDDING_MODEL`	`Cohere-embed-v3-english`
`agent-framework-azure-ai-search`	`AzureAISearchContextProvider`	`AZURE_SEARCH_ENDPOINT`	`https://my-search.search.windows.net`
`agent-framework-azure-ai-search`	`AzureAISearchContextProvider`	`AZURE_SEARCH_API_KEY`	`search-key`
`agent-framework-azure-ai-search`	`AzureAISearchContextProvider`	`AZURE_SEARCH_INDEX_NAME`	`hotels-index`
`agent-framework-azure-ai-search`	`AzureAISearchContextProvider`	`AZURE_SEARCH_KNOWLEDGE_BASE_NAME`	`hotels-kb`
`agent-framework-azure-cosmos`	`CosmosHistoryProvider`	`AZURE_COSMOS_ENDPOINT`	`https://my-cosmos.documents.azure.com:443/`
`agent-framework-azure-cosmos`	`CosmosHistoryProvider`	`AZURE_COSMOS_DATABASE_NAME`	`agent-history`
`agent-framework-azure-cosmos`	`CosmosHistoryProvider`	`AZURE_COSMOS_CONTAINER_NAME`	`messages`
`agent-framework-azure-cosmos`	`CosmosHistoryProvider`	`AZURE_COSMOS_KEY`	`C2F...==`
`agent-framework-bedrock`	`BedrockChatClient`	`BEDROCK_REGION`	`us-east-1`
`agent-framework-bedrock`	`BedrockChatClient`	`BEDROCK_CHAT_MODEL`	`anthropic.claude-3-5-sonnet-20241022-v2:0`
`agent-framework-bedrock`	`BedrockEmbeddingClient`	`BEDROCK_REGION`	`us-east-1`
`agent-framework-bedrock`	`BedrockEmbeddingClient`	`BEDROCK_EMBEDDING_MODEL`	`amazon.titan-embed-text-v2:0`
`agent-framework-bedrock`	`BedrockChatClient / BedrockEmbeddingClient`	`AWS_ACCESS_KEY_ID`	`AKIAIOSFODNN7EXAMPLE`
`agent-framework-bedrock`	`BedrockChatClient / BedrockEmbeddingClient`	`AWS_SECRET_ACCESS_KEY`	`wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`
`agent-framework-bedrock`	`BedrockChatClient / BedrockEmbeddingClient`	`AWS_SESSION_TOKEN`	`IQoJb3JpZ2luX2VjEO7//////////wEaCXVzLXdlc3QtMiJHMEUCIQD...`
`agent-framework-copilotstudio`	`CopilotStudioAgent`	`COPILOTSTUDIOAGENT__ENVIRONMENTID`	`00000000-0000-0000-0000-000000000000`
`agent-framework-copilotstudio`	`CopilotStudioAgent`	`COPILOTSTUDIOAGENT__SCHEMANAME`	`cr123_agentname`
`agent-framework-copilotstudio`	`CopilotStudioAgent`	`COPILOTSTUDIOAGENT__TENANTID`	`11111111-1111-1111-1111-111111111111`
`agent-framework-copilotstudio`	`CopilotStudioAgent`	`COPILOTSTUDIOAGENT__AGENTAPPID`	`22222222-2222-2222-2222-222222222222`
`agent-framework-core`	`enable_instrumentation()`	`ENABLE_INSTRUMENTATION`	`true`
`agent-framework-core`	`enable_instrumentation()`	`ENABLE_SENSITIVE_DATA`	`false`
`agent-framework-core`	`enable_instrumentation()`	`ENABLE_CONSOLE_EXPORTERS`	`true`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://localhost:4317`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	`http://localhost:4318/v1/traces`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	`http://localhost:4318/v1/metrics`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	`http://localhost:4318/v1/logs`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_PROTOCOL`	`grpc`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_HEADERS`	`api-key=demo`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_TRACES_HEADERS`	`api-key=trace-demo`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_METRICS_HEADERS`	`api-key=metric-demo`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_LOGS_HEADERS`	`api-key=log-demo`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_SERVICE_NAME`	`sample-agent`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_SERVICE_VERSION`	`1.0.0`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_RESOURCE_ATTRIBUTES`	`deployment.environment=dev,service.namespace=agent-framework`
`agent-framework-devui`	`DevUI server`	`DEVUI_AUTH_TOKEN`	`my-devui-token`
`agent-framework-foundry`	`FoundryChatClient`	`FOUNDRY_PROJECT_ENDPOINT`	`https://my-project.services.ai.azure.com/api/projects/my-project`
`agent-framework-foundry`	`FoundryChatClient`	`FOUNDRY_MODEL`	`gpt-4o`
`agent-framework-foundry`	`FoundryAgent`	`FOUNDRY_AGENT_NAME`	`travel-planner`
`agent-framework-foundry`	`FoundryAgent`	`FOUNDRY_AGENT_VERSION`	`v1`
`agent-framework-github-copilot`	`GitHubCopilotAgent`	`GITHUB_COPILOT_CLI_PATH`	`copilot`
`agent-framework-github-copilot`	`GitHubCopilotAgent`	`GITHUB_COPILOT_MODEL`	`gpt-5`
`agent-framework-github-copilot`	`GitHubCopilotAgent`	`GITHUB_COPILOT_TIMEOUT`	`60`
`agent-framework-github-copilot`	`GitHubCopilotAgent`	`GITHUB_COPILOT_LOG_LEVEL`	`info`
`agent-framework-mem0`	`agent_framework_mem0 package import`	`MEM0_TELEMETRY`	`false`
`agent-framework-ollama`	`OllamaChatClient`	`OLLAMA_HOST`	`http://localhost:11434`
`agent-framework-ollama`	`OllamaChatClient`	`OLLAMA_MODEL`	`llama3.1:8b`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`OPENAI_API_KEY`	`sk-proj-...`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`OPENAI_MODEL`	`gpt-4o-mini`
`agent-framework-openai`	`OpenAIChatClient`	`OPENAI_CHAT_MODEL`	`gpt-4.1-mini`
`agent-framework-openai`	`OpenAIChatCompletionClient`	`OPENAI_CHAT_COMPLETION_MODEL`	`gpt-4o`
`agent-framework-openai`	`OpenAIEmbeddingClient`	`OPENAI_EMBEDDING_MODEL`	`text-embedding-3-small`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`OPENAI_BASE_URL`	`https://api.openai.com/v1/`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`OPENAI_ORG_ID`	`org_123456789`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`AZURE_OPENAI_ENDPOINT`	`https://my-resource.openai.azure.com/`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`AZURE_OPENAI_API_KEY`	`sk-azure-...`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`AZURE_OPENAI_API_VERSION`	`2024-10-21`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`AZURE_OPENAI_BASE_URL`	`https://my-resource.openai.azure.com/openai/v1/`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`AZURE_OPENAI_MODEL`	`gpt-4o`
`agent-framework-openai`	`OpenAIChatClient`	`AZURE_OPENAI_CHAT_MODEL`	`gpt-4.1`
`agent-framework-openai`	`OpenAIChatCompletionClient`	`AZURE_OPENAI_CHAT_COMPLETION_MODEL`	`gpt-4o-mini`
`agent-framework-openai`	`OpenAIEmbeddingClient`	`AZURE_OPENAI_EMBEDDING_MODEL`	`text-embedding-3-large`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`AZURE_OPENAI_RESOURCE_URL`	`https://cognitiveservices.azure.com/`

agent-framework-openai supports the Azure OpenAI client-specific deployment aliases listed above; keep packages/openai/README.md as the authoritative reference for the exact fallback order and package-specific behavior.

Note for production: In production environments, set environment variables through your deployment platform (e.g., Azure App Settings, Kubernetes ConfigMaps/Secrets) rather than using .env files. The load_dotenv() call in samples will have no effect when a .env file is not present, allowing environment variables to be loaded from the system.

For Azure authentication, run az login before running samples.

Note on XML tags

Some sample files include XML-style snippet tags (for example <snippet_name> and </snippet_name>). These are used by our documentation tooling and can be ignored or removed when you use the samples outside this repository.

Additional Resources

Agent Framework Documentation
AGENTS.md — Structure documentation for maintainers
SAMPLE_GUIDELINES.md — Coding conventions for samples