Cloud Deployment - RunAgent

Deploy agents to RunAgent cloud infrastructure for production use with automatic scaling, monitoring, and global availability.

Prerequisites

Before deploying to the cloud, you need:

RunAgent Account - Sign up at run-agent.ai
API Key - Get your API key from the dashboard
Configured CLI - Authenticate your CLI with your API key

Authentication Setup

Configure your CLI with your API key:

# Setup authentication
runagent setup --api-key <your-api-key>

# Verify configuration
runagent setup --api-key <your-api-key>

The setup command will:

Validate your API key with the RunAgent middleware
Store credentials securely in ~/.runagent/config.json
Display your account information and tier
Show middleware sync status

Teardown Configuration

Remove stored credentials:

runagent teardown

Deployment Methods

Method 1: Quick Deploy (Upload + Start)

Deploy your agent in a single command:

# Deploy to cloud (combines upload + start)
runagent deploy --folder <agent-folder>

# Example
runagent deploy --folder ./my-agent

This command will:

Validate your agent configuration
Upload agent code and metadata to the cloud
Start the agent automatically
Return the deployment endpoint

Output:

✅ Full deployment successful!
🆔 Agent ID: abc-123-def-456
🌐 Endpoint: https://api.run-agent.ai/api/v1/agents/abc-123-def-456

Method 2: Two-Step Deploy (Upload Then Start)

For more control, upload and start separately:

Step 1: Upload Agent

# Upload agent to cloud
runagent upload --folder <agent-folder>

# Specify framework explicitly (optional)
runagent upload --folder <agent-folder> --framework langgraph

Upload Process:

Agent validation (checks for required files)
Fingerprint generation (for duplicate detection)
Metadata upload (config + entrypoints)
Source code packaging and upload
Local database tracking

Output:

📤 Uploading agent from: ./my-agent
🔍 Validating agent...
✅ Agent validation passed
📋 Agent config loaded successfully
🔍 Agent fingerprint: a1b2c3d4...

📦 Uploading to: https://api.run-agent.ai/api/v1
🌐 Uploading agent metadata...
   Metadata uploaded successfully
📦 Creating upload package...
   Created upload package: agent_abc12345.zip
   Uploading agent_abc12345.zip (1,234,567 bytes)...
   Processing upload...
   Upload completed!

✅ Upload successful!
🆔 Agent ID: abc-123-def-456
🌐 Server: https://api.run-agent.ai/api/v1
🔍 Fingerprint: a1b2c3d4...

💡 Next step: runagent start --id abc-123-def-456

Step 2: Start Agent

# Start uploaded agent
runagent start --id <agent-id>

# With custom configuration
runagent start --id <agent-id> --config '{"env": "production"}'

Output:

Starting agent: abc-123-def-456

✅ Agent started successfully!
🆔 Agent ID: abc-123-def-456
🌐 Endpoint: https://api.run-agent.ai/api/v1/agents/abc-123-def-456/execute

Agent Configuration

Agent ID and Entrypoints

When you initialize a new agent with runagent init, it automatically:

Generates a unique agent ID and adds it to runagent.config.json
Creates a basic configuration with framework and template settings

Important: You must add your entrypoints to the configuration file before deploying.

Using `runagent init` (Recommended)

# Initialize a new agent
runagent init my-agent --framework langgraph

# This creates runagent.config.json with:
# - Generated agent_id
# - Framework configuration
# - Empty entrypoints array (you need to add these)

Example runagent.config.json after init:

{
  "agent_name": "my-agent",
  "agent_id": "abc-123-def-456",
  "version": "1.0.0",
  "framework": "langgraph",
  "agent_architecture": {
    "entrypoints": []  // ← You need to add entrypoints here
  }
}

Add your entrypoints:

{
  "agent_name": "my-agent",
  "agent_id": "abc-123-def-456",
  "version": "1.0.0",
  "framework": "langgraph",
  "agent_architecture": {
    "entrypoints": [
      {
        "tag": "chat",
        "file": "main.py",
        "module": "chat_agent"
      },
      {
        "tag": "chat_stream",
        "file": "main.py",
        "module": "chat_agent_stream"
      }
    ]
  }
}

Manually Editing Agent ID

If you manually edit the agent_id in runagent.config.json, you must register the agent:

# Register the agent after manually editing agent_id
runagent register .

# Or use the config command
runagent config --register-agent .

Important: If you manually change the agent_id in your config file, RunAgent won’t recognize it until you register it. Always run runagent register . after manually editing the agent ID.

Agent Validation

Before upload, RunAgent validates your agent:

Required Files

runagent.config.json - Agent configuration with valid agent_id and entrypoints
main.py or agent.py - Entry point file
requirements.txt - Python dependencies (optional)

Validation Checks

✅ Configuration file exists and is valid JSON
✅ Agent ID exists in configuration
✅ Agent ID is registered (if manually edited)
✅ Entry point file exists
✅ Entrypoints are properly defined
✅ Framework is supported
✅ No syntax errors in configuration

