Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt

Use this file to discover all available pages before exploring further.

Get started with the Control Plane SDK to manage agents, integrations, and secrets. This guide uses the current ControlPlaneClient and minimal, factual examples.

​
Prerequisites

Before you begin, ensure you have:
  • Python 3.8 or higher installed
  • pip package manager
  • A Kubiya API key from the Kubiya platform

​
Installation

Install the Kubiya SDK using pip: 
pip install kubiya-sdk
Or using poetry: 
poetry add kubiya-sdk

​
Setup

​
Configure API Key

Set your API key as an environment variable: 
export KUBIYA_API_KEY="your-api-key-here"
Or use a .env file: 
# .env
KUBIYA_API_KEY=your-api-key-here

​
Initialize the Client

from kubiya import ControlPlaneClient

# Initialize with environment variable
client = ControlPlaneClient()

# Or pass API key directly
client = ControlPlaneClient(api_key="your-api-key-here")
Using environment variables is recommended for security. Never commit API keys to version control.

​
Create and Manage an Agent

Minimal agent creation: 
agent_data = {
    "name": "devops-helper",
    "model_id": "claude-sonnet-4"
}

created = client.agents.create(agent_data)
print(created["agent_id"])
Required fields for create:
  • name: Agent display name
  • model_id: Provider id (e.g., claude-sonnet-4)
Attach skills and integrations later via update() using IDs. Keep creation minimal until the agent is working end-to-end.
List agents: 
agents = client.agents.list(limit=10)
for a in agents:
    print(a["name"], a.get("agent_id"))
Update an agent (attach skills/integrations by IDs if needed): 
update_data = {
    "skill_ids": ["skill-123"]
}

updated = client.agents.update(created["agent_id"], update_data)
print(updated["agent_id"])

​
Execute an Agent

Execution requires worker_queue_id, and a prompt. 
payload = {
    "worker_queue_id": "default",
    "prompt": "Deploy NGINX to EKS"
}

result = client.agents.execute(created["agent_id"], payload)
print(result.get("status"))
Required fields for execute:
  • worker_queue_id: Queue name (e.g., default)
  • prompt: What the agent should do (task description)
Prefer executing by known agent_id. If you only have a name, first list() and resolve the agent_id to avoid name collisions.

​
Delete an Agent

resp = client.agents.delete(created["agent_id"])
print("deleted")

​
Integrations and Secrets

List integrations and get credentials: 
integrations = client.integrations.list()
creds = client.integrations.get_integration_credentials(vendor="aws", id="aws")
Some vendors (e.g., github_app, jira) may use a fixed id like "0". Check the list output and use the exact vendor and id returned.
List secrets and get a secret value: 
secrets = client.secrets.list()
value = client.secrets.get_value("github-token")
Best practices:
  • Store sensitive values in Secrets and reference them at runtime
  • list() returns metadata only; use get_value(name) to fetch the actual secret

​
Verify Setup

Quick health check: 
status = client.health.check()
print(status)
Expected output: a small dict indicating service health. If the call fails, verify your base_url, API key, and network access.

​
Best Practices

Always use clear, descriptive names for agents:
agent_data = {"name": "production-deploy-agent"}  # Good
agent_data = {"name": "agent"}  # Too vague
Add error handling around agent operations:
try:
    result = client.agents.execute(agent_id, payload)
    print(result)
except Exception as e:
    print(f"Agent execution failed: {e}")
Store sensitive values securely:
import os
client = ControlPlaneClient(api_key=os.getenv("KUBIYA_API_KEY"))
Check agent exists before execution:
agent = client.agents.get(agent_id)
if agent:
    result = client.agents.execute(agent_id, payload)

​
Next Steps

Control Plane Client Overview

Learn the services in the Control Plane client

Agents

Full agent lifecycle: create, list, get, update, execute, delete

Integrations

List integrations and fetch credentials

Secrets

List secret metadata and get values