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

Files

T

Eduard van Valkenburg 5e056b672e Python: [BREAKING] Python: Provider-leading client design & OpenAI package extraction (#4818 )

* Python: Provider-leading client design & OpenAI package extraction

Major refactoring of the Python Agent Framework client architecture:

- Extract OpenAI clients into new `agent-framework-openai` package
- Core package no longer depends on openai, azure-identity, azure-ai-projects
- Rename clients for discoverability: OpenAIResponsesClient → OpenAIChatClient,
  OpenAIChatClient → OpenAIChatCompletionClient
- Unify `model_id`/`deployment_name`/`model_deployment_name` → `model` param
- New FoundryChatClient for Azure AI Foundry Responses API
- New FoundryAgent/FoundryAgentClient for connecting to pre-configured Foundry agents
- Remove OpenAIBase/OpenAIConfigMixin from non-deprecated client MRO
- Deprecate AzureOpenAI* clients, AzureAIClient, OpenAIAssistantsClient
- Reorganize samples: azure_openai+azure_ai+azure_ai_agent → azure/
- ADR-0020: Provider-Leading Client Design

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

* fix: missing Agent imports in samples, .model_id → .model in foundry_local sample

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

* fix: CI failures — mypy errors, coverage targets, sample imports

- azure-ai mypy: add type ignores for TypedDict total=, model arg, forward ref
- Coverage: replace core.azure/openai targets with openai package target
- project_provider: add type annotation for opts dict

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

* fix: populate openai .pyi stub, fix broken README links, coverage targets

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

* fixes

* updated observabilitty

* reset azure init.pyi

* fix errors

* updated adr number

* fix foundry local

* fixed not renamed docstrings and comments, and added deprecated markers to old classes

* fix tests and pyprojects

* fix test vars

* updated function tests

* update durable

* updated test setup for functions

* Fix Foundry auth in workflow samples

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

* Stabilize Python integration workflows

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

* Update hosting samples for Foundry

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

* Trigger full CI rerun

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

* Trigger CI rerun again

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

* trigger rerun

* trigger rerun

* fix for litellm

* undo durabletask changes

* Move Foundry APIs into foundry namespace

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

* Fix Foundry pyproject formatting

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

* Split provider samples by Foundry surface

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

* Restore hosting sample requirements

Also fix the Foundry Local sample link after the provider sample move.

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

* updated tests

* udpated foundry integration tests

* removed dist from azurefunctions tests

* Use separate Foundry clients for concurrent agents

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

* fix client setup in azfunc and durable

* disabled two tests

* updated setup for some function and durable tests

* improved azure openai setup with new clients

* ignore deprecated

* fixes

* skip 11

* remove openai assistants int tests

---------

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

5e056b672e · 2026-03-25 09:56:29 +00:00

History

code_defined_skill

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

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

file_based_skill

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

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

mixed_skills

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

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

script_approval

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

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

README.md

Python: Support skill scripts execution (#4558 )

2026-03-11 18:28:30 +00:00

subprocess_script_runner.py

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

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

README.md

Agent Skills Samples

These samples demonstrate how to use Agent Skills — modular packages of instructions, resources, and scripts that extend an agent's capabilities. Skills follow the Agent Skills specification and use progressive disclosure to optimize token usage.

Learning Path

Start with file-based or code-defined skills, then explore combining them and adding approval workflows.

Sample	Description
file_based_skill	Define skills as `SKILL.md` files on disk with reference documents and executable scripts. Uses the unit-converter skill.
code_defined_skill	Define skills entirely in Python code using `Skill`, `@skill.resource`, and `@skill.script` decorators. Uses a code-defined unit-converter skill.
mixed_skills	Combine code-defined and file-based skills in a single agent. Uses a code-defined volume-converter and a file-based unit-converter.
script_approval	Require human-in-the-loop approval before executing skill scripts

Key Concepts

Progressive Disclosure

Skills use a three-step interaction model to minimize token usage:

Advertise — Skill names and descriptions (~100 tokens each) are injected into the system prompt
Load — Full instructions are loaded on-demand via the load_skill tool
Access — Resources are read via read_skill_resource; scripts are executed via run_skill_script

File-Based vs Code-Defined Skills

Aspect	File-Based	Code-Defined
Definition	`SKILL.md` files on disk	`Skill` instances in Python
Resources	Static files in `references/` and `assets/` directories	Callable functions via `@skill.resource` decorator
Scripts	Python files in `scripts/` directory (executed via subprocess)	Callable functions via `@skill.script` decorator (executed in-process)
Discovery	Automatic via `skill_paths` parameter	Explicit via `skills` parameter
Dynamic content	No (static files only)	Yes (functions can generate content at runtime)

Both types can be combined in a single SkillsProvider — see the mixed_skills sample.

Script Execution

Skills can include executable scripts. How a script runs depends on how it was defined:

	Code-Defined Scripts	File-Based Scripts
Defined via	`@skill.script` decorator	`.py` files in `scripts/` directory
Execution	In-process (direct function call)	Delegated to a `script_runner`
`script_runner` needed?	No — runs in-process automatically	Yes — required

The script_runner parameter on SkillsProvider is only applicable to file-based scripts. Code-defined scripts are always executed in-process regardless of this setting. See file_based_skill for an example using a SkillScriptRunner callable with a subprocess runner, and code_defined_skill for in-process scripts that need no runner.

Prerequisites

All samples require:

An Azure AI Foundry project with a deployed model (e.g. gpt-4o-mini)
Azure CLI authentication (az login)
Environment variables set in a .env file (see python/.env.example)