pltbkd opened a new pull request, #938: URL: https://github.com/apache/flink-agents/pull/938
Design discussion: #909 ### Purpose of change Introduces `AGENT` as a first-class resource type and the caller-facing sub-agent invocation API across Java / Python / YAML, per discussion #909. `SubagentSetup` is the general sub-agent framework. This PR lands the framework and the one way to plug into it today: a custom `SubagentSetup` implementation. Registering an `Agent` directly as an internal sub-agent is a follow-up addition. Included: - `ResourceType.AGENT`; register via `addResource(name, AGENT, setup)` and via YAML `subagents:`. - `Subagent` (caller interface) + `SubagentSetup` (base) + `Result` + `BaseSubagentCallable` (captures failures into `Result`). - `call()` / `asAsyncCallable()` run through durable execution; a deterministic `(sessionId, callId)` identity lets failover replay reuse cached results instead of re-invoking. Use `asAsyncCallable()` instead of `callAsync()` to support batch async execution. - `sessionId` is framework-generated and deterministic; callers may pass their own to continue a session. `callId` is auto-generated from the per-session conversation ordinal. Evolved from the #909 proposal during review: - `Result` carries a serializable `errorMessage` (the failure's full stack trace) instead of a live `Exception`, so it survives durable persistence. - The durable id is derived solely from `(sessionId, callId)`. ### Notes - Follow-up additions: **ChatModel calling sub-agents** (sub-agent-as-tool dispatch), and **internal sub-agent** (registering an `Agent` directly as an `AGENT` resource, compiled into a scoped child plan, and its isolated execution). - **Cross-language execution** (an action calling a sub-agent implemented in the other language) is not supported yet; registration round-trips across the plan-JSON boundary, execution will be added later. - **Timeout / cancellation** semantics are not included yet; planned as a follow-up. - `Result` and the parallel async primitive (`executeAllAsync`) overlap with Parallel Tool Execution (#926) and can be aligned/iterated during review. ### Tests - **Java unit**: AGENT registration, plan compilation (`SubagentSetup` + YAML descriptor), and deterministic-id context / failover-recovery / operator-integration tests. - **Python unit**: mirrors the Java surface (registration, plan resources, id delegation). - **e2e**: `ExternalSubagentTest` — programmatic and YAML-declared sub-agent invocation (including failure surfaced via `Result`) on a real Flink job. ### API Additive public API, kept semantically aligned across Java / Python / YAML: `ResourceType.AGENT`, `Subagent`, `SubagentSetup`, `Result`, `BaseSubagentCallable`, `RunnerContext#nextSessionId()` / `nextCallId(sessionId)`, and the YAML `subagents:` block. No breaking changes to existing APIs. ### Documentation <!-- Do not remove this section. Check the proper box only. --> - [x] `doc-needed` but deferred: add once the internal sub-agent lands and the API stabilizes - [ ] `doc-not-needed` - [ ] `doc-included` -- 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]
