Skip to content

fix(agentic): include inherited fields in supervisor argument descriptions - #6243

Merged
mariofusco merged 5 commits into
langchain4j:mainfrom
Lubaoshuai:fix/supervisor-planner-inherited-fields
Sep 3, 2026
Merged

mariofusco merged 5 commits into
langchain4j:mainfrom
Lubaoshuai:fix/supervisor-planner-inherited-fields

Conversation

@Lubaoshuai

Copy link
Copy Markdown
Contributor

Issue

Found during a code review of the same pattern fixed in #6222: SupervisorPlanner.argumentDescription() (langchain4j-agentic) describes agent argument types from Class.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 in JsonSchemaElementUtils (#6222). The helper is local to SupervisorPlanner to keep the PRs independent; if both are merged, the two helpers could later be unified.

General checklist

  • There are no breaking changes (API, behaviour) — descriptions only gain previously missing inherited fields
  • I have added unit and/or integration tests for my change
  • The tests cover both positive and negative cases (inherited fields, shadowing, records unchanged, simple types unchanged, nested recursion, null name)
  • I have manually run all the unit and integration tests in the module I have added/changed, and they are all green (langchain4j-agentic: 128 tests, 0 failures)
  • I have added/updated the documentation (no documentation change required)
  • I have added an example in the examples repo (only for "big" features)
  • I have added/updated Spring Boot starter(s) (if applicable)

LUbaoshuai and others added 2 commits August 30, 2026 22:10
…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 mariofusco left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
@mariofusco

Copy link
Copy Markdown
Collaborator

Please resolve conflicts.

…ner-inherited-fields

# Conflicts:
#	langchain4j-agentic/src/test/java/dev/langchain4j/agentic/SupervisorAgentIT.java
@mariofusco
mariofusco merged commit 2f27d4c into langchain4j:main Sep 3, 2026
7 checks passed
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
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]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants