Python: Fix PropertySchema.to_json_schema() not recursing into nested array items / object properties by exp-ouroborous · Pull Request #7200 · microsoft/agent-framework

exp-ouroborous · 2026-07-19T15:28:10Z

Motivation and Context

PropertySchema.to_json_schema() renames kind → type (and drops empty enum placeholders) only in its top-level properties loop. Nested schemas — array items, nested object properties (which serialize in the named-list shape) — keep kind and empty enum, producing JSON Schema that OpenAI rejects ("schema must have a 'type' key"). Reproduced on 1.0.0rc2.

Description

Fixes Python: [Bug]: PropertySchema.to_json_schema() doesn't recurse into array items — nested "kind" not renamed to "type", nested empty "enum" kept #7198
Adds _normalize_nested_schemas / _normalize_schema_node: recursively applies the same conversion the top-level loop performs — kind → type, empty-enum removal, named-list properties → dict with a required array — at every depth.
Minimal repro from the issue now produces "items": {"type": "string"} instead of "items": {"kind": "string", "enum": []}.
New tests: array-of-strings items, array-of-objects with nested properties.

Contribution Checklist

The code builds clean without any errors or warnings
The PR follows the Contribution Guidelines
All unit tests pass, and I have added new tests where possible (test_declarative_models.py: 98 passed)
Is this a breaking change? No — previously-invalid output becomes valid; schemas without nesting are byte-identical.

Copilot

Pull request overview

This pull request addresses a Python bug in PropertySchema.to_json_schema() where nested schemas (array items, nested object properties) were not normalized (kind→type, empty enum removal), producing JSON Schema that structured-output providers reject. The change set also introduces a sizeable set of new “research” docs and a new .NET learning/sandbox project (dotnet/learn/AgentLearn), plus repo-level editor/gitignore tweaks.

Changes:

Python: add recursive schema normalization for nested items / properties, and add regression tests.
Add dotnet/learn/AgentLearn sample app + integration tests for learning framework workflows/HITL/OTel.
Add research/ documentation and VS Code / gitignore convenience updates.

Reviewed changes

Copilot reviewed 40 out of 41 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
research/README.md	Adds a top-level README describing the `research/` folder.
research/python/agentic-capabilities.md	Adds Python agentic capabilities research document.
research/dotnet/agentic-capabilities.md	Adds .NET agentic capabilities research document.
research/agentic-capabilities-overview.md	Adds cross-language agentic capabilities overview research document.
python/packages/declarative/tests/test_declarative_models.py	Adds regression tests for nested schema normalization.
python/packages/declarative/agent_framework_declarative/_models.py	Implements recursive nested schema normalization in `to_json_schema()`.
dotnet/samples/run.bash	Adds helper script to run a .NET sample with `.env` variables loaded.
dotnet/learn/README.md	Adds documentation for the new AgentLearn project.
dotnet/learn/Directory.Packages.props	Disables central package management within `dotnet/learn`.
dotnet/learn/Directory.Build.targets	Isolates learn projects from parent build targets.
dotnet/learn/Directory.Build.props	Isolates learn projects from parent build props.
dotnet/learn/CLAUDE.md	Adds project guidance/conventions for `dotnet/learn`.
dotnet/learn/AgentLearn/tests/integration/StoryGeneratorWorkflowTests.cs	Adds HITL workflow integration tests.
dotnet/learn/AgentLearn/tests/integration/MockChatClientHelper.cs	Adds shared mock `IChatClient` helper for integration tests.
dotnet/learn/AgentLearn/tests/integration/JokeWriterWorkflowTests.cs	Adds workflow integration tests for single/sequential/concurrent joke flows.
dotnet/learn/AgentLearn/tests/integration/AgentLearn.IntegrationTests.csproj	Adds integration test project definition.
dotnet/learn/AgentLearn/TaskKinds/StoryGenerator/StoryGenerator.http	Adds REST client requests for StoryGenerator.
dotnet/learn/AgentLearn/TaskKinds/StoryGenerator/StoryGenerator.cs	Adds StoryGenerator task kind (models/executors/agent/workflow/handler/DI).
dotnet/learn/AgentLearn/TaskKinds/JokeWriter/JokeWriter.http	Adds REST client requests for JokeWriter.
dotnet/learn/AgentLearn/TaskKinds/JokeWriter/JokeWriter.cs	Adds JokeWriter task kind (models/executors/agents/workflows/handler/DI).
dotnet/learn/AgentLearn/Services/ITaskHandler.cs	Adds task-handler abstraction for dispatching requests by kind.
dotnet/learn/AgentLearn/Services/ChatClientFactory.cs	Adds multi-provider `IChatClient` factory + mock client.
dotnet/learn/AgentLearn/run.sh	Adds dev runner that starts Jaeger and runs AgentLearn.
dotnet/learn/AgentLearn/Properties/launchSettings.json	Adds local launch profiles for AgentLearn.
dotnet/learn/AgentLearn/Program.cs	Wires DI, OpenTelemetry, DevUI, OpenAI-compatible endpoints, and controllers.
dotnet/learn/AgentLearn/Models/TaskResponse.cs	Adds `/task` response DTO.
dotnet/learn/AgentLearn/Models/TaskRequest.cs	Adds `/task` request DTO.
dotnet/learn/AgentLearn/Models/TaskKind.cs	Adds task-kind enum for dispatch.
dotnet/learn/AgentLearn/Models/LlmOptions.cs	Adds configuration model for LLM provider selection.
dotnet/learn/AgentLearn/Models/AgentMode.cs	Adds workflow mode enum.
dotnet/learn/AgentLearn/Extensions/AIAgentBuilderExtensions.cs	Adds tool-invocation logging middleware extension.
dotnet/learn/AgentLearn/Controllers/TaskController.cs	Adds `/task` controller that routes to `ITaskHandler`s.
dotnet/learn/AgentLearn/CLAUDE.md	Adds AgentLearn-specific contributor guidance.
dotnet/learn/AgentLearn/appsettings.json	Adds default configuration for AgentLearn.
dotnet/learn/AgentLearn/appsettings.Development.json	Adds dev configuration (incl. debug logging).
dotnet/learn/AgentLearn/AgentLearn.csproj	Adds AgentLearn project definition and package references.
dotnet/learn/AgentLearn.sln	Adds solution file for AgentLearn.
dotnet/learn/.gitignore	Adds ignore rules for local `.env` variants.
CLAUDE.md	Adds/updates repo-level contributor guidance for Claude.
.vscode/settings.json	Sets VS Code `dotnet.defaultSolution`.
.gitignore	Ignores `.workspaces/` directory.

