goagent is a Go implementation of the AgentLoom-style multi-agent framework. It provides a lightweight CLI and embeddable Go API for running YAML-defined agents with OpenAI-compatible LLM backends, built-in tools, worker agents, CodeAct execution, checkpoint resume, MCP/LSP integrations, a Web UI, sandbox execution, and optional Langfuse tracing.
goagent 是一个 AgentLoom 风格多 Agent 框架的 Go 实现。它提供轻量 CLI 与可嵌入 Go API,用 YAML 定义 Agent,并支持 OpenAI 兼容 LLM 后端、内置工具、Worker 子 Agent、CodeAct 执行、checkpoint 断点恢复、MCP/LSP 集成、Web UI、沙箱执行以及可选 Langfuse 追踪。
- YAML 驱动 Agent:通过
applications/<app>/workflows/*.yaml定义 Agent 名称、任务描述、模型类型、工作流和工具。 - OpenAI 兼容 LLM:支持火山方舟 ARK、OpenAI 或其他兼容 Chat Completions API 的服务。
- Tool Calling Agent:支持模型原生 tool calls,也支持从文本中解析 JSON/XML/正则形式的工具调用。
- CodeAct Agent:让模型编写并执行
python、golang或bash代码块来完成任务。 - Worker-as-Tool:Supervisor Agent 可以把 Worker Agent 当成工具调用,并支持批量并发调度。
- 内置工具:文件读写、目录浏览、grep/glob 搜索、shell、编辑文件、网页搜索、repo map、LSP 代码跳转等。
- Skills:支持
SKILL.md+ YAML frontmatter,包含强制注入、按需加载、隐藏三种模式。 - MCP:读取
.mcp.json,通过 stdio JSON-RPC 连接 MCP server,并把 MCP tools 暴露给 Agent。 - LSP:通过语言服务器提供定义跳转、引用查找、文档符号等代码智能能力。
- Checkpoint:任务运行状态持久化,可列出和恢复中断任务。
- Web UI:基于 HTTP + SSE 实时展示 Agent 运行事件。
- Docker 沙箱:可把 shell 工具放入 Docker 容器中执行。
- Langfuse 追踪:通过环境变量启用 HTTP ingestion 上报。
- Go 1.25+
- 可访问的 OpenAI 兼容 Chat Completions API
- 可选:Docker(使用沙箱执行时需要)
- 可选:语言服务器(使用 LSP 工具时需要,例如
gopls) - 可选:Node/Python/其他运行时(MCP server 或 CodeAct 代码执行可能需要)
在仓库根目录执行:
go mod tidy
go build ./cmd/loom构建后会在当前目录生成 loom 可执行文件。你也可以直接用 go run:
go run ./cmd/loom --help如果希望全局使用:
go install ./cmd/loom复制示例配置:
cp config/llm.example.yaml config/llm.yaml编辑 config/llm.yaml:
model:
default_model_type: powerful
powerful:
base_url: "https://ark.cn-beijing.volces.com/api/v3"
api_key: "你的 ARK API Key"
model: "你的方舟 endpoint 或模型名"
temperature: 0.2
max_tokens: 8000
timeout: 300
num_retries: 3
supports_native_tool_calls: "auto"
fast:
base_url: "https://ark.cn-beijing.volces.com/api/v3"
api_key: "你的 ARK API Key"
model: "你的方舟 endpoint 或模型名"
temperature: 0.3
max_tokens: 4000
timeout: 120
num_retries: 3
supports_native_tool_calls: "auto"说明:
base_url是 OpenAI 兼容接口地址,结尾不要包含/chat/completions。api_key建议只放在本地config/llm.yaml,不要提交到 Git。model_type会在 Agent YAML 中引用,例如model_type: "powerful"。supports_native_tool_calls可选值:auto:自动探测模型是否支持原生 tool calls。true:强制使用原生 tool calls。false:不使用原生 tool calls,改用文本解析工具调用。
也可以用 OpenAI 或其他兼容服务:
powerful:
base_url: "https://api.openai.com/v1"
api_key: "sk-..."
model: "openai/gpt-4o"go run ./cmd/loom --help
# 或构建后
./loom --helpgo run ./cmd/loom run applications/demo/workflows/demo_agent.yaml覆盖 YAML 中的默认任务描述:
go run ./cmd/loom run applications/demo/workflows/demo_agent.yaml --task "列出 internal 目录,并总结核心模块"记录运行日志到 .logs/<agent>/<timestamp>/run.log:
go run ./cmd/loom run applications/demo/workflows/demo_agent.yaml --log-to-file运行时同时启动 Web UI:
go run ./cmd/loom run applications/demo/workflows/demo_agent.yaml --ui 8080然后打开:
http://localhost:8080
Web UI 是面向新手的操作界面,包含四个页签:
和模型对话:直接和config/llm.yaml中配置的模型聊天,不需要写命令。执行 Applications:自动列出applications/**/workflows/*.yaml,选择应用、填写任务并运行;支持同时创建多个执行,每次执行都有独立的历史结果。实时事件:通过 SSE 实时展示 Agent step、tool_call、tool_result、final_answer 等事件。本地日志:查看.logs/<agent>/<timestamp>/run.log。该页签需要运行 Agent 时加--log-to-file才会有归档日志。
go run ./cmd/loom run applications/demo/workflows/supervisor_agent.yaml --task "分析这个项目的目录结构和关键模块"supervisor_agent.yaml 会把 worker_agents 中声明的 Worker 包装为工具,Supervisor 可以直接调用子 Agent 完成局部任务。
go run ./cmd/loom run applications/demo/workflows/codeact_agent.yaml --task "用 Go 或 Python 计算 1 到 100 的平方和"CodeAct 模式会要求模型输出代码块并执行,支持:
```python
print("hello")
package main
func main() {}ls -la
#### 生成独立 Go 入口
```bash
go run ./cmd/loom create applications/demo/workflows/demo_agent.yaml
默认生成到:
applications/demo/workflows/demo_agent_app/main.go
指定输出路径:
go run ./cmd/loom create applications/demo/workflows/demo_agent.yaml -o ./demo_app/main.go运行生成的入口:
go run ./demo_app/main.go "检查 README 和 config 目录"列出可恢复任务:
go run ./cmd/loom list-tasks恢复指定任务:
go run ./cmd/loom run applications/demo/workflows/demo_agent.yaml --resume task_xxx清理 7 天前的 checkpoint:
go run ./cmd/loom clean-tasks清理所有 checkpoint:
go run ./cmd/loom clean-tasks --allgo run ./cmd/loom ui --port 8080打开 http://localhost:8080 后,新手可以直接:
- 在
和模型对话页签输入问题并发送。 - 在
执行 Applications页签选择一个应用,填写任务并点击运行;可以连续创建多个执行,结果会在历史列表中隔离展示。 - 切到
实时事件查看 Agent 执行过程。 - 切到
本地日志查看已经归档到.logs的历史日志。
注意:单独启动 UI 时,实时事件只会显示当前 UI 进程内的历史/新增事件;如果想边运行边看事件,可以用 loom run ... --ui 8080。
最小示例:
name: "my_agent"
description: |
请检查当前项目并总结核心文件。
model_type: "powerful"
tool_call_type: "tool_call"
workflow: |
1. 使用 browse_directory 查看目录。
2. 使用 read_file 阅读关键文件。
3. 用 final_answer 给出总结。
tools:
- name: "browse_directory"
- name: "read_file"
- name: "grep_search"
worker_agents: []常用字段:
| 字段 | 说明 |
|---|---|
name |
Agent 名称,必填 |
description |
默认任务描述,必填;--task 可覆盖 |
model_type |
对应 config/llm.yaml 中的模型类型 |
tool_call_type |
tool_call 或 code_act |
workflow |
注入给 Agent 的执行流程说明,必填 |
tools |
启用的工具列表 |
worker_agents |
子 Agent YAML 路径列表 |
skills |
Skill 目录列表 |
execution_env |
执行环境配置,支持 local 或 docker |
在 Agent YAML 的 tools 中声明即可启用:
| 工具名 | 用途 |
|---|---|
read_file |
读取文件内容 |
write_file |
写入文件 |
browse_directory |
浏览目录 |
get_file_outline |
获取文件概要/预览 |
shell_tool |
执行 shell 命令,受安全策略限制 |
grep_search |
正则搜索文件内容 |
glob_search |
按 glob 查找文件 |
edit_file |
对文件做局部编辑 |
web_search |
调用兼容 LLM 侧能力的网页搜索工具 |
repo_map |
生成仓库符号地图 |
lsp_find_definition |
LSP 定义跳转 |
lsp_find_references |
LSP 引用查找 |
lsp_get_document_symbols |
LSP 文档符号 |
Supervisor YAML:
worker_agents:
- path: "applications/demo/workflows/worker_agents/file_reader_worker.yaml"框架会读取 Worker YAML,并把 Worker Agent 包装成 Supervisor 可调用的工具。适合拆分复杂任务,例如:
- Supervisor 负责规划、分派和最终汇总。
- Worker 负责读取单个文件、分析单个模块或执行局部检查。
Agent YAML 中声明:
skills:
- path: "applications/demo/skills"
platform: "Claude"Skill 目录结构:
applications/demo/skills/
my_skill/
SKILL.md
SKILL.md 示例:
---
name: my_skill
description: 项目分析指南
version: 0.1.0
invocation-control:
allow-model: force-inject
---
当你分析项目时,请先阅读 README,再检查配置文件和入口文件。allow-model 支持:
force-inject:启动时强制注入系统提示词。true:Agent 可通过list_skills/load_skill按需加载。false:对模型隐藏。
在项目根目录创建 .mcp.json:
{
"mcpServers": {
"demo": {
"command": "python3",
"args": ["./scripts/fake_mcp_server.py"],
"env": {}
}
}
}config/system.yaml 可通过 mcp_servers 指定配置文件路径;默认逻辑兼容 Claude Code 风格 .mcp.json。MCP server 通过 stdio JSON-RPC 暴露的工具会被注册进 Agent 工具集合。
启用 LSP 工具:
tools:
- name: "lsp_find_definition"
- name: "lsp_find_references"
- name: "lsp_get_document_symbols"使用前请确保对应语言服务器可用。例如 Go 项目:
go install golang.org/x/tools/gopls@latestAgent YAML 可声明执行环境:
execution_env:
type: "docker"
image: "golang:1.21"
workdir: "/workspace"当 shell_tool 执行命令时,会通过 Docker CLI 在容器内运行。适合隔离高风险命令或为任务提供固定运行环境。
设置环境变量后自动启用:
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_HOST="https://cloud.langfuse.com" # 可选运行 Agent 时,框架会订阅事件总线,并将 trace/event 批量上报到 Langfuse ingestion API。
外部 Go 代码可以直接导入公开包:
package main
import (
"fmt"
"log"
"github.com/alanjchuang/goagent/pkg/loom"
)
func main() {
result, err := loom.RunApp("applications/demo/workflows/demo_agent.yaml", "总结 internal 目录")
if err != nil {
log.Fatal(err)
}
fmt.Println(result)
}cmd/loom/ CLI 入口
config/ system.yaml / llm.yaml
applications/demo/ 示例 workflows 和 skills
internal/agent/ Agent 主循环、Worker、CodeAct、RunApp
internal/config/ 配置加载
internal/llm/ OpenAI 兼容 LLM 客户端
internal/tools/ 内置工具与安全策略
internal/mcp/ MCP stdio JSON-RPC 客户端
internal/lsp/ LSP JSON-RPC 客户端
internal/skills/ SKILL.md 加载和注入
internal/checkpoint/ checkpoint 持久化
internal/ui/ Web UI + SSE
internal/tracing/ Langfuse HTTP 上报
pkg/loom/ 对外公开 API
可以。CLI 已兼容以下写法:
go run ./cmd/loom run applications/demo/workflows/demo_agent.yaml --task "你的任务"这通常表示当前方舟账号或 endpoint 未开通对应插件能力,例如 web search。普通对话、文件工具、CodeAct 等仍可使用;如需 web_search,请在 ARK 控制台开通对应能力或从 Agent YAML 中移除该工具。
该文件通常包含真实 API Key。请只提交 config/llm.example.yaml,本地自行维护 config/llm.yaml。
- YAML-driven agents: Define agent name, task description, model type, workflow, tools, workers, skills, and execution environment in YAML.
- OpenAI-compatible LLM backend: Works with Volcengine ARK, OpenAI, and other Chat Completions compatible providers.
- Tool-calling agents: Supports native tool calls and fallback text parsing with JSON/XML/regex strategies.
- CodeAct agents: The model can write and execute
python,golang, orbashcode blocks. - Worker-as-Tool: Supervisor agents can call worker agents as tools, including batched concurrent execution.
- Built-in tools: File I/O, directory browsing, grep/glob search, shell execution, file editing, web search, repo map, and LSP tools.
- Skills: Load
SKILL.mdfiles with YAML frontmatter and support force-inject, on-demand, and hidden modes. - MCP integration: Reads
.mcp.json, connects to MCP servers over stdio JSON-RPC, and exposes MCP tools to agents. - LSP integration: Provides definition lookup, reference lookup, and document symbols via language servers.
- Checkpointing: Persist task state and resume interrupted runs.
- Web UI: HTTP + SSE dashboard for real-time agent events.
- Docker sandbox: Run shell commands inside Docker containers.
- Langfuse tracing: Optional HTTP ingestion tracing via environment variables.
- Go 1.25+
- An OpenAI-compatible Chat Completions API endpoint
- Optional: Docker for sandbox execution
- Optional: Language servers for LSP tools, such as
gopls - Optional: Node/Python/other runtimes for MCP servers or CodeAct execution
From the repository root:
go mod tidy
go build ./cmd/loomThis creates a loom binary in the current directory. You can also run it directly:
go run ./cmd/loom --helpInstall it globally:
go install ./cmd/loomCopy the example configuration:
cp config/llm.example.yaml config/llm.yamlEdit config/llm.yaml:
model:
default_model_type: powerful
powerful:
base_url: "https://ark.cn-beijing.volces.com/api/v3"
api_key: "your ARK API key"
model: "your ARK endpoint or model name"
temperature: 0.2
max_tokens: 8000
timeout: 300
num_retries: 3
supports_native_tool_calls: "auto"
fast:
base_url: "https://ark.cn-beijing.volces.com/api/v3"
api_key: "your ARK API key"
model: "your ARK endpoint or model name"
temperature: 0.3
max_tokens: 4000
timeout: 120
num_retries: 3
supports_native_tool_calls: "auto"Notes:
base_urlshould not include/chat/completions.- Keep real API keys only in local
config/llm.yaml; do not commit it. - Agent YAML files reference these model profiles via
model_type. supports_native_tool_callscan beauto,true, orfalse.
OpenAI-compatible example:
powerful:
base_url: "https://api.openai.com/v1"
api_key: "sk-..."
model: "openai/gpt-4o"go run ./cmd/loom --help
# or after building
./loom --helpgo run ./cmd/loom run applications/demo/workflows/demo_agent.yamlOverride the default task from YAML:
go run ./cmd/loom run applications/demo/workflows/demo_agent.yaml --task "List the internal directory and summarize the core modules"Write logs to .logs/<agent>/<timestamp>/run.log:
go run ./cmd/loom run applications/demo/workflows/demo_agent.yaml --log-to-fileStart the Web UI together with the run:
go run ./cmd/loom run applications/demo/workflows/demo_agent.yaml --ui 8080Open:
http://localhost:8080
The Web UI is beginner-friendly and has four tabs:
和模型对话/ chat with model: chat directly with the model configured inconfig/llm.yaml.执行 Applications/ run applications: listapplications/**/workflows/*.yaml, choose one, enter a task, and run it. Multiple runs can execute concurrently, and each run has an isolated history result.实时事件/ live events: real-time agent events such as step, tool_call, tool_result, and final_answer over SSE.本地日志/ local logs: archived.logs/<agent>/<timestamp>/run.logfiles. Run the agent with--log-to-fileto generate these files.
go run ./cmd/loom run applications/demo/workflows/supervisor_agent.yaml --task "Analyze this project's structure and key modules"The supervisor loads worker agents from worker_agents and exposes them as callable tools.
go run ./cmd/loom run applications/demo/workflows/codeact_agent.yaml --task "Use Go or Python to calculate the sum of squares from 1 to 100"CodeAct supports python, golang, and bash fenced code blocks.
go run ./cmd/loom create applications/demo/workflows/demo_agent.yamlDefault output:
applications/demo/workflows/demo_agent_app/main.go
Specify an output path:
go run ./cmd/loom create applications/demo/workflows/demo_agent.yaml -o ./demo_app/main.goRun the generated app:
go run ./demo_app/main.go "Inspect README and config"List resumable tasks:
go run ./cmd/loom list-tasksResume a task:
go run ./cmd/loom run applications/demo/workflows/demo_agent.yaml --resume task_xxxClean old checkpoints:
go run ./cmd/loom clean-tasksClean all checkpoints:
go run ./cmd/loom clean-tasks --allgo run ./cmd/loom ui --port 8080Open http://localhost:8080, then a beginner can:
- Ask questions in the
和模型对话tab. - Choose and run an application in the
执行 Applicationstab. You can create multiple runs, and results are isolated in the run history. - Inspect agent execution in the
实时事件tab. - Read archived logs from
.logsin the本地日志tab.
When started standalone, live events are limited to events in the current UI process. To watch events while running an agent, use loom run ... --ui 8080.
Minimal example:
name: "my_agent"
description: |
Inspect the current project and summarize core files.
model_type: "powerful"
tool_call_type: "tool_call"
workflow: |
1. Use browse_directory to inspect the directory.
2. Use read_file to read key files.
3. Return the summary with final_answer.
tools:
- name: "browse_directory"
- name: "read_file"
- name: "grep_search"
worker_agents: []Common fields:
| Field | Description |
|---|---|
name |
Required agent name |
description |
Required default task; can be overridden by --task |
model_type |
Model profile in config/llm.yaml |
tool_call_type |
tool_call or code_act |
workflow |
Required workflow instructions |
tools |
Enabled tool list |
worker_agents |
Worker agent YAML paths |
skills |
Skill directory paths |
execution_env |
Execution environment: local or docker |
Enable tools in YAML with tools:
| Tool | Purpose |
|---|---|
read_file |
Read files |
write_file |
Write files |
browse_directory |
Browse directories |
get_file_outline |
Show file outline/preview |
shell_tool |
Run shell commands with safety checks |
grep_search |
Search file contents with regex |
glob_search |
Find files with glob patterns |
edit_file |
Patch files locally |
web_search |
Use provider-side web search capability |
repo_map |
Generate a repository symbol map |
lsp_find_definition |
Find definitions via LSP |
lsp_find_references |
Find references via LSP |
lsp_get_document_symbols |
Get document symbols via LSP |
Supervisor YAML:
worker_agents:
- path: "applications/demo/workflows/worker_agents/file_reader_worker.yaml"The framework loads each worker YAML and wraps the worker agent as a callable tool. This is useful for complex task decomposition:
- The supervisor plans, dispatches, and aggregates results.
- Workers inspect individual files, modules, or subtasks.
Declare skill directories in agent YAML:
skills:
- path: "applications/demo/skills"
platform: "Claude"Directory layout:
applications/demo/skills/
my_skill/
SKILL.md
SKILL.md example:
---
name: my_skill
description: Project analysis guide
version: 0.1.0
invocation-control:
allow-model: force-inject
---
When analyzing a project, read README first, then inspect config and entrypoint files.allow-model values:
force-inject: inject content into the system prompt at startup.true: visible to the agent and loadable on demand.false: hidden from the model.
Create .mcp.json in the repository root:
{
"mcpServers": {
"demo": {
"command": "python3",
"args": ["./scripts/fake_mcp_server.py"],
"env": {}
}
}
}The framework reads MCP server definitions, connects over stdio JSON-RPC, lists tools, and registers them as agent tools.
Enable LSP tools:
tools:
- name: "lsp_find_definition"
- name: "lsp_find_references"
- name: "lsp_get_document_symbols"Install a language server first. For Go:
go install golang.org/x/tools/gopls@latestAgent YAML can declare a Docker execution environment:
execution_env:
type: "docker"
image: "golang:1.21"
workdir: "/workspace"When shell_tool runs commands, the framework executes them through Docker CLI inside the configured container image.
Set environment variables to enable tracing:
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_HOST="https://cloud.langfuse.com" # optionalDuring agent runs, goagent subscribes to the internal event bus and sends trace/event batches to the Langfuse ingestion API.
Use the public package:
package main
import (
"fmt"
"log"
"github.com/alanjchuang/goagent/pkg/loom"
)
func main() {
result, err := loom.RunApp("applications/demo/workflows/demo_agent.yaml", "Summarize the internal directory")
if err != nil {
log.Fatal(err)
}
fmt.Println(result)
}cmd/loom/ CLI entrypoint
config/ system.yaml / llm.yaml
applications/demo/ example workflows and skills
internal/agent/ agent loop, workers, CodeAct, RunApp
internal/config/ configuration loading
internal/llm/ OpenAI-compatible LLM client
internal/tools/ built-in tools and security policy
internal/mcp/ MCP stdio JSON-RPC client
internal/lsp/ LSP JSON-RPC client
internal/skills/ SKILL.md loading and injection
internal/checkpoint/ checkpoint persistence
internal/ui/ Web UI + SSE
internal/tracing/ Langfuse HTTP ingestion
pkg/loom/ public API
Yes:
go run ./cmd/loom run applications/demo/workflows/demo_agent.yaml --task "your task"It usually means the ARK account or endpoint has not enabled the requested provider-side tool capability, such as web search. Regular chat, file tools, and CodeAct still work. Enable the capability in ARK or remove web_search from the agent YAML.
It usually contains real API keys. Commit config/llm.example.yaml only and keep config/llm.yaml local.