Skip to content
BranchesTags

Repository files navigation

AgentGate

AgentGate 是一个与外部 Agent 解耦的 MCP 能力网关和策略/审批 Broker。Agent 只拿 AgentGate Access Key；Kubernetes、Elasticsearch、Prometheus 或其他目标系统凭据留在平台执行侧。

External Agent
  -> POST /mcp
  -> stable Operation Tool + profileRef
  -> PolicyService
  -> read execution | ActionPlan -> Web/Feishu approval -> write execution
  -> controlled target executor

AgentGate 不保存模型、会话、记忆、提示词或 Agent 工作流，也不要求外部调用方安装专用 SDK。支持 MCP 的 Agent 直接连接 /mcp；不支持 MCP 的 Host 可以使用自动生成的 Guide/OpenAPI 或仓库内的可选 Skill。

核心模型

Department
  -> API Consumer
       -> Access Key
       -> Capability Grant
            -> Execution Profile (Capability Instance)
                 -> immutable Definition Version
                 -> Target Profile -> deployment-side connectorRef
                 -> scope + approval policy
  • Operation 表示“能做什么”，按定义和版本稳定发布，例如 platform.elasticsearch.search.v1_0_0。
  • profileRef 表示“以哪份授权配置执行”，固定目标集群/数据源、环境、Scope、Grant 和审批策略。
  • 同一个 ES 查询定义即使绑定十个集群，MCP 仍只有一个 Tool，Agent 从目录或 Resources 中选择获授权的 Profile。
  • tools/list、MCP Resources、Runtime Guide、Catalog、OpenAPI 和真实执行都读取同一个 Key-scoped 目录与 PolicyService。

已实现

  • 官方 MCP TypeScript SDK v2，兼容 MCP 2026-07-28 和 2025-era Stateless Streamable HTTP 客户端。
  • 稳定 operation Tools、低基数 Catalog/Profile/Target Resources、分页 agentgate_catalog_search 与 agentgate_resources_search。
  • HMAC 签名游标，绑定 Access Key、目录版本、查询条件和有效期。
  • API Consumer、可轮换/撤销 Access Key、Capability Grant、多 Target Profile 和部门隔离。
  • Kubernetes、Prometheus、Elasticsearch、SSH 演示 Operation 和 demo:* 数据，以及可由外部 AI 声明的受控 HttpOperation；资源发现支持 parentRef 层级约束。
  • Python 3.11/3.12、Bash Base Runtime；Runtime 环境、不可变版本、uv wheel-only 构建、hash lock、SBOM、内容寻址 artifact、发布/弃用和引用统计。
  • Python、Shell、OCI Manifest；单文件或 ZIP 上传、Runtime Version 绑定、扫描、固定版本、权限子集评审、发布和沙箱 ABI。
  • 单机 Linux runnerd：API 只提交签名 invocation ID，runnerd 从只读 SQLite 恢复固定版本；rootless Docker/Podman 一次性执行、默认断网、只读挂载、非 root、cgroup/ulimit/output/timeout 限制和遗留容器清理。
  • 内网 Site Connector：同时支持资源侧主动回连的 Reverse，以及 AgentGate 主动连接统一网关的 Forward；使用 HMAC Token 或 Ed25519 单次 lease、CIDR/DNS 校验、连接/时长/流量上限，平台自动生成 Docker Run、Compose 和 Kubernetes YAML。受控 HTTP/ES/Prometheus/K8s API 可经站点隧道执行。
  • 大结果 Job/Artifact：能力调用先返回可轮询 Job，Runner 通过单文件 ABI 暂存结果，API 校验摘要后持久化；Agent 使用有界文本分块或带认证的 HTTP Range 下载，不把大文件塞进 MCP 上下文。
  • 写 ActionPlan、SHA-256 摘要、幂等、Web/飞书审批、Outbox、执行前完整重新授权和验证。
  • 飞书群聊/私聊投递、审批人 @、callback token、timestamp/nonce/signature、事件去重和身份映射。
  • 0.0.0.0 监听，并对 MCP 强制 Host/Origin 白名单以防 DNS rebinding。
  • 管理端：AI 委托授权、Consumer/Key、内网站点及部署内容、Target、能力/Grant、能力包、审批、Key-scoped 目录、MCP Console 和审计。
  • “AI 委托授权”由人员管理员创建受限 Automation Principal 和限时 agc_ Key，并生成带当前发现链接的 Skill 迁移提示词；明文 Key 一次性单独显示，不进入提示词。

