mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Ben Thomas
8e54f0b0e7
* feat(tools): add cross-OS LocalShellTool in new agent-framework-tools package Introduces a safe, cross-OS local shell tool as the first citizen of a new agent-framework-tools workspace package. Supports persistent (default) and stateless modes across pwsh/powershell.exe/bash/sh, with policy denylist, allowlist, approval gating, process-tree kill on timeout, output truncation, and audit hooks. Integrates with existing provider get_shell_tool(func=...) factories via FunctionTool kind='shell'. See docs/decisions/0026-builtin-tools-local-shell.md for the full design. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat(tools): security hardening for LocalShellTool Codifies what LocalShellTool does and does not defend against, and delegates the security-relevant lifecycle primitive to a battle-tested library instead of hand-rolled per-OS code. Changes: - Adopt psutil for cross-OS process-tree termination (executor + session). Replaces hand-rolled taskkill/killpg with one canonical implementation. - Resolve taskkill.exe to absolute %SystemRoot%\System32 path so PATH poisoning cannot redirect us to an attacker-supplied binary. - Reframe ShellPolicy docstring + ADR + README: denylist is a guardrail, not a security boundary. - Require acknowledge_unsafe=True to set approval_mode='never_require', making the unsafe path explicitly opt-in with a self-documenting name. - Add tests/test_security.py codifying named CVE-style cases. Defenses we DO claim are asserted; non-defenses (denylist bypasses via backslash insertion, variable expansion, interpreter escape, base64, alternative tools, PowerShell-native verbs) are documented as expected-to-pass tests so residual risk stays visible. - Add Threat Model + Confidence Strategy sections to ADR 0026. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat(tools): add DockerShellTool sandboxed shell tier Adds a container-backed shell executor as the recommended pattern for untrusted-input shell workflows. The container provides the security boundary (--network none, non-root user, --read-only, --cap-drop ALL, no-new-privileges, memory/pids limits, tmpfs /tmp), so approval gating is optional unlike LocalShellTool. Also introduces a ShellExecutor Protocol so callers can plug in custom backends (Firecracker, SSH, WASI) without forking the framework. Removes the planned HyperlightShellExecutor follow-up from ADR 0026: Hyperlight is a WASM code sandbox with no kernel/userland/shell binary, so a Hyperlight-backed shell is not viable. Docker is the realistic sandbox tier for shell. Tests: 11 unit tests for argv builders + lifecycle (no Docker daemon required); 3 integration tests gated on is_docker_available(). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(tools): backport shell-tool fixes from .NET parity review Applies the applicable subset of bug fixes accumulated during the .NET shell-tool PR review (microsoft/agent-framework#5604) to the Python shell tool. A1 - Quote workdir safely in _maybe_reanchor Previously _tool.py used double-quote interpolation when emitting the cd/Set-Location prefix, which expanded $VAR, $(), and backticks in the workdir path. A workdir containing shell metacharacters could trigger arbitrary command execution before the user command ran. Replaced with single-quote escaping helpers _quote_posix and _quote_powershell that emit literal-string forms safe for both hosts. A5/A6 - Consolidate truncation to a single byte-aware helper Extracted a shared truncate_head_tail / truncate_text_head_tail helper in _truncate.py. The new implementation distributes odd caps so head receives floor(cap/2) and tail receives ceil(cap/2) bytes, matching the .NET round-9 fix and ensuring no input bytes are silently dropped on the boundary. _session.py previously truncated by Python str length while the caller passed _max_output_bytes - the unit mismatch is now gone: raw byte buffers go through truncate_head_tail and decoded text goes through truncate_text_head_tail. Unit tests added for the truncate and quote helpers. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(tools): tone down narrative and overconfident comments in shell tool The shell tool's docstrings and comments contained two patterns that the .NET review pushed back on: - Narrative framing about implementation history ("hard-won", "we sidestep", "design inspiration: ...", competitor framework name-drops in module docstrings). - Overstated security guarantees ("battle-tested", "reasonable for untrusted input", "recommended executor for any agent that runs commands from untrusted input", "destructive commands are blocked", "safe local shell tool", "blocks shell injection"). Rewrites the affected docstrings and comments to describe what the code does in neutral terms. Behaviour is unchanged. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat(tools): add ShellEnvironmentProvider for the Python shell tool Ports the .NET ShellEnvironmentProvider as a Python ContextProvider so agents using LocalShellTool or DockerShellTool can be primed with an accurate description of the shell they're talking to (family, version, OS, working directory, and which CLIs are available). The provider runs probes through any ShellExecutor, caches the resulting snapshot, and on every before_run extends the session instructions with a markdown block describing the shell idiom to use. A failed first probe leaves the cache empty so the next call retries (no permanent poisoning). Probe failures from a narrow set of expected error types (ShellCommandError, ShellExecutionError, ShellTimeoutError, and asyncio.TimeoutError from the per-probe timeout) are recorded as None fields in the snapshot. Other exceptions propagate. Tool names are validated against ^[A-Za-z0-9._-]+$ before being interpolated into a probe command. Includes 12 unit tests covering happy path, stderr fallback, timeout handling, expected/unexpected exception paths, malicious tool name rejection, case-insensitive deduplication, retry after failure, concurrent first-callers sharing one probe, and the default and custom formatter paths. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(tools): document ShellEnvironmentProvider and finish comment cleanup Add a README section introducing ShellEnvironmentProvider, soften two remaining overconfident security-boundary comments in _executor_base.py and the DockerShellTool class docstring, and add a sample (shell_with_environment_provider.py) that demonstrates the provider in stateless and persistent modes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * refactor(tools): move shell samples to python/samples/02-agents/tools The repository convention is to host samples under python/samples/ rather than inside the package directory. Move the two net-new shell samples (allow-list and environment-provider) to python/samples/02-agents/tools/ and drop the in-package samples/ directory; the existing top-level providers/openai/client_with_local_shell.py already covers the basic LocalShellTool walkthrough. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * test(tools): cover confine_workdir default and ShellResult.format_for_model Two new tests in test_local_shell_tool.py exercise the default confine_workdir=True behaviour on POSIX and PowerShell, asserting that 'cd' inside one persistent-mode call does not leak into the next. A new test_shell_result.py module provides direct unit coverage for every conditional branch of ShellResult.format_for_model (stdout, truncated, stderr, timed_out, exit_code) so regressions in the LLM-facing format are caught immediately. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(tools): address PR #5664 review feedback - _tool.py: detect PowerShell via is_powershell() helper instead of basename string match - _environment.py: use public ContextProvider import (no private _ prefix) - _session.py: trim _stdout_buf/_stderr_buf after copying to avoid unbounded retention across calls - _docker.py: short-circuit start()/close() in stateless mode; add configurable shell kwarg (default bash, e.g. 'sh' for alpine) - tests: parenthesized multi-line assert; alpine integration tests now pass shell='sh' Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(tools): satisfy CI quality gates - pyupgrade: drop quoted self-class refs in __aenter__/method annotations - ruff format: reflow long lines per workspace style - pyright: assert psutil non-None in optional-import branch; lowercase mutable module globals; annotate _approval_mode as Literal so tool() Literal-typed kwarg is accepted; add ... body to ShellExecutor.run protocol; remove unused deprecated _kill_tree wrapper - tests: skip docker integration tests on win32 (Windows containers don't support --read-only / alpine images) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Remove DEFAULT_DENYLIST; document single-session ownership; fix bandit findings Mirrors the .NET PR #5604 cleanup: - Remove DEFAULT_DENYLIST from ShellPolicy. ShellPolicy() now ships with an empty deny-list; operators opt into site-specific patterns explicitly. No major agent framework uses regex matching as a primary security control; AutoGen v2 removed theirs. Approval gating + sandbox tier remain the real boundaries. - Rewrite module / class docstrings to frame ShellPolicy as a UX pre-filter, not a security control. - Add Single-session ownership paragraphs to ShellExecutor, ShellSession, LocalShellTool, and DockerShellTool: a persistent-mode tool is owned by exactly one conversation / agent session; do not share across users or concurrent conversations. - Tests now supply explicit deny patterns instead of relying on a default. - Address Pre-commit Hooks (bandit) CI failures: convert internal-invariant asserts to explicit RuntimeError, annotate intentional subprocess/shell usage with # nosec, document container-internal /tmp paths. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address PR #5664 round-2 review feedback Deny-list documentation drift: - README and the OpenAI/local-shell sample no longer claim a built-in deny-list of destructive commands. ShellPolicy is described as an optional, operator-supplied UX pre-filter; the real boundaries remain approval gating and the sandbox tier. Behavioural fixes called out in review: - ShellPolicy.evaluate() now denies empty / whitespace-only commands explicitly instead of returning allow with no rationale. - truncate_head_tail() raises ValueError for cap <= 0 instead of silently returning the full input with truncated=False, which previously could defeat output-capping in callers that mis-configured the budget. - LocalShellTool.as_function() / DockerShellTool.as_function() return the ShellCommandError text directly so the model sees a single, non-redundant 'Command rejected by policy: …' message instead of the prior duplicated 'Command blocked by policy: Command rejected …' wrapping. - ShellSession POSIX sentinel trailer now snapshots and restores the prior errexit (set -e) state around the trailer, so a user 'set -e' in the persistent shell is no longer permanently disabled by the next run(). Tests: - New test_shell_parse_rc.py covers the full _parse_rc() edge-case surface (zero, positive, negative, CRLF, no newline, missing prefix, empty input, non-digits, trailing garbage, partial digits). - test_policy.py asserts the new empty-command deny. - test_shell_truncate_and_quote.py asserts ValueError for cap=0 and cap<0. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address PR review feedback for shell tool - _resolve.py: reject empty/whitespace shell override string - _tool.py / _docker.py: mode-aware default tool description (persistent vs stateless) - _tool.py: fix misleading workdir docstring (re-anchor, not blocking) - _types.py: emit stream-agnostic [output truncated] marker - _policy.py: declare _denies/_allows as dataclass fields - _environment.py: use $(pwd) instead of $PWD in POSIX probe Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address PR review feedback: shell override flag + probe timeout safety - _resolve.py: in stateless mode, ensure shell overrides end with -c/-Command so commands aren't misinterpreted as script-file paths. - ShellExecutor.run / LocalShellTool.run / DockerShellTool.run now accept an optional imeout kwarg; ShellEnvironmentProvider drops the outer asyncio.wait_for and lets the executor enforce the probe timeout internally, so cancellation no longer risks leaving a hung subprocess or corrupted session. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address review feedback: docker isolation + lifecycle robustness - pyproject.toml: bump agent-framework-core minimum from 1.2.0 to 1.2.2 to align with the rest of the workspace. - _docker.py: validate extra_run_args at construction time and reject flags that would dismantle the isolation defaults (--privileged, --cap-add, --security-opt, --network/--net, -v/--volume/--mount, --device, --pid, --ipc, --userns, --user, --read-only, --tmpfs, --add-host, --gpus, --cgroupns, --device-cgroup-rule); also documented the warning on the docstring. - _docker._stop_container: retry docker rm -f once and log a warning/error when it does not succeed, so operators can audit leaked containers instead of getting a silent success. - _docker._run_stateless timeout path: fall back to docker rm -f when docker kill fails or times out (--rm only reaps on clean exit), and log instead of silently swallowing communicate() errors. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: alliscode <bentho@microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: alliscode <25218250+alliscode@users.noreply.github.com>
8e54f0b0e7
·
2026-05-22 00:29:59 +00:00
History
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, explicit output designation |
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.exampleto.envin thepython/directory:cp .env.example .env - Edit
.envand 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, orapi_version OPENAI_API_KEY/ explicit OpenAI API-key parameters- Azure environment fallback such as
AZURE_OPENAI_ENDPOINTandAZURE_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/module | 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 |
observability |
ENABLE_INSTRUMENTATION |
true |
agent-framework-core |
observability |
ENABLE_SENSITIVE_DATA |
false |
agent-framework-core |
observability |
ENABLE_CONSOLE_EXPORTERS |
true |
agent-framework-core |
observability |
OTEL_EXPORTER_OTLP_ENDPOINT |
http://localhost:4317 |
agent-framework-core |
observability |
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT |
http://localhost:4318/v1/traces |
agent-framework-core |
observability |
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT |
http://localhost:4318/v1/metrics |
agent-framework-core |
observability |
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT |
http://localhost:4318/v1/logs |
agent-framework-core |
observability |
OTEL_EXPORTER_OTLP_PROTOCOL |
grpc |
agent-framework-core |
observability |
OTEL_EXPORTER_OTLP_HEADERS |
api-key=demo |
agent-framework-core |
observability |
OTEL_EXPORTER_OTLP_TRACES_HEADERS |
api-key=trace-demo |
agent-framework-core |
observability |
OTEL_EXPORTER_OTLP_METRICS_HEADERS |
api-key=metric-demo |
agent-framework-core |
observability |
OTEL_EXPORTER_OTLP_LOGS_HEADERS |
api-key=log-demo |
agent-framework-core |
observability |
OTEL_SERVICE_NAME |
sample-agent |
agent-framework-core |
observability |
OTEL_SERVICE_VERSION |
1.0.0 |
agent-framework-core |
observability |
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