Universal Agent

Workflows

This skill should be used when the user needs to execute tasks through a complete automated workflow: understand natural language intent, dynamically generate commands or Python scripts, auto-execute them via shell, and summarize results. This is a minimal universal agent implementation based on "LLM brain + command executor limbs" architecture. Use this when users say things like "help me do X automatically", "generate code and run it", "universal agent", "execute task end-to-end", or when tasks require dynamic code generation and execution with automatic error recovery.

Install

openclaw skills install universal-agent

Universal Agent Skill

A minimal universal AI agent that automates end-to-end task execution: understand user intent in natural language, generate commands or scripts, execute them, analyze results, and self-recover from errors.

Architecture

Natural Language Input
       ↓
  ┌─────────────┐
  │ LLM (Brain) │ Understand intent, generate command/Python script
  └──────┬──────┘
         │ Auto-generate code/command
         ↓
  ┌─────────────────┐
  │ Command Executor │ Execute any command, control software & hardware
  │ (Limbs)          │
  └───────┬─────────┘
          │ Actual execution
          ↓
     Task Complete ✅

File Structure

universal-agent/
├── SKILL.md                    # This file (skill definition)
├── scripts/
│   ├── universal_agent.py      # Main program (complete standalone implementation)
│   └── config.json             # Configuration file (fill in API key for standalone mode)
└── references/
    └── README.md               # Detailed usage documentation

When to Use

Use this skill when:

User describes a task in natural language that requires automated execution
Task needs dynamic code generation (Python script) and immediate execution
Task involves file operations, data processing, system administration, CLI tools, API calls
User wants end-to-end automation without manual intervention
Keywords: "万能agent", "universal agent", "自动执行", "动态生成代码", "生成并执行", "帮我做XX"

How It Works

Automated Workflow (4 Steps)

Think — LLM understands task, judges complexity, decides whether to generate a shell command or Python script
Execute — Auto-write file → Run command/script → Capture output
Fix — On error, LLM analyzes error, auto-fixes code, retries (up to 2 times)
Summarize — Translates technical output into human-friendly language

Why It's "Universal"

Capability	Description
Shell Commands	File ops, process management, system admin
Python Scripts	Data processing, web scraping, ML, image processing
CLI Tools	git, docker, ffmpeg, aws, any CLI
Hardware Control	Serial/GPIO/network-controlled physical devices
API Calls	Any HTTP API

Command executor can run Python → Python can do anything → Agent can do anything

Usage Modes

This skill supports three distinct usage modes, each suited to different scenarios:

Mode 1: Standalone (独立运行)

Run the bundled script directly as an independent program. The script handles everything internally — LLM calls, command execution, safety checks, retries, memory.

# Single task mode (needs API key)
python scripts/universal_agent.py --run "task description"

# Interactive mode
python scripts/universal_agent.py

# With environment variables
set LLM_API_KEY=sk-xxx && python scripts/universal_agent.py --run "任务"

What works: Safety ✅ | Auto-retry ✅ | Memory persistence ✅ | Needs API Key.

Mode 2: Bridge Execution (桥接执行 — 推荐)

Execute the script with --backend bridge. The script's brain is provided by the external Agent that loaded this Skill, while the script itself handles execution, safety, retry, and memory. Any Agent with LLM + command execution can use this.

# Basic bridge execution
python scripts/universal_agent.py --backend bridge --run "任务描述"

# View full protocol spec
python scripts/universal_agent.py --bridge-info

How it works — the Agent drives the script through environment variables:

┌─────────────────────────────────────────────────────────────┐
│                    Bridge Mode Flow                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ① User: "列出当前目录的文件"                                │
│       ↓                                                     │
│  ② External Agent LLM → generates decision                  │
│     set UA_THINK={"type":"command","content":"dir /b"}      │
│       ↓                                                     │
│  ③ Agent executes:                                          │
│     python ... --backend bridge --run "列出当前目录的文件"   │
│       ↓                                                     │
│  ④ Script reads UA_THINK → runs "dir /b"                    │
│     → safety check passes → captures output                 │
│       ↓ (if error)                                          │
│  ⑤ Script requests fix via UA_DEBUG_AND_FIX env var         │
│       ↓                                                     │
│  ⑥ External Agent provides fixed code                       │
│     set UA_DEBUG_AND_FIX="fixed_command_or_script"           │
│       ↓                                                     │
│  ⑦ Script re-executes → success                             │
│       ↓                                                     │
│  ⑧ Script reads UA_SUMMARIZE for final output               │
│     → returns structured JSON result                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Environment Variable Protocol:

