Skip to main content

​
Overview

Capabilities and governance resources define what agents can do and enforce rules around how they operate. These resources ensure agents have the right tools while maintaining security and compliance.

​
Tool Sets (Skills)

Tool sets, also known as skills, define collections of tools and capabilities that agents can use. They package related functionality together for reusability. Tool sets include:
  • Tool definitions and schemas
  • API integrations
  • Custom functions
  • MCP (Model Context Protocol) servers
Common tool sets:
  • Kubernetes: kubectl commands, cluster operations
  • Cloud Providers: AWS, GCP, Azure operations
  • DevOps: CI/CD, monitoring, deployment tools
  • Communication: Slack, email, notifications
  • Data: SQL queries, data analysis, reporting
Benefits:
  • Reusability: Define once, use across multiple agents
  • Versioning: Manage tool versions and updates
  • Governance: Control which tools are available to which agents
  • Testing: Test tools independently before deployment

​
Policies

Policies enforce governance rules using Open Policy Agent (OPA). They control:
  • Which tools agents can use
  • What resources agents can access
  • What actions require approval
  • Compliance and security rules
Policy types:
  • Permission policies: Control access to tools and resources
  • Approval policies: Require human approval for sensitive operations
  • Rate limiting policies: Prevent abuse and control costs
  • Data policies: Enforce data handling and privacy rules

​
Policy Language

Policies are written in Rego (OPA’s policy language): 
package kubiya.agent.permissions

# Allow agent to use kubectl
allow {
    input.agent.team == "devops"
    input.tool.name == "kubectl"
}

# Require approval for production deployments
requires_approval {
    input.tool.name == "kubectl"
    input.args.namespace == "production"
    input.command contains "apply"
}

​
Common Patterns

​
List Available Skill Definitions

# Get all available skill types
GET /api/v1/skills/definitions

# Get specific skill definition
GET /api/v1/skills/definitions/{skill_type}

# Get skill variants/presets
GET /api/v1/skills/definitions/{skill_type}/variants

​
Create a Skill

POST /api/v1/skills
{
  "name": "kubernetes-ops",
  "type": "kubernetes",
  "configuration": {
    "cluster_url": "https://k8s.example.com",
    "namespace": "default"
  }
}

​
Validate Skill Configuration

POST /api/v1/skills/definitions/{skill_type}/validate
{
  "configuration": {
    "cluster_url": "https://k8s.example.com"
  }
}

​
Associate Skills with Entities

# Add skill to an agent
POST /api/v1/skills/associations/agents/{agent_id}/skills
{
  "skill_id": "skill-uuid"
}

# List agent's skills (with inheritance)
GET /api/v1/skills/associations/agents/{agent_id}/skills/resolved

# Add skill to a team
POST /api/v1/skills/associations/teams/{team_id}/skills
{
  "skill_id": "skill-uuid"
}

​
Create a Policy

POST /api/v1/policies
{
  "name": "production-deployment-approval",
  "description": "Require approval for production deployments",
  "policy_text": "package kubiya.agent.approval\n\nrequires_approval {\n  input.tool.name == \"kubectl\"\n  input.args.namespace == \"production\"\n}",
  "policy_type": "approval"
}

​
Associate Policies

# Create policy association
POST /api/v1/policies/associations
{
  "policy_id": "policy-uuid",
  "entity_type": "agent",
  "entity_id": "agent-uuid",
  "enabled": true,
  "priority": 100
}

# Get resolved policies for an entity (with inheritance)
GET /api/v1/policies/resolved/agents/{agent_id}

# Evaluate policies
POST /api/v1/policies/evaluate/agents/{agent_id}
{
  "input": {
    "tool": {"name": "kubectl"},
    "args": {"namespace": "production"}
  }
}

​
Tool Discovery

Agents can discover available tools through:
  • Tool set catalogs
  • Dynamic tool loading
  • MCP server discovery
  • Integration-based tools

​
Policy Evaluation

Policies are evaluated in real-time:
  1. Agent requests to use a tool
  2. System evaluates applicable policies
  3. If allowed, tool executes
  4. If approval required, creates approval request
  5. If denied, returns error to agent

​
Best Practices

​
Tool Set Design

  1. Focused functionality: Group related tools together
  2. Clear documentation: Document each tool’s purpose and parameters
  3. Versioning: Use semantic versioning for tool sets
  4. Testing: Test tools thoroughly before deployment

​
Policy Management

  1. Least privilege: Start with minimal permissions, add as needed
  2. Audit logging: Log all policy evaluations
  3. Testing: Test policies in development before production
  4. Documentation: Document policy intent and scope
  5. Regular review: Review and update policies regularly

​
Security

  1. Input validation: Validate all tool inputs
  2. Secrets management: Never hardcode credentials in tools
  3. Rate limiting: Prevent abuse through rate limits
  4. Monitoring: Monitor tool usage for anomalies

​
Next Steps

Explore the API endpoints for tool sets and policies to learn how to define capabilities and enforce governance rules.