Skip to main content
The Kubiya Python SDK provides programmatic access to the Kubiya Control Plane, enabling teams to manage organization-scoped resources such as Agents, Teams, Environments, and the global Context Graph.

​
Requirements

  • Python 3.8 or higher
  • pip or poetry package manager
  • A Kubiya API key from the Kubiya platform
For installation instructions, see the Installation Guide.

​
Core Capabilities

Control Plane Client

Manage organization-scoped resources (Agents, Teams, Environments, Context Graph)

Workflow DSL

Define workflows as Python code with type safety and IDE support (DSL is orthogonal to Control Plane resource management)

Real-time Streaming

Stream long-running operations and events from Control Plane endpoints

Production Ready

Error handling, retries, logging, and async support built-in

​
Quick Example

from kubiya import ControlPlaneClient

# Initialize control plane client (point to your Control Plane endpoint)
cp = ControlPlaneClient(api_key="your-api-key", base_url="https://control-plane.kubiya.ai")

# List organization resources
agents = cp.agents.list()
teams = cp.teams.list()
projects = cp.projects.list()
environments = cp.environments.list()
jobs = cp.jobs.list()

print(f"Agents: {len(agents)}, Teams: {len(teams)}, Projects: {len(projects)}")

# Use intelligent search on the Context Graph
result = cp.graph.intelligent_search(
    keywords="Find all production services related to payments"
)
print(f"Answer: {result['answer']}")
print(f"Found {len(result['nodes'])} related nodes")

​
SDK Components

​
Control Plane Client

The Control Plane Client provides access to organization-scoped services:
  • Teams: create and manage multi-agent teams with collaborative execution
  • Projects: organize agents and teams into structured projects
  • Jobs: schedule recurring tasks with cron or create webhook-triggered automations
  • Environments: manage isolated runtime environments and worker registration
  • Agents: manage agent records and executions at the organization level
  • Task Planning: AI-powered task decomposition and planning
  • Context: resolve entity context with inheritance across organizational layers
  • Context Graph: query and resolve entity relationships with intelligent search
  • Models, Runtimes, Skills, Policies: configure LLMs, runtimes, tools, and access controls
  • Workers, Secrets, Integrations: manage infrastructure, credentials, and external integrations
Learn more about the Control Plane Client →

​
Workflow DSL

The Workflow DSL is a Python-first way to define automation workflows. The DSL focuses on describing steps and control flow; orchestration and runtime execution integrate with Control Plane resources where appropriate. Learn more about the Workflow DSL →

​
What You Can Build

  • Organization automation — Manage Agents, Teams, and Environments across your enterprise
  • Context-aware applications — Use the Context Graph to resolve entity relationships and make informed decisions
  • Workflow definitions — Express automation using the Workflow DSL and orchestrate via Control Plane runtimes

​
Getting Started

1

Install the SDK

pip install kubiya-sdk
2

Configure Authentication

export KUBIYA_API_KEY="your-api-key"
3

Use the Control Plane client

from kubiya import ControlPlaneClient

cp = ControlPlaneClient()
print(cp.agents.list())
View detailed installation guide →

​
Architecture

​
Next Steps

Installation & Setup

Get the SDK installed and configured in minutes

Control Plane Client

Access orchestration and graph services

Context Graph

Query entities and relationships

Workflow DSL Guide

Define automation workflows in Python

Examples Gallery

Browse real-world usage patterns

API Reference

Complete API documentation

​
Support & Community