Skip to main content
In this lesson we cover agents and their architecture — a core component of KAgent. You’ll learn what agents are, how they’re structured, and how they use instructions, tools, and skills to act on behalf of users. An AI agent is an application that interacts in natural language, typically backed by a large language model (LLM). Agents not only generate conversational responses but can also execute actions using callable capabilities. The main agent components are summarized below.
ComponentPurpose
Agent instructionsSystem-like prompt defining role, behavior, and constraints
ToolsCallable functions that interact with external systems or the environment
SkillsReusable capability descriptions or executable modules that guide agent planning

​
Agent instruction

Agent instructions act like a system prompt (similar to the system role in ChatGPT). They define the agent’s role, permitted actions, tone, and how to handle special situations (including collaboration with other agents). Common elements of an agent instruction:
  • Role definition (for example: “You are a Kubernetes agent that helps users manage cluster resources.”)
  • Response style (concise, verbose, formal, etc.)
  • Allowed and disallowed actions
  • Guidance for interacting with other agents or external systems
Example agent instruction (brief):
  • You are a Kubernetes agent that helps users manage Kubernetes resources.
  • Your responses should be clear and concise.
  • Provide helpful information and guidance to users.
Primary goals of agent instructions:
  • Define role and capabilities
  • Help the agent interpret the environment and user intent
  • Guide response style and decision-making
Quick recap — what an agent instruction enables:
  1. Understand the task at hand.
  2. Know which tools and skills are available.
  3. Interpret the user’s intent and produce an appropriate plan.

​
Tools

Tools are the functions an agent can call to interact with external systems (e.g., cluster APIs, databases, third-party services). Tool definitions and descriptions are provided to the LLM along with the agent instruction so the model can choose which tool to call and with what inputs. Typical example flow:
  • User: “How many pods are failing in the payment namespace?”
  • Agent sends the user query, agent instruction, and tool list (e.g., list pods, get pod status) to the LLM.
  • LLM selects list pods with namespace=payment.
  • Agent executes list pods and returns pod names.
  • LLM decides to call get pod status for each pod.
  • Agent runs get pod status for each pod, collects results.
  • LLM aggregates the results, counts failing pods, formats a response, and returns it to the user.
Design tool interfaces clearly: provide precise parameter schemas, expected outputs, and error semantics so the LLM can reliably choose and invoke the right tool.
Tool types in KAgent:
  • Built-in tools: Provided by KAgent (examples: Helm, Argo Rollouts, gateway-related tools).
  • MCP tools: External or third-party tools integrated via KAgent’s MCP mechanism (using KMCP or similar connectors).

​
Skills

Skills are higher-level capabilities that make agent behavior goal-directed rather than purely reactive. They help the agent decide when and how to use tools to accomplish user goals.
  • A skill can be a descriptive capability (metadata) or an executable component (container-based).
  • Skills help map user intent to appropriate tool usage and planning strategies.
  • Skills are reusable across multiple agents and are typically narrower and more focused than general system instructions.
A presentation slide titled "Skills — Characteristics" with three dark rounded boxes labeled "Wrapped functions," "Reusable Prompt templates," and "Synonym for a tool." A small "© Copyright KodeKloud" appears in the bottom-left.
Differences between tools and skills
  • Tools are executable functions that produce direct output when invoked.
  • Skills can be non-executable descriptions that guide planning or can be executable (container-based) capabilities.
  • System instructions are global rules that are always active; skills are applied contextually and are typically task-specific.
A slide titled "Skills — Differences" showing a two-column comparison of "Tools" vs "Skills" and "System Instructions" vs "Skills." Each column contains labeled boxes listing attributes like "Executable functions / Produce direct output" versus "Non-executable abilities / Guide task execution" and "Global rules / Always active" versus "Task-specific behavior."
Skills are the building blocks that guide how an agent uses tools and plans actions. They help the LLM form a multi-step plan and decide which tools to call and when. Example — same tool, different skills:
  • Two agents (Troubleshooting Agent and Research Agent) both have access to a DescribePod tool:
    • Troubleshooting Agent (skill: incident resolution) uses DescribePod to inspect pod events, determine recovery actions, and possibly restart pods.
    • Research Agent (skill: information analysis) uses DescribePod to collect pod metadata, interpret it for insights, and answer analytical questions.
