Welcome! This template helps you get started with the Cua SDK - a powerful framework for building AI agents that can interact with computers and automate tasks.

Note: This template will walk through a cloud based run. If you want to change this to local, please visit the Quickstart.

This example demonstrates how to use the ComputerAgent with OpenAI's computer-use model to:

• Automate web interactions (visiting websites, downloading files)
• Fill out forms automatically using information from documents
• Run tasks on a cloud-based Linux virtual machine

The agent can see your screen, control your mouse and keyboard, and make intelligent decisions about how to complete tasks - just like a human would!

Before you begin, you'll need:

• A Cua account and active sandbox
• An OpenAI API key with access to the computer-use model
• uv package manager (we'll help you install it if needed)

1. Clone this repository:

   git clone https://github.com/trycua/agent-template.git
   cd agent-template

2. Copy the environment template:

   cp .env.example .env

3. Start your virtual machine:

   • Go to Cua Dashboard
   • Make sure your sandbox is running (you'll see a green status indicator)

4. Configure your API keys:

   • Open the .env file in your favorite editor
   • Fill in your CUA_API_KEY, CUA_SANDBOX_NAME, and OPENAI_API_KEY
   • Save the file

5. Install dependencies:

   uv sync

You can run the agent in two ways:

Option 1: Direct run (recommended for beginners)

uv run python main.py

Option 2: Traditional virtual environment

source .venv/bin/activate
python main.py

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Alternative (using pip):

pip install uv

Want to try different models or tasks? Here are some ideas:

• Switch models: Check out supported model providers for options like Claude, UI-TARS, or local models
• Change tasks: Modify the tasks list in main.py to automate different workflows
• Local development: Switch to a free local macOS computer for testing (see commented code in main.py), find resources on local development: https://docs.cua.ai/docs/quickstart-devs

We're here to help you succeed!

• 📚 Documentation - Comprehensive guides and examples
• 💬 Discord Community - Get support from our team and other developers
• 🔧 GitHub Repository - Source code, issues, and contributions

Once you've got this example running, try:

• Building your own custom agents
• Integrating with your existing workflows
• Exploring advanced features like multi-agent systems
• Contributing to the open-source community

Happy automating, feel free to leave us a star if you liked this! 🚀