Agents Management

The rf agents command (or rf agent singular) provides complete agent management capabilities with an interactive menu and support for automation via non-interactive flags.

Commands Overview

Command	Description
`rf agents list`	Interactive menu to manage agents
`rf agents get`	Show current agent details
`rf agents clone`	Clone agent repository locally
`rf agents pull`	Pull latest changes from server
`rf agents deploy`	Deploy local changes to server
`rf agents duplicate`	Duplicate agent on server
`rf agents delete`	Delete agent

List Agents

List all available agents with an interactive menu:

rf agents list

This opens an interactive menu where you can:

📋 Browse all your agents
🔽 Clone repository to local machine
🚀 Deploy changes to server
📋 Duplicate agent on server
🗑️ Delete agent
👁️ View agent details

The interactive menu is the fastest way to manage agents - no need to remember multiple commands!

Main Commands

Get Agent Details

Show details of the current/selected agent:

rf agents get

Output:

Agent: support-bot
ID: agent_abc123
Tenant: ACME Corp (tenant_xyz)
Created: 2024-01-15
Status: Active
Repository: https://github.com/runflow-agents/support-bot

Clone Agent Repository

Download an agent repository to your local machine:

rf agents clone

Or use the interactive menu (rf agents list → select agent → Clone repository). This creates a local folder with the agent’s code, allowing you to:

Make changes locally
Test changes with rf test
Deploy updates with rf agents deploy

What gets cloned:

agent-name/
├── .runflow/
│   └── rf.json         # Agent configuration
├── src/
│   └── index.ts        # Agent code
├── package.json
└── README.md

Deploy Changes

Deploy your local changes to the server:

cd my-agent/
rf agents deploy

Make sure you’re in the agent’s directory before deploying. The CLI detects the agent from .runflow/rf.json.

Deployment Process:

Validates .runflow/rf.json exists
Commits local changes to git
Pushes to remote repository
Server automatically rebuilds agent
Agent is live with new changes

Pull Latest Changes

Pull the latest changes from the server (overwrites local changes):

cd my-agent/
rf agents pull

This command will overwrite your local changes. Make sure to commit or backup your work before pulling.

When to use:

After changes made via dashboard
Sync with team member changes
Reset to server state

Duplicate Agent

Create a copy of an agent on the server:

rf agents duplicate

Or use the interactive menu (rf agents list → select agent → Duplicate). Use cases:

Create dev/staging versions
Fork agent for different client
Experiment without affecting original

Delete Agent

Delete an agent from the server:

# With confirmation prompt
rf agents delete

# Skip confirmation (for scripts/automation)
rf agents delete --yes
rf agents delete -y

Or use the interactive menu (rf agents list → select agent → Delete).

This action is permanent and cannot be undone! The agent and its repository will be deleted.

Non-Interactive Mode

All commands support --yes or -y flag to skip confirmations, perfect for automation:

# Delete without confirmation
rf agents delete --yes

# Use in scripts
#!/bin/bash
rf agents delete --yes
echo "Agent deleted"

Common Workflows

Development Workflow

# 1. Create new agent
rf create --name my-agent --template starter --yes

# 2. Navigate to agent folder
cd my-agent/

# 3. Make your changes
# ... edit src/index.ts ...

# 4. Test locally
rf test

# 5. Deploy changes
rf agents deploy

# 6. Pull latest changes when needed (if changed via dashboard)
rf agents pull

Existing Agent Workflow

# 1. List and select agent (interactive menu)
rf agents list

# 2. Clone repository (select "Clone repository" from menu)
# This creates a folder with the agent name

# 3. Navigate to agent folder
cd agent-name/

# 4. Make your changes
# ... edit files ...

# 5. Test locally
rf test

# 6. Deploy changes
rf agents deploy

Staging-to-Production Workflow

Runflow has two environments per tenant: staging and production. rf agents deploy always deploys to staging. When staging is validated, promote it to production.

# 1. Make your changes and test locally (runs in staging mode)
cd my-agent/
rf test

# 2. Deploy to staging
rf agents deploy

# 3. Validate on the staging endpoint
# ... run real traffic through the staging endpoint URL ...

# 4. Promote staging to production when ready
rf agents promote

For the full environment model — which entities are per-environment, how to publish prompts and connectors, and how the dashboard Releases screen works — see Environments.

Agent Duplication & Experimentation

# Duplicate agent for testing
rf agents list
# → Select agent → Duplicate
# → Enter new name: "my-agent-experimental"

