Repository navigation
feat: enhance A2A subagent description to include AgentCard skills and examples - #68
Merged
tzolov merged 3 commits intoOct 3, 2026
Conversation
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.
# 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
Contributor
|
Thanks @caio-henrique, this resolves the old I pushed one commit to your branch before merging (after merging
The rendered entry now looks like: |
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.
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.
📌 Summary
This PR enhances the
A2ASubagentDefinitionclass to provide a much richer and more contextual description for A2A-based subagents.Previously, the
getDescription()method returned only the rawAgentCard.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
buildDescription(AgentCard card)private static method.card.skills()and append:namedescriptionexamples(formatted as nested bullet points)✅ Why this is important
AgentCardelsewhere.🧪 Example of the new output
Before:
After:
🔬 Testing done
null/empty skills.AgentCardinstance (from sample A2A server).Stringand the interface contract (SubagentDefinition) is fully respected.📂 Files changed
org.springaicommunity.agent.subagent.a2a.A2ASubagentDefinition.java