Skip to main content

Shows my svg

Python macOS Discord PyPI

cua-agent is a general Computer-Use framework for running multi-app agentic workflows targeting macOS and Linux sandbox created with Cua, supporting local (Ollama) and cloud model providers (OpenAI, Anthropic, Groq, DeepSeek, Qwen).

Get started with Agent

Install

pip install "cua-agent[all]"

# or install specific loop providers
pip install "cua-agent[openai]" # OpenAI Cua Loop
pip install "cua-agent[anthropic]" # Anthropic Cua Loop
pip install "cua-agent[omni]" # Cua Loop based on OmniParser (includes Ollama for local models)
pip install "cua-agent[ui]" # Gradio UI for the agent

Run

async with Computer() as macos_computer:
  # Create agent with loop and provider
  agent = ComputerAgent(
      computer=macos_computer,
      loop=AgentLoop.OPENAI,
      model=LLM(provider=LLMProvider.OPENAI)
      # or
      # loop=AgentLoop.ANTHROPIC,
      # model=LLM(provider=LLMProvider.ANTHROPIC)
      # or
      # loop=AgentLoop.OMNI,
      # model=LLM(provider=LLMProvider.OLLAMA, model="gemma3")
  )

  tasks = [
      "Look for a repository named trycua/cua on GitHub.",
      "Check the open issues, open the most recent one and read it.",
      "Clone the repository in users/lume/projects if it doesn't exist yet.",
      "Open the repository with an app named Cursor (on the dock, black background and white cube icon).",
      "From Cursor, open Composer if not already open.",
      "Focus on the Composer text area, then write and submit a task to help resolve the GitHub issue.",
  ]

  for i, task in enumerate(tasks):
      print(f"\nExecuting task {i}/{len(tasks)}: {task}")
      async for result in agent.run(task):
          print(result)

      print(f"\n✅ Task {i+1}/{len(tasks)} completed: {task}")

Refer to these notebooks for step-by-step guides on how to use the Computer-Use Agent (CUA):

Using the Gradio UI

The agent includes a Gradio-based user interface for easy interaction. To use it:

# Install with Gradio support
pip install "cua-agent[ui]"

# Create a simple launcher script
```python
# launch_ui.py
from agent.ui.gradio.app import create_gradio_ui

app = create_gradio_ui()
app.launch(share=False)

Run the launcher

python launch_ui.py


### Setting up API Keys

For the Gradio UI to show available models, you need to set API keys as environment variables:

```bash
# For OpenAI models
export OPENAI_API_KEY=your_openai_key_here

# For Anthropic models
export ANTHROPIC_API_KEY=your_anthropic_key_here

# Launch with both keys set
OPENAI_API_KEY=your_key ANTHROPIC_API_KEY=your_key python launch_ui.py

Without these environment variables, the UI will show "No models available" for the corresponding providers, but you can still use local models with the OMNI loop provider.

The Gradio UI provides:

  • Selection of different agent loops (OpenAI, Anthropic, OMNI)
  • Model selection for each provider
  • Configuration of agent parameters
  • Chat interface for interacting with the agent

You can also embed the Gradio UI in your own application:

# Import directly in your application
from agent.ui.gradio.app import create_gradio_ui

# Create the UI with advanced features
demo = create_gradio_ui()
demo.launch()

# Or for a simpler interface
from agent.ui.gradio import registry
demo = registry(name='cua:gpt-4o')
demo.launch()

Agent Loops

The cua-agent package provides three agent loops variations, based on different CUA models providers and techniques:

Agent Loop Supported Models Description Set-Of-Marks
AgentLoop.OPENAI • computer_use_preview Use OpenAI Operator CUA model Not Required
AgentLoop.ANTHROPIC • claude-3-5-sonnet-20240620
• claude-3-7-sonnet-20250219
Use Anthropic Computer-Use Not Required
AgentLoop.OMNI • claude-3-5-sonnet-20240620
• claude-3-7-sonnet-20250219
• gpt-4.5-preview
• gpt-4o
• gpt-4
• phi4
• phi4-mini
• gemma3
• ...
• Any Ollama-compatible model
Use OmniParser for element pixel-detection (SoM) and any VLMs for UI Grounding and Reasoning OmniParser

AgentResponse

The AgentResponse class represents the structured output returned after each agent turn. It contains the agent's response, reasoning, tool usage, and other metadata. The response format aligns with the new OpenAI Agent SDK specification for better consistency across different agent loops.

async for result in agent.run(task):
  print("Response ID: ", result.get("id"))

  # Print detailed usage information
  usage = result.get("usage")
  if usage:
      print("\nUsage Details:")
      print(f"  Input Tokens: {usage.get('input_tokens')}")
      if "input_tokens_details" in usage:
          print(f"  Input Tokens Details: {usage.get('input_tokens_details')}")
      print(f"  Output Tokens: {usage.get('output_tokens')}")
      if "output_tokens_details" in usage:
          print(f"  Output Tokens Details: {usage.get('output_tokens_details')}")
      print(f"  Total Tokens: {usage.get('total_tokens')}")

  print("Response Text: ", result.get("text"))

  # Print tools information
  tools = result.get("tools")
  if tools:
      print("\nTools:")
      print(tools)

  # Print reasoning and tool call outputs
  outputs = result.get("output", [])
  for output in outputs:
      output_type = output.get("type")
      if output_type == "reasoning":
          print("\nReasoning Output:")
          print(output)
      elif output_type == "computer_call":
          print("\nTool Call Output:")
          print(output)

Metadata

Release files for cua-agent 0.1.24

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cua-agent 0.1.24
File Size Uploaded Provenance Actions
cua_agent-0.1.24.tar.gz 92.0 kB Without provenance Details for cua_agent-0.1.24.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cua-agent 0.1.24
File Interpreter ABI Platform Actions
cua_agent-0.1.24-py3-none-any.whl Python 3 none any Details for cua_agent-0.1.24-py3-none-any.whl

Total release size: 214.6 kB

Release files / cua_agent-0.1.24.tar.gz

Download URL cua_agent-0.1.24.tar.gz
Size 92.0 kB
Tags Source
SHA-256 checksum
How to use checksums
d33e102fb8cfb5f31402d4e4e32fc832de4b9694f4ff7a9200381e7897a58782
BLAKE2b-256 checksum
How to use checksums
69a9ba48d4dfacaf25e61d8dffa46fa671f495e5bb7467c3b7f64d3ac5bf6b62
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.10.11

Release files / cua_agent-0.1.24-py3-none-any.whl

Download URL cua_agent-0.1.24-py3-none-any.whl
Size 122.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
facb02bf780e75bc494f9925451863fe1b88d672a90e07af2e749b67814abe90
BLAKE2b-256 checksum
How to use checksums
8685a6d07845c77a7477f6c512b398c3b958bd771b689be07358bc1ef24b95f1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.10.11

Security for cua-agent 0.1.24

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.24 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page