Example Valid Configuration:

{
  "agent_name": "my-agent",
  "agent_id": "abc-123-def-456",
  "version": "1.0.0",
  "framework": "langgraph",
  "agent_architecture": {
    "entrypoints": [
      {
        "tag": "chat",
        "file": "main.py",
        "module": "agent.chat"
      }
    ]
  }
}

Duplicate Detection

RunAgent uses fingerprinting to detect duplicate agents:

How It Works

Fingerprint Generation: Creates a unique hash of your agent’s content
Duplicate Check: Compares with existing agents in your account
User Prompt: If duplicate found, asks whether to overwrite or create new

Example Scenarios: Scenario 1: Identical Content

⚠️ Agent with identical content already exists!
🆔 Existing Agent ID: abc-123-def-456
📊 Status: deployed
📍 Type: Remote

Do you want to overwrite the existing agent? [y/N]: 

Scenario 2: Modified Content

⚠️ Agent content has changed!
🆔 Existing Agent ID: abc-123-def-456
📊 Status: deployed
📍 Type: Remote
🔍 Content fingerprint changed (modified files detected)

What would you like to do?
  [overwrite] - Overwrite existing agent (coming soon)
  [new] - Create new agent
  [cancel] - Cancel upload

Running Cloud Agents

Execute your deployed agents:

Basic Execution

# Run with entrypoint tag
runagent run --id <agent-id> --tag <entrypoint> --param1=value1 --param2=value2

# Examples
runagent run --id abc-123 --tag chat --message="Hello"
runagent run --id abc-123 --tag process --data='{"key": "value"}'

Using Input Files

# Run with JSON input file
runagent run --id <agent-id> --tag <entrypoint> --input config.json

Example input.json:

{
  "message": "Hello, world!",
  "config": {
    "temperature": 0.7,
    "max_tokens": 100
  }
}

Streaming Execution

For streaming entrypoints (must end with _stream):

# Run streaming endpoint using run-stream command
runagent run-stream --id <agent-id> --tag chat_stream --message="Tell me a story"

# Or with local agent
runagent run-stream --id <agent-id> --tag chat_stream --local --message="Tell me a story"

Important: Use runagent run-stream (not runagent run) for streaming execution. The run-stream command uses WebSocket connections for real-time streaming.

Cloud vs Local Deployment

Feature	Local	Cloud
Setup	`runagent serve`	`runagent deploy`
Infrastructure	Your machine	RunAgent cloud
Scaling	Manual	Automatic
Uptime	While running	24/7
Monitoring	Local logs only	Full monitoring dashboard
URL	localhost:port	Global endpoint
Authentication	None	API key required
Cost	Free	Usage-based pricing

Deployment Workflow

Complete Example

# 1. Create and test agent locally
runagent init my-agent --framework langgraph --template default
cd my-agent

# 2. Add entrypoints to runagent.config.json
# Edit the file and add your entrypoints to agent_architecture.entrypoints

# 3. If you manually edited agent_id, register it
runagent register .

# 4. Test locally
runagent serve

# 5. Authenticate (if not already done)
runagent setup --api-key <your-key>

# 6. Deploy to cloud
runagent deploy --folder .

# 7. Test cloud deployment
runagent run --id <agent-id> --tag chat --message="Hello"

CI/CD Integration

GitHub Actions

name: Deploy to RunAgent Cloud

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      
      - name: Install RunAgent
        run: pip install runagent
      
      - name: Deploy Agent
        env:
          RUNAGENT_API_KEY: ${{ secrets.RUNAGENT_API_KEY }}
        run: |
          runagent setup --api-key $RUNAGENT_API_KEY
          runagent deploy --folder .

GitLab CI

deploy:
  stage: deploy
  image: python:3.9
  
  script:
    - pip install runagent
    - runagent setup --api-key $RUNAGENT_API_KEY
    - runagent deploy --folder .
  
  only:
    - main

Monitoring and Management

View Agent Status

# Check if agent is running
runagent start --id <agent-id>

Local Deployment Info

Deployment information is saved locally in .deployments/:

{
  "agent_id": "abc-123-def-456",
  "remote": true,
  "base_url": "https://api.run-agent.ai/api/v1",
  "fingerprint": "a1b2c3d4...",
  "source_folder": "/path/to/my-agent",
  "saved_at": "2025-01-15 10:30:00",
  "client_version": "1.0"
}

Troubleshooting

Authentication Errors

Error: Not authenticated. Run 'runagent setup --api-key <key>' first Solution:

# Setup authentication
runagent setup --api-key <your-api-key>

# Verify setup worked
runagent setup --api-key <your-api-key>

Upload Failures

Error: Agent validation failed Solution:

Check that runagent.config.json exists and is valid
Verify entry point file exists (main.py or agent.py)
Ensure all required dependencies are in requirements.txt
Run runagent serve locally to test first

Error: Failed to upload agent: HTTP 413 Solution: Your agent folder is too large. Remove unnecessary files:

