CUGA with Digital Sales OpenAPI Server

CUGA can load any OpenAPI endpoint as a tool. You can use external APIs or host your own locally. This guide shows you how to configure and run CUGA with a Digital Sales API.

📋 Prerequisites

Before starting, ensure you have:

Python 3.12+ - Download here
uv package manager - Installation guide
CUGA installed - Clone from GitHub

Setup Steps

# Navigate to CUGA directory
cd cuga-agent

# Create and activate virtual environment
uv venv --python=3.12 && source .venv/bin/activate

# Install dependencies
uv sync

# Create .env file with your API keys
echo "OPENAI_API_KEY=your-openai-api-key-here" > .env
# Or use another LLM provider (see CUGA README for options)

💡 Tip: For LLM configuration options (OpenAI, WatsonX, Azure, etc.), see the CUGA README.

✅ What You'll Do

Configure settings and API registry.
Add authentication (optional).
Start CUGA in demo mode.

⚙️ Configuration Steps

1. Settings File

CUGA uses APIs by default. Check your settings.toml (located at src/cuga/settings.toml):

[advanced_features]
mode = "api"

💡 Tip: APIs work in api and hybrid modes. Learn more about hybrid here.

2. API Registry (`mcp_servers.yaml`)

Default location:

src/cuga/backend/tools_env/registry/config/mcp_servers.yaml

To use a custom file:

export MCP_SERVERS_FILE="<path-to-file>"

Example:

services:
    - digital_sales:
          url: https://digitalsales.19pc1vtv090u.us-east.codeengine.appdomain.cloud/openapi.json
          description: Digital Sales Skills API for territory accounts and client information

🔐 Adding Authentication (Optional)

services:
  - digital_sales:
      url: https://digitalsales.19pc1vtv090u.us-east.codeengine.appdomain.cloud/openapi.json
      description: Digital Sales Skills API for territory accounts and client information
    - auth:
        type: api-key
        value: <your-api-key>

✅ The type and value are sent as headers: {type: value} or as in the example above {'api-key': '<your-api-key>'}.

▶️ Running CUGA in Demo Mode

Make sure your virtual environment is activated, then start CUGA:

# Ensure virtual environment is activated
source .venv/bin/activate

# Start CUGA demo mode
cuga start demo

What happens next:

✅ Loads all APIs from mcp_servers.yaml.
✅ Makes all endpoints available as tools.
✅ Launches demo mode and opens in your browser after a few seconds at http://localhost:8005.

🎯 You're Ready!

Now you can query CUGA using the API endpoints as tools.

Example Queries

Try these queries in the CUGA demo interface:

"Get top account by revenue from digital sales"
"List all accounts in my territory"
"Get client information for account XYZ"

🔍 Troubleshooting

Common Issues

Issue: cuga: command not found

Solution: Ensure virtual environment is activated: source .venv/bin/activate

Issue: API endpoints not loading

Solution: Check mcp_servers.yaml path and format. Verify the OpenAPI URL is accessible.

Issue: Browser doesn't open

Solution: Manually navigate to http://localhost:8005

CUGA with Digital Sales OpenAPI Server

On this page