当前仓库中的 demo:* 执行器只操作 SQLite 演示数据，不会访问真实生产系统，也不是要求平台后续逐个内置 Provider Connector 的路线图。生产能力默认由外部 AI 生成受控 HttpOperation；目标可由 API 直接访问，也可通过 Site Connector 访问内网。独立 Linux runnerd 继续执行无网络、无 Secret 的 Python/Shell 能力包。Site Tunnel 虽承载任意 TCP 字节，但当前真实接通的协议执行器是受控 HTTP；生产 SSH/数据库仍需要对应 typed adapter，不能把 demo SSH 描述为已可用。需要网络和 Secret 的任意非 HTTP 上传代码仍由认证 OCI 路线处理，当前 MVP 会拒绝其发布/执行。

本地运行

要求 Node.js 24+。本地构建 Python Runtime 还需要已安装的 uv 和对应 Python 版本；不使用上传能力时可不安装。

npm install
cp .env.example .env
# 编辑 .env，为 LOCAL_ADMIN_PASSWORD 设置唯一的长密码
npm run dev

默认监听：

API 和 Web 都绑定 0.0.0.0，局域网设备可用宿主机 IP 访问。MCP 开发环境自动允许本机接口地址；生产通过 MCP_ALLOWED_HOSTS 和 MCP_ALLOWED_ORIGINS 明确配置公开域名。

首次启动会把 LOCAL_ADMIN_USERNAME 和 LOCAL_ADMIN_PASSWORD 写成不可逆的本地账号密码验证记录；登录成功后浏览器使用服务端持久 Session。确认可以登录后，从 .env 删除 LOCAL_ADMIN_PASSWORD 并重启，已有账号不会被重置。

交给 AI 安装到 Linux

生产安装的 canonical 入口是 Linux Runner 部署手册。不要让部署 AI 仅根据 README 猜测安装步骤，也不要在生产机器上用 npm run dev 代替 API + 独立 runnerd 拓扑。

将下面这些文件一起提供给部署 AI：

部署 AI 必须先检测现有容器引擎，再决定安装路径：

主机现状 处理方式
当前部署用户可使用 rootless Docker 直接选择 Docker，不安装 Podman；使用默认 Docker Compose 完整拓扑，或宿主 systemd runnerd
当前部署用户可使用 rootless Podman 使用 Podman；使用独立 Podman Compose 拓扑，或宿主 systemd runnerd
只有普通 rootful Docker，或当前用户无 daemon 权限 不能把用户加入 docker 组后直接继续；安装 rootless Docker/Podman，或更换专用隔离 Runner 主机
两者都没有 按组织运维标准选择一种 rootless 引擎，并使用与该 Engine 匹配的 Compose 文件

容器化 API/Runtime 镜像已经携带所需 Python 和 uv，因此宿主 Python 3.10 而非 3.12、宿主未安装 uv，都不是容器化生产部署的阻塞项。只有直接在宿主运行 API 并启用 RUNTIME_BUILDER=local_uv 时，宿主才需要匹配的 Python 与 uv。

可以直接使用以下提示词：

请严格按照 docs/deploy/linux-runner.md 将 AgentGate 部署到这台 Linux 主机。
先读取该文档及其引用的 compose/env/Containerfile，不要自行简化安全拓扑。
先检测当前部署用户能否使用 rootless Docker 或 rootless Podman。已有可用的 rootless
Docker 时直接选择 CAPABILITY_CONTAINER_ENGINE=docker，不要额外安装 Podman。compose.yaml 与
compose.env.example 是完整 Docker Compose 路径；Podman 必须改用 compose.podman.yaml 与
compose.podman.env.example，不得混用两套 runnerd 镜像、socket 或 user namespace 配置。
普通 rootful Docker socket 或加入 docker 组不算通过安全 preflight。
部署前先执行 preflight，并向我报告缺失的主机条件和必须由我提供的域名、
本地管理员初始密码（或可信身份网关）、镜像仓库 digest、UID/GID 与可选飞书配置；遇到缺失输入时停下来询问我，
不要编造占位值。API 不得挂 Docker/Podman/containerd/CRI socket；API 与 runnerd
必须使用相同绝对 RUNTIME_RESULT_STAGING_PATH，持久 runtime-results 只挂给 API。
采用容器化 API/Runtime 时，不要把宿主 Python 3.12 或 uv 当作必需条件。
完成后执行健康检查、MCP 连接、真实 Python/Shell 单文件 Artifact、权限撤销、
Range/分块读取和受控写审批 smoke test，并输出脱敏的验收结果与回滚命令。

