# template-agent

**Repository Path**: ihezebin/template-agent

## Basic Information

- **Project Name**: template-agent
- **Description**: eino agent 模板项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-02
- **Last Updated**: 2026-08-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Template Agent

一套可直接拷贝的 **前后端 Agent 脚手架**：用「查天气」这个最小业务，演示如何把大模型 + 工具调用接到 Web 聊天里。

你可以用它：

1. 快速跑通「前端聊天 → 后端 Agent → 调外部 API」整条链路  
2. 换成自己的工具与提示词，做成新的 Agent 产品  

示例业务只有一个工具：`get_weather`（[高德天气 API](https://lbs.amap.com/api/webservice/guide/api/weatherinfo)）。

技术栈简述：

| 端 | 技术 |
|---|---|
| 前端 | React + Vite + Ant Design + Zustand |
| 后端 | Go，分层参考 [go-template-ddd](https://gitee.com/hezebin-go/go-template-ddd)；HTTP / 日志 / 配置复用 [olympus](https://github.com/ihezebin/olympus)；Agent 用 [Eino](https://github.com/cloudwego/eino) `ChatModelAgent` |

---

## 5 分钟上手

**依赖**：Go 1.24+、Node 22+（Mongo 可选）

1. 编辑 `template-agent-server/config/config.toml`，填入：
   - `[model]`：任意 OpenAI 兼容的 `base_url` / `api_key` / `model`
   - `[amap].api_key`：高德「Web 服务」Key（[申请地址](https://console.amap.com/dev/key/app)）
2. 启动后端：

```bash
cd template-agent-server
go run . -c ./config/config.toml
```

3. 另开终端启动前端：

```bash
cd template-agent-web
npm install
npm run dev
```

4. 打开 http://localhost:5173 → **新建会话** → 发送「杭州今天天气怎么样」。

也可用本目录 Makefile：`make dev-server` / `make dev-web`。Docker 见 [DEPLOY.md](./DEPLOY.md)。

---

## 目录结构

```text
template-agent/
├── template-agent-web/      # 聊天 UI（侧栏会话列表 + 设置）
├── template-agent-server/   # Agent API（DDD 分层）
├── docker-compose.yml
├── Makefile
├── DEPLOY.md
└── README.md
```

### 后端分层（读代码时按这个找）

```text
template-agent-server/
├── main.go / cmd/           # 进程入口：读配置 → 初始化 → 起 HTTP
├── config/                  # TOML 配置结构
├── server/                  # 路由与中间件（SSE 写在这里）
├── application/             # 用例编排：会话、聊天、落库
├── domain/                  # 实体、仓储接口、领域服务入口
└── component/
    ├── agent/               # Eino Agent + 天气工具（改行为主要看这里）
    ├── hub/                 # 按会话广播进度事件（给 SSE 用）
    └── storage/             # Mongo 连接（可选）
```

| 想改什么 | 先看哪个文件 |
|---|---|
| Agent 人设 / 何时调工具 | `component/agent/runner.go` 里的 Instruction |
| 增加或修改工具 | `component/agent/tools.go` |
| 聊天业务（落库、历史） | `application/service/chat.go` |
| HTTP 接口 | `server/router/chat.go` |
| 进度如何推给前端 | `component/hub/hub.go` + router 里的 SSE |
| 模型 / 高德 Key | `config/config.toml` |

### 前端

- 左侧：会话列表、新建会话、系统设置（当前仅「Agent 部署」说明页）
- 右侧：欢迎页 / 聊天 / 部署说明
- 开发时 Vite 把 `/api` 代理到 `8080`；生产用 nginx 反代（关闭缓冲以支持 SSE）

---

## Agent 怎么跑起来的

一次用户提问大致是：

```text
用户消息
  → 大模型（带系统 Instruction + 工具定义）
  → 若回复含 tool_calls：执行 get_weather → 把结果塞回对话 → 再调模型
  → 若没有 tool_calls：用自然语言回答用户 → 本轮结束
MaxIterations：防止模型一直调工具不收尾（默认 20）
```

实现入口：`template-agent-server/component/agent/runner.go`。

前端「查询过程」面板的数据来自 SSE 事件（`progress` / `tool` / `token` / `done` / `error`）。  
`POST .../chat` 会边跑边推；`GET .../events` 用于刷新页面后旁路订阅。事件缓冲与广播由 **Hub** 负责，详见该文件头部注释。

---

## 配置说明

`template-agent-server/config/config.toml`：

```toml
[model]
base_url = "https://api.openai.com/v1"
api_key = "sk-..."
model = "gpt-4o-mini"

[amap]
api_key = "你的高德 Web 服务 Key"
base_url = "https://restapi.amap.com"

# 留空 = 会话/消息存在内存（重启清空，适合本地试用）
# 填写 = 使用 Mongo 持久化
mongo_dsn = ""
```

Docker 使用 `config/config.docker.toml`，部署前同样需要填入密钥。

---

## 基于本模板做新产品

1. **换工具**：在 `tools.go` 用 `utils.InferTool` 注册新函数，并改掉 Instruction。  
2. **改产品文案 / 布局**：前端 `App.tsx`、`ChatPanel.tsx`、`Sidebar.tsx`；样式在 `styles.css`。  
3. **加业务实体**：按 DDD 增加 `domain/entity` → `repository` → `application/service` → `server/router`。  
4. **多会话已内置**：侧栏会话列表对应后端 `/api/sessions`；一般无需从零设计会话模型。

---

## API 一览

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/health` | 健康检查（olympus 内置） |
| GET/POST | `/api/sessions` | 列出会话 / 新建会话 |
| PATCH/DELETE | `/api/sessions/:id` | 改标题或固定 / 删除 |
| GET/DELETE | `/api/sessions/:id/messages` | 消息列表 / 清空消息 |
| POST | `/api/sessions/:id/chat` | 发起对话（SSE） |
| GET | `/api/sessions/:id/events` | 订阅进度（SSE） |