- 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
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
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.
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:- 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
CLI Usage
Below is the improved, structured, easy-to-understand CLI reference.1. List Agents
Lists all agents in your workspace with optional filtering and sorting.Commands
Flags
| Flag | Description |
|---|---|
--active | Show only active agents |
--all | Show full details including capabilities |
--filter | Filter by name/description/tags |
--sort | Sort by name, created, or updated |
--output | Output as text or json |
2. Get Agent Details
Shows complete configuration of a specific agent.Commands
Flags
| Flag | Description |
|---|---|
--output | Output format (text or json) |
3. Create Agents
Creates a new agent with the model, Skills, integrations, and configuration you specify.Commands
Parameter-basedFlags
| Flag | Description |
|---|---|
--name | Agent name |
--desc | Description |
--llm | Model to use |
--env | Add environment variable(s) |
--secret | Attach secrets |
--integration | Add integrations |
--source | Attach source UUIDs |
--knowledge-file | Upload docs as knowledge items |
--webhook-method | slack / teams / http |
--webhook-dest | Channel/URL (except http) |
4. Edit Agents
Updates agent metadata, Skills, integrations, credentials, environment variables, or system prompts.Commands
Common update flags
| Flag | Description |
|---|---|
--add-env / --remove-env | Manage environment variables |
--add-secret / --remove-secret | Manage secrets |
--add-integration / --remove-integration | Manage integrations |
--add-source / --remove-source | Manage source/tools |
--instructions-file | Replace system prompt |
--editor | Edit raw JSON |
5. Manage Access Control
Controls which users and groups can use the agent.Commands
Flags
| Flag | Description |
|---|---|
add-user / remove-user | Manage allowed users |
add-group / remove-group | Manage allowed groups |
clear | Makes agent publicly accessible |
6. Manage Environment Variables
Sets or removes non-secret configuration values.Commands
7. Manage Secrets
Adds or removes agent-specific secrets.Commands
8. Manage Skills
Controls which system-level capabilities the agent has access to.Commands
9. Set Model
Updates the LLM used by the agent.Commands
10. Manage System Prompt
Reads, edits, replaces, or appends to the system prompt.Commands
11. Set Runner
Defines where the agent executes (Kubernetes cluster, local runner, self-hosted worker).Commands
12. Delete Agents
Permanently removes an agent.Commands
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