agentops-run-agent

MCP (Model Context Protocol) tool server for running AI CLI programs (Gemini CLI, Claude Code, etc.) programmatically from orchestrator agents with session management.

Overview

run_agent is a specialized MCP tool server that enables orchestrator agents to execute AI CLI programs and maintain interactive sessions. This tool bridges the gap between agent orchestration systems and interactive AI assistants like Gemini CLI and Claude Code, enabling full automation of multi-agent workflows with context preservation.

Features

• Interactive AI CLI Support: Native support for Gemini CLI, Claude Code, and other conversational AI tools
• Session Management: Maintain persistent sessions for continuous conversations
• Smart CLI Detection: Automatically detects CLI type and applies optimal execution strategy
• MCP Protocol Compliance: Full support for the Model Context Protocol standard
• Flexible Execution: Both one-off execution and persistent session modes
• Error Handling: Comprehensive error handling with automatic retry mechanisms
• Security: Uses spawn instead of exec to prevent command injection

Installation

NPM Installation

npm install -g agentops-run-agent

Local Development

git clone <repository-url>
cd run_agent
npm install
npm run build

Usage

As MCP Server

Start the MCP server:

run-agent-server

Or using npx:

npx agentops-run-agent

MCP Tool Definitions

The server provides three tools for different use cases:

1. run_agent (Basic execution)

For one-off execution of CLI programs:

{
  "name": "run_agent",
  "description": "Execute a CLI program once and return the result",
  "inputSchema": {
    "type": "object",
    "properties": {
      "agent_path": { "type": "string", "description": "Path to CLI program or command name" },
      "prompt": { "type": "string", "description": "Input prompt to send to the program" }
    },
    "required": ["agent_path", "prompt"]
  }
}

2. run_agent_with_session (Interactive AI CLI)

For maintaining sessions with conversational AI tools:

{
  "name": "run_agent_with_session",
  "description": "Execute AI CLI with session management for continuous conversation",
  "inputSchema": {
    "type": "object",
    "properties": {
      "agent_path": { "type": "string", "description": "AI CLI command (e.g., 'gemini', 'claude')" },
      "prompt": { "type": "string", "description": "Message to send to AI" },
      "session_id": { "type": "string", "description": "Existing session ID (optional)" },
      "keep_session": { "type": "boolean", "description": "Keep session alive after execution (default: true)" },
      "timeout": { "type": "number", "description": "Response timeout in ms (default: 30000)" }
    },
    "required": ["agent_path", "prompt"]
  }
}

3. close_session (Session cleanup)

For manually closing active sessions:

{
  "name": "close_session",
  "description": "Close an active session",
  "inputSchema": {
    "type": "object",
    "properties": {
      "session_id": { "type": "string", "description": "Session ID to close" }
    },
    "required": ["session_id"]
  }
}

Parameters

• agent_path (string, required): Absolute or relative path to the specialist agent CLI program
• prompt (string, required): Task instruction prompt to be passed to the specialist agent

Usage Examples

1. Basic CLI Execution

Execute a simple CLI program once:

{
  "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": {
    "name": "run_agent",
    "arguments": {
      "agent_path": "./scripts/data_analyzer.js",
      "prompt": "Analyze the sales data from Q4"
    }
  }
}

2. Interactive AI Session (Gemini CLI)

Start a conversation with Gemini CLI:

{
  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "run_agent_with_session",
    "arguments": {
      "agent_path": "gemini",
      "prompt": "Hello! Can you help me write a Python function?",
      "keep_session": true
    }
  }
}

3. Continue Existing Session

Continue the conversation using the session ID from previous response:

{
  "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": {
    "name": "run_agent_with_session",
    "arguments": {
      "agent_path": "gemini",
      "prompt": "Make it return fibonacci numbers",
      "session_id": "session_1234567890_abc123"
    }
  }
}

4. Close Session

Clean up when done:

{
  "jsonrpc": "2.0", "id": 4, "method": "tools/call",
  "params": {
    "name": "close_session",
    "arguments": {
      "session_id": "session_1234567890_abc123"
    }
  }
}

Response Formats

Basic Success Response:

{
  "content": [
    {
      "type": "text",
      "text": "Agent output goes here..."
    }
  ]
}

Session-enabled Success Response:

{
  "content": [
    {
      "type": "text",
      "text": "AI response here..."
    },
    {
      "type": "text", 
      "text": "\n\n[Session ID: session_1234567890_abc123]"
    }
  ]
}

Error Response:

{
  "error": {
    "code": -32603,
    "message": "Session not found: session_invalid"
  }
}

Architecture

The enhanced run_agent system uses a pluggable strategy pattern:

┌─────────────────┐    ┌─────────────────┐    ┌──────────────────┐
│ MCP Request     │───▶│ CLI Detector    │───▶│ Strategy Factory │
└─────────────────┘    └─────────────────┘    └──────────────────┘
                                                        │
                       ┌────────────────────────────────┼────────────────────────────────┐
                       │                                │                                │
                       ▼                                ▼                                ▼
              ┌─────────────────┐            ┌─────────────────┐            ┌─────────────────┐
              │ Default Strategy│            │ Gemini Strategy │            │ Claude Strategy │
              │ (one-off exec)  │            │ (session-based) │            │ (session-based) │
              └─────────────────┘            └─────────────────┘            └─────────────────┘
                       │                                │                                │
                       │                ┌───────────────┼───────────────┐                │
                       │                │               │               │                │
                       ▼                ▼               ▼               ▼                ▼
              ┌─────────────────┐    ┌─────────────────────────────────────────────────────────┐
              │ Child Process   │    │           Session Manager                                │
              │ (spawn & close) │    │ • Process lifecycle management                          │
              └─────────────────┘    │ • Interactive I/O handling                              │
                                     │ • Session cleanup & timeout                             │
                                     └─────────────────────────────────────────────────────────┘

Execution Flow:

1. CLI Detection: Analyze agent_path to determine CLI type (Gemini, Claude, or default)
2. Strategy Selection: Choose appropriate execution strategy based on CLI type
3. Session Management: For interactive CLIs, create/reuse persistent sessions
4. I/O Handling: Handle bidirectional communication with AI CLI processes
5. Response Processing: Format and return results with optional session information
6. Cleanup: Automatic session cleanup after timeout or manual closure

Error Handling

The tool handles several error conditions:

• Agent Path Not Found: When the specified path doesn't exist
• Process Execution Error: When the agent program fails to start
• Non-zero Exit Code: When the agent exits with an error code
• Invalid Parameters: When required parameters are missing or invalid

Development

Build

npm run build

Development Mode

npm run dev

Testing

A simple test client is included:

node test_client.js

Requirements

• Node.js >= 18.0.0
• NPM or Yarn package manager

License

MIT