An infographic titled "Skills" showing two friendly robot agents — a Troubleshooting Agent and a Research Agent — linked by a central "Describe Pod" box. Each agent has a vertical flow of steps: the Troubleshooting Agent focuses on incident resolution and pod restart, while the Research Agent gathers pod details, interprets data, and answers queries.

​
Types of skills

KAgent supports two primary skill types:
  1. A2A metadata skills — declarative descriptions that guide reasoning and mapping of user intent.
  2. Container-based (executable) skills — packaged containers that provide runnable logic.
A slide titled "Types of Skills" showing two top categories ("A2A Skills Metadata" and "Container-Based Skills") and a central "Actions-to-Actions Skills" area. Below that is a large "a2aConfig.skills" box with fields like Description, Examples, ID, and a "kagent" logo at the bottom.
A2A metadata skills
  • Structured descriptions of capabilities (not executable).
  • Metadata fields commonly include: description, examples, ID, tags, input/output modes, and safety guidance.
  • Use cases: guiding the LLM’s reasoning, mapping user phrasings to capabilities, and offering contextual examples.
  • Typically defined under a2aConfig.skills with fields for description, examples, id, and tags.
Example A2A skill definition (declarative): 
a2aConfig:
  skills:
  - id: get-resources-skill
    name: Get Resources
    description: Get resources in the Kubernetes cluster
    inputModes:
      - text
    outputModes:
      - text
    tags:
      - k8s
      - resources
    examples:
      - "Get all resources in the Kubernetes cluster"
      - "Get the pods in the default namespace"
      - "Get the services in the istio-system namespace"
      - "Get the deployments in the istio-system namespace"
      - "Get the jobs in the istio-system namespace"
      - "Get the cronjobs in the istio-system namespace"
      - "Get the statefulsets in the istio-system namespace"
Note: A2A skills are metadata-only; they do not contain executable logic. Container-based (executable) skills
  • Packaged as container images and include runnable logic, validation, and side-effectful operations.
  • Referenced in agent config (for example via spec.skills.reference with an image URL) and loaded at runtime.
  • Suitable when procedural steps or external side effects are required (for example: interacting with cloud APIs, running scripts, or performing automated remediation).
A slide titled "Types of Skills" comparing "A2A Skills Metadata" and "Container-Based Skills." It shows five labeled boxes: Executable procedures, Callable behaviors, Validation steps, Reusable functions, and Direct execution.
Container-based skill lifecycle:
  1. Implement skill logic (scripts, entrypoint, resources).
  2. Package into a container image.
  3. Push the image to a container registry.
  4. Reference the image in the agent configuration (spec.skills.reference).
  5. Agent loads the container at runtime and exposes callable operations.
Benefits:
  • Reusable and provider-agnostic (can be invoked by agents using OpenAI, Vertex AI, Azure OpenAI Service, Ollama, and others).
  • Enables deterministic, testable procedures for complex or side-effecting operations.

​
Best practices for skills

Follow these guidelines when designing skills to maximize discoverability, reliability, and maintainability:
  • Single responsibility: each skill should represent one clear capability.
  • Provide diverse, realistic examples: include multiple phrasings users might use to invoke the skill.
  • Use descriptive tags: tags help organize and search skills across teams.
  • Align skills with tools: ensure the skill’s described behavior matches the tool(s) the agent can call.
  • Keep skills narrow and focused: prefer “generate PDF” or “generate docx” over a broad “document generator” to make behavior predictable and testable.
A slide titled "Best Practices for Skills" with three numbered cards. The cards advise defining one clear capability per skill, providing diverse realistic usage examples, and using descriptive tags for easy management.
A presentation slide titled "Best Practices for Skills" showing five numbered cards across the page with brief tips for skill design. The fifth card is highlighted and reads "Keep each skill narrowly focused."

​
Skill management

Manage skills through a standard lifecycle to ensure versioning, reuse, and discoverability:
  • Create the skill metadata or implementation.
  • Containerize executable skills and push the image to a registry.
  • Store skills in a centralized skill/agent registry that supports push/pull/versioning.
  • Reference skills from agents and reuse across teams and agents.
A centralized registry simplifies sharing, version control, and governance of skills.
A flow diagram titled "Skill Management" showing steps from Skill Creation to Containerization, into a Skill Registry (built & pushed via AgentRegistry/Claude), and finally Agents that reuse those skills.
When possible, start with an A2A metadata skill to describe the capability and add container-based skills only for actions that require procedural logic, side effects, or external integration.
Links and references

Watch Video