只有类型检查或单元测试通过不代表 Linux 执行环境已验收。部署 AI 必须在目标主机上完成文档中的 rootless Docker/Podman、cgroup v2、固定 digest 镜像和真实能力 smoke test，才能报告生产安装完成。

Agent 接入

给 Agent Host 配置两项运行时 Secret：

MCP URL: https://agentgate.example.com/mcp
Authorization: Bearer agk_<key-id>.<secret>

推荐流程：

tools/list + resources/list
  -> agentgate_catalog_search (目录很大时)
  -> agentgate_resources_search(profileRef, kind, query)
  -> <stable-operation-tool>(profileRef, arguments, _context)
       read -> succeeded | failed
       large read -> delivery: task -> agentgate_jobs_get
                  -> delivery: artifact -> agentgate_artifacts_read
       write -> awaiting_approval + request id + digest
  -> agentgate_requests_get(requestId)

例如 K8s 读取工具：

{
  "name": "platform.kubernetes.workload.get.v1_0_0",
  "arguments": {
    "profileRef": "profile:cap-k8s-get",
    "environment": "production",
    "namespace": "payments",
    "workload": "checkout-api",
    "_context": {
      "reason": "Inspect current workload health",
      "idempotencyKey": "incident-42-read-1"
    }
  }
}

Agent 不应永久缓存集群、namespace、索引或指标清单，也不能猜 profileRef。Grant 或 Target 被停用后，下一次发现和执行立即反映撤权。

API 分层

