# g2rain-agent-studio

下一代AI软件开发范式，AI原生Agent平台，开源的企业级SaaS底座。

谷雨 Agent 的运行资料管理服务。它维护 Agent 画像、Skill 定义及其执行契约、Agent-Skill 绑定和 Skill-Tool 绑定，并向 Runtime 提供可直接装载的能力包。

官网 (opens new window) · Issues (opens new window) · Discussions (opens new window)

# 平台定位

Agent Studio 是 Agent 平台的配置与资料所有者：管理端在此维护 Agent 与 Skill；Agent Runtime 通过目录、画像、Skill 摘要和能力包接口取得运行资料。它不执行对话任务，也不注册 MCP 服务或管理模型供应商。

# 功能概览

能力	说明
Agent 画像管理	维护身份、使命、边界、风格、原则及启停状态。
Skill 管理	维护 Skill 的语义描述、操作手册和执行契约。
能力绑定	管理 Agent-Skill 与 Skill-Tool 绑定，限定 Agent 可使用的能力。
Runtime 装载	提供活动 Agent 目录、指定画像、Skill 短目录与完整能力包。

# 核心流程

flowchart LR
  App[管理端] --> Studio[Agent Studio]
  Studio --> DB[(MySQL)]
  Runtime[Agent Runtime] -->|目录、画像、能力包| Studio
  Runtime --> Registry[MCP Registry]

管理端创建或维护 Agent、Skill 及其绑定关系。
Runtime 查询活动 Agent 目录，并按需解析指定画像或 Skill 摘要。
Runtime 请求能力包；Studio 仅返回启用绑定的活动 Skill，并为每个 Skill 组装已启用的工具名称。

# 工程结构

模块	说明
`g2rain-agent-studio-api`	发布查询、目录、画像、Skill 摘要及能力包契约。
`g2rain-agent-studio-biz`	实现配置领域、Controller、Service、DAO 与转换逻辑。
`g2rain-agent-studio-startup`	组装 Spring Boot、虚拟线程、参数解析和环境配置。

模块依赖方向固定为：startup → biz → api。

# 本地启动

前置条件：JDK 25、Maven，以及可用的 MySQL、Redis 与所依赖的基础设施。默认 profile 为 nacos；本地联调可选择 dev，并在本机安全地补全环境配置。

mvn -pl g2rain-agent-studio-startup -am spring-boot:run "-Dspring-boot.run.profiles=dev"

端口由 SERVER_PORT 环境变量决定；未设置时使用 8080。部署到共享环境时，推荐由 Nacos 管理数据源和服务发现配置，凭据仅通过安全的环境配置注入。

# 接口说明

接口	用途
`GET /agent_profile/active_catalog`	获取活动 Agent 目录；合并平台级与当前租户的自定义画像。
`GET /agent_profile/{agentId}/resolve`	按 ID 解析 Agent 画像及状态。
`GET /agent_profile/{agentId}/skill_digest`	获取启用且活动的 Skill 短目录，不包含手册、契约与工具。
`GET /agent_profile/{agentId}/capability_bundle`	获取完整能力包：Skill 手册、执行契约及已绑定工具。
`/agent_profile`、`/skill_profile`、`/agent_skill_binding`、`/skill_tool_binding`	管理端的查询、保存与删除入口。

# 配置与数据

配置项	说明
`SERVER_PORT`	HTTP 端口，默认 `8080`。
`SPRING_PROFILES_ACTIVE`	默认 `nacos`；本地可显式使用 `dev`。
`NACOS_SERVER_ADDR`	Nacos 注册与配置中心地址。
`spring.datasource.*`	由 `dev` 或 Nacos 提供的 MySQL 数据源。

核心数据为 agent_profile、skill_profile、agent_skill_binding 和 skill_tool_binding。初始化脚本 scripts/g2rain-agent-studio.sql 含有 DROP TABLE，仅可用于独立、空白的开发数据库；生产环境使用受控增量迁移。

# 构建与验证

目标	命令	说明
构建与验证	`mvn clean verify`	执行 Maven 验证生命周期。
启动服务	`mvn -pl g2rain-agent-studio-startup -am spring-boot:run -Dspring-boot.run.profiles=dev`	本地联调使用独立的开发环境。
构建本地镜像	`./build.sh <tag>`	使用 Jib 构建 `g2rain/g2rain-agent-studio:<tag>`。

# 协作关系

Agent Runtime 在任务执行时读取由 Studio 管理的 Agent 配置与技能资料。
MCP Registry 管理 Agent 可使用的外部工具能力。
Model Nexus 为 Agent 工作流提供统一模型访问入口。

# 安全边界

管理端访问应经 Gateway 与 IAM 身份链路；保存、删除、启停和绑定调整需要细粒度授权与审计。
organ_id 必须来自可信上下文，查询、写入和能力包返回需保持租户一致。
Skill 手册、执行契约、Agent 边界与工具绑定可能含敏感业务资料，日志、响应和文档遵循最小化原则。
不在仓库或配置中提交密码、Token、密钥和真实环境地址。

# 开发约定

对外模型放在 api 模块；业务规则、控制器和数据访问放在 biz 模块；环境装配仅放在 startup 模块。跨模块调用应优先依赖 API 契约，避免反向依赖实现模块。

# 文档与贡献

欢迎通过 Issue、文档改进、功能建议和 Pull Request 参与贡献。提交前请补充必要的测试与文档，执行 mvn clean verify，并同步 API、SQL、配置、安全和架构说明。

← g2rain-agent-runtime g2rain-agent-app →