Jac Cloud Client

0.2.11 · active · verified Thu Apr 16

Jac Cloud (version 0.2.11) provides a high-level Python API to interact with Jaseci services on the cloud, built upon the `jac-sdk`. It simplifies the deployment and management of AI agents and workflows within the Jaseci ecosystem. The library is actively developed, with releases typically following updates to the underlying `jac-sdk` and a strict requirement for Python 3.12 or newer.

Common errors

```
ModuleNotFoundError: No module named 'jac_cloud'
```
cause The `jac-cloud` package is not installed in the current Python environment.

fix Run `pip install jac-cloud` to install the library.
```
jac_cloud.exceptions.JacCloudException: Unauthorized
```
cause The `JAC_API_KEY` environment variable is either missing, incorrect, or expired for the target Jaseci service.

fix Set the correct `JAC_API_KEY` environment variable, e.g., `export JAC_API_KEY="your_valid_api_key_here"`, or pass it directly to `JacClient`.
```
requests.exceptions.ConnectionError: HTTPConnectionPool(...) Failed to establish a new connection: [Errno 111] Connection refused
```
cause The `JAC_API_URL` environment variable is incorrect, or the Jaseci service at that URL is not running or unreachable.

fix Verify `JAC_API_URL` points to an active Jaseci service (e.g., `export JAC_API_URL="http://localhost:8000"`), and ensure the service is running and accessible.
```
TypeError: JacClient.__init__() got an unexpected keyword argument 'auth_token'
```
cause An older API parameter or constructor signature is being used with a newer version of `jac-cloud`, or vice-versa.

fix Consult the latest official documentation or `jac_cloud` source code for the correct `JacClient` constructor arguments and method signatures for your installed version.

Warnings

breaking API instability due to pre-1.0 versioning. `jac-cloud` follows the `jac-sdk` which is also in early development, leading to frequent changes in method signatures and object structures between minor versions.
Fix: Always refer to the latest official documentation and quickstart examples for your installed `jac-cloud` version to ensure correct API usage.
gotcha Strict Python 3.12+ requirement. The library explicitly requires Python 3.12.0 or higher, which can cause `ModuleNotFoundError` or other installation issues if a lower version is used.
Fix: Use `pyenv`, `conda`, or ensure your virtual environment is configured with Python 3.12.0 or newer (e.g., `python3.12 -m venv .venv`).
gotcha `JacClient` relies on environment variables for authentication by default. Missing or incorrect `JAC_API_KEY` or `JAC_API_URL` environment variables will lead to `Unauthorized` or `ConnectionError`.
Fix: Ensure `export JAC_API_KEY="your_key_here"` and `export JAC_API_URL="http://your_jaseci_instance:8000"` are set in your shell, or explicitly pass these parameters to `JacClient(api_url=..., api_key=...)`.

Install

pip install jac-cloud Install latest version

Imports

JacClient
wrong:
```
from jac_client import JacClient
```
correct:
```
from jac_cloud.jac_client import JacClient
```
JacClient is nested within the `jac_cloud` package, not directly at the top level.

Quickstart

Initializes a `JacClient` using environment variables for authentication, checks the Jaseci service health, creates and retrieves a simple agent, and then cleans up by deleting it. Requires a running Jaseci service with `JAC_API_KEY` and `JAC_API_URL` configured.

import os
from jac_cloud.jac_client import JacClient

# Ensure JAC_API_KEY and JAC_API_URL are set as environment variables
# e.g., export JAC_API_URL="http://localhost:8000" and export JAC_API_KEY="your_key"

# Initialize JacClient (it picks up env vars by default)
client = JacClient()

try:
    # Check the health of the connected Jaseci service
    health_status = client.get_health()
    print(f"Jaseci Cloud Health Status: {health_status}")

    # Example: Create a simple agent
    agent_name = "quickstart_example_agent"
    print(f"\nAttempting to create agent: {agent_name}")
    agent = client.create_agent(name=agent_name)
    print(f"Agent '{agent.name}' created with UUID: {agent.uuid}")

    # Example: Retrieve agent details
    retrieved_agent = client.get_agent(uuid=agent.uuid)
    print(f"Retrieved agent name: {retrieved_agent.name}")

    # Clean up: Delete the created agent
    print(f"Deleting agent: {agent.uuid}")
    delete_result = client.delete_agent(uuid=agent.uuid)
    print(f"Agent deletion result: {delete_result}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("\nHint: Please ensure JAC_API_KEY and JAC_API_URL environment variables are set and point to a running Jaseci service.")

view raw JSON →