面 Canonical path 调用者
MCP runtime POST /mcp MCP Agent/Host
HTTP runtime /api/runtime/v1/* 不支持 MCP 的机器客户端
Control plane /api/control/v1/* 管理端和可信人员
Feishu webhook POST /hooks/feishu/events 飞书开放平台

Runtime 入口：

GET  /api/runtime/v1/identity
GET  /api/runtime/v1/catalog
POST /api/runtime/v1/catalog/search
POST /api/runtime/v1/resources/search
GET  /api/runtime/v1/guide.md
GET  /api/runtime/v1/openapi.json
POST /api/runtime/v1/invocations
GET  /api/runtime/v1/invocations/{request_id}
GET  /api/runtime/v1/jobs?limit=50
GET  /api/runtime/v1/jobs/{job_id}
POST /api/runtime/v1/jobs/{job_id}/cancel
GET  /api/runtime/v1/artifacts?limit=50
GET  /api/runtime/v1/artifacts/{artifact_id}
POST /api/runtime/v1/artifacts/{artifact_id}/read
GET  /api/runtime/v1/artifacts/{artifact_id}/content

所有目录和 Guide 响应都按当前 Access Key 动态生成，使用 Cache-Control: private, no-store，且不包含 Access Key、connectorRef 或目标凭据。项目不提供 /apis/* 或 /api/admin/* 迁移别名。

外部 AI Authoring

AgentGate 不内置 Skill 分析器或转换器。外部 AI 自己读取旧 Skill/脚本，完成能力拆分、JSON Schema、迁移编排以及受控 HTTP、Python、Shell 或 OCI 实现；它先从 /.well-known/agentgate、/api/control/v1/openapi.json、Schemas、Providers 和当前 export 获取实时标准，再生成 agentgate.dev/v1alpha1 Bundle 与所需能力包。默认路径是新建受控 HttpOperation 或能力包；只有实时 Catalog 中已有完全同义的 Operation 时才选择复用。

平台不可外包的职责是 Secret write-only 保管与注入、Schema/引用校验、Runtime 隔离、Policy/Scope/Grant、ChangePlan 与并发控制、生产写审批、审计，以及统一 MCP projection。控制面使用独立 agc_ Token；资源按 Bundle -> ChangePlan -> exact planDigest apply 写入，Credential 通过 write-only action 单独创建。应用配置后，为 Consumer 一次性签发独立 agk_，业务 Agent 再通过 /mcp 发现和调用被 Grant 的能力。控制面 AI 不能批准目标系统写操作。

管理员可以直接在管理台“AI 委托授权”完成两步操作：先选择 Scope 创建委托身份，再签发限时 agc_。结果页自动把当前部署的 /.well-known/agentgate 和 /api/control/v1/authoring.md 完整地址写入迁移提示词，用户只需补充“将 xxx Skill 迁移到此平台”等实际任务。Key 应通过 AGENTGATE_AUTHOR_KEY 或 AGENTGATE_AUTHOR_KEY_FILE 注入运行 AI 的环境，不能粘进提示词；迁移完成后应撤销或轮换。

当前受控 HTTP 执行器支持固定 endpoint、method/path template、输入/输出 Schema、响应上限、禁止重定向以及服务端 Credential Header 注入。普通 Python/Shell 仍默认断网且无 Secret，只能纯计算或生成 Broker plan；不要把 Manifest 中尚未可发布的 OCI/network/secrets 字段误解为当前已有的直通能力。

完整协议和多 ES/K8s 示例见 外部 AI Authoring 标准，可选薄客户端位于 skills/agentgate-author。

飞书审批

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx
FEISHU_CHAT_ID=oc_xxx
FEISHU_CALLBACK_TOKEN=xxx
FEISHU_ENCRYPT_KEY=xxx
FEISHU_NOTIFY_MODE=group_and_direct

回调地址：

https://agentgate.example.com/hooks/feishu/events

飞书只是交互入口，AgentGate 数据库是审批唯一事实源。批准绑定精确 ActionPlan digest；执行前再次检查 Key、Consumer、Grant、定义版本、Profile、目标、参数范围、审批策略和有效期。未配置飞书应用凭据时保存 preview 投递，Web 审批仍可测试。

人员认证

OIDC 可不开启。HUMAN_AUTH_MODE 支持：

  • local：默认模式，本地账号密码登录；密码使用带 Pepper 的 scrypt 哈希，浏览器使用 HttpOnly + SameSite=Strict 服务端 Session，写请求需要 CSRF Token。
  • demo：仅本地开发，使用演示人员。
  • trusted_proxy：生产由现有 SSO、飞书登录网关或内网身份网关注入 x-agentgate-user-id。

生产环境拒绝 demo。API 和 Web 可以继续监听 0.0.0.0；HTTP 内网部署可直接登录，WEB_ORIGIN 为 HTTPS 时 Session Cookie 会自动增加 Secure 和 __Host- 约束。HTTP 不提供传输加密，只应放在受信任私网；跨共享或不可信网络时建议启用 TLS。Access Key 是机器身份，与人员登录/OIDC 相互独立。

能力包

先在“Runtime 环境”创建环境和不可变版本，完成构建并发布；上传 .py 或 .sh 时选择一个语言匹配的已发布 Runtime Version。版本弃用后禁止新能力绑定，但已经固定到该版本的能力继续运行，避免弃用被误用成紧急撤权。

普通 Python/Shell 包默认没有网络和 Secret：

Tier 能力包可以做什么
compute 无网络纯计算
brokered_read 生成受限 read plan，由平台 Broker 读取
brokered_write_plan 生成 ActionPlan，人工批准后由 Broker 写入
certified_connector 外部交付的固定 digest 认证 OCI；当前 MVP 只接受声明/扫描，拒绝发布和执行

compute 能力需要返回较大结果时，可在 Manifest 的 limits.artifactOutput 中声明最大字节数和允许的媒体类型。平台向 Python/Shell 注入 AGENTGATE_OUTPUT_FILE=/work/artifact；程序只向该路径写一个普通文件，同时 stdout 仍只返回一个有界 JSON envelope，并用至多一项 artifacts: [{"filename":"result.ndjson","mediaType":"application/x-ndjson"}] 声明它。文件字节不经过 stdout 或 base64；Agent 收到 delivery: "task" 后轮询 Job，再按需分块读取或下载运行时 Artifact。

本地开发默认启用 uv Runtime Builder；生产默认关闭，单一可信管理员的首版部署可显式设置 RUNTIME_BUILDER=local_uv，但 Builder 必须运行在与 Base Runtime 匹配的系统 Python/OS/架构中。macOS sandbox_exec 只用于本地 ABI 验证。Linux 单机生产使用独立 runnerd，API 容器绝不挂 Docker/Podman socket；runnerd 启动前强制检查 rootless、cgroup v2/systemd controllers、seccomp 和本地 digest 镜像。多节点或更高隔离要求再使用 Kubernetes Job + gVisor/Kata。详见 Linux Runner 部署 和 能力包契约。

验证

npm run typecheck
npm test
npm run build

详细文档：

skills/agentgate-ops 是不支持 MCP 的 Host 使用的可选 HTTP Skill，不是 AgentGate 的 SDK，也不是接入前置条件。

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages