Skip to content

feat: enhance A2A subagent description to include AgentCard skills and examples - #68

Merged
tzolov merged 3 commits into
spring-ai-community:mainfrom
caio-henrique:feature/enhance-a2a-subagent-description
Oct 3, 2026
Merged

tzolov merged 3 commits into
spring-ai-community:mainfrom
caio-henrique:feature/enhance-a2a-subagent-description

Conversation

@caio-henrique

Copy link
Copy Markdown
Contributor

📌 Summary

This PR enhances the A2ASubagentDefinition class to provide a much richer and more contextual description for A2A-based subagents.

Previously, the getDescription() method returned only the raw AgentCard.description() string. In multi-agent orchestration scenarios, this sparse information forced the orchestrator (or LLM) to rely solely on a short, often generic text to decide which subagent to invoke, increasing the risk of misrouting.

With this improvement, the description now automatically includes the full list of the agent's skills, their individual descriptions, and the associated examples (if provided in the AgentCard). This turns the description into a self-contained, LLM-friendly capability summary.


🚀 What changed

  • Modified the buildDescription(AgentCard card) private static method.
  • Added logic to iterate over card.skills() and append:
    • Skill name
    • Skill description
    • Skill examples (formatted as nested bullet points)

✅ Why this is important

  • Better LLM reasoning: With explicit skill names and examples, the orchestrator LLM can perform more accurate tool/subagent selection using semantic matching.
  • Improved debugging & observability: When logging subagent definitions, developers now see the full capability set without needing to parse the raw AgentCard elsewhere.
  • Alignment with A2A philosophy: The A2A protocol provides rich agent cards; our definition layer now exposes that richness to the agent framework's core contracts.

🧪 Example of the new output

Before:

"General-purpose mathematical solver."

After:

"General-purpose mathematical solver.
Capabilities:
- Algebra Solver: Solves linear and polynomial equations.
  - Example: Solve 2x + 5 = 15
  - Example: Factor x^2 - 4
- Calculus Assistant: Computes derivatives and integrals.
  - Example: Differentiate x^2
  - Example: Integrate 2x"

🔬 Testing done

  • Unit tests updated/validated to cover scenarios with null/empty skills.
  • Manually verified the string formatting by printing the description from an actual AgentCard instance (from sample A2A server).
  • Ensured no breaking changes—the return type remains String and the interface contract (SubagentDefinition) is fully respected.

📂 Files changed

  • org.springaicommunity.agent.subagent.a2a.A2ASubagentDefinition.java

kezhenxu94 added a commit to kezhenxu94/spring-ai-agent-utils that referenced this pull request Aug 30, 2026
…community#68)

`SkillsTool.build()` used to return a single `Skill` tool whose description
embedded a `<available_skills>` catalog of every loaded skill, invoked
indirectly as `Skill(command="pdf")` with a `HashMap` lookup.

That design does not scale, and it interacts badly with the tool search tool:
with ~100 skills, the catalog of all 100 descriptions lives inside one tool
description, so that tool can never be deferred or indexed per skill. Every
tool search has to load all 100 skill descriptions just to pick one - wasted
tokens and latency on each call.

Each skill is now its own `ToolCallback`, named after the skill and described
by that skill's own front-matter, taking no arguments. Skill selection becomes
ordinary tool selection, so skills are individually searchable and can be
deferred via `defer_loading`.

Further benefits:

- A hallucinated skill name is prevented by the tool schema instead of failing
  at runtime with `Skill not found: ...`.
- Duplicate skill names used to be silently shadowed by `HashMap.put` - both
  appeared in the catalog, only the last was reachable. `build()` now fails
  fast, naming both skills and base paths.
- Front-matter is no longer injected raw into pseudo-XML, so a `<` or
  `</skill>` in a description can no longer corrupt the prompt structure.
- Per-skill allow/deny filtering in subagent `tools` / `disallowedTools` now
  works, since those match on `ToolDefinition.name()`.
- The per-skill description drops the boilerplate that the tool schema now
  conveys (empty input schema, tool name), keeping only the base-directory
  note the model cannot infer.

Scoped skill names are preserved: the skill `name` stays as written, and the
tool name is derived from it by replacing characters the model providers
reject in a tool name - `project-a:pdf` is registered as `project-a_pdf`
(tool names must match `^[a-zA-Z0-9_-]{1,64}$`). Uniqueness and length are
enforced on the derived name.

Breaking changes, with a migration section added to `docs/SkillsTool.md`:

- `build()` returns `ToolCallbackProvider` instead of `ToolCallback`.
  Registration is unchanged - `defaultTools(...)` and
  `defaultToolCallbacks(...)` both accept it, so no example app needed edits.
- `SkillsInput` / `SkillsFunction` are replaced by `SkillFunction`.
- `toolDescriptionTemplate`'s `%s` is now a single skill's front-matter
  rather than the whole catalog.

