oracle / oracle/agent-spec

[Spec] How should a child task's input-required state propagate through a parent FlowNode?

Open
#183 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
421
Forks
60
Avg merge
9h 30m
Merged PRs (30d)
4

Description

Per the A2A spec ll. 1056–1059, an input-required task is resumable by sending a new message with the same taskId / contextId. The Agent Spec doesn't define the parent-flow side of this contract when a FlowNode invokes a child agent over A2A.

Scenario

Parent flow A contains a FlowNode that invokes agent B. Agent B reaches an InputMessageNode and yields input-required. What is the parent A expected to do?

a) Pause its own run and surface B's pending input to A's client (nested HITL propagation)
b) Treat the child pause as a leaf event and continue A's flow (fire-and-forget)
c) Implementation-defined

The spec is silent. Implementations diverge. In practice this matters whenever an agent composes a sub-agent that itself contains a HITL gate — a very common pattern for orchestrators that delegate to leaf agents with operator approval steps.

Why filing as spec-level

The A2A protocol covers the bilateral task contract. The Agent Spec's FlowNode is the natural place to nail down "what happens when the invoked agent returns input-required" — it sits exactly at that protocol seam.

Possible answers worth documenting in the spec

  • A FlowNode MUST propagate the child's input-required to its own client, mirroring the contract for InputMessageNode (most explicit option)
  • A FlowNode MAY declare propagate_pending_input: true | false per-node (gives flow authors a choice)
  • The parent run's status transitions when a child A2A task yields are normatively defined for each child task state

Current consequence

Without a defined contract, every implementation either:

  • Reinvents nested-HITL surfacing (real platform work — runtime needs to render child task state in the parent's UI)
  • Falls back to operationally-deep-linked separate runs ("open this in a new tab, then return")

Both are workable, but they produce very different UX and authoring contracts depending on which runtime the same OAS file targets.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with A2A spec lines 1056–1059 and the Agent Spec definitions for FlowNode and InputMessageNode. Compare the three proposed propagation behaviors and determine the parent status and client-facing contract for each relevant child task state. Done means the chosen behavior and its authoring implications are stated normatively in the spec.

Written by the indexing model from the issue text.

Assessment

Domain
backend-api-design, distributed-systems, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.