… schemas Nested array 'items' and object 'properties' kept the declarative 'kind' key and empty 'enum' placeholders, producing JSON Schema OpenAI rejects ('schema must have a type key'). Recursively apply the same conversion the top-level properties loop performs, including the serialized named-list properties shape and nested required arrays. Fixes microsoft#7198 (cherry picked from commit c156ffd)

…ial conversion Review feedback: the list-shaped properties branch popped name/required from each element and returned on the first unexpected one, leaving earlier elements half-converted. Validate the whole list first so an unexpected shape leaves the node fully untouched.

exp-ouroborous · 2026-07-19T15:51:04Z

Note for reviewers: the other review threads (research/, dotnet/learn/, .vscode/settings.json) referenced unrelated files that were accidentally included from a stale fork base — the branch has been rebuilt as a single commit on top of main and those files are no longer part of this PR (now 2 files: _models.py + its tests).

exp-ouroborous · 2026-07-19T15:52:24Z

@microsoft-github-policy-service agree

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

github-actions · 2026-07-20T21:53:14Z

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/declarative/agent_framework_declarative
_models.py	514	28	94%	28, 31, 64, 69, 230, 235, 237–239, 552, 618, 626, 630, 653, 679, 703, 731, 841, 903, 1011, 1137, 1139, 1141, 1143, 1145, 1147, 1151, 1153
TOTAL	44713	5216	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9083	33 💤	0 ❌	0 🔥	2m 15s ⏱️

peibekwe · 2026-07-20T22:02:20Z

+        node["properties"] = new_props
+        if required_fields:
+            node["required"] = required_fields
+    elif isinstance(props, dict):


This branch looks unreachable via to_json_schema : ObjectProperty.properties is always stored/serialized as a named list, so nested properties is a list here, never a dict.

peibekwe · 2026-07-20T22:05:32Z

@exp-ouroborous thank you for authoring this fix. Can you please take a look at the comment and the Pyright type-check error failures.

Copilot AI review requested due to automatic review settings July 19, 2026 15:28

giles17 added documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python .NET Usage: [Issues, PRs], Target: .Net labels Jul 19, 2026

github-actions Bot changed the title ~~Python: Fix PropertySchema.to_json_schema() not recursing into nested array items / object properties~~ .NET: Python: Fix PropertySchema.to_json_schema() not recursing into nested array items / object properties Jul 19, 2026

Copilot started reviewing on behalf of exp-ouroborous July 19, 2026 15:28 View session

Copilot AI reviewed Jul 19, 2026

View reviewed changes

Comment thread python/packages/declarative/agent_framework_declarative/_models.py

Comment thread research/README.md Outdated

Comment thread .vscode/settings.json Outdated

Comment thread dotnet/learn/AgentLearn/AgentLearn.csproj Outdated

exp-ouroborous force-pushed the fix/property-schema-nested-items branch from c156ffd to 53784b0 Compare July 19, 2026 15:32

exp-ouroborous marked this pull request as ready for review July 19, 2026 15:52

exp-ouroborous requested a review from Copilot July 19, 2026 21:25

Copilot started reviewing on behalf of exp-ouroborous July 19, 2026 21:26 View session

Copilot AI reviewed Jul 19, 2026

View reviewed changes

exp-ouroborous changed the title ~~.NET: Python: Fix PropertySchema.to_json_schema() not recursing into nested array items / object properties~~ Python: Fix PropertySchema.to_json_schema() not recursing into nested array items / object properties Jul 19, 2026

peibekwe reviewed Jul 20, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Python: Fix PropertySchema.to_json_schema() not recursing into nested array items / object properties#7200

Python: Fix PropertySchema.to_json_schema() not recursing into nested array items / object properties#7200
exp-ouroborous wants to merge 2 commits into
microsoft:mainfrom
exp-ouroborous:fix/property-schema-nested-items

exp-ouroborous commented Jul 19, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

exp-ouroborous commented Jul 19, 2026

Uh oh!

exp-ouroborous commented Jul 19, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions Bot commented Jul 20, 2026

Uh oh!

peibekwe Jul 20, 2026

Uh oh!

peibekwe commented Jul 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

exp-ouroborous commented Jul 19, 2026

Motivation and Context

Description

Contribution Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

exp-ouroborous commented Jul 19, 2026

Uh oh!

exp-ouroborous commented Jul 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

github-actions Bot commented Jul 20, 2026

Python Unit Test Overview

Uh oh!

peibekwe Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

peibekwe commented Jul 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants