Skip to content

Python: expose CodeAct tool parameter schemas - #26

Closed
eavanvalkenburg wants to merge 8 commits into
mainfrom
hyperlight-tool-schemas
Closed

Python: expose CodeAct tool parameter schemas#26
eavanvalkenburg wants to merge 8 commits into
mainfrom
hyperlight-tool-schemas

Conversation

@eavanvalkenburg

@eavanvalkenburg eavanvalkenburg commented Sep 17, 2026

Copy link
Copy Markdown
Owner

Motivation & Context

Hyperlight and Monty currently list registered host-tool names in their CodeAct guidance but omit requiredness, types, parameter descriptions, enum values, and nested schema details. Models therefore lack enough information to reliably call tools unless developers repeat the contract in tool-level descriptions.

This change exposes that existing schema metadata while letting applications balance completeness and prompt size. It addresses the Python portion of microsoft#8125; the separate .NET work remains tracked in microsoft#8446.

Description & Review Guide

  • What are the major changes? Added a private core helper that returns structured compact parameter metadata or the complete JSON Schema when compact rendering would be lossy. Added one tool_description_format option to the Hyperlight and Monty standalone tools and context providers. It accepts "compact", "json", or a per-tool mapping; compact is the default and missing mapping entries use compact. Both packages preserve configuration in run-scoped snapshots and serialized state, with Monty applying it to both tool descriptions and context instructions. Tests and package documentation cover rendering, fallback, validation, mapping copies, and lifecycle behavior.
  • What is the impact of these changes? Simple scalar tools receive concise parameter contracts by default. Complex constraints automatically fall back to complete JSON Schema with an explicit note instead of silently losing metadata. Sandbox execution, approvals, input schemas, caches, Monty type stubs, and runtime capabilities are unchanged.
  • What do you want reviewers to focus on? Please review the conservative compact-schema eligibility rules and the single string-or-mapping API. This is a draft because Hyperlight and Monty must raise their agent-framework-core minimum to the release that first contains the shared helper; that future core version has not yet been assigned, so this PR intentionally does not guess a dependency floor.

Related Issue

Closes microsoft#8445

Partially addresses microsoft#8125. The .NET portion remains open in microsoft#8446.

No other open PR was found for microsoft#8445.

Contribution Checklist

  • The code builds clean without any errors or warnings
  • All unit tests pass, and I have added new tests where possible
  • The PR follows the Contribution Guidelines
  • This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
  • This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