Variable	When Used	Format
`UA_THINK`	Step 1 — decision	JSON: `{"type":"command\|script","content":"...","explanation":"..."}`
`UA_GENERATE_SCRIPT`	If type=script and code needed	Complete Python source code
`UA_SUMMARIZE`	Final step — result summary	Natural language summary text
`UA_DEBUG_AND_FIX`	On error retry — fixed code	Fixed Python/shell code

What works: Safety ✅ | Auto-retry ✅ | Memory persistence ✅ | No API Key needed (Agent provides LLM).

Who can use this: WorkBuddy, Cursor, Continue.dev, Aider, Cline, any AI IDE/tool with LLM + shell access.

Mode 3: Inline Simulation (模拟执行)

The loaded Agent reads this SKILL.md, learns the architecture pattern, and simulates the workflow using its own native capabilities without executing the script at all. The script serves as a reference/teaching example only.

Agent uses its own LLM instead of LLMBrain
Agent uses its own execute_command instead of UniversalExecutor
Agent does its own summarization

What works: Fastest ⚡ | No setup | Safety ❌ Retry ❌ Memory ❌ (script features unused).

Core Components

`scripts/universal_agent.py` — Main Program

Four core classes implementing the full agent:

Class	Role	Key Methods
`LLMBrain`	Brain — HTTP LLM interface (Mode 1)	`think()`, `generate_script()`, `summarize()`, `debug_and_fix()`
`AgentBridge`	Brain — External Agent bridge (Mode 2)	`think()`, `generate_script()`, `summarize()`, `debug_and_fix()`, `set_response()`
`UniversalExecutor`	Limbs (command execution)	`execute()`, `_execute_command()`, `_execute_script()`, `_check_danger()`
`ContextManager`	Memory (state management)	`add_task_record()`, `get_context_string()`, `save()/load()`
`UniversalAgent`	Main orchestrator	`run()`, `chat()`, `batch_run()`

See references/README.md for full API documentation and examples.

Safety Mechanisms

The executor includes built-in danger detection:

Level	Examples	Handling
🔴 High	`rm -rf /`, `format C:`	Forced confirmation required
🟡 Medium	`pip uninstall`, `sudo`	Warning prompt
🟢 Low	`ls`, `cat`, `python script.py`	Direct execution

Danger patterns are defined in HIGH_DANGER_PATTERNS and MEDIUM_DANGER_PATTERNS within the script.

Configuration

Mode 1 (Standalone) — Needs API Key

Option A — Config File: Edit scripts/config.json and fill in your API key.

Option B — Environment Variables:

set LLM_API_KEY=your-key-here
set LLM_MODEL=gpt-4o
set LLM_BASE_URL=https://api.openai.com/v1

Option C — Local Ollama (Free):

ollama run llama3
# Then select ollama_llama3 preset when starting the script

Configuration priority: Environment variables > config.json > Interactive input.

Mode 2 (Bridge) — No API Key Needed

The external Agent provides all LLM capabilities. Configure only optional settings:

# Optional: change input source from env to file
set UA_INPUT_SOURCE=file

# Optional: skip safety confirmations (not recommended)
# Use --dangerous flag instead

Mode 3 (Simulation) — No Configuration Needed

Agent uses its own native capabilities. Nothing to configure.

Supported LLM Providers

Provider	Models	base_url
OpenAI	gpt-4o, gpt-4o-mini	https://api.openai.com/v1
DeepSeek	deepseek-chat, deepseek-reasoner	https://api.deepseek.com
Qwen	qwen-max, qwen-turbo	https://dashscope.aliyuncs.com/compatible-mode/v1
Zhipu GLM	glm-4-plus	https://open.bigmodel.cn/api/paas/v4
Local Ollama	llama3, qwen2, any model	http://localhost:11434/v1
Groq	llama-3.1-70b-versatile	https://api.groq.com/openai/v1
Any OpenAI-compatible API	any	your-url

Platform Support

✅ Cross-platform — Windows, macOS, Linux:

OS	Shell Backend
Windows	`cmd.exe /c` (with `CREATE_NO_WINDOW`)
macOS	`bash` (`shell=True`)
Linux	`bash` (`shell=True`)

All file I/O uses UTF-8 encoding. Python script execution uses sys.executable for platform-agnostic invocation.

Dependencies

✅ Zero external dependencies — Python standard library only:

os, sys — System operations
subprocess — Command execution
json, re — JSON parsing and regex
time/datetime — Time handling
urllib — HTTP requests (fallback)

Optional:

requests library — Better HTTP support (pip install requests)

Free Options

Ollama + local model (completely free, unlimited, private)
DeepSeek (~¥1/million tokens, excellent cost-performance)
Groq Cloud (free tier available, ultra-fast inference)