Configuration

Configure cua-sdk to fit your needs. This guide explains all configuration parameters, how to use .env files, and how to customize agent behavior.

1. Using a .env File

Create a .env file in your project root to store configuration and secrets. The SDK uses python-dotenv to load these automatically.

OPENAI_API_KEY=your-openai-key
AGENT_NAME=Merlin
AGENT_MODE=interactive
DOCKER_IMAGE=merlin/agent:latest
LOG_LEVEL=INFO

2. Configuration Parameters

Tip: Any environment variable in .env can be accessed in your code using os.getenv("VAR_NAME").

3. Loading Environment Variables

The SDK automatically loads .env if present. To load manually in your script:

from dotenv import load_dotenv
load_dotenv()

4. Overriding Configuration

You can override config parameters at runtime:

import os
os.environ["AGENT_NAME"] = "SuperAgent"

5. Advanced Configuration: Docker Setup

Run cua-sdk agents in isolated, reproducible Docker containers for maximum security and scalability.

Prerequisites

• Docker installed and running on your system.

Building the Docker Image

docker build -t merlin/agent:latest -f cua_docker/Dockerfile .

Running an Agent in Docker

docker run --rm -it \
  --env-file .env \
  merlin/agent:latest

Mounting Volumes (Optional)

docker run --rm -it \
  --env-file .env \
  -v $(pwd)/data:/app/data \
  merlin/agent:latest

Passing Environment Variables Directly

docker run --rm -it \
  -e OPENAI_API_KEY=your-key \
  merlin/agent:latest

Running Multiple Agents

docker run --rm -d --env-file .env --name agent1 merlin/agent:latest
docker run --rm -d --env-file .env --name agent2 merlin/agent:latest

Common Docker Commands

• List running containers: docker ps
• Stop a container: docker stop
• View logs: docker logs

Troubleshooting

• Ensure Docker is running.
• Check .env is present and correct.
• Use docker logs for debugging.

Usage Examples

Basic Agent Task

from cua_sdk import ComputerAgent

agent = ComputerAgent()
result = agent.run_task("Open Notepad and type 'Hello, world!'")
print(result)

Creating Multiple Agents

from cua_sdk import ComputerAgent

agents = [ComputerAgent(name=f"Agent{i}") for i in range(3)]
for agent in agents:
    agent.run_task("Check system status")

Custom Configuration

from cua_sdk import ComputerAgent

config = {
    "AGENT_MODE": "batch",
    "LOG_LEVEL": "DEBUG"
}
agent = ComputerAgent(name="BatchAgent", config=config)
agent.run_task("Process data files in C:/data")

Using Docker for Isolation

docker build -t merlin/agent:latest -f cua_docker/Dockerfile .
docker run --rm -it --env-file .env merlin/agent:latest

Advanced: Orchestrating Agents

from cua_sdk import ComputerAgent

def orchestrate():
    agent1 = ComputerAgent(name="WebScraper")
    agent2 = ComputerAgent(name="DataProcessor")
    data = agent1.run_task("Scrape data from example.com")
    result = agent2.run_task(f"Process the following data: {data}")
    print(result)

orchestrate()

Error Handling

from cua_sdk import ComputerAgent

agent = ComputerAgent()
try:
    agent.run_task("Open a non-existent application")
except Exception as e:
    print("Task failed:", e)

Testing

Verify Installation

python -c "from cua_sdk import ComputerAgent; print('OK')"

Example Test Script

from cua_sdk import ComputerAgent

def test_basic_task():
    agent = ComputerAgent()
    result = agent.run_task("Open Notepad and type 'Test successful!'")
    print("Task result:", result)

if __name__ == "__main__":
    test_basic_task()

Using pytest (Optional)

pip install pytest

from cua_sdk import ComputerAgent

def test_agent_runs():
    agent = ComputerAgent()
    result = agent.run_task("Echo 'pytest test'")
    assert result is not None

pytest

Troubleshooting

• Ensure your .env file is present and contains valid API keys.
• Check Docker is running if using Docker-based agents.
• Review error messages for missing dependencies or misconfigurations.

FAQ

What can cua-sdk do?

• Automate desktop and cloud tasks using intelligent agents.
• Run multiple agents in parallel, each with its own configuration.
• Integrate with OpenAI and other APIs for advanced capabilities.
• Deploy agents in Docker containers for isolation and scalability.
• Easily extend and customize agent behavior with Python.

What can't it do?

• Merlin agents cannot perform tasks outside the permissions of the host system or Docker container.
• Cannot bypass OS-level security restrictions.
• Not designed for real-time or high-frequency trading, critical infrastructure, or safety-critical systems.
• Does not provide a GUI (command-line and API only).

Do I need Docker to use Merlin?

• No, Docker is optional. You can run agents directly on your host system.
• Docker is recommended for isolation, reproducibility, and scaling.

How do I get an OpenAI API key?

• Sign up at OpenAI.
• Create an API key in your account dashboard.
• Add it to your .env file as OPENAI_API_KEY=your-key.

My agent isn't working. What should I check?

• Is your .env file present and correct?
• Are all required dependencies installed?
• Is Docker running (if using Docker)?
• Check logs and error messages for details.

How do I contribute or report bugs?

• See Contributing for guidelines.
• Open issues or pull requests on GitHub.

Where can I find more examples?

• See Usage Examples and API Reference.

Changelog

[0.1.0] - Initial Release

• First public release of Merlin AI Foundation SDK.
• Core features:
  • Python SDK for creating and managing computer agents.
  • Multi-agent support.
  • Docker integration for agent isolation.
  • Configuration via .env and environment variables.
  • Example scripts and comprehensive documentation.

[Unreleased]

• Add new features and improvements here as development continues.

For each new release, add a new section with the version number, date, and a summary of changes.