Skip to main content

​
Install the SDK Client

pip install kubiya-sdk
Optional extras: 
pip install kubiya-sdk[dev]
pip install kubiya-sdk[all]

​
Configure Environment

Set environment variables for the client: 
export KUBIYA_CONTROL_PLANE_API_KEY="your-api-key"
export KUBIYA_CONTROL_PLANE_BASE_URL="https://control-plane.kubiya.ai"  # or your on-prem URL

​
Verify Client Access

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")
)

print("Health:", client.health.check())
print("Models:", client.models.list())
print("Agents:", client.agents.list())
If these calls succeed, your SDK is correctly authenticated and able to reach the Control Plane. You can now manage organization resources programmatically.

​
Available Services

Below is a practical overview of the client’s main services and when to use them.

​
Health

  • Purpose: Confirm the Control Plane is reachable and ready.
  • Common calls: client.health.check(), client.health.ready()
  • When to use: Before running automation or on app startup to verify connectivity.

​
Models

  • Purpose: Discover available LLM models and defaults for agent runs.
  • Common calls: client.models.list()
  • When to use: Selecting a model during agent creation or validating model support.

​
Agents

  • Purpose: Create, read, update, execute, and delete organization agents.
  • Common calls: list(), get(id), create(data), update(id, data), execute(id, data), delete(id)
  • When to use: Any agent lifecycle operations (e.g., DevOps persona agent that deploys services).
  • Example:
    • Create minimal agent: { name, llm_model, model_id, instruction_type, ai_instructions }
    • Execute: provide integration_id, worker_queue_id, and an execution prompt.

​
Integrations

  • Purpose: Connect to external systems like GitHub, Jira, or cloud providers using central credentials.
  • Common calls: list(connected_only), get(id), get_integration_credentials(vendor, id)
  • When to use: Agents or apps need to call external APIs without embedding secrets in code.

​
Secrets

  • Purpose: Access organization-managed credentials safely at runtime.
  • Common calls: list() (metadata only), get_value(name)
  • When to use: Fetch secrets on demand (e.g., database passwords, API keys) without logging or storing in source.

​
Graph

  • Purpose: Explore the Context Graph (entities, relationships) for context-aware automation.
  • Common calls: list_labels(), list_nodes(...), get_node(id)
  • When to use: Resolving dependencies (e.g., which service depends on which DB) or enriching agent decisions.
Tip: Use only the client-side SDK in application code. Server deployment variables (Redis/Temporal/DB) are for Control Plane operators and aren’t required for using the SDK client.