Repository navigation
fix(agentic): include inherited fields in supervisor argument descriptions - #6243
Merged
mariofusco merged 5 commits intoSep 3, 2026
Merged
mariofusco merged 5 commits into
mariofusco merged 5 commits into
Conversation
…tions SupervisorPlanner.argumentDescription() described an agent argument type using Class.getDeclaredFields() only, so for an output POJO that extends a base class the supervisor's request context omitted every inherited field — the planning LLM never saw those fields and could not route or populate them correctly. Walk the class hierarchy (superclass fields first, up to Object) and merge declared fields, with a subclass redeclaration shadowing the inherited one — the same semantics as the schema-generation fix in JsonSchemaElementUtils (langchain4j#6222). Records keep using their constructor parameters.
mariofusco
reviewed
Sep 1, 2026
mariofusco
reviewed
Sep 1, 2026
mariofusco
requested changes
Sep 1, 2026
mariofusco
left a comment
Collaborator
There was a problem hiding this comment.
Please review my comments. I also would appreciate if you could add a new integration test to check this fix end-to-end in SupervisorAgentIT.
- Rewrite fieldsIncludingInherited() recursively per review comment: collectFields() recurses to the superclass first, then appends each level's declared fields, letting a redeclared field shadow the inherited one by name - Rename SupervisorPlannerTest to SupervisorArgumentDescriptionTest to reflect that it covers the argument-description aspect only - Add an end-to-end integration test in SupervisorAgentIT: a sub-agent whose argument type extends a base class, verifying the supervisor fills the inherited field through the full plan -> arguments -> invocation pipeline
Collaborator
|
Please resolve conflicts. |
…ner-inherited-fields # Conflicts: # langchain4j-agentic/src/test/java/dev/langchain4j/agentic/SupervisorAgentIT.java
mariofusco
approved these changes
Sep 3, 2026
Snow7-G
added a commit
to Snow7-G/langchain4j
that referenced
this pull request
Sep 14, 2026
SupervisorPlanner built every agent card entry from AgentArgument.rawType(),
so a parameter declared as List<String> reached the renderer as List.class and
fell into the field walk. List is an interface with no declared fields, so the
argument came out as {}, leaving the planner to guess the shape of every
non-scalar argument.
Use the declared Type instead, and render generic collections, parameterized
maps, arrays and object types in a form the planner can act on. Classes keep
going through the existing logic, including the inherited-field walk added in
langchain4j#6243.
Fixes langchain4j#6391
5 of 8 tasks
mariofusco
added a commit
that referenced
this pull request
Sep 14, 2026
…ds (#6392) ## Issue Closes #6391 ## Change `SupervisorPlanner` built every agent card entry from `AgentArgument.rawType()`, so a parameter declared as a generic or an array reached the renderer already erased: `List<String>` arrived as `List.class` and fell into the field walk. `List` is an interface with no declared fields, so the argument came out as `{}` and the planner had to guess the shape of every non-scalar argument. The card now uses the declared `Type` and renders it in a form the planner can act on. Classes keep going through the existing logic, including the inherited-field walk added in #6243. Record components are read with `getParameterizedType()` instead of `getType()`, so a record field declared as `List<Integer>` keeps its type as well. For a sub-agent declared like this: ```java @agent("Searches records in the backing system") String search( @v("recordType") String recordType, @v("fields") List<String> fields, @v("recordIds") String[] recordIds, @v("filters") Map<String, Object> filters, @v("unknown") Object unknown, @v("recordFilter") RecordFilter recordFilter); ``` the entry in the planner prompt goes from ``` [recordType: String, fields: {}] ``` to ``` [recordType: String, fields: List<String>, recordIds: String[], filters: Map<String, Object>, unknown: Object, recordFilter: {name: String, values: List<Integer>}] ``` This is the rendering half of #6226. The type derivation half landed in #6240, which also closed #6226; the rendering side was pulled out of that PR in 8d577f1 to keep it scoped to the MCP work, and its test went with it. One case I deliberately left alone: a parameterized interface used as an argument type, say `Comparable<String>`, still comes out as `{}`, because there are no fields to walk. Agent arguments are normally collections, maps, arrays or POJOs, so I kept this PR to the cases listed in #6391. Happy to pick that up separately if you want it. ## Tests `SupervisorGenericArgumentCardTest` drives a real supervisor invocation and asserts on the prompt the planning model actually receives, rather than on the derived `AgentArgument`. That is the seam where this was going unnoticed: `SupervisorArgumentDescriptionTest` only passes plain `Class` values, and `McpAgentTest` asserts on the derived argument. Commands run: - `./mvnw -pl langchain4j-agentic,langchain4j-agentic-mcp clean test` (159 and 26 tests, all green) - `./mvnw -pl langchain4j-core,langchain4j clean test` (1387 and 1713 tests, all green; 4 and 19 skipped) - `./mvnw -pl langchain4j-agentic spotless:check` (clean) Reverting only the change in `SupervisorPlanner` makes `SupervisorGenericArgumentCardTest` fail on `fields: List<String>`, and leaves `SupervisorArgumentDescriptionTest` passing, so the new test fails for this bug and not as collateral. ## General checklist - [x] There are no breaking changes (API, behaviour). `argumentDescription` is package private and its behaviour for `Class` arguments is unchanged; the parameter type is widened from `Class<?>` to `Type`. - [x] I have added unit and/or integration tests for my change - [x] The tests cover both positive and negative cases (scalars still render as before; collections, arrays, maps and `Object` are the regression) - [x] I have manually run all the unit and integration tests in the module I have added/changed, and they are all green - [x] I have manually run all the unit and integration tests in the [[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)](https://github.com/langchain4j/langchain4j/tree/[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)/langchain4j-core) and [main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j) modules, and they are all green - [ ] I have added/updated the [[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)](https://github.com/langchain4j/langchain4j/tree/main/docs/docs) (not applicable, this only changes how argument types are written into the supervisor prompt) - [ ] I have added an example in the [[examples repo](https://github.com/langchain4j/langchain4j-examples)](https://github.com/langchain4j/langchain4j-examples) (only for "big" features) (not applicable) - [ ] I have added/updated [[Spring Boot starter(s)](https://github.com/langchain4j/langchain4j-spring)](https://github.com/langchain4j/langchain4j-spring) (if applicable) (not applicable) Co-authored-by: Mario Fusco <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Issue
Found during a code review of the same pattern fixed in #6222:
SupervisorPlanner.argumentDescription()(langchain4j-agentic) describes agent argument types fromClass.getDeclaredFields()only.Change
For a supervisor agent whose argument/output POJO extends a base class, the supervisor's request context omitted every inherited field. The planning LLM therefore never saw those fields — it could not route to the right sub-agent with the right arguments when the state lived (partly) in a superclass. Records were unaffected (they describe constructor parameters).
This PR walks the class hierarchy (superclass fields first, up to
Object) and merges declared fields, with a subclass redeclaration shadowing the inherited one — the same semantics as the JSON-schema generation fix inJsonSchemaElementUtils(#6222). The helper is local toSupervisorPlannerto keep the PRs independent; if both are merged, the two helpers could later be unified.General checklist
langchain4j-agentic: 128 tests, 0 failures)