Remove __pycache__ directories
Remove .pyc files
Remove large data files (use cloud storage instead)
Add .gitignore patterns to exclude files

Deployment Fails But Upload Succeeds

Error: Upload succeeded but start failed Solution:

# Agent is uploaded, just needs to be started
runagent start --id <agent-id>

Connection Issues

Error: Cannot connect to middleware server Solution:

Check your internet connection
Verify the base URL is correct
Check if middleware server is accessible
Try with explicit base URL: runagent setup --api-key <key> --base-url https://api.run-agent.ai

Best Practices

1. Test Locally First

Always test your agent locally before deploying:

# Test locally
runagent serve
runagent run --id <local-agent-id> --tag chat --local --message="test"

# Deploy after successful local testing
runagent deploy --folder .

2. Version Control

Include deployment info in version control:

# Add to .gitignore
.deployments/*.json
.runagent/

# But track your agent code
git add runagent.config.json main.py requirements.txt
git commit -m "feat: add chat agent"

3. Environment Variables

Use environment variables for sensitive data:

{
  "env_vars": {
    "OPENAI_API_KEY": "${OPENAI_API_KEY}",
    "DATABASE_URL": "${DATABASE_URL}"
  }
}

Set them before deploying:

export OPENAI_API_KEY="sk-..."
runagent deploy --folder .

4. Incremental Updates

For agent updates:

# Upload new version
runagent upload --folder .

# Test before switching
runagent run --id <new-agent-id> --tag chat --message="test"

# If good, can use new agent ID

5. Monitor Performance

After deployment:

Test all entrypoints
Check response times
Verify outputs are correct
Monitor error rates

Security

API Key Management

Best Practices:

✅ Store API keys in environment variables
✅ Use different keys for development and production
✅ Rotate keys regularly
✅ Never commit API keys to version control
❌ Don’t share API keys
❌ Don’t hardcode keys in agent code

Secure Deployment

# Use environment variables
export RUNAGENT_API_KEY="your-key"
runagent deploy --folder .

# Or use secure config file
runagent setup --api-key $RUNAGENT_API_KEY

Limits and Quotas

Free Tier

5 local agents
Cloud deployment available
Standard execution limits

Enhanced Limits

Contact sales for:

Unlimited local agents
Higher execution limits
Priority support
Custom SLAs

Check your current limits:

runagent db status --capacity

Next Steps

RunAgent Cloud Overview - Learn about RunAgent Cloud infrastructure
Local Development - Test agents locally
SDK Overview - Use Python SDK for deployment
API Reference - Direct API access
Monitoring Guide - Track agent performance

Support

Need help with cloud deployment?

RunAgent Cloud

Documentation Index

​Prerequisites

​Authentication Setup

​Teardown Configuration

​Deployment Methods

​Method 1: Quick Deploy (Upload + Start)

​Method 2: Two-Step Deploy (Upload Then Start)

​Step 1: Upload Agent

​Step 2: Start Agent

​Agent Configuration

​Agent ID and Entrypoints

​Using runagent init (Recommended)

​Manually Editing Agent ID

​Agent Validation

​Required Files

​Validation Checks

​Duplicate Detection

​How It Works

​Running Cloud Agents

​Basic Execution

​Using Input Files

​Streaming Execution

​Cloud vs Local Deployment

​Deployment Workflow

​Complete Example

​CI/CD Integration

​GitHub Actions

​GitLab CI

​Monitoring and Management

​View Agent Status

​Local Deployment Info

​Troubleshooting

​Authentication Errors

​Upload Failures

​Deployment Fails But Upload Succeeds

​Connection Issues

​Best Practices

​1. Test Locally First

​2. Version Control

​3. Environment Variables

​4. Incremental Updates

​5. Monitor Performance

​Security

​API Key Management

​Secure Deployment

​Limits and Quotas

​Free Tier

​Enhanced Limits

​Next Steps

​Support

Prerequisites

Authentication Setup

Teardown Configuration

Deployment Methods

Method 1: Quick Deploy (Upload + Start)

Method 2: Two-Step Deploy (Upload Then Start)

Step 1: Upload Agent

Step 2: Start Agent

Agent Configuration

Agent ID and Entrypoints

Using `runagent init` (Recommended)

Manually Editing Agent ID

Agent Validation

Required Files

Validation Checks

Duplicate Detection

How It Works

Running Cloud Agents

Basic Execution

Using Input Files

Streaming Execution

Cloud vs Local Deployment

Deployment Workflow

Complete Example

CI/CD Integration

GitHub Actions

GitLab CI

Monitoring and Management

View Agent Status

Local Deployment Info

Troubleshooting

Authentication Errors

Upload Failures

Deployment Fails But Upload Succeeds

Connection Issues

Best Practices

1. Test Locally First

2. Version Control

3. Environment Variables

4. Incremental Updates

5. Monitor Performance

Security

API Key Management

Secure Deployment

Limits and Quotas

Free Tier

Enhanced Limits

Next Steps

Support