> ## 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.

# Quick Start Guide

> Get started with the Kubiya Control Plane SDK

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](https://compose.kubiya.ai)

## Installation

Install the Kubiya SDK using pip:

```bash theme={null}
pip install kubiya-sdk
```

Or using poetry:

```bash theme={null}
poetry add kubiya-sdk
```

## Setup

### Configure API Key

Set your API key as an environment variable:

```bash theme={null}
export KUBIYA_API_KEY="your-api-key-here"
```

Or use a `.env` file:

```bash theme={null}
# .env
KUBIYA_API_KEY=your-api-key-here
```

### Initialize the Client

```python theme={null}
from kubiya import ControlPlaneClient

# Initialize with environment variable
client = ControlPlaneClient()

# Or pass API key directly
client = ControlPlaneClient(api_key="your-api-key-here")
```

<Tip>
  Using environment variables is recommended for security. Never commit API keys to version control.
</Tip>

## Create and Manage an Agent

Minimal agent creation:

```python theme={null}
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`)

<Tip>
  Attach skills and integrations later via `update()` using IDs. Keep creation minimal until the agent is working end-to-end.
</Tip>

List agents:

```python theme={null}
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):

```python theme={null}
update_data = {
    "skill_ids": ["skill-123"]
}

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

<Hint>
  To find valid IDs:

  * Skills: Use your platform UI or API to list skills and copy `skill_id`
  * Integrations: See the section below to list integrations and use `vendor/id` (e.g., `aws`)
</Hint>

## Execute an Agent

Execution requires `worker_queue_id`, and a `prompt`.

```python theme={null}
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)

<Tip>
  Prefer executing by known `agent_id`. If you only have a name, first `list()` and resolve the `agent_id` to avoid name collisions.
</Tip>

## Delete an Agent

```python theme={null}
resp = client.agents.delete(created["agent_id"])
print("deleted")
```

<Hint>
  Delete may return an empty 200 OK or a small JSON confirmation depending on deployment. Treat the 200 status as success.
</Hint>

## Integrations and Secrets

List integrations and get credentials:

```python theme={null}
integrations = client.integrations.list()
creds = client.integrations.get_integration_credentials(vendor="aws", id="aws")
```

<Tip>
  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.
</Tip>

List secrets and get a secret value:

```python theme={null}
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:

```python theme={null}
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

<AccordionGroup>
  <Accordion title="Use Descriptive Names" icon="tag">
    Always use clear, descriptive names for agents:

    ```python theme={null}
    agent_data = {"name": "production-deploy-agent"}  # Good
    agent_data = {"name": "agent"}  # Too vague
    ```
  </Accordion>

  <Accordion title="Handle Errors Gracefully" icon="shield-exclamation">
    Add error handling around agent operations:

    ```python theme={null}
    try:
        result = client.agents.execute(agent_id, payload)
        print(result)
    except Exception as e:
        print(f"Agent execution failed: {e}")
    ```
  </Accordion>

  <Accordion title="Use Environment Variables" icon="lock">
    Store sensitive values securely:

    ```python theme={null}
    import os
    client = ControlPlaneClient(api_key=os.getenv("KUBIYA_API_KEY"))
    ```
  </Accordion>

  <Accordion title="Validate Before Executing" icon="check">
    Check agent exists before execution:

    ```python theme={null}
    agent = client.agents.get(agent_id)
    if agent:
        result = client.agents.execute(agent_id, payload)
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Control Plane Client Overview" icon="code" href="/sdk/control-plane-client-overview">
    Learn the services in the Control Plane client
  </Card>

  <Card title="Agents" icon="flow" href="/sdk/client-agents">
    Full agent lifecycle: create, list, get, update, execute, delete
  </Card>

  <Card title="Integrations" icon="plug" href="/sdk/integrations">
    List integrations and fetch credentials
  </Card>

  <Card title="Secrets" icon="lock" href="/sdk/secrets">
    List secret metadata and get values
  </Card>
</CardGroup>