Skip to main content
Agents are configurable AI services that plan and execute tasks. Each agent runs a selected LLM model, a set of Skills (and optional MCP servers), and the configuration it inherits from attached Environments. Agents execute deterministic step-by-step plans, using Skills for system operations and MCP integrations for external APIs. Kubiya Platform Overview Examples:
  • A DevOps Assistant that checks system health and deploys updates
  • A Cost Auditor that reviews cloud spending and raises alerts
  • A SRE Helper that diagnoses incidents using logs, metrics, and runbooks
Agents are reusable, can be shared across teams and workflows, and automatically inherit configuration from the Environments they run in.

​
When to use an Agent

Create an agent when you need a reusable operational capability that:
  • Runs tasks repeatedly (deployments, audits, checks)
  • Automates domain workflows (SRE, DevOps, ops, finance, support)
  • Can be invoked by users, Teams, or tasks and workflows

​
Prerequisites

Before creating an agent, ensure:
  • At least one Environment is in Ready state
  • A Worker Queue with at least one connected worker is attached to that Environment
  • Any required secrets or integration credentials exist (prefer storing them at the Environment level)

​
Key concepts & defaults

  • Model The LLM the agent uses (Sonnet, Opus, GPT-4o). Higher tiers are more capable but costlier.
  • Skills Capabilities for local/system operations (shell, file operations, Docker, Python). Agents inherit Skills from their Environments.
  • MCP Servers External services and platform APIs the agent can call.
  • Environments Provide runtime configuration, env vars, secrets, credentials, and policies.
  • Policies (OPA) Attach after creation to restrict actions or access.
  • System Prompt Defines AI instructions. The default covers tool usage, planning, and safety. Edit only when needed.

​
Create an agent

Agents Creation

​
1. Basic Info

  • Agent Name Clear and specific: “DevOps Assistant”, “SRE Helper”, “Cost Auditor”.
  • Description Helps users understand the use case.
  • AI Model Select capability tier appropriate for the tasks.
  • Capabilities (tags) Optional filters such as: devops, monitoring, cost, security.

​
2. Deployment

  • Runtime Default recommended unless you have a specific need.
  • Environments Add one or more Environments (e.g., staging, prod). The agent inherits configuration and can run where capacity exists.
Tip: If the agent should operate in multiple environments, attach both and keep environment-specific secrets and URLs at the Environment level, not the agent.

​
3. Execution Environment

  • Environment Variables Non-secret configuration values.
  • Secrets Add only when agent-specific. Prefer keeping shared secrets on the Environment.
  • Integration Credentials Add credentials for external systems the agent needs to access.

​
4. Tools (Skills & MCP)

​
MCP Servers

  • Leave Enable Kubiya Platform APIs ON unless restricted by policy.
  • Add custom MCP servers as needed (name, command, arguments).

​
Skills

  • Add only the minimum Skills required.
  • Remember: Skills from Environments also apply.

​
5. Policies

After saving the agent, return to associate OPA policies that limit scope (e.g., allowed paths, allowed commands, allowed resources).

​
6. Advanced

  • System Prompt A sensible default is provided. Adjust only to add specific constraints or operational guidance. Keep it short, testable, and easy to maintain.

​
Verify & troubleshoot

After creation, open the agent’s Chat and run a safe read-only test such as: 
List running services.
If a task remains Pending:
  • Ensure the target Environment is Ready
  • Check the Environment’s Worker Queue has at least one connected worker
  • Verify required Skills or credentials are attached
  • Review OPA policies for restrictions blocking execution
For more info on how to use the cli to manage agents go to Agents Cli

​
Best Practices

  • Start with least privilege, add Skills gradually
  • Store common secrets/config at the Environment level
  • Use one agent across multiple Environments instead of cloning
  • Test with simple read-only commands first
  • Apply OPA policies after verifying correct behavior

​
Next Steps

  • Attach more Skills or MCP integrations
  • Ensure Worker Queues have active workers
  • Build tasks or workflows that use this agent
  • Configure policies for safe multi-environment operation