`Skill.toXml()` is retained - `ClaudeSubagentExecutor` still uses it to
preload skills into a subagent system prompt, a path this change leaves alone.
kezhenxu94 added a commit to kezhenxu94/spring-ai-agent-utils that referenced this pull request Sep 2, 2026
…community#68)

`SkillsTool.build()` used to return a single `Skill` tool whose description
embedded a `<available_skills>` catalog of every loaded skill, invoked
indirectly as `Skill(command="pdf")` with a `HashMap` lookup.

That design does not scale, and it interacts badly with the tool search tool:
with ~100 skills, the catalog of all 100 descriptions lives inside one tool
description, so that tool can never be deferred or indexed per skill. Every
tool search has to load all 100 skill descriptions just to pick one - wasted
tokens and latency on each call.

Each skill is now its own `ToolCallback`, named after the skill and described
by that skill's own front-matter, taking no arguments. Skill selection becomes
ordinary tool selection, so skills are individually searchable and can be
deferred via `defer_loading`.

Further benefits:

- A hallucinated skill name is prevented by the tool schema instead of failing
  at runtime with `Skill not found: ...`.
- Duplicate skill names used to be silently shadowed by `HashMap.put` - both
  appeared in the catalog, only the last was reachable. `build()` now fails
  fast, naming both skills and base paths.
- Front-matter is no longer injected raw into pseudo-XML, so a `<` or
  `</skill>` in a description can no longer corrupt the prompt structure.
- Per-skill allow/deny filtering in subagent `tools` / `disallowedTools` now
  works, since those match on `ToolDefinition.name()`.
- The per-skill description drops the boilerplate that the tool schema now
  conveys (empty input schema, tool name), keeping only the base-directory
  note the model cannot infer.

Scoped skill names are preserved: the skill `name` stays as written, and the
tool name is derived from it by replacing characters the model providers
reject in a tool name - `project-a:pdf` is registered as `project-a_pdf`
(tool names must match `^[a-zA-Z0-9_-]{1,64}$`). Uniqueness and length are
enforced on the derived name.

Breaking changes, with a migration section added to `docs/SkillsTool.md`:

- `build()` returns `ToolCallbackProvider` instead of `ToolCallback`.
  Registration is unchanged - `defaultTools(...)` and
  `defaultToolCallbacks(...)` both accept it, so no example app needed edits.
- `SkillsInput` / `SkillsFunction` are replaced by `SkillFunction`.
- `toolDescriptionTemplate`'s `%s` is now a single skill's front-matter
  rather than the whole catalog.

`Skill.toXml()` is retained - `ClaudeSubagentExecutor` still uses it to
preload skills into a subagent system prompt, a path this change leaves alone.
tzolov added 2 commits October 3, 2026 17:21
# Conflicts:
#	spring-ai-agent-utils-a2a/pom.xml
- Indent the skill list under the agent and label it "Can help with" so
  skills are not mistaken for other agents in the Task tool listing, or
  for Agent Skills of the Skill tool
- Use "\n" instead of System.lineSeparator() in the prompt text
- Restore the original tab formatting and license header; add a license
  header and tabs to the test, and assert the exact description output
@tzolov
tzolov merged commit 8f0e7fb into spring-ai-community:main Oct 3, 2026
1 check passed
@tzolov tzolov added this to the 0.13.0 milestone Oct 3, 2026
@tzolov

tzolov commented Oct 3, 2026

Copy link
Copy Markdown
Contributor

Thanks @caio-henrique, this resolves the old TODO include more details like skills? nicely! Merged for 0.13.0.

I pushed one commit to your branch before merging (after merging main in to resolve the pom conflict with fc4c3ca):

  • Indentation: the description is inserted into the Task tool's agent list, one -name: /description entry per agent. Unindented - Skill: ... lines read like additional agents, so the skills are now indented under the agent.
  • Label: Can help with: instead of Skills:/Capabilities:, so the model does not confuse remote A2A skills with Agent Skills invoked through the Skill tool (whose description talks about "skills" and "capabilities").
  • \n instead of System.lineSeparator() (no \r\n in prompts on Windows), the original tab formatting, and exact-output assertions in your tests.

The rendered entry now looks like:

-airbnb: /Finds and books Airbnb stays
  Can help with:
  - Search listings: Find stays for dates and guests
    Examples: Find a room in Paris for 2 people next weekend
  - Book: Book a listing

kezhenxu94 added a commit to kezhenxu94/spring-ai-agent-utils that referenced this pull request Oct 13, 2026
…community#68)

`SkillsTool.build()` used to return a single `Skill` tool whose description
embedded a `<available_skills>` catalog of every loaded skill, invoked
indirectly as `Skill(command="pdf")` with a `HashMap` lookup.

