From 883a06cdc82f5a5315fe75a1b25983beb8f7bc9c Mon Sep 17 00:00:00 2001 From: Art Berger Date: Fri, 21 Nov 2025 16:48:17 -0500 Subject: [PATCH 1/3] agent skills draft Signed-off-by: Art Berger --- public/sitemap.xml | 203 +++++++------- src/app/docs/kagent/concepts/agents/page.mdx | 42 ++- src/app/docs/kagent/examples/page.mdx | 1 + src/app/docs/kagent/examples/skills/page.mdx | 276 +++++++++++++++++++ src/config/navigation.json | 7 +- 5 files changed, 428 insertions(+), 101 deletions(-) create mode 100644 src/app/docs/kagent/examples/skills/page.mdx diff --git a/public/sitemap.xml b/public/sitemap.xml index f4dca152..54f5af17 100644 --- a/public/sitemap.xml +++ b/public/sitemap.xml @@ -2,686 +2,693 @@ https://kagent.dev/agents - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/blog - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/community - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/concepts/agents - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/concepts/architecture - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/concepts - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/concepts/tools - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/examples/a2a-agents - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/examples/a2a-byo - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/examples/crewai-byo - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/examples/discord-a2a - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/examples/documentation - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/examples/langchain-byo - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/examples - 2025-11-20 + 2025-11-21 + weekly + 0.8 + + + + https://kagent.dev/docs/kagent/examples/skills + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/examples/slack-a2a - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/first-agent - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/first-mcp-tool - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/local-development - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/getting-started - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/quickstart - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/system-prompts - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/tracing - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/introduction/installation - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/introduction - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/introduction/what-is-kagent - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/operations/debug - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/operations - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/operations/uninstall - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/operations/upgrade - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/api-ref - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-add-mcp - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-bug-report - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-build - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-dashboard - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-deploy - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-get - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-init - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-install - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-invoke - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-mcp - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-run - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-uninstall - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-version - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/faq - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/helm - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/resources/release-notes - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/amazon-bedrock - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/anthropic - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/azure-openai - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/byo-openai - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/gemini - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/google-vertexai - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/ollama - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/openai - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/deploy/install-controller - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/deploy - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/deploy/server - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/develop/fastmcp-python - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/develop/mcp-go - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/develop - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/introduction - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/quickstart - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/reference/api-ref - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-add-tool - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-build - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-deploy - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-init - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-install - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-run - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-secrets - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/reference - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs/kmcp/secrets - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/docs - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/enterprise - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/page.tsx - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/tools - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/agents/argo-rollouts-conversion-agent - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/agents/cilium-crd-agent - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/agents/helm-agent - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/agents/istio-agent - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/agents/k8s-agent - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/agents/kgateway-agent - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/agents/observability-agent - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/agents/promql-agent - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/tools/istio - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/tools/kubernetes - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/tools/prometheus - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/tools/documentation - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/tools/helm - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/tools/argo - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/tools/grafana - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/tools/other - 2025-11-20 + 2025-11-21 weekly 0.8 https://kagent.dev/tools/cilium - 2025-11-20 + 2025-11-21 weekly 0.8 diff --git a/src/app/docs/kagent/concepts/agents/page.mdx b/src/app/docs/kagent/concepts/agents/page.mdx index 2fa2368b..beb6e433 100644 --- a/src/app/docs/kagent/concepts/agents/page.mdx +++ b/src/app/docs/kagent/concepts/agents/page.mdx @@ -1,12 +1,12 @@ --- title: "Agents" pageOrder: 2 -description: "Dive into the concept of AI agents in kagent, their components (instructions, tools), and how they can even use other agents as tools." +description: "Dive into the concept of AI agents in kagent, their components (instructions, tools, skills), and how they can even use other agents as tools." --- export const metadata = { title: "What are AI agents?", - description: "Dive into the concept of AI agents in kagent, their components (instructions, tools), and how they can even use other agents as tools.", + description: "Dive into the concept of AI agents in kagent, their components (instructions, tools, skills), and how they can even use other agents as tools.", author: "kagent.dev" }; @@ -19,6 +19,7 @@ Each agent consists of the following components: - Agent instructions: A set of instructions that define the agent's behavior and capabilities. This is also called a system prompt. - Tools: Functions that the agent can use to interact with its environment. Kagent features built-in tools and has support for accessing tools over the [MCP](https://github.com/modelcontextprotocol). +- Skills: Descriptions of capabilities that help the agent act more autonomously and guide its tool usage and planning. ## Agent Instructions @@ -47,6 +48,43 @@ Some tools support additional configuration that can be set in when adding the t Kagent comes with a set of built-in tools that you can use to interact with your environment. Kagent also supports the [MCP (Model Configuration Protocol)](https://modelcontextprotocol.io/introduction) tools. Using MCP, you can bring any external tool into kagent and make it available for your agents to run. +## Skills + +Skills are descriptions of the capabilities that an agent has to act more autonomously. They make the LLM's responses more than just reactions to prompts by orienting them toward goals. + +In some frameworks, skills are expressed as wrapped functions, reusable prompt templates, or even a synonym for a tool. + +In kagent, think of skills like a catalog that expresses what the agent is capable of doing for a user. Unlike tools, skills are not a specific function that produces an output, like "fetch a website" or "tell the weather." Unlike system instructions, they are not rules that apply to all interactions, such as "Follow my company's style guide." + +Instead, skills are building blocks that guide the agent's tool usage and planning. They help the agent understand what its goals are, and when and how to use tools effectively. + +For example, two agents may share the same tools but use them differently based on their skills: + +- A troubleshooting agent might use a `describe` tool to check the events of a crashing pod before taking a recovery action, such as restarting the pod. +- A research agent might use the same `describe` tool to gather details about a pod in order to answer a user's question. + +Kagent supports two types of skills: + +1. **A2A skills** (metadata): Structured descriptions of capabilities defined in `a2aConfig.skills`. These consist of a description, examples, ID, and tags that help guide the agent's behavior. The description and examples provide context for both humans and the agent itself, often incorporated into system instructions. The ID and tags help you manage skills, such as by making it simpler to compare and reuse them across agents. + +2. **Container-based skills**: Executable skill implementations packaged as container images. These skills contain instructions, scripts, and resources that are loaded from container registries and made available to the agent at runtime. You can build and push skills as container images, then reference them in `spec.skills.refs` to load them into your agents. + +Skills in kagent are similar to [Claude's Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview), but with a key advantage: any agent can use skills, regardless of the LLM provider. You're not limited to Anthropic Claude. You can use skills with OpenAI, Google Vertex AI, Azure OpenAI, Ollama, and any other LLM provider that kagent supports. + +### Best practices for skills + +Containerize and store your skills in a specialized registry so that you can reuse them across agents. You can use the [agentregistry project](https://github.com/agentregistry-dev/agentregistry) to build and push skills to a registry. + +When creating skills for your agents, consider the following best practices. Agentregistry also has a [repo of example skills](https://github.com/agentregistry-dev/skills) based on Claude Skills that you can use as a starting point. + +1. **Be specific**: Each skill should represent a distinct capability. +2. **Provide good examples**: Include diverse examples that cover different ways users might express the need for that skill. +3. **Use descriptive tags**: Tags help organize skills and make them easier to manage. +4. **Align with tools**: Ensure your skills align with the tools available to the agent. If you have a skill that centers around writing docs in markdown, you might want to align it with the `write-markdown` tool (as opposed to a `generate-pdf` tool). +5. **Keep skills focused**: Each skill should have a clear, focused purpose. For example, a document-generating skill might be too broad, but a skill that focuses on creating a specific type of document, such as a `.docx` file or alternatively a genre like a getting started guide, might be more appropriate. + +To learn more about using skills in your agents, see the [Skills example guide](/docs/kagent/examples/skills). + ## Agents as Tools Kagent also supports using agents as tools. Any agent you create can be referenced and used by other agents you have. An example use case would be to have a PromQL agent that knows how to create PromQL queries from natural language. Then you'd create a second agent that would use the PromQL agent whenever it needs to create a PromQL query. diff --git a/src/app/docs/kagent/examples/page.mdx b/src/app/docs/kagent/examples/page.mdx index a8cbe227..18bdcc8d 100644 --- a/src/app/docs/kagent/examples/page.mdx +++ b/src/app/docs/kagent/examples/page.mdx @@ -22,6 +22,7 @@ import QuickLink from '@/components/quick-link'; + diff --git a/src/app/docs/kagent/examples/skills/page.mdx b/src/app/docs/kagent/examples/skills/page.mdx new file mode 100644 index 00000000..9d30fe06 --- /dev/null +++ b/src/app/docs/kagent/examples/skills/page.mdx @@ -0,0 +1,276 @@ +--- +title: "Skills" +pageOrder: 6 +description: "Learn how to add skills to your agents to guide their behavior and tool usage." +--- + +export const metadata = { + title: "Add skills to agents", + description: "Learn how to add skills to your agents to guide their behavior and tool usage.", + author: "kagent.dev" +}; + +# Add skills to agents + +Skills are descriptions of capabilities that help agents act more autonomously. They guide the agent's tool usage and planning by orienting responses toward goals rather than just reacting to prompts. + +In this guide, you learn how to add skills to your agents in kagent. Kagent supports two types of skills: + +1. **A2A skills** (metadata): Structured descriptions of capabilities defined inline the agent specification in the `a2aConfig.skills` field. +2. **Container-based skills**: Executable skills packaged as container images and loaded from registries, for reuse across agents. You can use the [agentregistry project](https://github.com/agentregistry-dev/agentregistry) to build and push skills to a registry. + +## Before you begin + +1. Install kagent by following the [quick start](/docs/kagent/getting-started/quickstart) guide. + +2. Review the concepts of [agents and skills](/docs/kagent/concepts/agents) in kagent. + +## Inline A2A skills metadata + +Create an agent that uses skills to guide its behavior. This example creates a Kubernetes troubleshooting agent with skills for diagnosing and fixing issues. + +Skills are defined under `a2aConfig` in the agent specification. Even if you're not exposing your agent via the A2A protocol, defining skills under `a2aConfig` helps guide the agent's behavior and tool usage in all conversations. + +```yaml +kubectl apply -f - <"Investigate the pod restarts in the production namespace"
"Check why the pod is not starting"
"Diagnose resource issues with my deployment" | "What's the health status of my cluster?"
"Check if there are any issues in the cluster"
"Analyze cluster resource usage"
"Review cluster events for problems" | + +## Container-based skills + +Container-based skills are executable skill implementations packaged as container images. These skills contain instructions, scripts, and other resources that the agent can discover and use at runtime. This way, you can reuse skills across agents. You might pair the inline metadata skills with more general purpose, container-based skills depending on your agent's needs. + + + +### Build a skill container + +To create a container-based skill, package your skill files into a container image. This example creates a skill that deploys simple applications to Kubernetes. + +1. Create a skill directory with your skill files. + + ```bash + mkdir k8s-deploy-skill + cd k8s-deploy-skill + ``` + +2. Create a `SKILL.md` file with skill metadata and instructions. The file should include YAML frontmatter with the skill name and description, followed by detailed instructions for the agent. + + ```markdown + # Kubernetes simple deploy skill + + Use this skill when users want to deploy a basic app on the Kubernetes cluster. + + ## Instructions + + - Expect the user to provide the name for an app they wish to deploy, along with a docker image reference. + Optionally they may supply number of replicas and port number, but these are not required, and have defaults. + - Call the script `scripts/deploy-app.py` passing the supplied name, image, and optional parameters (# of replicas and port number) if supplied, in that order. + - The script generates a correct two-resource manifest (Deployment + Service) and writes it to the file `temp-manifest.yaml`. + + You, the **agent**, are expected to apply the generated manifest `temp-manifest.yaml` against the current Kubernetes context. + + ## Example + + User: Deploy an app called "nginx" using image "docker/nginx" with 2 replicas on port 8080. + Agent: Invokes `scripts/deploy-app.py nginx docker/nginx 2 8080` + + The skill creates a manifest named `temp-manifest.yaml` consisting of a Deployment + Service in one shot. + The agent in turn applies the generated temp-manifest.yaml to the cluster. + ``` + + The agent learns how to use the skill by reading this file. The instructions tell the agent when to use the skill, what parameters to expect, and how to invoke the scripts. + +3. Add any scripts or resources your skill needs. + + ```bash + mkdir scripts + # Add your Python scripts, configs, etc. + # For example: scripts/deploy-app.py + ``` + + The scripts perform the actual work. In this example, `deploy-app.py` generates Kubernetes manifests based on the parameters provided. + +4. Create a Dockerfile. + + ```dockerfile + FROM scratch + COPY . / + ``` + +5. Build and push the image to a container registry. You can push skill containers to any container registry: + + - Docker Hub: `docker.io/username/skill-name:tag` + - GitHub Container Registry: `ghcr.io/username/skill-name:tag` + - Google Container Registry: `gcr.io/project/skill-name:tag` + - Amazon ECR: `123456789012.dkr.ecr.region.amazonaws.com/skill-name:tag` + - Any private registry: `registry.example.com/skill-name:tag` + + ```bash + docker build -t your-registry/k8s-deploy-skill:latest . + docker push your-registry/k8s-deploy-skill:latest + ``` + +### Use container-based skills in an agent + +To load container-based skills into your agent, reference them in the `spec.skills.refs` field. + + + +```yaml +kubectl apply -f - < Date: Fri, 21 Nov 2025 17:23:33 -0500 Subject: [PATCH 2/3] revise skills based on testing Signed-off-by: Art Berger --- src/app/docs/kagent/examples/skills/page.mdx | 276 ++++++++++++++++--- 1 file changed, 243 insertions(+), 33 deletions(-) diff --git a/src/app/docs/kagent/examples/skills/page.mdx b/src/app/docs/kagent/examples/skills/page.mdx index 9d30fe06..f6466653 100644 --- a/src/app/docs/kagent/examples/skills/page.mdx +++ b/src/app/docs/kagent/examples/skills/page.mdx @@ -109,6 +109,21 @@ Review the following table to understand the A2A skills metadata configuration. | **tags** | Categories for organizing and filtering skills | `troubleshooting`, `pods`, `diagnostics` | `cluster`, `health`, `monitoring` | | **examples** | Sample queries that trigger this skill | "Why is my pod crashing?"
"Investigate the pod restarts in the production namespace"
"Check why the pod is not starting"
"Diagnose resource issues with my deployment" | "What's the health status of my cluster?"
"Check if there are any issues in the cluster"
"Analyze cluster resource usage"
"Review cluster events for problems" | +### Test A2A skills + +For agents with A2A skills metadata, test with queries that match the skill examples. + +```bash +kagent invoke --agent k8s-troubleshooting-agent --task "Can you find any unhealthy pods in the kagent namespace?" +``` + +Example output: The agent uses its "Diagnose Pod Issues" skill to systematically investigate the problem. + +```json +{"artifacts":[{"artifactId":"b626f5ea-1994-48e0-8266-0141bda3322d","parts":[{"kind":"text","text":"All the pods in the kagent namespace appear to be healthy. They are all in the \"Running\" status with all containers ready (1/1) and no restarts reported. There are no unhealthy pods in the kagent namespace at this time. Is there anything specific you would like me to check or troubleshoot further?"}]}], +... +``` + ## Container-based skills Container-based skills are executable skill implementations packaged as container images. These skills contain instructions, scripts, and other resources that the agent can discover and use at runtime. This way, you can reuse skills across agents. You might pair the inline metadata skills with more general purpose, container-based skills depending on your agent's needs. @@ -117,7 +132,7 @@ Container-based skills are executable skill implementations packaged as containe You can use the [agentregistry project](https://github.com/agentregistry-dev/agentregistry) to build and push skills to a registry. Agentregistry also has a [repo of example skills](https://github.com/agentregistry-dev/skills) based on Claude Skills that you can use as a starting point. -### Build a skill container +### Step 1: Build a skill container To create a container-based skill, package your skill files into a container image. This example creates a skill that deploys simple applications to Kubernetes. @@ -130,7 +145,8 @@ To create a container-based skill, package your skill files into a container ima 2. Create a `SKILL.md` file with skill metadata and instructions. The file should include YAML frontmatter with the skill name and description, followed by detailed instructions for the agent. - ```markdown + ```bash + cat > SKILL.md <<'EOF' # Kubernetes simple deploy skill Use this skill when users want to deploy a basic app on the Kubernetes cluster. @@ -151,6 +167,7 @@ To create a container-based skill, package your skill files into a container ima The skill creates a manifest named `temp-manifest.yaml` consisting of a Deployment + Service in one shot. The agent in turn applies the generated temp-manifest.yaml to the cluster. + EOF ``` The agent learns how to use the skill by reading this file. The instructions tell the agent when to use the skill, what parameters to expect, and how to invoke the scripts. @@ -159,38 +176,186 @@ To create a container-based skill, package your skill files into a container ima ```bash mkdir scripts - # Add your Python scripts, configs, etc. - # For example: scripts/deploy-app.py + cat > scripts/deploy-app.py <<'EOF' + #!/usr/bin/env python3 + + # deploy-app.py + + import sys + from pathlib import Path + from textwrap import dedent + + def generate_manifest(app_name, image, replicas=1, port=80): + """Generate valid Kubernetes YAML using only built-in Python""" + + manifest = f"""\ + apiVersion: apps/v1 + kind: Deployment + metadata: + name: {app_name} + labels: + app: {app_name} + spec: + replicas: {replicas} + selector: + matchLabels: + app: {app_name} + template: + metadata: + labels: + app: {app_name} + spec: + containers: + - name: {app_name} + image: {image} + ports: + - containerPort: {port} + --- + apiVersion: v1 + kind: Service + metadata: + name: {app_name} + labels: + app: {app_name} + spec: + type: ClusterIP + selector: + app: {app_name} + ports: + - port: 80 + targetPort: {port} + protocol: TCP + """ + + # Clean dedent + write + clean_yaml = dedent(manifest).strip() + "\n" + file_path = Path("temp-manifest.yaml") + file_path.write_text(clean_yaml, encoding="utf-8") + return str(file_path) + + def print_usage(): + print("""Kubernetes Zero-Dependency Deploy + + Usage: + python deploy-app.py [replicas] [port] + + Examples: + python deploy-app.py web nginx:latest + python deploy-app.py api ghcr.io/myorg/api:v2 3 5000 + python deploy-app.py redis redis:7.2 1 6379 + + No pip, no yaml, no problem. + + """) + + if __name__ == "__main__": + args = sys.argv[1:] + + if not args or "-h" in args or "--help" in args: + print_usage() + sys.exit(0) + + if len(args) < 2: + print("Error: Need ") + print_usage() + sys.exit(1) + + app_name = args[0] + image = args[1] + + replicas = 1 + port = 80 + + # Parse optional positional numeric args: [replicas] [port] + if len(args) > 2: + if args[2].isdigit(): + replicas = int(args[2]) + else: + print(f"Error: replicas must be a number, got '{args[2]}'") + sys.exit(1) + + if len(args) > 3: + if args[3].isdigit(): + port = int(args[3]) + else: + print(f"Error: port must be a number, got '{args[3]}'") + sys.exit(1) + + if len(args) > 4: + print("Error: Too many arguments") + print_usage() + sys.exit(1) + + # Optional: validate reasonable ranges + if replicas < 1: + print("Error: replicas must be >= 1") + sys.exit(1) + if not (1 <= port <= 65535): + print("Error: port must be between 1 and 65535") + sys.exit(1) + + print(f"Deploying {app_name}") + print(f" Image: {image}") + print(f" Replicas: {replicas}") + print(f" Container port: {port} → Service port: 80") + print() + + path = generate_manifest(app_name, image, replicas, port) + print(f"Manifest saved → {path}") + print() + print("Next:") + print(f" kubectl apply -f {path}") + EOF + chmod +x scripts/deploy-app.py ``` The scripts perform the actual work. In this example, `deploy-app.py` generates Kubernetes manifests based on the parameters provided. 4. Create a Dockerfile. - ```dockerfile + ```bash + cat > Dockerfile <<'EOF' FROM scratch COPY . / + EOF + ``` + +5. For local testing, start a Docker registry on your local host. Before building and pushing to a localhost registry, check if you already have one running. + + ```bash + docker ps | grep registry ``` -5. Build and push the image to a container registry. You can push skill containers to any container registry: + - If you see a registry container, note the port mapping (for example, `127.0.0.1:5001->5000/tcp` means the registry is accessible on port 5001). + - If no registry is running, start one. + ```bash + docker run -d -p 5000:5000 --restart=always --name local-registry registry:2 + ``` + + If your registry is on a different port (like 5001), use that port in the following commands instead of 5000. + +6. Build and push the image to a container registry. You can push skill containers to any container registry: + + - Localhost registry: `localhost:PORT/skill-name:tag` - Docker Hub: `docker.io/username/skill-name:tag` - GitHub Container Registry: `ghcr.io/username/skill-name:tag` - Google Container Registry: `gcr.io/project/skill-name:tag` - Amazon ECR: `123456789012.dkr.ecr.region.amazonaws.com/skill-name:tag` - Any private registry: `registry.example.com/skill-name:tag` + ```bash - docker build -t your-registry/k8s-deploy-skill:latest . - docker push your-registry/k8s-deploy-skill:latest + docker build -t localhost:5000/k8s-deploy-skill:latest . + docker push localhost:5000/k8s-deploy-skill:latest ``` -### Use container-based skills in an agent +### Step 2: Use container-based skills in an agent To load container-based skills into your agent, reference them in the `spec.skills.refs` field. ```yaml @@ -205,9 +370,10 @@ spec: type: Declarative skills: # Only for development/testing (e.g., localhost registry) - # insecureSkipVerify: true + insecureSkipVerify: true refs: - - your-registry/k8s-deploy-skill:latest + # For Kind clusters, use kind-registry:5000 instead of localhost:5000 + - kind-registry:5000/k8s-deploy-skill:latest declarative: modelConfig: default-model-config stream: true @@ -234,40 +400,84 @@ When the agent starts, kagent automatically: The agent can then discover and load skills using the SkillsTool, which reads the `SKILL.md` files and makes the skill instructions available to the LLM. -## Test the agent's skills + +### Step 3: Test container-based skills After creating the agent, test it with queries that match your skills. -### Test A2A skills +1. Ask the agent what skills it has. -For agents with A2A skills metadata, test with queries that match the skill examples. + ```bash + kagent invoke --agent k8s-assistant-with-skills --task "What skills do you have?" + ``` -```bash -kagent invoke --agent k8s-troubleshooting-agent --task "Why is my pod in the default namespace restarting?" -``` + Example output: -The agent should use its "Diagnose Pod Issues" skill to systematically investigate the problem. + ```json + {"artifacts":[{"artifactId":"91afd732-3fa5-4e25-8f0e-07a4968050e5","parts":[{"kind":"text","text":"I am a Kubernetes AI agent with deployment skills. I can help you deploy and manage Kubernetes applications by working with manifests, describing resources, getting resource details, and applying configurations to your Kubernetes cluster. However, currently, I do not have any additional specialized skills loaded beyond these core Kubernetes capabilities. If you have any Kubernetes-related tasks or questions, feel free to ask!"}]}],"contextId":"f130122c-06e1-467c-9eb3-fe3704988b4d","history":[{"contextId":"f130122c-06e1-467c-9eb3-fe3704988b4d","kind":"message","messageId":"msg-cd691a32-c0d8-471d-b8eb-e4e3265621ce","parts":[{"kind":"text","text":"What skills do you have?"}],"role":"user","taskId":"b7ee2804-b15e-4dee-b6e9-ca2901383a10"},{"contextId":"f130122c-06e1-467c-9eb3-fe3704988b4d","kind":"message","messageId":"msg-cd691a32-c0d8-471d-b8eb-e4e3265621ce","parts":[{"kind":"text","text":"What skills do you have?"}],"role":"user","taskId":"b7ee2804-b15e-4dee-b6e9-ca2901383a10"},{"kind":"message","messageId":"e22926e1-50d2-4571-a039-a3dcf8dfb2b8","parts":[{"kind":"text","text":"I am a Kubernetes AI agent with deployment skills. I can help you deploy and manage Kubernetes applications by working with manifests, describing resources, getting resource details, and applying configurations to your Kubernetes cluster. However, currently, I do not have any additional specialized skills loaded beyond these core Kubernetes capabilities. If you have any Kubernetes-related tasks or questions, feel free to ask!"}],"role":"agent"}],"id":"b7ee2804-b15e-4dee-b6e9-ca2901383a10","kind":"task","metadata":{"kagent_app_name":"kagent__NS__k8s_assistant_with_skills","kagent_author":"k8s_assistant_with_skills","kagent_invocation_id":"e-ceaee83e-40a1-4088-b545-89e96f71608e","kagent_session_id":"f130122c-06e1-467c-9eb3-fe3704988b4d","kagent_usage_metadata":{"candidatesTokenCount":74,"promptTokenCount":1236,"totalTokenCount":1310},"kagent_user_id":"admin@kagent.dev"},"status":{"state":"completed","timestamp":"2025-11-21T22:13:16.484468+00:00"}} + ``` -### Test container-based skills +2. Invoke a skill, such as by asking it to deploy an app. -For agents with container-based skills, you can ask the agent what skills it has. + ```bash + kagent invoke --agent k8s-assistant-with-skills --task "Use your skill to deploy an app named 'httpbin' using the image 'docker.io/mccutchen/go-httpbin:v2.15.0' on port 8080" + ``` -```bash -kagent invoke --agent agent-with-container-skills --task "What skills do you have?" -``` + The agent: + 1. Reviews the instructions in the skill's `SKILL.md` file. + 2. Invokes the appropriate script with the correct parameters. + 3. Uses its tools to apply the generated resources (in this case, applying the Kubernetes manifest). -The agent will list its available skills. Then you can invoke a skill. + Example output: -```bash -kagent invoke --agent agent-with-container-skills --task "Use your skill to deploy an app named 'httpbin' using the image 'docker.io/mccutchen/go-httpbin:v2.15.0' on port 8080" -``` + ```json + {"artifacts":[{"artifactId":"9f7ad622-9e1a-4b6e-8c59-7b33846e6245","parts":[{"kind":"text","text":"The app named 'httpbin' has been deployed using the image 'docker.io/mccutchen/go-httpbin:v2.15.0' on port 8080. A deployment and a corresponding service have been created. Let me know if you need any other assistance with this deployment."}]}],"contextId":"6d25b097-ab63-4f9b-8c37-7481fe9a1098","history":[{"contextId":"6d25b097-ab63-4f9b-8c37-7481fe9a1098","kind":"message","messageId":"msg-7e6a6435-997b-4afa-9f63-2777ad44a154","parts":[{"kind":"text","text":"Use your skill to deploy an app named 'httpbin' using the image 'docker.io/mccutchen/go-httpbin:v2.15.0' on port 8080"}],"role":"user","taskId":"3020e09e-3e9b-4840-a805-feb9817d20a2"},{"contextId":"6d25b097-ab63-4f9b-8c37-7481fe9a1098","kind":"message","messageId":"msg-7e6a6435-997b-4afa-9f63-2777ad44a154","parts":[{"kind":"text","text":"Use your skill to deploy an app named 'httpbin' using the image 'docker.io/mccutchen/go-httpbin:v2.15.0' on port 8080"}],"role":"user","taskId":"3020e09e-3e9b-4840-a805-feb9817d20a2"},{"kind":"message","messageId":"114436b5-1b9e-4191-aabc-cc4f1db6f6a0","parts":[{"kind":"data","data":{"args":{"manifest":"apiVersion: apps/v1\nkind: Deployment\nmetadata:\n name: httpbin\nspec:\n replicas: 1\n selector:\n matchLabels:\n app: httpbin\n template:\n metadata:\n labels:\n app: httpbin\n spec:\n containers:\n - name: httpbin\n image: docker.io/mccutchen/go-httpbin:v2.15.0\n ports:\n - containerPort: 8080\n---\napiVersion: v1\nkind: Service\nmetadata:\n name: httpbin\nspec:\n selector:\n app: httpbin\n ports:\n - protocol: TCP\n port: 8080\n targetPort: 8080\n type: ClusterIP\n"},"id":"call_PdIQF51hPu1iBcOt3v1DkOzC","name":"k8s_apply_manifest"},"metadata":{"kagent_type":"function_call"}}],"role":"agent"},{"kind":"message","messageId":"1279457b-137b-4730-a1be-5dbe2985973b","parts":[{"kind":"data","data":{"id":"call_PdIQF51hPu1iBcOt3v1DkOzC","name":"k8s_apply_manifest","response":{"result":{"content":[{"text":"deployment.apps/httpbin created\nservice/httpbin created\n","type":"text"}],"isError":false}}},"metadata":{"kagent_type":"function_response"}}],"role":"agent"},{"kind":"message","messageId":"aefb1f07-3258-46bb-b078-515a9a6f08e5","parts":[{"kind":"text","text":"The app named 'httpbin' has been deployed using the image 'docker.io/mccutchen/go-httpbin:v2.15.0' on port 8080. A deployment and a corresponding service have been created. Let me know if you need any other assistance with this deployment."}],"role":"agent"}],"id":"3020e09e-3e9b-4840-a805-feb9817d20a2","kind":"task","metadata":{"kagent_app_name":"kagent__NS__k8s_assistant_with_skills","kagent_author":"k8s_assistant_with_skills","kagent_invocation_id":"e-b8f3e41b-a741-4338-b19b-f3a46ca33826","kagent_session_id":"6d25b097-ab63-4f9b-8c37-7481fe9a1098","kagent_usage_metadata":{"candidatesTokenCount":60,"promptTokenCount":1505,"totalTokenCount":1565},"kagent_user_id":"admin@kagent.dev"},"status":{"state":"completed","timestamp":"2025-11-21T22:14:33.755060+00:00"}} + ``` + +3. Check that the `httpbin` app was deployed successfully. + + ```bash + kubectl get pods --namespace kagent | grep httpbin + ``` + + Example output: + + ``` + httpbin-b8b86ff46-rn7mf 1/1 Running 0 2m16s + ``` + +## Cleanup -The agent: -1. Reviews the instructions in the skill's `SKILL.md` file. -2. Invokes the appropriate script with the correct parameters. -3. Uses its tools to apply the generated resources (in this case, applying the Kubernetes manifest). +When you're done, you can clean up the resources that you created. -You can verify the results by checking that the resources were created successfully. +1. Delete the agents that you created. + + ```bash + kubectl delete agent k8s-troubleshooting-agent -n kagent + kubectl delete agent k8s-assistant-with-skills -n kagent + ``` + +2. Clean up any applications that were deployed during testing, such as the `httpbin` app. + + ```bash + kubectl delete deployment httpbin -n kagent + kubectl delete service httpbin -n kagent + ``` + +3. Remove the skill directory and files that you created. + + ```bash + cd .. + rm -rf k8s-deploy-skill + ``` + +4. Optionally, remove the Docker image and registry that you used for local testing. + + ```bash + docker rmi localhost:5000/k8s-deploy-skill:latest + docker stop local-registry + docker rm local-registry + ``` ## Next steps From 79a7830f1cd73255fd0e991e04f40a63748a2d91 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Mon, 24 Nov 2025 09:40:04 -0500 Subject: [PATCH 3/3] Revise and remove A2A Signed-off-by: Art Berger --- src/app/docs/kagent/concepts/agents/page.mdx | 49 +++++++- src/app/docs/kagent/examples/skills/page.mdx | 112 +------------------ 2 files changed, 48 insertions(+), 113 deletions(-) diff --git a/src/app/docs/kagent/concepts/agents/page.mdx b/src/app/docs/kagent/concepts/agents/page.mdx index beb6e433..4c2aefde 100644 --- a/src/app/docs/kagent/concepts/agents/page.mdx +++ b/src/app/docs/kagent/concepts/agents/page.mdx @@ -50,11 +50,11 @@ Kagent comes with a set of built-in tools that you can use to interact with your ## Skills -Skills are descriptions of the capabilities that an agent has to act more autonomously. They make the LLM's responses more than just reactions to prompts by orienting them toward goals. +Skills are descriptions or even executable implementations of the capabilities that an agent has to act more autonomously. They make the LLM's responses more than just reactions to prompts by orienting them toward goals. In some frameworks, skills are expressed as wrapped functions, reusable prompt templates, or even a synonym for a tool. -In kagent, think of skills like a catalog that expresses what the agent is capable of doing for a user. Unlike tools, skills are not a specific function that produces an output, like "fetch a website" or "tell the weather." Unlike system instructions, they are not rules that apply to all interactions, such as "Follow my company's style guide." +Think of skills like a catalog that expresses what the agent is capable of doing for a user. Unlike tools, skills are not a specific function that produces an output, like "fetch a website" or "tell the weather." Unlike system instructions, they are not rules that apply to all interactions, such as "Follow my company's style guide." Instead, skills are building blocks that guide the agent's tool usage and planning. They help the agent understand what its goals are, and when and how to use tools effectively. @@ -63,13 +63,50 @@ For example, two agents may share the same tools but use them differently based - A troubleshooting agent might use a `describe` tool to check the events of a crashing pod before taking a recovery action, such as restarting the pod. - A research agent might use the same `describe` tool to gather details about a pod in order to answer a user's question. -Kagent supports two types of skills: +Skills can refer to two broad types: -1. **A2A skills** (metadata): Structured descriptions of capabilities defined in `a2aConfig.skills`. These consist of a description, examples, ID, and tags that help guide the agent's behavior. The description and examples provide context for both humans and the agent itself, often incorporated into system instructions. The ID and tags help you manage skills, such as by making it simpler to compare and reuse them across agents. +* **A2A skills**: Metadata-based skills that are defined inline in the agent specification. +* **Kagent's container-based skills**: Executable skills packaged as container images and loaded from registries, for reuse across agents. You can use the [agentregistry project](https://github.com/agentregistry-dev/agentregistry) to build and push skills to a registry. -2. **Container-based skills**: Executable skill implementations packaged as container images. These skills contain instructions, scripts, and resources that are loaded from container registries and made available to the agent at runtime. You can build and push skills as container images, then reference them in `spec.skills.refs` to load them into your agents. +### A2A skills metadata -Skills in kagent are similar to [Claude's Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview), but with a key advantage: any agent can use skills, regardless of the LLM provider. You're not limited to Anthropic Claude. You can use skills with OpenAI, Google Vertex AI, Azure OpenAI, Ollama, and any other LLM provider that kagent supports. +Actions-to-actions (A2A) skills are metadata—structured descriptions of capabilities, not executable code. Think of A2A skills as a machine-readable catalog entry about what a tool can do. + +A2A skills metadata describes: + +- What a capability is +- What the capability can do +- The inputs and outputs +- Safety requirements +- How a model should think about the capability + +A2A skills metadata does not: + +- Provide runtime code +- Execute actions +- Bundle actual logic for performing the skill + +In kagent, you define A2A skills in `a2aConfig.skills`. These consist of a description, examples, ID, and tags that help guide the agent's behavior. The description and examples provide context for both humans and the agent itself, often incorporated into system instructions. The ID and tags help you manage skills, such as by making it simpler to compare and reuse them across agents. + +A2A skills are instructions about capabilities, not the capabilities themselves. That is why A2A is sometimes described as "just metadata"—it's descriptive information, not executable code. + +### Container-based skills + +Kagent's container-based skills are executable skill implementations packaged as container images. These are runnable procedural logic that the agent can use as an extension of itself. + +Container-based skills include: + +- Executable code snippets or procedures +- Behavior modules that the agent can call at inference time +- Validation and step-by-step behaviors +- Reusable functions +- Direct execution capabilities + +These skills contain instructions, scripts, and resources that are loaded from container registries and made available to the agent at runtime. You can build and push skills as container images, then reference them in `spec.skills.refs` to load them into your agents. + +Container-based skills are actual, callable capabilities—not just descriptions of capabilities. + +Kagent's skills are similar to [Claude's Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview), but with a key advantage: any agent can use skills, regardless of the LLM provider. You're not limited to Anthropic Claude. You can use skills with OpenAI, Google Vertex AI, Azure OpenAI, Ollama, and any other LLM provider that kagent supports. ### Best practices for skills diff --git a/src/app/docs/kagent/examples/skills/page.mdx b/src/app/docs/kagent/examples/skills/page.mdx index f6466653..58c3f8b4 100644 --- a/src/app/docs/kagent/examples/skills/page.mdx +++ b/src/app/docs/kagent/examples/skills/page.mdx @@ -14,10 +14,11 @@ export const metadata = { Skills are descriptions of capabilities that help agents act more autonomously. They guide the agent's tool usage and planning by orienting responses toward goals rather than just reacting to prompts. -In this guide, you learn how to add skills to your agents in kagent. Kagent supports two types of skills: +In this guide, you learn how to add container-based skills to your agents in kagent. -1. **A2A skills** (metadata): Structured descriptions of capabilities defined inline the agent specification in the `a2aConfig.skills` field. -2. **Container-based skills**: Executable skills packaged as container images and loaded from registries, for reuse across agents. You can use the [agentregistry project](https://github.com/agentregistry-dev/agentregistry) to build and push skills to a registry. + ## Before you begin @@ -25,112 +26,9 @@ In this guide, you learn how to add skills to your agents in kagent. Kagent supp 2. Review the concepts of [agents and skills](/docs/kagent/concepts/agents) in kagent. -## Inline A2A skills metadata - -Create an agent that uses skills to guide its behavior. This example creates a Kubernetes troubleshooting agent with skills for diagnosing and fixing issues. - -Skills are defined under `a2aConfig` in the agent specification. Even if you're not exposing your agent via the A2A protocol, defining skills under `a2aConfig` helps guide the agent's behavior and tool usage in all conversations. - -```yaml -kubectl apply -f - <"Investigate the pod restarts in the production namespace"
"Check why the pod is not starting"
"Diagnose resource issues with my deployment" | "What's the health status of my cluster?"
"Check if there are any issues in the cluster"
"Analyze cluster resource usage"
"Review cluster events for problems" | - -### Test A2A skills - -For agents with A2A skills metadata, test with queries that match the skill examples. - -```bash -kagent invoke --agent k8s-troubleshooting-agent --task "Can you find any unhealthy pods in the kagent namespace?" -``` - -Example output: The agent uses its "Diagnose Pod Issues" skill to systematically investigate the problem. - -```json -{"artifacts":[{"artifactId":"b626f5ea-1994-48e0-8266-0141bda3322d","parts":[{"kind":"text","text":"All the pods in the kagent namespace appear to be healthy. They are all in the \"Running\" status with all containers ready (1/1) and no restarts reported. There are no unhealthy pods in the kagent namespace at this time. Is there anything specific you would like me to check or troubleshoot further?"}]}], -... -``` - ## Container-based skills -Container-based skills are executable skill implementations packaged as container images. These skills contain instructions, scripts, and other resources that the agent can discover and use at runtime. This way, you can reuse skills across agents. You might pair the inline metadata skills with more general purpose, container-based skills depending on your agent's needs. - - +Container-based skills are executable skill implementations packaged as container images. These skills contain instructions, scripts, and other resources that the agent can discover and use at runtime. This way, you can reuse skills across agents. ### Step 1: Build a skill container