Lubaoshuai and others added 8 commits September 17, 2026 08:15
@Lubaoshuai @moonbox3
Python: exclude encrypted reasoning payloads from compaction token co…
d90355f 
…unts (microsoft#8354)

* Python: exclude encrypted reasoning payloads from compaction token counts

The compaction token counter serialises each message and tokenises the JSON.
Content.protected_data (OpenAI encrypted_content, Anthropic thinking
signature, Gemini thought_signature, OpenAI reasoning_details) is opaque
ciphertext the model replays but never tokenises, so counting it inflated
every token-aware compaction decision. The same blob can also ride in
additional_properties as encrypted_content.

Both are now excluded from serialised content, matching the existing
exclusions for raw_representation and mirrored items.

Fixes microsoft#8348

* fix(compaction): count clear-text reasoning details and invalidate stale token caches

Review follow-up for the protected-data token exclusion:

- reasoning_details stored in protected_data are JSON-serialised and
  replayed to the provider as clear text (summary, reasoning_text and
  nested reasoning.text), so only opaque members (encrypted_content) are
  excluded from the estimate; non-JSON payloads (Anthropic signature,
  Responses API encrypted blobs) are still dropped entirely.
- group token counts are stamped with a serialization basis version;
  counts cached under an older basis (e.g. sessions annotated before a
  serialization change) are recomputed instead of reused.

* fix(compaction): resolve pyright/mypy typing errors in token estimation

- annotate the recursive reasoning-payload filter with explicit
  dict[Any, Any] / list[Any] casts so iterating the narrowed Any dict
  does not leak Unknown types under pyright strict
- cast additional_properties before the encrypted_content filter
- assert non-None token counts in the clear-text regression test so the
  ordering comparison does not involve optional integers

---------

Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
@eavanvalkenburg
Python: preserve approval context across resume paths (microsoft#8433)
f187b68 
* Python: fix mixed function-call batch classification

* Python: scope mixed pause correlation

* Python: preserve streaming approval updates

* Python: preserve approval resume context

* Python: address approval resume review feedback

* Python: harden mixed approval replay

* Python: keep stateless mixed approvals inert
@FOWEPJF255 @lhl-lhi
@ktz03 @eavanvalkenburg
Python: include checkpoint_id on AG-UI interrupt metadata (microsoft#…
3b110ad 
…8150) (microsoft#8163)

* Python: include checkpoint_id on AG-UI interrupt metadata (microsoft#8150)

Attach the pause workflow checkpoint id to RUN_FINISHED interrupt
metadata.agent_framework so multi-worker clients can resume via
forwardedProps.checkpoint_id without a side channel.

* Python: Prefer runner pause checkpoint over shared get_latest (microsoft#8150)

* Python: Fix ag-ui lint and ty ignores for microsoft#8150 tests

* Python: Core resolve_pause_checkpoint_id for AG-UI (microsoft#8150)

Move pause-checkpoint selection into Workflow and require a run-scoped
baseline so leftover runner ids are not advertised across runs.

* fix(python): resolve pyright failures in pause checkpoint lookup

Unblocks Package Checks / merge-gatekeeper on PR microsoft#8163.

* fix(ag-ui): address microsoft#8163 review on pause checkpoint ownership (#2)

- Workflow captures run baseline / restored id inside run(); resolve uses them
  so callers need not thread baseline_checkpoint_id.
- Exclude restored checkpoint from pause candidates after resume.
- Drop issue reference in docstring; emit RUN_FINISHED via existing
  _build_run_finished_event after attaching pause id.
- Move core pause-resolve coverage into test_workflow.py (no new test file).

* fix(ag-ui): resume builder-storage pause IDs without AG-UI storage

When checkpoint_id+resume is supplied, load pending requests from the workflow's effective builder/runtime storage if AG-UI was not given an explicit checkpoint_storage, so emitted pause IDs remain round-trippable.

* fix(ag-ui): silence ty invalid-argument-type on builder-storage resume test

Match existing yield_output ignore markers so Test Typing Checks accept the new resume round-trip coverage.

* fix(ag-ui): resume builder storage via AgentFrameworkWorkflow.run()

Allow forwardedProps.checkpoint_id when only WorkflowBuilder storage is configured, so wrapper/endpoint hosts round-trip pause ids without duplicating checkpoint_storage.

---------

Co-authored-by: minelhi <3417378192@qq.com>
Co-authored-by: LI <2484593937@qq.com>
Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>
@SergeyMenshykh @moonbox3
.NET/Python: Refine skill frontmatter parsing (microsoft#8430)
52e03cb 
* Reject ambiguous skill frontmatter fields in Python and .NET

Validate recognized top-level field casing and uniqueness while preserving existing scalar parsing and nested metadata behavior. Add file and MCP archive regression coverage.

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

* Keep first duplicate skill metadata value in Python and .NET

Warn on duplicate metadata entries without rejecting skills, preserve existing key comparison rules, and expand scalar and archive regression coverage.

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

* Preserve unset optional skill frontmatter fields

Keep bare empty optional fields null while retaining duplicate and casing validation in Python and .NET. Add file and MCP archive regression coverage.

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

* Support quoted skill frontmatter property names

Normalize single- and double-quoted root names before existing field validation in Python and .NET. Support quoted metadata headers and expand scalar and archive regression coverage.

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

* Use PyYAML for Python skill frontmatter parsing

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

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
@westey-m @eoindoherty1
.NET/Python: Add more content types to purview handling (microsoft#8370)
a3fc29d 
* Add more content types to purview handling

* Address PR comments

* Split Purview content processing requests

Create one processContent request per content entry in both .NET and Python while preserving the Graph contentEntries array contract.

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

* Skip empty Purview content

Avoid sending empty text or binary data to Graph processContent APIs in both .NET and Python.

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

* Address PR comments

---------

Co-authored-by: Eoin Doherty <eoindoherty@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@eavanvalkenburg
Python: Add per-tool AgentModeProvider exposure controls (microsoft#8450
0c07eb6 
)

* Python: Add mode tool exposure controls

* Python: Support replacement mode state updates

* Python: Clear stale mode notifications
@eavanvalkenburg
Python: expose instrumentation message event control (microsoft#8451)
63aacbb
@eavanvalkenburg
Python: expose CodeAct tool parameter schemas
df62c2a
@eavanvalkenburg

eavanvalkenburg commented Sep 17, 2026

Copy link
Copy Markdown
Owner Author

Closing because this PR was created against the fork instead of microsoft/agent-framework. The replacement targets upstream main.

This branch had an error being deployed

1 failed and 1 inactive deployments
integration — df62c2a1 Deployed Sep 17, 2026 by eavanvalkenburg via dotnet-test (net10.0, ubuntu-latest, Release, true, integration) #612
github-app-auth — df62c2a1 Deployed Sep 17, 2026 by eavanvalkenburg via team_check #34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Python: Hyperlight and Monty host-tool schema rendering with format selection

5 participants

@eavanvalkenburg @Lubaoshuai @FOWEPJF255 @SergeyMenshykh @westey-m