# Clone and test
rf agents clone  # Select experimental version
cd my-agent-experimental/
# ... make experimental changes ...
rf test
rf agents deploy

# If successful, apply to original
cd ../my-agent/
# ... apply changes ...
rf agents deploy

# Delete experimental version
rf agents delete --yes

Project Configuration

Each agent folder contains .runflow/rf.json:

{
  "agentId": "agent_abc123",
  "agentName": "my-agent",
  "tenantId": "tenant_xyz"
}

Don’t delete or modify .runflow/rf.json - it’s required for deployment and local testing!

Using with AI Tools

Non-interactive mode works seamlessly with AI coding assistants:

# Cursor / Copilot can execute these
rf agents delete --yes
rf agents deploy
rf agents pull

Automation Scripts

Bulk Deployment

#!/bin/bash

agents=("support-bot" "sales-assistant" "feedback-analyzer")

for agent in "${agents[@]}"; do
  cd "$agent"
  rf test
  if [ $? -eq 0 ]; then
    rf agents deploy
  else
    echo "Tests failed for $agent"
  fi
  cd ..
done

CI/CD Integration

# .github/workflows/deploy.yml
name: Deploy Agent

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install CLI
        run: npm i -g @runflow-ai/cli
      - name: Login
        run: rf login --api-key ${{ secrets.RUNFLOW_API_KEY }}
      - name: Deploy
        run: rf agents deploy

Troubleshooting

Not in Agent Directory

rf agents deploy
# Error: No agent configuration found (.runflow/rf.json)

Solution: Navigate to agent directory:

cd my-agent/
rf agents deploy

Merge Conflicts on Pull

rf agents pull
# Error: Local changes conflict with server

Solution:

# Commit local changes first
git add .
git commit -m "Local changes"

# Then pull
rf agents pull

# Or discard local changes
git reset --hard HEAD
rf agents pull

Deployment Failed

rf agents deploy
# Error: Deployment failed

Solution:

Check for syntax errors in your code
Verify all dependencies are in package.json
Check server logs via dashboard
Ensure valid .runflow/rf.json

Aliases

You can use either rf agents (plural) or rf agent (singular):

rf agent list      # Same as rf agents list
rf agent deploy    # Same as rf agents deploy
rf agent clone     # Same as rf agents clone
rf agent delete -y # Same as rf agents delete -y

Next Steps

Create Agent

Create new agent from template

Test

Test agents locally with web interface

Knowledge Base

Add knowledge base for RAG

Prompts

Manage prompt templates

Getting Started

CLI

Core Concepts

Real-World Examples

Advanced

Configuration

Extending Runflow

Help & Support

Agents Management

Commands Overview

Interactive Menu

List Agents

Main Commands

Get Agent Details

Clone Agent Repository

Deploy Changes

Pull Latest Changes

Duplicate Agent

Delete Agent

Non-Interactive Mode

Common Workflows

Development Workflow

Existing Agent Workflow

Staging-to-Production Workflow

Agent Duplication & Experimentation

Project Configuration

Using with AI Tools

Automation Scripts

Bulk Deployment

CI/CD Integration

Troubleshooting

Not in Agent Directory

Merge Conflicts on Pull

Deployment Failed

Aliases

Next Steps

Create Agent

Test

Knowledge Base

Prompts

​Commands Overview

​Interactive Menu

​List Agents

​Main Commands

​Get Agent Details

​Clone Agent Repository

​Deploy Changes

​Pull Latest Changes

​Duplicate Agent

​Delete Agent

​Non-Interactive Mode

​Common Workflows

​Development Workflow

​Existing Agent Workflow

​Staging-to-Production Workflow

​Agent Duplication & Experimentation

​Project Configuration

​Using with AI Tools

​Automation Scripts

​Bulk Deployment

​CI/CD Integration

​Troubleshooting

​Not in Agent Directory

​Merge Conflicts on Pull

​Deployment Failed

​Aliases

​Next Steps

Create Agent

Test

Knowledge Base

Prompts

Commands Overview

Interactive Menu

List Agents

Main Commands

Get Agent Details

Clone Agent Repository

Deploy Changes

Pull Latest Changes

Duplicate Agent

Delete Agent

Non-Interactive Mode

Common Workflows

Development Workflow

Existing Agent Workflow

Staging-to-Production Workflow

Agent Duplication & Experimentation

Project Configuration

Using with AI Tools

Automation Scripts

Bulk Deployment

CI/CD Integration

Troubleshooting

Not in Agent Directory

Merge Conflicts on Pull

Deployment Failed

Aliases

Next Steps