Skip to main content
Agents are AI services that plan and execute tasks. Each agent runs with a chosen model, the tools you attach (MCP servers and Skills), and the configuration it inherits from one or more Environments. Kubiya Platform Overview For example, you might create a “DevOps Assistant” agent that automatically checks system health and deploys updates, or a “Cost Auditor” agent that reviews cloud expenses and sends alerts if budgets are exceeded. Each agent is dedicated to executing a specific set of tasks, ensuring that responsibilities are clearly defined and easily reusable.

​
When to use

Create an agent when you want a reusable capability (e.g., “DevOps Assistant”, “SRE Helper”, “Cost Auditor”) that can be invoked by users, Teams, and workflows.

​
Prerequisites

  • At least one Environment (e.g., default) in Ready state.
  • A Worker Queue connected to that Environment so tasks can run.
  • Any required secrets or integration credentials available (prefer storing them at the Environment level).

​
Key concepts & defaults

  • Model: The base LLM the agent uses (e.g., Claude Sonnet 4).
  • MCP Servers vs. Skills
    • MCP Servers: External integrations and platform APIs (workflows, resources, collaboration).
    • Skills: System-level capabilities such as file operations, shell, Docker, Python. Grant least privilege; agents also inherit Skills from their Environments.
  • Environments: Provide runtime config (env vars, secrets, credentials), context (knowledge, resources), and policies the agent inherits.
  • Policies: OPA rules you associate after creating the agent.
  • System Prompt (Advanced): A sensible default is provided; only tailor it when you need stricter guidance.

​
Create an agent

Agents Creation
  1. Open: Agents > Create Agent.
  2. Basic Info
    • Agent Name: Clear and specific (e.g., “DevOps Assistant”).
    • Description: What this agent is for (shows up in lists).
    • AI Model: Pick the model.
    • Capabilities (tags): Optional labels to aid search (e.g., devops, monitoring).
  3. Deployment
    • Runtime: Leave default unless you have a specific need.
    • Environments: Add one or more (staging, prod, etc.). The agent will inherit config and can run wherever there is capacity.
    • Execution Environment
      • Environment Variables: Non-secret parameters.
      • Secrets: Attach only if agent-specific; otherwise keep them at the Environment.
      • Integration Credentials: Bind credentials for external systems. Tip: If the agent should run in both staging and production, add both Environments here and keep differences (URLs, tokens) at the Environment level.
  4. Tools
    • MCP Servers
      • Keep “Enable Kubiya Platform APIs” on (recommended) unless a policy requires otherwise.
      • Add Custom MCP Servers as needed (name, command, arguments).
    • Skills
      • Click Add/Browse Skills and select the minimum the agent needs.
      • Remember: Skills from the Environment also apply.
  5. Policies
    • Save the agent first, then return to associate OPA policies that restrict actions, data, or scope.
  6. Advanced
    • System Prompt: The default instructs the agent to check available tools, use MCP for integrations, use Skills for system operations, and work step-by-step. Adjust only if necessary and keep it brief and testable.

​
Verify & troubleshoot

  • From Agents, open the agent’s Chat and try a safe read-only action (e.g., “List running services”).
  • If a task stays Pending:
    • Confirm the target Environment is Ready.
    • Check the Worker Queue for that Environment has at least one connected worker.
    • Review attached Skills/credentials match what the task needs.

​
Good practices

  • Least privilege first: Start with “safe” Skills; add fuller access only when required.
  • Centralize configuration: Put common env vars, secrets, and credentials at the Environment level.
  • One agent, many contexts: Attach multiple Environments instead of duplicating agents for staging/prod.
  • Add policies after testing: Validate expected behavior on harmless tasks, then lock down with OPA.