TubeCLI — AI Agent Operating Guide

1. System Overview

TubeCLI is a headless CLI system for managing AI agents, skills (workflow templates), and workflows. AI agents can use this system via CLI commands or REST API.

Architecture

tubecli (Click CLI)
├── agent  — Manage AI agents (create, list, delete)
├── skill  — Manage & run skills (workflow templates)
├── workflow — Run workflow JSON files
├── api    — Start REST API server
└── init   — Initialize workspace

Key Concepts

• Agent: An AI entity with name, description, system prompt, persona, and assigned skills
• Skill: A reusable workflow template (DAG of connected nodes)
• Workflow: A directed acyclic graph (DAG) of nodes connected by ports
• Node: An execution unit with typed input/output ports (text, json, file, any)

2. Installation

bash
1cd tubecli
2pip install -e .
3tubecli init

3. CLI Commands

Initialize

bash
1tubecli init  # Creates data dirs, installs default skills, creates default agent

Agents

bash
1tubecli agent create "Agent Name" --description "desc" --model "qwen:latest"
2tubecli agent list
3tubecli agent show <agent_id_or_name>
4tubecli agent delete <agent_id>

Skills

bash
1tubecli skill list
2tubecli skill show "AI Summarizer"
3tubecli skill run "AI Summarizer" --input "Text to summarize"
4tubecli skill run "Batch Command Runner"

Workflows

bash
1tubecli workflow list
2tubecli workflow run workflow.json --input "input text"

API Server

bash
1tubecli api start --port 5295
2tubecli api status

4. REST API Reference

Base URL: http://localhost:5295

5. Workflow JSON Format

json
1{
2  "name": "My Workflow",
3  "nodes": [
4    {"id": "input1", "type": "text_input", "config": {"text": "Hello"}},
5    {"id": "ai1", "type": "ai_node", "config": {"model": "qwen:latest"}},
6    {"id": "out1", "type": "output", "config": {"print": true}}
7  ],
8  "connections": [
9    {"from_node_id": "input1", "from_port_id": "content", "to_node_id": "ai1", "to_port_id": "prompt"},
10    {"from_node_id": "ai1", "from_port_id": "response", "to_node_id": "out1", "to_port_id": "data"}
11  ]
12}

6. Available Node Types

7. Agent JSON Schema

json
1{
2  "id": "uuid",
3  "name": "Agent Name",
4  "description": "What this agent does",
5  "system_prompt": "You are...",
6  "allowed_skills": ["skill_id_1", "skill_id_2"],
7  "model": "qwen:latest",
8  "persona": {},
9  "routine": {},
10  "cloud_api_keys": {"gemini": "", "openai": "", "claude": "", "deepseek": ""}
11}

8. Creating Custom Skills

To create a custom skill, POST to /api/v1/skills or use the skill manager:

json
1{
2  "name": "My Custom Skill",
3  "description": "What it does",
4  "skill_type": "Skill",
5  "workflow_data": {
6    "nodes": [...],
7    "connections": [...]
8  }
9}

9. Common Workflow Patterns

Pattern: Input → AI → Output

json
1{
2  "nodes": [
3    {"id": "in", "type": "text_input", "config": {"text": "..."}},
4    {"id": "ai", "type": "ai_node", "config": {}},
5    {"id": "out", "type": "output", "config": {}}
6  ],
7  "connections": [
8    {"from_node_id": "in", "from_port_id": "content", "to_node_id": "ai", "to_port_id": "prompt"},
9    {"from_node_id": "ai", "from_port_id": "response", "to_node_id": "out", "to_port_id": "data"}
10  ]
11}

Pattern: Loop → Command → Output

json
1{
2  "nodes": [
3    {"id": "list", "type": "text_input", "config": {"text": "cmd1\ncmd2"}},
4    {"id": "loop", "type": "loop", "config": {}},
5    {"id": "exec", "type": "run_command", "config": {}},
6    {"id": "out", "type": "output", "config": {}}
7  ],
8  "connections": [
9    {"from_node_id": "list", "from_port_id": "lines", "to_node_id": "loop", "to_port_id": "items"},
10    {"from_node_id": "loop", "from_port_id": "current_item", "to_node_id": "exec", "to_port_id": "command"},
11    {"from_node_id": "exec", "from_port_id": "stdout", "to_node_id": "out", "to_port_id": "data"}
12  ]
13}