企业官网建设流程全解析

5分钟跑通 Unreal Agent：unreal-agent-runner 智能体 CLI 快速上手教程

【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agent

Unreal Agent 是 Unreal Labs 推出的异步优先（async-first）智能体框架，其中的命令行工具unreal-agent-runner让你只需一条命令，就能让 AI 智能体读取你本地的项目代码、执行 Bash 命令并输出结果。本教程带你 5 分钟内完成安装、配置与首次运行，零门槛跑通自己的第一个 AI 智能体任务。

它能为新手做什么？

unreal-agent-runner是一个开箱即用的智能体 CLI：

• 🚀一句话驱动：输入一段提示词（prompt），智能体即可自动阅读项目文件、调用工具、完成任务；
• 🔧内置工具：自带 Bash 执行、图片查看（ViewImage）和 skill 调用能力，由 工具注册表 统一挂载；
• 📝JSONL 事件流：运行过程中所有事件以 JSONL 格式写入标准输出，方便脚本化集成与回溯；
• 🧩多模型提供商：通过环境变量即可切换 OpenAI、Ollama 等，无需改代码（见 providers.go）。

环境准备与一键安装

方式一：Go 一行命令安装（推荐）

要求 Go 1.27+，一条命令完成：

go install github.com/unreallabsai/unreal-agent/cmd/unreal-agent-runner@latest

方式二：从源码直接运行

克隆仓库后在项目根目录执行，无需安装：

git clone https://gitcode.com/gh_mirrors/un/unreal-agent cd unreal-agent go run ./cmd/unreal-agent-runner -p 'Inspect this project and explain how to run its tests.'

最快配置方法：设置 API Key 并跑通首条提示词

以默认的 OpenAI 提供商为例，只需两步：

export OPENAI_API_KEY="你的密钥" unreal-agent-runner -p '检查这个项目，并说明如何运行它的测试。'

运行结束后，智能体在标准输出打印的 JSONL 事件流就是完整的任务记录。

切换其他模型提供商

设置两个环境变量即可，无需任何代码改动：

本地体验可配合 Ollama：UNREAL_HARNESS_LLM_PROVIDER=ollama即可接入本地模型，零 API 费用。

指定工作区并保存运行结果

-workspace参数决定智能体读取哪个目录、Bash 命令在哪个目录下执行（定义见 run.go）。将输出重定向到文件，就得到一份可复查的运行日志：

unreal-agent-runner -workspace ./my-project -p 'Summarize this project.' > run.jsonl

进阶：用 JSON 请求精细控制

除了-p提示词，还支持传入完整 JSON 请求（参数位置需放在选项之后），来源可以是命令行参数或 stdin：

unreal-agent-runner '{"prompt":"Summarize this project."}' unreal-agent-runner < request.json

常用字段一览（完整定义见 usage.go）：

• prompt/messages：任务描述，messages优先级更高；
• session_id：创建或恢复一个持久化会话，跨次运行保留上下文；
• system_prompt：替换默认系统提示词；
• thinking_level：low/medium/high/xhigh/max，控制思考深度；
• disallowed_tools：禁用指定工具（如禁止智能体执行 Bash）。

Docker 方式：免安装开箱即用

项目提供了官方镜像（构建逻辑见 Dockerfile，支持 Linux AMD64/ARM64），把当前目录挂载为/workspace即可：

docker run --rm -i --user "$(id -u):$(id -g)" \ -e OPENAI_API_KEY -v "$PWD:/workspace" \ unrea1labs/unreal-agent:latest -p 'Summarize this project.'

常见问题速查

更多细节可参考 runner 使用说明 与 框架整体设计文档。

小结

• 1 条命令安装：go install .../cmd/unreal-agent-runner@latest；
• 1 个环境变量：设置OPENAI_API_KEY；
• 1 条提示词：-p参数即可驱动智能体分析你的项目。

Unreal Agent 的核心价值在于"异步优先"的会话与操作模型——智能体的每一步工具调用都是可持久化、可恢复的操作（设计见 operation 组件）。对于想快速落地 AI 智能体能力的新手来说，unreal-agent-runner是最短路径的入门之选。

【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agent