83 lines
2.9 KiB
Markdown
83 lines
2.9 KiB
Markdown
# Design
|
|
|
|
## Architecture
|
|
|
|
```text
|
|
src/main/resources/skills/
|
|
-> SKILL.md files
|
|
-> ClasspathSkillRegistry bean
|
|
-> loads classpath skills
|
|
-> backs official read_skill
|
|
-> PlannerSkillMetadataHook
|
|
-> adds planner-only skill metadata messages
|
|
-> does not expose read_skill
|
|
-> SkillsAgentHook
|
|
-> adds official read_skill ToolCallback for Executor / single-agent Chat
|
|
-> adds SkillsInterceptor prompt augmentation outside Planner
|
|
-> ChatService / AiOpsService
|
|
-> Planner receives metadata only
|
|
-> Executor and single-agent Chat receive official skill hook
|
|
-> Verifier remains isolated
|
|
```
|
|
|
|
## Skill Contract
|
|
|
|
Each skill folder contains a `SKILL.md` with YAML frontmatter:
|
|
|
|
```yaml
|
|
---
|
|
name: diagnose-mysql-connection-pool
|
|
description: ...
|
|
---
|
|
```
|
|
|
|
The body contains:
|
|
|
|
- Trigger conditions.
|
|
- Required evidence.
|
|
- Recommended tool order.
|
|
- Query construction hints.
|
|
- Stop conditions and low-confidence behavior.
|
|
- Report requirements.
|
|
- Eval anchor when one exists.
|
|
|
|
## Prompt Injection
|
|
|
|
Planner agents receive a project-local `PlannerSkillMetadataHook` message that contains skill names and descriptions only. The message also requires `selected_skill`, `selection_reason`, and an ordered `plan` in the Planner output.
|
|
|
|
`SkillsAgentHook` provides `SkillsInterceptor`, which injects the official compact skill section containing skill names, descriptions, and loading instructions into model requests for:
|
|
|
|
- Chat Executor prompt.
|
|
- AIOps Executor prompt.
|
|
- Single-agent Chat prompt.
|
|
|
|
Planner prompts are not augmented by `SkillsAgentHook`, so Planner cannot receive the official `read_skill` tool. Verifier prompt is not augmented.
|
|
|
|
## Tool Exposure
|
|
|
|
Spring AI Alibaba's official `ReadSkillTool` exposes:
|
|
|
|
```java
|
|
read_skill(skill_name)
|
|
```
|
|
|
|
The tool returns the full `SKILL.md` body for a known skill or a structured error for missing skills.
|
|
|
|
`read_skill` is supplied by `SkillsAgentHook`, not by local `methodTools`. Planner selects a skill from metadata and writes the selection into `planner_plan`; Executor reads the selected skill before executing scenario-specific evidence collection.
|
|
|
|
## Trace Behavior
|
|
|
|
`read_skill` is a guidance tool, not an evidence tool. It does not write `tool_invocation` because the existing eval and verifier treat evidence tools as factual data sources. Actual diagnostic evidence must still come from `lookup_knowledge`, `query_logs`, `query_metrics`, and alert tools.
|
|
|
|
## Fallback
|
|
|
|
If a skill is not found or cannot be read:
|
|
|
|
- The tool returns a structured text error.
|
|
- The agent must fall back to generic Executor prompt behavior.
|
|
- It must not invent playbook content.
|
|
|
|
## Alibaba Skills Integration
|
|
|
|
The implementation uses `spring-ai-alibaba-agent-framework:1.1.2.0`, where `SkillsAgentHook` lives in `com.alibaba.cloud.ai.graph.agent.hook.skills` and `ClasspathSkillRegistry` lives in `com.alibaba.cloud.ai.graph.skills.registry.classpath`.
|