Skip to main content
The Agents Service provides comprehensive management of AI agents through the Kubiya platform, including lifecycle management, access control, environment configuration, and tool integration. 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.

​
Agents: Detailed guide

This page focuses on the agent-specific parts of the SDK: creation, configuration, access control, environment variables, tool integration, and common patterns. If you haven’t set up a ControlPlaneClient yet, see the Client Quick Start at Client Overview for initialization and authentication instructions. Below are practical, in-depth examples and patterns for working with agents. The first example demonstrates creating a DevOps-focused agent and verifying the returned configuration.

​
Create an agent (devops-assistant example)

The following example demonstrates creating a minimal agent using the Control Plane SDK, then verifying it by fetching its details: 
from kubiya.control_plane_client import ControlPlaneClient
import os

client = ControlPlaneClient(
    api_key=os.environ.get("KUBIYA_CONTROL_PLANE_API_KEY"),
    base_url=os.environ.get("KUBIYA_CONTROL_PLANE_BASE_URL", "https://control-plane.kubiya.ai")
)

agent_data = {
    "name": "devops-assistant-demo",
    "description": "AI assistant for DevOps automation",
    "model_id": "claude-sonnet-4"
}

agent = client.agents.create(agent_data)
print(f"✅ Created agent: {agent.get('name')} (UUID: {agent.get('uuid')})")

# Verify details
details = client.agents.get(agent.get('uuid'))
print("✅ Verified agent details:")
print({k: details.get(k) for k in ("uuid", "name", "llm_model", "tools")})
Example output from a run of this flow (sanitized and factual from a real execution): 
🚀 Creating agent...
{
  "name": "devops-assistant-1764853010",
  "description": "AI assistant for DevOps automation",
  "llm_model": "claude-sonnet-4",
  "tools": [
    "kubectl",
    "terraform"
  ],
  "integrations": [
    "slack",
    "github"
  ]
}
✅ Created agent: devops-assistant-1764853010 (UUID: e9df18d2-a33f-4570-aafd-347e5018e047)
✅ Verified agent details:
{
  "uuid": "e9df18d2-a33f-4570-aafd-347e5018e047",
  "name": "devops-assistant-1764853010",
  "llm_model": "claude-sonnet-4",
  "tools": [
    "kubectl",
    "terraform"
  ]
}
The fields shown are exactly those returned by the client.agents.create and client.agents.get calls. Typical fields include uuid, name, llm_model, tools, integrations, and other configuration metadata. You can verify the same on the platform dashboard under Agents. SDK Agent Created

​
Core Operations

The typical lifecycle flow is: Create → List → Update → Execute → Delete.

​
Create

Create a new DevOps-focused agent with minimal required fields: 
agent_data = {
  "name": "devops-persona-agent",
  "description": "AI assistant for DevOps automation.",
  "model_id": "claude-sonnet-4"
}
agent = client.agents.create(agent_data)
Required fields (minimal):
  • name: Unique agent name
  • model_id: Provider-specific model identifier
Common optional fields:
  • description: Short, clear purpose
  • skill_ids: List of skills that the agent can use

​
List

Retrieve a list of agents (supports pagination). Use this to confirm creation and discover IDs: 
agents = client.agents.list(skip=0, limit=10)
for agent in agents:
  print(agent)

​
Get Agent Details

Fetch a single agent’s details. Resolve the agent ID by name, then call get(): 
agents = client.agents.list()
agent = next((a for a in agents if a.get("name") == "devops-persona-agent"), None)
if not agent:
  raise RuntimeError("Agent 'devops-persona-agent' not found")
agent_id = agent.get("id") or agent.get("uuid")

details = client.agents.get(agent_id)
print(details)
Tip:
  • If you already have the agent_id (e.g., stored after creation), prefer calling client.agents.get(agent_id) directly.
  • Use list-by-name only when you don’t have the ID available at hand.

​
Update

Update an agent’s configuration. Pass only the fields you wish to change. Example: attach Skills and Integrations by ID. 
# Find agent by name and get its UUID/ID
agents = client.agents.list()
agent = next((a for a in agents if a.get("name") == "devops-persona-agent"), None)
if not agent:
  raise RuntimeError("Agent 'devops-persona-agent' not found")
agent_id = agent.get("id") or agent.get("uuid")

# Prepare update payload (IDs only)
update_data = {
  "skill_ids": [
    "071729f9-3dca-4321-9575-bdb13de9c07e",
    "b5db2d36-85cd-4ad7-8d64-7202a8cf013b"
  ]
}

updated = client.agents.update(agent_id, update_data)
print(updated)

​
Execute

Start an agent execution. Provide the required fields and an execution prompt, then call execute(agent_id, execution_data): 
# Resolve agent_id first
agents = client.agents.list()
agent = next((a for a in agents if a.get("name") == "devops-persona-agent"), None)
if not agent:
  raise RuntimeError("Agent 'devops-persona-agent' not found")
agent_id = agent.get("id") or agent.get("uuid")

# Prepare execution payload
execution_data = {
  "worker_queue_id": "c33658da-8831-4323-869e-0188ec8e2187",  # required worker queue ID
  "prompt": "Deploy an nginx server on EKS in us-east-1 on the existing cluster attractive-country-seal using AWS CLI. After deployment, verify the pod is running and accessible.",
  "parameters": {
    "cluster_name": "test-eks-cluster",
    "namespace": "default"
  }
}

result = client.agents.execute(agent_id, execution_data)
print(result)

# Optional: check status in result
status = result.get("status") or result.get("execution_status")
print("Status:", status)
Required fields:
  • agent_id: UUID/ID of the target agent
  • worker_queue_id: ID of the worker queue handling execution
  • prompt: Instruction describing the task to perform

​
Delete

Permanently remove an agent by UUID when no longer needed: 
result = client.agents.delete("agent-uuid")
# The API returns a JSON body with deletion status when available
print(result)
Notes:
  • Returns a JSON object with deletion status when provided by the API.
  • Some deployments may return HTTP 200 with an empty body; treat that as success.
  • agent_id: UUID of the agent to execute

​
Best Practices

  • Use descriptive unique agent names
  • Provide clear AI instructions
  • Use environment variables for configuration
  • Handle errors with try/except