diff --git a/docs/agents/index.md b/docs/agents/index.md index e0381b31f..6afe2fc2a 100644 --- a/docs/agents/index.md +++ b/docs/agents/index.md @@ -41,9 +41,44 @@ While each agent type serves a distinct purpose, the true power often comes from Understanding these core types is the first step toward building sophisticated, capable AI applications with ADK. ---- +## Extend Agent Capabilities -## What's Next? +Beyond the core agent types, ADK allows you to significantly expand what your +agents can do through several key mechanisms: + +* [**AI Models**](/adk-docs/agents/models/): + Swap the underlying intelligence of your agents by integrating with + different generative AI models from Google and other providers. + +* [**Artifacts**](/adk-docs/artifacts/): + Enable agents to create and manage persistent outputs like files, code, or + documents that exist beyond the conversation lifecycle. + +* [**Pre-built tools and integrations**](/adk-docs/integrations/): + Equip your agents with a wide array tools, plugins, and other integrations + to interact with the world, including web sites, MCP tools, applications, + databases, programming interfaces, and more. + +* [**Custom tools**](/adk-docs/tools-custom/): + Create your own, task-specific tools for solving specific problems with + precision and control. + +* [**Plugins**](/adk-docs/plugins/): + Integrate complex, pre-packaged behaviors and third-party services directly + into your agent's workflow. + +* [**Skills**](/adk-docs/skills/): + Use prebuilt or custom [Agent Skills](https://agentskills.io/) to extend + agent capabilities in a way that works efficiently inside AI context window + limits. + +* [**Callbacks**](/adk-docs/callbacks/): + Hook into specific events during an agent's execution lifecycle to add + logging, monitoring, or custom side-effects without altering core agent + logic. + + +## Next Steps Now that you have an overview of the different agent types available in ADK, dive deeper into how they work and how to use them effectively: diff --git a/docs/skills/index.md b/docs/skills/index.md new file mode 100644 index 000000000..4cfa0b547 --- /dev/null +++ b/docs/skills/index.md @@ -0,0 +1,154 @@ +# Skills for ADK agents + +
+ Supported in ADKPython v1.25.0Experimental +
+ +An agent ***Skill*** is a self-contained unit of functionality that an ADK agent +can use to perform a specific task. An agent Skill encapsulates the necessary +instructions, resources, and tools required for a task, based on the +[Agent Skill specification](https://agentskills.io/specification). +The structure of a Skill allows it to be loaded incrementally to minimize the +impact on the operating context window of the agent. + +!!! example "Experimental" + The Skills feature is experimental and has some + [known limitations](#known-limitations). We welcome your + [feedback](https://github.com/google/adk-python/issues/new?template=feature_request.md&labels=skills)! + +## Get started + +Use the `SkillToolset` class to include one or more Skills in your agent +definition and then add to your agent's tools list. You can define a +[Skill in code](#inline-skills), +or load the skill from a file definition, as shown below: + +```python +import pathlib + +from google.adk import Agent +from google.adk.skills import load_skill_from_dir +from google.adk.tools import skill_toolset + +weather_skill = load_skill_from_dir( + pathlib.Path(__file__).parent / "skills" / "weather_skill" +) + +my_skill_toolset = skill_toolset.SkillToolset( + skills=[weather_skill] +) + +root_agent = Agent( + model="gemini-2.5-flash", + name="skill_user_agent", + description="An agent that can use specialized skills.", + instruction=( + "You are a helpful assistant that can leverage skills to perform tasks." + ), + tools=[ + my_skill_toolset, + ], +) +``` + +For a complete code example of an ADK agent with a Skill, including both +file-based and in-line Skill definitions, see the code sample +[skills_agent](https://github.com/google/adk-python/tree/main/contributing/samples/skills_agent). + +## Define Skills + +The Skills feature allows you to create modular packages of Skill instructions +and resources that agents can load on demand. This approach helps you organize +your agent's capabilities and optimize the context window by only loading +instructions when they are needed. The structure of Skills is organized into +three levels: + +- **L1 (Metadata):** Provides metadata for skill discovery. This information + is defined in the frontmatter section of the `SKILL.md` file and includes + properties such as the Skill name and description. +- **L2 (Instructions):** Contains the primary instructions for the Skill, + loaded when the Skill is triggered by the agent. This information is defined + in the body of the `SKILL.md` file. +- **L3 (Resources):** Includes additional resources such as reference + materials, assets, and scripts that can be loaded as needed. These resources + are organized into the following directories: + - `references/`: Additional Markdown files with extended instructions, + workflows, or guidance. + - `assets/`: Resource materials such as database schemas, API + documentation, templates, or examples. + - `scripts/`: Executable scripts supported by the agent runtime. + +### Define Skills with files + +The following directory structure shows the recommended way to include Skills in +your ADK agent project. The `example_skill/` directory shown below, and any +parallel Skill directories, must follow the +[Agent Skill specification](https://agentskills.io/specification) +file structure. Only the `SKILL.md` file is required. + +``` +my_agent/ + agent.py + .env + skills/ + example_skill/ # Skill + SKILL.md # main instructions (required) + references/ + REFERENCE.md # detailed API reference + FORMS.md # form-filling guide + *.md # domain-specific information + assets/ + *.* # templates, images, data + scripts/ + *.py # utility scripts +``` + +!!! warning "Script execution not supported" + Scripts execution is not yet supported and is a + [known limitation](#known-limitations). + +### Define Skills in code {#inline-skills} + +In ADK agents, you can also define Skills within the code of the agent, using +the `Skill` model class, as shown below. This method of Skill definition enables +you to dynamically modify skills from your ADK agent code. + +```python +from google.adk.skills import models + +greeting_skill = models.Skill( + frontmatter=models.Frontmatter( + name="greeting-skill", + description=( + "A friendly greeting skill that can say hello to a specific person." + ), + ), + instructions=( + "Step 1: Read the 'references/hello_world.txt' file to understand how" + " to greet the user. Step 2: Return a greeting based on the reference." + ), + resources=models.Resources( + references={ + "hello_world.txt": "Hello! So glad to have you here!", + "example.md": "This is an example reference.", + }, + ), +) +``` + +## Known limitations {#known-limitations} + +The Skills feature is experimental and includes the following +limitations: + +- **Script execution:** The Skills feature does not currently support + script execution (`scripts/` directory). + +## Next steps + +Check out these resources for building agents with Skills: + +* ADK Skills agent code sample: + [skills_agent](https://github.com/google/adk-python/tree/main/contributing/samples/skills_agent). +* Agent Skills + [specification documentation](https://agentskills.io/) diff --git a/mkdocs.yml b/mkdocs.yml index 5f531126a..11e08b693 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -225,6 +225,7 @@ plugins: - integrations/*.md - tools/*.md - tools-custom/*.md + - skills/*.md Run Agents: - runtime/*.md - deploy/*.md @@ -304,6 +305,8 @@ nav: - OpenAPI tools: tools-custom/openapi-tools.md - Authentication: tools-custom/authentication.md - Tool limitations: tools/limitations.md + - Skills for Agents: + - skills/index.md - Run Agents: - Agent Runtime: - Agent Runtime: runtime/index.md