自定义工具指南

TrueAGT允许你把自己的 HTTP 接口 或 Python 脚本 变成 Agent 可以直接调用的工具,无需改代码、重启服务,在「设置 → 自定义工具」里点几下即可完成。

适用于:想让 Agent 接入你私有的内部系统、第三方 API、或一段固定计算逻辑,而不想等官方内置支持的场景。

两种工具类型

类型适合做什么怎么跑参数怎么传
HTTP / API调用任意外部 REST 接口(汇率、天气、内部工单系统…)服务端用 urllib 发请求拼进 URL / 请求体模板的 {参数名} 占位符
Python 脚本一段固定计算、数据转换、调用本地库服务端起子进程跑 python -c(与内置「代码解释器」同一模型)从标准输入读 JSON:args = json.loads(sys.stdin.read() or '{}')

权限模型(个人 / 全局)

身份判定基于登录账号。未开启鉴权(纯本地/演示)时,所有工具都是「个人」、且只有一位使用者。

配置示例

示例 1:HTTP 工具(查汇率)

假设有一个公开的汇率接口 https://api.exchangerate.host/convert?from=USD&to=CNY&amount=1。

  {
    "type": "object",
    "properties": {
      "amount": {"type": "number", "description": "美元金额"}
    },
    "required": ["amount"]
  }

保存后在对话里说「帮我查 100 美元是多少人民币」,模型就会调用这个工具。

示例 2:Python 工具(格式化一段文本)

  {"type":"object","properties":{"text":{"type":"string","description":"原始文本"}},"required":["text"]}
  import sys, json, re
  args = json.loads(sys.stdin.read() or "{}")
  text = args.get("text", "")
  out = "\n".join(line for line in text.splitlines() if line.strip())
  print(out)

模型调用时,会把 {"text": "..."} 以 JSON 形式写到脚本的标准输入,脚本 print 的内容就是工具返回给模型的结果。

管理操作

安全提示(务必阅读)

  1. HTTP 工具默认有 SSRF 防护:目标主机解析到私网/回环/链路本地/保留地址时会被拦截,防止你的TrueAGT实例被当成跳板打内网。需要调用内网服务时,由管理员在 config.json 的 server.custom_tools_allow_private: true 放开(仅在可信内网环境)。
  2. Python 工具不是沙箱:它与内置「代码解释器」一样,以服务端进程身份运行,能访问本机文件系统与网络。请不要在其中硬编码密码/密钥等敏感信息(应走请求头或环境变量);也不要让不可信的人获得管理员或你的账号。
  3. 公开部署前:自定义工具随账号体系一起受鉴权保护;但凡是「能执行代码/发请求」的能力,对外服务时都请评估最小权限,并只把必要的工具开放给必要的人。
  4. 删除/停用要及时:不再需要的工具请停用或删除,避免工具集膨胀、行为不可预期。

数据存放

工具定义保存在 <data_dir>/custom_tools.json(默认 data/custom_tools.json),与对话数据同目录、随该目录迁移/备份。

本文档随 TrueAGT 安装包一同发布;如与软件实际行为不一致,以软件当前版本为准。