Skip to main content
Agents are configuration entities that define reusable AI-powered automation capabilities. Rather than running as standalone services, agents are executed by workers connected to task queues, enabling durable execution across diverse compute environments. Each agent configuration specifies:
  • Runtime - The execution engine (e.g., Claude Code for coding tasks, Agno for multi-model flexibility)
  • Model - The LLM powering the agent’s reasoning
  • Skills - Capabilities for system operations (shell, file ops, Docker, Python)
  • Environment - Runtime configuration, secrets, and policies inherited from attached environments
Primary way to consume agents: Use the Meta Agent to execute agents via natural language. The Meta Agent’s task management tools create durable tasks that are routed to appropriate workers, tracked through completion, and can span multiple compute environments.
Agents Configuration

​
How Agent Execution Works

Key characteristics:
  • Durable execution - Tasks persist through worker restarts and network interruptions
  • Environment-agnostic - Same agent config can run on different workers (dev, staging, prod)
  • Real-time streaming - See agent reasoning and tool calls as they happen
  • Trackable - Every execution gets an ID for monitoring and audit
When to create custom agents: Most users interact with Kubiya through the Meta Agent, which handles general orchestration. Create custom agents only when you need specialized, reusable automation for a specific domain (DevOps, Security, FinOps, etc.).

​
Example Use Cases

AgentRuntimeDescription
DevOps EngineerClaude CodeChecks system health, manages deployments, writes automation scripts
Security EngineerClaude CodePerforms CVE scans, security audits, compliance checks
SRE HelperClaude CodeDiagnoses incidents using logs, metrics, and runbooks
Cost AuditorAgnoReviews cloud spending and raises cost alerts
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:
  • Specialized domain expertise beyond general Meta Agent capabilities
  • Reusable operational capability that runs repeatedly (deployments, audits, compliance checks)
  • Custom automation invoked by other systems, Teams, or workflows
  • Specific model or capability configuration different from defaults
For general exploration and task execution, use the Meta Agent instead. It provides access to all platform capabilities without custom configuration.

​
Prerequisites

Before creating an agent, ensure:
  • At least one Environment is in Ready state
  • A Task 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)

​
Built-in Cognitive Capabilities

Every agent automatically inherits cognitive memory capabilities. No configuration required. All agents can store context, recall relevant information, and share knowledge across your organization through Kubiya’s Cognitive Memory system.

​
Automatic Skills

Agents inherit these cognitive memory operations by default:
  • store_memory(content, metadata) - Store context, findings, solutions
  • recall_memory(query, limit) - Semantic search across stored memories
  • list_memories() - List all stored memories for current context
  • get_dataset_info() - Get information about current dataset
These skills are always available—agents can use them without any setup.

​
Environment-Based Datasets

By default, agents automatically use a dataset named after their execution environment.
Agent EnvironmentDefault DatasetScopeShared With
productionproductionORGAll agents in production
stagingstagingORGAll agents in staging
devdevORGAll agents in dev
Benefits:
  • Automatic isolation - Production agents can’t access staging memories
  • Shared team context - All agents in the same environment share knowledge
  • Zero configuration - Works out of the box, no setup needed
  • Environment-specific learning - Each environment builds its own knowledge base

​
Cross-Agent Memory Sharing

Agents in the same environment share an organization-scoped dataset, enabling collective learning: Key benefits:
  • Agents don’t re-solve problems already handled
  • Organizational knowledge compounds over time
  • Audit trail shows which agent solved what
  • Teams learn collectively

​
Environment Context

Agents automatically know their execution environment through:
  • Environment variable: KUBIYA_ENVIRONMENT
  • Automatic dataset selection: Uses environment name as dataset name
  • Isolation: Production memories ≠ staging memories
Environment-based dataset isolation:
Learn more about cognitive memory capabilities in Cognitive Memory Overview.

​
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 Choose the execution engine for your agent. Agno for multi-model flexibility, Claude Code for code-focused tasks. Compare runtimes to decide.
  • 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 Task 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 Task Queues have active workers
  • Build tasks or workflows that use this agent
  • Configure policies for safe multi-environment operation