Skip to content

feat(subagents): add structured direct results - #373

Open
testikun wants to merge 2 commits into
openpi-dev:mainfrom
testikun:codex/issue-155-structured-subagent
Open

feat(subagents): add structured direct results#373
testikun wants to merge 2 commits into
openpi-dev:mainfrom
testikun:codex/issue-155-structured-subagent

Conversation

@testikun

@testikun testikun commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Problem

Direct Subagents can currently return only free-form assistant text. Callers that need typed review findings, research evidence, or test matrices must parse prose, while Workflow already has a private structured-result mechanism that Direct Subagents cannot reuse.

Closes #155.

Value

Callers can opt into a schema-validated Direct Subagent result without changing the default text path. The result is delivered as typed tool details and retained as a private, immutable content-addressed JSON artifact, giving downstream work an exact machine-readable handoff.

Approach

  • add optional output_schema to subagent_spawn;
  • extract Workflow's terminating structured_output tool into a shared child-safe primitive, preserving Workflow's existing artifact-budget behavior;
  • inject the tool and instruction only for opted-in runs, and fail closed if the child finishes without a valid submission;
  • bound structured schemas and values, persist complete JSON with a SHA-256 identity and mode 0600, and expose the structured value/artifact path through automatic delivery and explicit waits;
  • keep ordinary text-only Direct Subagent sessions unchanged.

Validation

  • bun run check — passed.
  • full Node 22 suite via node scripts/run-tests.mjs — 1,248 passed, 1 skipped, 0 failed.
  • Vitest suite — 30 passed, 0 failed.
  • focused Workflow compatibility and shared structured-output tests — 22 passed, 0 failed.

Impact

  • User-visible behavior: subagent_spawn accepts an optional output_schema; no UI changes.
  • Model-visible context/tools: opted-in children receive one terminating structured_output tool and one short instruction; default children do not.
  • Runtime/lifecycle: an opted-in run succeeds only after a valid structured submission and durable artifact write.
  • Persisted config/data: no config change; successful structured results add private content-addressed .json artifacts alongside existing subagent result artifacts.
  • Compatibility/risk: additive for Direct Subagents; the refactor preserves Workflow's prior schema tool, limits, and failure semantics.

@github-actions github-actions Bot added documentation Improvements or additions to documentation area:workflows Workflow engine, capability, skills, or tests area:subagents Subagent delegation, skills, or tests labels Sep 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:subagents Subagent delegation, skills, or tests area:workflows Workflow engine, capability, skills, or tests documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

subagents: 为 Direct Subagent 研究可选的结构化结果合同

1 participant