github-featured/microsoft--agent-framework

Files

T

History

Eduard van Valkenburg 6e95517659 Python: Split type checkers by target (pyright source, 5 checkers on tests/samples) (#6443 )

* Python: Split type checkers by target (pyright source, 5 checkers on tests/samples)

Rework the typing setup along the lines of the 'too many type checkers'
approach:

- Pyright (strict) is now the sole source-code type checker; mypy is
  removed from source and its [tool.mypy] block becomes a relaxed profile
  used only for tests/samples.
- Tests are checked by all five checkers (pyright relaxed, mypy, pyrefly,
  ty, zuban); samples by pyright, pyrefly, and ty. All run in a relaxed/
  basic profile so authors aren't forced into over-annotation.
- Add pyrightconfig.tests.json and bump sample pyright configs to basic.
- Unify test/sample typing onto the same parallel fan-out used by source
  pyright via run_command_items in task_runner.py.
- Make version-conditional imports symmetric: keep or drop the
  '# type: ignore' on both branches so results match across interpreter
  versions (local vs CI).
- Update SKILL.md, DEV_SETUP.md, and CODING_STANDARD.md for the five
  gating checkers and pyright on source+tests+samples.

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

* Python: Fix merge regressions from main (typing + runtime)

Merging main into the type-checker split branch surfaced regressions that
the new five-checker test suite and unit tests caught:

Runtime fixes:
- anthropic: restore the dropped `cache_read_input_token_count` mapping in
  _parse_usage_from_anthropic (lost during merge conflict resolution).
- gemini: _get_function_calling_mode test helper returned str(enum)
  ('FunctionCallingConfigMode.AUTO') instead of the enum value ('AUTO').
- openai: _response_id_from_token test helper was an infinite self-recursion;
  return token['response_id'].
- orchestrations: reset output_events per approval iteration so the terminal
  output assertion counts only the final run.
- core: drop a stale duplicate harness test whose message ('non-negative')
  contradicted the source ('positive').
- purview: import PolicyLocation/PolicyScope/ProtectionScopeActivities/
  ExecutionMode used by the processor tests.

Type-checker fixes (tests, relaxed profile):
- core: pyright/mypy/pyrefly/ty/zuban green-ups across the harness, MCP,
  observability and types tests.
- anthropic/openai: route provider-namespaced UsageDetails keys through a
  dict cast (extra_items TypedDict unsupported by mypy/ty).
- purview: typed model constructors and cache-mock casts.
- ag-ui: annotate WorkflowContext[Any, Any] so yield_output accepts test
  payloads, guard Optional forwarded_props, and ty-ignore intentional bad args.

Source pyright (sole source checker) flagged unnecessary ignores newly
introduced by merged code in core _tools.py and declarative _declarative_base.py.

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

* Python: Isolate per-package mypy cache in test-typing fan-out

The parallel test-typing fan-out runs many mypy processes concurrently,
all defaulting to a single shared ./.mypy_cache. Concurrent writes corrupt
the cache and mypy aborts with INTERNAL ERROR (intermittently, depending on
worker timing) -- which is why CI's Test Typing job failed on a shifting set
of packages while a single-package run was fine.

Give each mypy invocation an isolated cache dir keyed by its target paths so
incremental caching still works per package without races. Other checkers
(zuban/pyrefly/ty/pyright) maintain their own caches and are unaffected.

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

* Python: Make lab pyright-only on source (drop source mypy)

Lab was the last package still running mypy on its source code, requiring
mypy-only `# type: ignore` comments that pyright (the sole source checker
everywhere else) flags as unnecessary. Align lab with the rest of the
monorepo:

- Remove the lab source mypy poe tasks (mypy-gaia/lightning/tau2) and the
  now-dead strict [tool.mypy] config block.
- Drop the 'Run lab mypy' CI step; lab source is type-checked by pyright only.

Lab tests remain covered by the workspace test-typing fan-out (mypy, pyrefly,
ty, zuban, pyright over tests using the relaxed root config).

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

* Python: Fix test-typing regressions from latest main merge

A fresh merge from main brought in new test code never run under the
five-checker test-typing suite. Green up across the affected packages:

- core: narrow Optional span.attributes with 'and' guards in span filters
  and assert+cast the json.loads(...attributes[...]) reads (test_observability);
  match the existing as_agent ignore on the protocol-typed fixture (test_clients).
- openai: align new streaming tests with the established chat_options dict
  pattern (ChatOptions TypedDict isn't assignable to dict), route Optional
  .annotations[0] access through a small _first_annotation helper (mirrors the
  file's assert-not-None convention), and annotate a mapped ResponseStream.
- foundry_hosting: annotate error: dict[str, Any] = body.get(...) or {}
  (zuban needs the annotation).
- foundry: narrow ignores for the live AIProjectClient credential arg (pyrefly)
  and connections.get_default (zuban) SDK type gaps.

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

* updated pyright version

* pyright fix

* Python: Fix source typing for pyright 1.1.410

Pyright 1.1.410 tightened several checks. Apply the same source fixes as
upstream PR #6275:

- anthropic: import AsyncAnthropicBedrock from anthropic.lib.bedrock and
  AsyncAnthropicVertex from anthropic.lib.vertex (no longer re-exported from
  the anthropic top-level package -> reportPrivateImportUsage).
- core _types.py: cast the transform-hook result to UpdateT (reportAssignmentType).
- core _workflows/_events.py: annotate the @contextmanager helper as
  Generator[None] instead of Iterator[None] (reportDeprecated).
- redis: build the combined filter expression with an explicit loop instead of
  reduce(and_, ...), which pyright could no longer fully type (drops the now
  unused functools.reduce / operator.and_ imports).

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

* Python: Accept plain-text body in Azure Functions workflow/run endpoint

The workflow_orchestrator already accepts plain strings as well as JSON
objects via context.get_input(), but the start_workflow_orchestration HTTP
handler only accepted JSON and returned 400 for any non-JSON body. This made
the functions integration tests that POST text/plain to /api/workflow/run
(e.g. test_09_workflow_shared_state) fail consistently with 400 != 202.

Fall back to the raw request body (decoded as UTF-8) when the body is not
JSON, rejecting only a truly empty body. The JSON path is unchanged.

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

---------

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

2026-06-18 15:06:20 +00:00

class_based_skill

…

code_defined_skill

…

file_based_skill

Python: Split type checkers by target (pyright source, 5 checkers on tests/samples) (#6443 )

2026-06-18 15:06:20 +00:00

mcp_based_skill

…

mixed_skills

Python: Split type checkers by target (pyright source, 5 checkers on tests/samples) (#6443 )

2026-06-18 15:06:20 +00:00

script_approval

Python: Split type checkers by target (pyright source, 5 checkers on tests/samples) (#6443 )

2026-06-18 15:06:20 +00:00

skill_filtering

Python: Split type checkers by target (pyright source, 5 checkers on tests/samples) (#6443 )

2026-06-18 15:06:20 +00:00

README.md

…

subprocess_script_runner.py

…

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.
class_based_skill	Define skills as Python classes using `ClassSkill` with `@ClassSkill.resource` and `@ClassSkill.script` decorators for auto-discovery. Uses a class-based unit-converter skill.
mixed_skills	Combine code-defined, class-based, and file-based skills in a single agent. Uses a code-defined volume-converter, a class-based temperature-converter, and a file-based unit-converter.
mcp_based_skill	Discover skills served over the Model Context Protocol (MCP) via `MCPSkillsSource`. Connects to a remote MCP server that exposes skills as `skill://...` resources following the SEP-2640 convention.
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 vs Class-Based Skills

Aspect	File-Based	Code-Defined	Class-Based
Definition	`SKILL.md` files on disk	`Skill` instances in Python	Classes extending `ClassSkill`
Resources	Static files in `references/` and `assets/` directories	Callable functions via `@skill.resource` decorator	`@ClassSkill.resource` decorator (auto-discovered)
Scripts	Python files in `scripts/` directory (executed via subprocess)	Callable functions via `@skill.script` decorator (executed in-process)	`@ClassSkill.script` decorator (executed in-process)
Discovery	Automatic via `skill_paths` parameter	Explicit via `skills` parameter	Explicit via `skills` parameter
Dynamic content	No (static files only)	Yes (functions can generate content at runtime)	Yes (functions can generate content at runtime)
Sharing pattern	Copy skill directory	Inline or shared instances	Package in shared libraries/PyPI

All three 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)

Suppressing the experimental warning

The Agent Skills APIs in these samples are still experimental. Each sample includes a short commented warnings.filterwarnings(...) snippet near the imports. Uncomment it if you want to suppress the Skills warning before using the experimental APIs.