rob-9 opened a new pull request, #1200:
URL: https://github.com/apache/flink-agents/pull/1200
Linked issue: #1139; umbrella: #1134. Includes the #1138 prerequisite;
#1114/#1132 are incorporated through current main.
### Purpose of change
Let parent agents delegate reasoning and tool tasks to a ready-made
ReActAgent through explicit calls or model-selected tools.
#### Runtime flow
Create a child with `forSubagent` (Java) or `for_subagent` (Python),
register it as an `AGENT` resource, and invoke it with `{"prompt": "task"}`.
Its reasoning/tool loop uses scoped resources and invocation-local memory;
outputs return through `SubagentResult` or the parent's tool response.
#### Key decisions
Keep routing descriptions separate from child instructions, and child schema
prompts separate from parent schemas. Await internal calls cooperatively so
nested calls can progress with one async worker. Preserve durable call
identities and checkpoint only committed child state.
### Behavioral Semantics
#### Interaction decisions
| Invocation | No child output schema | Child output schema supplied |
|---|---|---|
| Explicit call | Text outputs in `SubagentResult` | Structured outputs in
`SubagentResult` |
| Model delegation | JSON-compatible tool response | Structured JSON tool
response |
#### Behavioral contracts
- Calls have isolated memory, including successive and nested invocations.
- Children resolve their own configuration, tools, skills, and schema
prompts; shared resources remain available.
- Waiting callers leave async workers available.
- Recovery restores in-flight calls and committed memory; recorded
model/tool results replay when action-state storage is configured.
- Callable metadata survives plan reconstruction.
- Cleanup closes owned resources; inherited resources remain open.
- Delegation metrics use the registered subagent name.
#### Failure behavior
Invalid factory metadata/schema declarations raise during construction.
Invalid prompts and child action failures return failed results with their
reason preserved; model delegation exposes error tool responses. Java
interruption propagates without recording terminal failure. Unfinished actions
restart after recovery, so external side effects outside durable calls can
repeat.
### Tests
| Contract | Coverage |
|---|---|
| Invocation paths and structured results | Java `ReActSubagentTest`; Python
ReAct end-to-end tests |
| Memory isolation | `ReActSubagentTest` |
| Child configuration, schemas, and skills | Java ReAct/MiniCluster tests;
Python scope/end-to-end tests |
| Single-worker and nested execution | Java concurrent-call tests; Python
runtime/end-to-end tests |
| Checkpoint recovery and replay | Java recovery harnesses; Python
durable-result tests |
| Metadata reconstruction | Agent-plan tests; Python
`test_chat_model_subagents.py` |
| Resource ownership | `ResourceCacheTest`; `InternalSubagentLifecycleTest`;
Python scope tests |
| Failure propagation | Java recovery tests; Python end-to-end tests |
| Delegation metrics | Java/Python tool-call tests;
`BuiltInExecutionMetricsTest` |
Validation: Java 267 passed, 12 skipped on JDK 21; Python end-to-end nine
passed; Python API/plan/runtime unit tests 1,140 passed, 14 skipped, two failed
because `ibm_watsonx_ai` is missing locally. Ruff, Spotless, and whitespace
checks passed.
Not verified: live model services, production-cluster recovery, or
cross-language delegation (#1141). Recovery tests use operator harnesses. Java
verification used JDK 21.
### API
Adds Java/Python ReAct subagent factories and Agent callable metadata.
Existing constructors remain available; child registration is explicit. Java
internal calls require JDK 21+ with continuation support; Python calling
actions must be async. Durable event keys now normalize polymorphic attributes
to preserve replay identity after serialization; restoring journals from older
code is not verified.
### Documentation
- [ ] `doc-needed`
- [ ] `doc-not-needed`
- [x] `doc-included`
Includes invocation examples, isolation/recovery behavior, runtime
requirements, and metrics.
### Was this patch authored or co-authored using generative AI tooling?
- [x] Yes
- [ ] No
Generated-by: Codex (GPT-6; exact build versions unavailable)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