That design does not scale, and it interacts badly with the tool search tool:
with ~100 skills, the catalog of all 100 descriptions lives inside one tool
description, so that tool can never be deferred or indexed per skill. Every
tool search has to load all 100 skill descriptions just to pick one - wasted
tokens and latency on each call.

Each skill is now its own `ToolCallback`, named after the skill and described
by that skill's own front-matter, taking no arguments. Skill selection becomes
ordinary tool selection, so skills are individually searchable and can be
deferred via `defer_loading`.

Further benefits:

- A hallucinated skill name is prevented by the tool schema instead of failing
  at runtime with `Skill not found: ...`.
- Duplicate skill names used to be silently shadowed by `HashMap.put` - both
  appeared in the catalog, only the last was reachable. `build()` now fails
  fast, naming both skills and base paths.
- Front-matter is no longer injected raw into pseudo-XML, so a `<` or
  `</skill>` in a description can no longer corrupt the prompt structure.
- Per-skill allow/deny filtering in subagent `tools` / `disallowedTools` now
  works, since those match on `ToolDefinition.name()`.
- The per-skill description drops the boilerplate that the tool schema now
  conveys (empty input schema, tool name), keeping only the base-directory
  note the model cannot infer.

Scoped skill names are preserved: the skill `name` stays as written, and the
tool name is derived from it by replacing characters the model providers
reject in a tool name - `project-a:pdf` is registered as `project-a_pdf`
(tool names must match `^[a-zA-Z0-9_-]{1,64}$`). Uniqueness and length are
enforced on the derived name.

Breaking changes, with a migration section added to `docs/SkillsTool.md`:

- `build()` returns `ToolCallbackProvider` instead of `ToolCallback`.
  Registration is unchanged - `defaultTools(...)` and
  `defaultToolCallbacks(...)` both accept it, so no example app needed edits.
- `SkillsInput` / `SkillsFunction` are replaced by `SkillFunction`.
- `toolDescriptionTemplate`'s `%s` is now a single skill's front-matter
  rather than the whole catalog.

`Skill.toXml()` is retained - `ClaudeSubagentExecutor` still uses it to
preload skills into a subagent system prompt, a path this change leaves alone.
kezhenxu94 added a commit to kezhenxu94/spring-ai-agent-utils that referenced this pull request Oct 13, 2026
…community#68)

`SkillsTool.build()` used to return a single `Skill` tool whose description
embedded a `<available_skills>` catalog of every loaded skill, invoked
indirectly as `Skill(command="pdf")` with a `HashMap` lookup.

That design does not scale, and it interacts badly with the tool search tool:
with ~100 skills, the catalog of all 100 descriptions lives inside one tool
description, so that tool can never be deferred or indexed per skill. Every
tool search has to load all 100 skill descriptions just to pick one - wasted
tokens and latency on each call.

Each skill is now its own `ToolCallback`, named after the skill and described
by that skill's own front-matter, taking no arguments. Skill selection becomes
ordinary tool selection, so skills are individually searchable and can be
deferred via `defer_loading`.

Further benefits:

- A hallucinated skill name is prevented by the tool schema instead of failing
  at runtime with `Skill not found: ...`.
- Duplicate skill names used to be silently shadowed by `HashMap.put` - both
  appeared in the catalog, only the last was reachable. `build()` now fails
  fast, naming both skills and base paths.
- Front-matter is no longer injected raw into pseudo-XML, so a `<` or
  `</skill>` in a description can no longer corrupt the prompt structure.
- Per-skill allow/deny filtering in subagent `tools` / `disallowedTools` now
  works, since those match on `ToolDefinition.name()`.
- The per-skill description drops the boilerplate that the tool schema now
  conveys (empty input schema, tool name), keeping only the base-directory
  note the model cannot infer.

Scoped skill names are preserved: the skill `name` stays as written, and the
tool name is derived from it by replacing characters the model providers
reject in a tool name - `project-a:pdf` is registered as `project-a_pdf`
(tool names must match `^[a-zA-Z0-9_-]{1,64}$`). Uniqueness and length are
enforced on the derived name.

Breaking changes, with a migration section added to `docs/SkillsTool.md`:

- `build()` returns `ToolCallbackProvider` instead of `ToolCallback`.
  `defaultTools(...)` / `defaultToolCallbacks(...)` accept it directly, so apps
  that pass it there are unchanged; an app that collected it into a
  `List<ToolCallback>` must now expand `build().getToolCallbacks()` instead
  (updated in the `code-agent-demo` example).
- `SkillsInput` / `SkillsFunction` are replaced by `SkillFunction`.
- `toolDescriptionTemplate`'s `%s` is now a single skill's front-matter
  rather than the whole catalog.

`Skill.toXml()` is retained - `ClaudeSubagentExecutor` still uses it to
preload skills into a subagent system prompt, a path this change leaves alone.
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