Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions .github/workflows/cli.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
name: cli CI

on:
push:
branches: ["main"]
pull_request:
branches: ["main"]

defaults:
run:
working-directory: data-agent-cli

jobs:
lint:
name: Lint & Format Check
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
cache-dependency-path: data-agent-cli/package-lock.json
- run: npm ci
- run: npm run lint:check
- run: npm run format:check

build:
name: Build & Test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
cache-dependency-path: data-agent-cli/package-lock.json
- run: npm ci
- run: npm run build
- run: npm test
25 changes: 25 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
- **资产与数据证据**:内置报表、CSV 导出与数据证据视图,记录回答涉及的 SQL、指标、Python 执行及表列来源。
- **Skill 系统**:从文件系统 / Git / Nacos 多源加载可复用的查询流程("已验证查询模式")。
- **MCP 配置管理(开发中)**:提供外部 MCP Server 的配置增删改查与启停状态管理;当前尚未将外部 MCP 工具接入 Agent 工具箱。
- **外部 Agent 接入**:可直接通过 npm 安装 `data-agent-cli`,并提供可直接复制到 Claude Code、Codex、Cursor、OpenCode 等 Skill 目录的 `data-agent-skill/`。
- **可观测性(OpenTelemetry)**:HTTP、Agent、LLM、工具与 JDBC 调用统一走 OTel trace;标准 OTLP 导出,可接入任意 OTel 后端(Jaeger / Tempo / SigNoz / Langfuse 等),仓库自带 Grafana LGTM 本地示例。

## 💡 核心设计亮点
Expand Down Expand Up @@ -77,6 +78,30 @@ Data Agent 反其道而行——**不引入任何向量检索**。语义层把

详见 [docs/observability.md](docs/observability.md)。

## 🤖 外部 Agent 接入

Data Agent 支持面向外部 Agent 的只读接入:

- 用户在「API 访问令牌」页面(`/settings/tokens`)创建 PAT
- 通过 `/agent/health`、`/agent/tools`、`/agent/tools/{name}` 调用只读工具
- 使用 `data-agent-cli` 完成登录、工具发现和工具调用
- 将 `data-agent-skill/` 复制到外部 Agent 的 Skill 存储目录,即可安装问数 Skill

```bash
npm install -g @malone-talk/data-agent-cli
data-agent-cli auth login --token pat_xxx
data-agent-cli tools list
data-agent-cli skill
```

外部 Agent 可按自身约定复制 Skill:

```bash
cp -R data-agent-skill <your-agent-skill-directory>/
```

当前对外暴露 `get_datasources`、`get_domains`、`get_tables`、`get_table_schema`、`get_metric_caliber` 和 `execute_sql`,`execute_sql` 只允许 SELECT。完整说明见 [docs/external-agent.md](docs/external-agent.md)。

## 🚀 快速开始

> Docker 与手动搭建步骤见 [docs/getting-started.md](docs/getting-started.md)。以下命令使用 Bash;Windows PowerShell 的环境变量写法见该文档。
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
import io.github.malonetalk.agent.models.ModelProperties;
import io.github.malonetalk.agent.provenance.AnswerProvenanceService;
import io.github.malonetalk.agent.skill.SkillLoaderService;
import io.github.malonetalk.agent.tools.MarkAgentTool;
import io.github.malonetalk.agent.tools.DataAgentTool;
import io.github.malonetalk.agent.tools.ToolCallConstants;
import io.github.malonetalk.convertor.EventConverter;
import io.github.malonetalk.dto.ChatRequest;
Expand Down Expand Up @@ -77,7 +77,7 @@ public class AgentService {
private static final ZoneId DEFAULT_ZONE = ZoneId.of("Asia/Shanghai");

private final ModelFactory modelFactory;
private final List<MarkAgentTool> allToolBeans;
private final List<DataAgentTool> allToolBeans;
private final ModelProperties modelProperties;
private final SessionService sessionService;
private final SessionDatasourceService sessionDatasourceService;
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
/*
* Copyright (C) 2026 github.com/MaloneTalk
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
* published by the Free Software Foundation, either version 3 of the
* License, or any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
* limitations under the License.
*/
package io.github.malonetalk.agent;

import io.github.malonetalk.agent.tools.AgentToolInvoker;
import io.github.malonetalk.exception.BusinessException;
import io.github.malonetalk.exception.ErrorCode;
import io.github.malonetalk.interceptor.AgentAuthInterceptor;
import io.github.malonetalk.model.bo.ToolResultBo;
import io.github.malonetalk.model.bo.UserPatBo;
import io.github.malonetalk.model.converter.UserPatConverter;
import io.github.malonetalk.model.holder.UserContextHolder;
import io.github.malonetalk.model.vo.AgentToolVo;
import io.github.malonetalk.model.vo.ListVo;
import io.github.malonetalk.model.vo.ToolResultVo;
import io.github.malonetalk.model.vo.UserPatVo;
import io.github.malonetalk.service.DataPermissionService;
import io.micrometer.tracing.Tracer;
import jakarta.servlet.http.HttpServletRequest;
import java.util.Map;
import java.util.Optional;
import lombok.AllArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@AllArgsConstructor
@Slf4j
@RequestMapping("/agent")
public class AgentToolController {

private static final String SESSION_ID_HEADER = "X-Session-Id";
private static final String CLIENT_AGENT_CODE = "CLIENT";
private static final String DEFAULT_SESSION = "__default__";

private final AgentToolInvoker invoker;
private final DataPermissionService dataPermissions;
private final UserContextHolder userContextHolder;
private final UserPatConverter userPatConverter;
private final Tracer tracer;

@GetMapping("/health")
public UserPatVo health(HttpServletRequest request) {
UserPatBo pat =
Optional.ofNullable(
(UserPatBo)
request.getAttribute(
AgentAuthInterceptor.AUTHENTICATED_PAT_ATTRIBUTE))
.orElseThrow(() -> BusinessException.of(ErrorCode.UNAUTHORIZED));
return userPatConverter.toVo(pat);
}

@GetMapping("/tools")
public ListVo<AgentToolVo> listTools() {
return new ListVo<>(
invoker.list().stream()
.map(
tool ->
new AgentToolVo(
tool.name(), tool.description(), tool.parameters()))
.toList());
}

@PostMapping("/tools/{name}")
public ToolResultVo callTool(
@PathVariable String name,
@RequestBody(required = false) Map<String, Object> input,
HttpServletRequest request) {
var user = userContextHolder.checkAndGet();
Map<String, Object> params = input == null ? Map.of() : input;
String externalSessionId =
Optional.ofNullable(request.getHeader(SESSION_ID_HEADER))
.map(String::trim)
.orElse(DEFAULT_SESSION);
String sessionId =
SessionIdFactory.build(CLIENT_AGENT_CODE, user.userId(), externalSessionId);
ToolCallContext context =
ToolCallContext.builder()
.sessionId(sessionId)
.userId(user.userId())
.datasourceIds(
dataPermissions.accessibleDatasourceIds(user).stream()
.sorted()
.toList())
.build();

long startedAt = System.nanoTime();
ToolResultBo result = invoker.invoke(name, params, context);
long durationMs = (System.nanoTime() - startedAt) / 1_000_000;
String traceId = currentTraceId();
log.info(
"Agent tool call: tool={}, userId={}, sessionId={}, durationMs={}, traceId={}",
name,
user.userId(),
sessionId,
durationMs,
traceId);
return new ToolResultVo(result.text(), result.metadata(), traceId);
}

private String currentTraceId() {
var span = tracer.currentSpan();
return span == null ? null : span.context().traceId();
}
}
Loading
Loading