CUGA Agent

Common errors

• ModuleNotFoundError: No module named 'cuga'

  cause The `cuga` package is not installed in your current Python environment.
  fix Run `pip install cuga` to install the library.

• openai.APIConnectionError: Connection error. Please check your network connection, proxy settings, or firewall.

  cause This often indicates that an LLM API key (e.g., `OPENAI_API_KEY`) is missing, invalid, or incorrectly configured in the environment.
  fix Verify that `OPENAI_API_KEY` (or the relevant key for your chosen LLM) is correctly set in your environment variables. Ensure there are no typos and the key is valid.

• raise RuntimeError(f"Python {sys.version.split(' ')[0]} is not supported by this package.")

  cause You are trying to install or run `cuga` with an unsupported Python version (e.g., Python 3.9 or 3.14).
  fix Switch to a supported Python version (3.10, 3.11, 3.12, or 3.13) for your project. You can use tools like `pyenv` or `conda` to manage Python versions.

Warnings

• breaking CUGA is in active pre-1.0 development, meaning APIs and internal architecture may change with minor version updates. Features like the Policy System (v0.2.7) and Supervisor SDK (v0.2.10) involved significant overhauls that could impact existing code.
  Fix: Always review release notes for new versions and pin your `cuga` dependency to a specific minor version in production environments (e.g., `cuga==0.2.*`).
• gotcha CUGA requires specific Python versions. Currently, it supports Python 3.10, 3.11, 3.12, and 3.13. Using unsupported versions will lead to installation or runtime errors.
  Fix: Ensure your Python environment is within the supported range (>=3.10, <3.14). Use `pyenv` or `conda` to manage Python versions if necessary.
• gotcha To function, `CugaAgent` needs access to Large Language Models (LLMs). This typically requires setting environment variables like `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `COHERE_API_KEY`. Without these, the agent will fail to interact with LLMs.
  Fix: Set the required LLM API keys in your environment variables. It is recommended to use a `.env` file and `python-dotenv` for local development, or your cloud provider's secrets management for deployment.

Install

• pip install cuga Install latest version

Imports

• CugaAgent

  from cuga.agent import CugaAgent

Quickstart

This quickstart demonstrates how to initialize a `CugaAgent` and invoke it with a simple task. It relies on environment variables (like `OPENAI_API_KEY`) for LLM configuration, which can be loaded from a `.env` file using `python-dotenv`.

import os
from dotenv import load_dotenv
from cuga.agent import CugaAgent

# Load environment variables from a .env file if present
load_dotenv()

# Ensure your OpenAI API key is set in your environment (e.g., in a .env file or directly)
# For testing, you can explicitly set it or retrieve it safely.
# os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'your-openai-api-key-here')

# Initialize the agent. It will pick up LLM configurations from environment variables.
cuga_agent = CugaAgent()

# Define a task for the agent
task = "Explain the concept of quantum entanglement in simple terms."

# Invoke the agent with the task
try:
    response = cuga_agent.invoke(task=task)
    # Print the agent's response
    print(f"Agent's response: {response.result}")
except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure your LLM API keys (e.g., OPENAI_API_KEY) are correctly set in your environment.")