Skip to main content

​
Overview

Agents are the core execution units in Kubiya. They can operate individually or collaborate as teams to accomplish complex tasks. This section covers creating, configuring, and executing agents.

​
Agents

Individual AI agents that can execute tasks, interact with tools, and respond to prompts. Each agent has:
  • A configured runtime environment
  • Access to specific tools and integrations
  • Associated policies for governance
  • LLM model configuration
Key capabilities:
  • Execute tasks synchronously or asynchronously
  • Stream execution results in real-time
  • Access context from projects and environments
  • Use skills and integrations

​
Teams

Multi-agent teams coordinate multiple specialized agents to handle complex workflows. Teams enable:
  • Agent specialization and role assignment
  • Parallel task execution
  • Collaborative problem-solving
  • Shared context and knowledge

​
Task Planning

AI-powered analysis and planning for complex tasks. The task planner:
  • Breaks down complex requests into steps
  • Identifies required tools and resources
  • Suggests optimal execution strategies
  • Estimates task complexity

​
Common Workflows

​
Creating an Agent

POST /api/v1/agents
{
  "name": "DevOps Assistant",
  "description": "Helps with infrastructure and deployment tasks",
  "runtime": "claude_code",
  "model_id": "anthropic/claude-sonnet-4-5",
  "system_prompt": "You are a DevOps expert. Help with Kubernetes, cloud infrastructure, and deployments.",
  "skill_ids": ["skill-uuid-1", "skill-uuid-2"],
  "environment_ids": ["env-uuid-1"]
}
Required fields: name Note: Use model_id (not model) and runtime should be "claude_code" or "default" (Agno)

​
Executing a Task

POST /api/v1/agents/{agent_id}/execute
{
  "prompt": "Check the status of pods in the production namespace",
  "worker_queue_id": "worker-queue-uuid",
  "stream": true
}
Required fields: prompt, worker_queue_id Note: worker_queue_id must be a valid UUID of an existing worker queue

​
Creating a Team

POST /api/v1/teams
{
  "name": "Incident Response Team",
  "description": "Multi-agent team for handling production incidents",
  "configuration": {
    "instructions": "Coordinate to investigate and resolve incidents quickly",
    "reasoning": true
  },
  "skill_ids": ["skill-uuid-1", "skill-uuid-2"]
}
Required fields: name Note: Teams use the Agno framework for multi-agent coordination

​
Executing a Team Task

POST /api/v1/teams/{team_id}/execute
{
  "prompt": "Investigate the recent spike in API errors",
  "worker_queue_id": "worker-queue-uuid",
  "stream": true
}

​
Best Practices

  1. Agent Design: Create focused agents with specific responsibilities
  2. Team Composition: Use 2-4 agents per team for optimal coordination
  3. Task Streaming: Enable streaming for long-running tasks
  4. Context Management: Provide relevant context through projects and environments

​
Next Steps

Explore the API endpoints to learn how to create, configure, and execute agents and teams.