{"id":8046,"library":"cuga","title":"CUGA Agent","description":"CUGA is an open-source generalist agent for the enterprise, supporting complex task execution on web and APIs, OpenAPI/MCP integrations, composable architecture, reasoning modes, and policy-aware features. It is under active development, with minor versions released frequently introducing new features and improvements.","status":"active","version":"0.2.21","language":"en","source_language":"en","source_url":"https://github.com/cuga-project/cuga-agent","tags":["agent","llm","ai","enterprise","multi-agent","orchestration","policy","web-automation","api-automation"],"install":[{"cmd":"pip install cuga","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for connecting to various LLM providers.","package":"litellm","optional":false},{"reason":"Core dependency for LLM orchestration and integrations.","package":"langchain","optional":false},{"reason":"Used for data validation and settings management (requires Pydantic V2).","package":"pydantic","optional":false},{"reason":"Required for OpenAI model interactions.","package":"openai","optional":false}],"imports":[{"symbol":"CugaAgent","correct":"from cuga.agent import CugaAgent"}],"quickstart":{"code":"import os\nfrom dotenv import load_dotenv\nfrom cuga.agent import CugaAgent\n\n# Load environment variables from a .env file if present\nload_dotenv()\n\n# Ensure your OpenAI API key is set in your environment (e.g., in a .env file or directly)\n# For testing, you can explicitly set it or retrieve it safely.\n# os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'your-openai-api-key-here')\n\n# Initialize the agent. It will pick up LLM configurations from environment variables.\ncuga_agent = CugaAgent()\n\n# Define a task for the agent\ntask = \"Explain the concept of quantum entanglement in simple terms.\"\n\n# Invoke the agent with the task\ntry:\n    response = cuga_agent.invoke(task=task)\n    # Print the agent's response\n    print(f\"Agent's response: {response.result}\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure your LLM API keys (e.g., OPENAI_API_KEY) are correctly set in your environment.\")","lang":"python","description":"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`."},"warnings":[{"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.*`).","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Ensure your Python environment is within the supported range (>=3.10, <3.14). Use `pyenv` or `conda` to manage Python versions if necessary.","message":"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.","severity":"gotcha","affected_versions":"<0.2.21"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install cuga` to install the library.","cause":"The `cuga` package is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'cuga'"},{"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.","cause":"This often indicates that an LLM API key (e.g., `OPENAI_API_KEY`) is missing, invalid, or incorrectly configured in the environment.","error":"openai.APIConnectionError: Connection error. Please check your network connection, proxy settings, or firewall."},{"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.","cause":"You are trying to install or run `cuga` with an unsupported Python version (e.g., Python 3.9 or 3.14).","error":"raise RuntimeError(f\"Python {sys.version.split(' ')[0]} is not supported by this package.\")"}]}