agent-integration

从头开始将此 Agent 仓库与 Veris 集成。

此技能将仓库从“普通客户 Agent 源码”转变为“已就绪且可推送到 Veris”。如果用户提供了 Agent 仓库路径，请将其用作仓库根目录；否则使用当前工作目录。

将任何现有的 .veris/ 文件或旧脚手架输出仅视为起始材料。生成内容时，以此技能中当前随附的参考资料为准。

核心原则：Agent 是被测对象，Veris 是测试工具

Veris 用于在真实条件下测试 Agent。Agent 是被测对象；Veris 是围绕它搭建的测试工具。这种不对称关系决定了此技能中的每个决策：

• Agent 在 Veris 中的运行方式与在生产环境中相同。 如果 Agent 在生产环境中通过 HTTP 调用 Slack Web API，那么在模拟环境中也应通过 HTTP 调用 Veris 的 Slack 模拟服务。如果它在生产环境中会调用 CLI，那么在模拟环境中也应调用 CLI。不得设置特殊的模拟代码路径。
• 所有集成工作都放在 .veris/ 中。 .veris/veris.yaml、.veris/Dockerfile.sandbox、.veris/config.yaml、.veris/.dockerignore 是部署描述文件——相当于此 Agent 的 Helm chart 或 docker-compose.yaml。它们描述的是如何在此环境中启动 Agent，不应包含属于 Agent 本身的行为。
• 不要编写包装器、垫片或胶合代码来“适配”Agent，使其适用于 Veris。 用于暴露可调用接口的 CLI Agent Python 包装文件、用于将 Veris 的 actor 格式转换为 Agent 原生格式的脚本、经过修改以接受 Veris 特定参数的 Agent 版本——这些做法都不对。它们意味着最终被测试的已不是 Agent 本身。
• 不要修改 Agent 源码以使其在 Veris 中运行。 如果 Agent 依赖 Veris 无法原样满足的条件，这要么是需要记录的 Veris 平台缺口，要么是 Agent 本身的问题，而且该问题在生产环境中也会导致故障。无论哪种情况，修复都不应放在 Agent 源码中。
• 如果发现自己需要编写包装器，请停下来并将其视为一项发现。 问问自己：Agent 在生产环境中真正采用的集成路径是什么？如果 Agent 在生产环境中运行 HTTP 服务，就使用该服务。如果它在生产环境中只能通过 CLI 运行，而 Veris 的 actor 无法调用 CLI，就升级报告——这是 Veris 的能力缺口，不是自行编写胶合代码的理由。
• 唯一可以包含非纯配置内容的 .veris/ 文件，是用于编排容器的 start.sh，它负责捆绑多个进程（例如，将数据库与 Agent 一起运行）。即使如此，它也只能按原样启动并运行 Agent，不得改变其行为。

如有疑问，Agent 的作者应该能够阅读 .veris/，并将其视为“用于 Veris 的部署配置”，而不是“有人分叉并修改了我的 Agent”。

传输桥接是明确的例外

传输桥接负责在参与者的通道格式（例如 voice_ws PCM16）与 Agent 框架的原生传输格式（例如 LiveKit WebRTC、SIP 媒体或专有消息封装）之间进行转换，同时逐字节保留底层负载。它不是包装器。在生产环境中，Agent 的其他产品界面（移动客户端、自助终端、IVR 供应商）也采用相同模式，因此这种桥接属于真正的产品代码，而非 Veris 专用胶水代码。

以下情况允许使用桥接：

• Agent 的框架无法重新配置为直接使用参与者的通道格式（例如，LiveKit Agents 端到端使用 WebRTC，且不支持原始 PCM16 WS 传输）。
• 桥接仅进行纯传输转换：输入和输出中的音频字节／JSON 负载保持一致，不进行语义重塑。（对于语音，Agent 模型收到的音频字节必须与参与者发送的完全相同。对于文本，Agent 看到的消息负载必须与参与者发送的完全相同。）
• 桥接作为生产代码存放在 Agent 的代码库中（例如 app/bridge.py），并由 Agent 自身的测试覆盖，而不是放在 .veris/ 中。它是 Agent 的 voice_ws over WebRTC 产品界面；Veris 只是其中一个调用方。

以下情况不允许使用桥接：

• 它会重塑 Agent 看到的内容：重写消息、重组工具调用 JSON、规范化 STT 输出，或将 Veris 专属的参与者字段转换为 Agent 的原生参数。这属于包装器，须遵守上文的禁止包装器规则。
• 框架可以配置为使用参与者的通道（例如，Pipecat 可通过 RawAudioFrameSerializer 支持 voice_ws，框架自带的 HTTP 插件可支持 http 等）。应先配置框架；只有传输方式固定时才使用桥接。

快速判断标准：“相同字节，不同网络格式”＝传输桥接（允许）。“不同字节／不同结构”＝包装器（不允许）。

架构说明请参阅 reference/infrastructure-patterns.md Pattern 9，语音专用应用说明请参阅 reference/voice-channels.md。

向评分器报告客户端工具调用是获准的例外（仅限语音 Agent）

这是唯一真正违反“不能有 Veris 专用代码路径”规则的例外，而且是有意为之。它仅适用于基于托管式语音到语音平台构建的语音 Agent（ElevenLabs Conversational AI、OpenAI Realtime、Gemini Live、Vapi 等），这些 Agent 的工具在 Agent 进程内执行——作为通过供应商 WebSocket 往返调用的客户端工具，或作为平台通过 HTTP 向 Agent 的 webhook 发起 POST 请求的 Vapi 式服务端工具。无论哪种情况，调用都不会出现在语音转录文本中。

之所以需要这样做：语音评分器会根据语音转录文本以及 Agent 报告的任何工具调用事件来构建跟踪记录。客户端工具不会出现在转录文本中，因此如果不报告，评分器就无法看到工具已运行，会把真实操作（冻结银行卡、更换银行卡）误判为幻觉。文本/HTTP Agent 没有这个问题——它们的工具调用会自动捕获——因此此例外仅适用于语音 Agent。

解决方法：每次工具运行后，Agent 都向沙盒引擎 POST 一个 agent_tool_call 事件，平台会将其呈现在评分跟踪记录中。保持实现严格精简，使其仅用于记录，而不是包装器：

• 模拟之外不执行任何操作。 通过 SIMULATION_ID 控制（在生产环境中未设置 → 立即返回）。生产行为不变。
• 即发即弃，失败时宽容处理。 使用较短的超时时间，忽略错误，并记录警告。报告失败绝不能中断调用或改变 Agent 的输出。
• 只观察，不改造。 在真实工具运行后进行报告，原样传递真实名称/参数/结果。它只记录发生的情况，不改变 Agent 的行为或模型看到的内容。

此许可仅用于让评分器看到客户端工具调用，仅适用于语音 Agent，且只能采用这种精简形式——它并不授权创建通用垫片。准确的端点、事件架构以及可直接复制粘贴的钩子见 reference/voice-channels.md。

核心规则

• 在每个主要步骤之前，说明你将要做什么。
• 明确提出需要做出的选择，说明其中实际存在的权衡，并让用户决定。
• 在对依赖项进行分类或决定如何集成 Agent 时，引用仓库中的具体证据。
• 不要默默保留过时的 Veris 配置。应将其迁移为当前首选形式。
• 不要生成 .env.simulation。当前运行时流程是 agent.environment 加上 veris env vars set。
• 优先使用当前的 actor.channels 架构和规范服务名称。除非用户明确要求兼容性，否则不要生成旧版 persona.modality、email_address 或旧服务别名。
• 不要编写 Python 包装器、Shell 垫片或任何在 Veris 与 Agent 之间进行转换的“适配器”代码。应使用 Agent 的真实生产接口。如果无法直接使用，就将其说明为平台缺口，而不是创建包装器的理由。
• 执行外部操作或不可逆操作前，先征求同意：
  • 安装 veris-cli
  • 运行 veris login
  • 运行 veris env create
  • 使用 veris env vars set 设置环境变量
  • 使用 veris env push 推送

快速通道模式

如果用户说“全部完成”“全部都做”，或以其他方式预先批准完整流程：

• 跳过中间检查点（第 2 阶段结束、第 3 阶段结束、第 4 阶段结束）
• 做出决策时仍要随时说明原因，让用户了解进展
• 对真正不可逆或涉及外部操作的事项，仍须停下来征求同意：veris env create、veris env push、使用真实密钥执行 veris env vars set
• 如果某项决策确实存在模糊的权衡（例如，将大型服务打包还是作为外部依赖），即使在快速通道模式下也要暂停并询问
• 最后汇总所有已做出的决策

按需阅读这些文件

• 当前服务名称和检测方式：reference/service-mapping.md
• 环境变量覆盖项和模拟凭据：reference/env-var-overrides.md
• 可打包的本地基础设施：reference/bundling-recipes.md
• 容器重构模式：reference/infrastructure-patterns.md
• 语音 Agent（voice_ws 通道、框架选择、尾随静音、报告客户端工具调用以便评测器能够看到）：reference/voice-channels.md
• 当前的 veris.yaml 结构：reference/veris-yaml-schema.md
• 生成的配置示例：templates/veris-yaml.md
• Dockerfile 模式：templates/dockerfile-sandbox.md
• 运行时环境变量处理：templates/env-vars.md
• 多进程启动脚本：templates/start-sh.md
• 集成故障：phases/troubleshooting.md

工作流概览

阶段	目标
0	初始化 Veris 工具和环境
1	探查代码仓库和当前运行时
2	分析依赖项和服务策略
3	选择集成模式和容器架构
4	生成 .veris/veris.yaml
5	生成 .veris/Dockerfile.sandbox 和支持文件
6	配置运行时环境变量、验证并推送
7	使用单个场景和模拟进行冒烟验证

---

阶段 0：初始化 Veris 工具和环境

[阶段 0/7]

告诉用户：“我将检查此代码仓库是否具备后续集成工作所需的 Veris 工具和环境配置。”

0.1 确认代码仓库根目录

确认该目录是 Agent 代码仓库，而不只是一个父文件夹。查找源代码、依赖清单和应用入口点。

0.2 确认 veris-cli

检查是否已安装 veris，且可以正常运行。

如果尚未安装：

• 优先使用 uv tool install veris-cli
• 备选方案：pip install veris-cli

说明你使用的安装方式及原因。

0.3 确认 Veris 身份验证

检查用户是否已登录，以及正在使用哪个配置文件／后端。

如果尚未通过身份验证：

• 建议使用 veris login 进行浏览器身份验证
• 仅在用户明确偏好时使用 API 密钥登录

在身份验证正常工作之前，不要执行 veris env push。

0.4 确认或创建 .veris/

检查：

• .veris/config.yaml
• .veris/veris.yaml
• .veris/Dockerfile.sandbox
• .veris/.dockerignore

如果 .veris/ 不存在，或者目录存在但没有环境绑定：

1. 根据代码仓库目录名推导一个候选环境名称。
2. 向用户展示建议的名称。
3. 获得批准后，运行 veris env create --self-serve --name "<name>"。

--self-serve（veris-cli >= 2.27.0）是本技能面向用户的正确模式：你将自行编写 .veris/，并且环境应立即准备好供 veris env push 使用。不使用该选项时，env create 默认采用托管设置模式，由 Veris 团队为客户生成 Dockerfile.sandbox 和 veris.yaml；在设置完成之前，veris env push 会返回 409: Run veris env submit first。如果 veris env create --help 未列出 --self-serve，请先使用管理 veris 的安装管理器升级 CLI（uv tool upgrade veris-cli 或 pip install -U veris-cli）。若要恢复已在未使用 --self-serve 的情况下创建的环境，请参阅 phases/troubleshooting.md。

说明 veris env create 会为用户提供什么：

• .veris/veris.yaml — Veris 模拟配置
• .veris/Dockerfile.sandbox — 镜像构建定义
• .veris/.dockerignore — 构建上下文排除项
• .veris/config.yaml — 此代码仓库的环境绑定

0.5 将脚手架视为占位内容，而非事实

生成的 .veris/ 文件只是起点。它们可能使用旧的默认值或通用占位内容。你需要为此仓库替换为正确的集成方式。

直接进入阶段 1。

---

阶段 1：了解仓库和当前运行时

[阶段 1/7]

告诉用户：“我将盘点此仓库当前的运行方式、依赖项，以及用户与它的交互方式。”

1.1 现有 Veris 状态

如果 .veris/ 已存在，请先读取所有现有的 Veris 文件。指出任何看起来过时或属于旧版的内容：

• persona.modality
• email_address
• crm、calendar、oracle 等旧服务名称
• 缺少 .veris/config.yaml 环境变量绑定
• 与当前文档相冲突的假设

1.2 基础设施文件

读取并总结以下文件（如有）：

• docker-compose.yml、docker-compose.yaml、compose.yml
• Dockerfile、Dockerfile.*
• Procfile
• supervisord.conf、supervisord.ini
• vercel.json、serverless.yml、netlify.toml
• Kubernetes 清单

确定：

• 哪个进程是面向用户的 Agent
• 还有哪些其他服务
• 系统当前如何启动

1.3 环境变量和密钥

读取：

• .env.example、.env.sample、.env.template
• 配置/设置模块
• 密钥或保管库引用

收集 Agent 读取的所有环境变量，并注明哪些属于：

• 稳定的非密钥变量
• 密钥
• 服务端点
• 可选变量或仅用于调试的变量

1.4 依赖项

读取此仓库所用语言/运行时的包清单，并确定：

• 包管理器
• 框架
• Python/Node 运行时假设
• 外部服务的 SDK

1.5 源代码入口点

找到处理用户传入任务的实际代码路径：

• 应用/服务器入口点
• 聊天/消息处理器
• 配置/设置模块
• 请求路由
• 用户对话期间涉及的后台工作进程或 Webhook 监听器

1.5a 平台托管的 Agent（仅配置仓库）

如果仓库没有传统的应用入口点（例如 main.py、app.py、server.js、index.ts），请检查它是否属于平台托管的 Agent：即一组运行在已安装框架（CrewAI、LangServe、AutoGen、Dify、n8n、Flowise 或类似框架）上的配置文件。

迹象：

• 主要文件是 YAML/JSON 配置、提示词模板和工具定义
• pyproject.toml 或 package.json 将某个框架列为主要依赖项
• 除少量工具/钩子文件外，没有实质性的应用逻辑
• README 指示“安装[框架]，然后运行[框架命令]”

如果符合这种情况：

• 框架就是运行时——它将在 Dockerfile 中安装，而非从源码构建
• 入口点是框架的 CLI 或服务器命令
• 完整的重构方法请参阅 reference/infrastructure-patterns.md 中的模式 8
• 如果尝试在这些仓库上运行 pip install .，请留意源码树编译错误

1.6 确定集成接口

这很关键。确定模拟参与者应如何与 Agent 通信。

查找以下四类接口：

HTTP

• 聊天端点
• 请求／响应正文结构
• 会话或对话字段
• JSON 或 SSE 响应形式

WebSocket

• WS 路由
• 消息封装格式
• 会话处理

Email

• 收件箱地址
• 轮询或 webhook 流程

Function

• Agent 已通过其公共 API 暴露的简洁 Python 可调用对象
• Agent 自身文档所述、作为入口点的现有 handle_message 风格函数

不要通过包装 CLI 或服务来杜撰函数接口。如果 Agent 在生产环境中仅支持 CLI，那么集成方式就是由 CLI 驱动——指出这一点，并找到合适的 Veris 通道，或将其记录为平台缺口。只有当仓库已将可调用对象作为主要接口或文档说明的接口提供时，函数通道才是正确选择。

如果网络模式和函数模式都可行，请使用仓库的实际产品接口。生产环境运行的就是它；我们测试的也应该是它。

准确告知用户你发现了什么，并在继续之前确认可能的最佳集成路径。

进入阶段 2。

---

Phase 2: Analyze Dependencies And Service Strategy

[Phase 2/7]

告知用户：“我现在将每项依赖归类为 mock、打包、外部或跳过。”

阅读：

• reference/service-mapping.md
• reference/env-var-overrides.md
• reference/bundling-recipes.md

将每项依赖归类为以下类别之一：

1. 使用 Veris mock
2. 在容器内打包
3. 使用外部端点
4. 完全跳过
5. 需要讨论
6. 允许真实外网访问 — Agent 必须访问真实互联网（例如，网页搜索、URL 抓取、没有 mock 的实时 API）。不同模拟运行的结果将不确定。

分类规则

• 做决定前务必阅读源代码。不要仅凭服务名称推断其重要性。
• 如果判定某项依赖可以跳过，请提供依据。
• 在相关情况下说明打包成本，尤其是 Elasticsearch 或 LocalStack 等大型服务。
• 如果依赖能与 Veris 服务准确对应，优先使用 mock 服务。
• 尽可能优先使用环境变量覆盖，而不是修改代码。

特殊情况

Postgres

• 决定使用 Veris postgres 还是外部数据库
• 如果使用 Veris postgres，找到 schema 工件或迁移源，并确定最佳复制路径

LLM providers

• 无需添加 Veris 服务条目
• LLM 代理会自动拦截受支持的域名

Email

• 如果参与者使用 Email 通道，请注明 Veris Email 服务会自动注入

Auth helpers

• Google／Microsoft／Atlassian／Intuit auth helpers 是平台级辅助工具，通常不应手动添加为服务

Web search and scraping

• 如果 Agent 调用搜索 API（Google、Bing、SerpAPI、Tavily、Brave Search、DuckDuckGo）或抓取实时 URL，则无法 mock
• 将其归类为“允许真实外网访问”
• 警告用户：实时互联网调用会使模拟结果不确定——同一场景在不同运行中可能产生不同输出
• 如果搜索确实是可选的（例如，知识库没有答案时才使用的后备方案），可考虑通过环境变量禁用，以便进行确定性模拟

Real internet egress (general)

• 某些 Agent 需要访问 Veris 无法 mock 的任意外部端点（第三方服务的 webhook、实时数据流、没有对应 Veris 服务的公共 REST API）
• 这些也应归类为“允许真实外网访问”
• Veris 容器默认允许访问未被拦截域名的外网
• 向用户说明这种做法在结果确定性方面的权衡

检查点

继续之前，先与用户逐项确认依赖分析。用户应了解：

• 将模拟什么
• 将打包什么
• 哪些内容保持外部依赖
• 哪些内容会跳过
• 哪些事项仍需决定

获得批准后再继续。

---

第 3 阶段：选择集成模式和容器架构

[Phase 3/7]

告诉用户：“我正在确定此 Agent 如何在 Veris 容器中运行，以及 actor 将如何与它通信。”

阅读 reference/infrastructure-patterns.md。

3.1 选择通信渠道策略

从以下选项中选择一项：

• HTTP — 产品本身已是 HTTP 聊天 API 时优先选择
• WebSocket — 实时、有状态的消息传递是核心功能时优先选择
• Email — 产品确实以电子邮件驱动时优先选择
• Function — 仓库提供清晰的可调用路径，或应将其视为一次性请求／响应 Agent 时优先选择

3.2 Function 渠道规则

如果选择 Function 渠道：

• 可调用路径必须是 Agent 仓库已经公开的接口（已记录、在其 README 中引用，或属于其契约的其他部分）
• 不要创建包装文件，将 CLI 或服务变成可调用接口；如果仓库本身没有提供此类接口，Function 就不是合适的渠道
• 在 veris.yaml 中省略 agent.entry_point 和 agent.port
• 如果可调用接口是一次性的且无状态，请设置 actor.config.MAX_TURNS: 1

3.3 网络渠道规则

如果选择 HTTP / WS / email：

• 确定准确的请求和响应映射
• 确定启动命令
• 选择一个非保留端口
• 决定是否需要 start.sh 来打包基础设施或多个进程

3.4 容器布局

确定：

• 哪些内容会复制到 /agent
• 哪些文件应排除在镜像之外
• 是否需要 start.sh 来打包多个进程（这是容器编排，不是修改 Agent）

不要规划“需要修改哪些代码”。目标是 Agent 零代码改动。如果环境变量覆盖还不够，且 Agent 确实无法按原样运行，这就是一项发现——应升级处理，而不是修补源代码。

检查点

说明：

• actor 将如何与 Agent 通信（使用 Agent 实际的生产接口）
• Agent 将如何在容器中启动（使用其实际的生产启动命令）
• 哪些文件将被复制

如果你认为需要对 Agent 进行任何代码修改，请在此处指出并停止。默认答案是零代码改动。如果找不到不做修改的可行方案，问题很可能出在 Veris 平台，而不是集成步骤。

唯一预先批准的例外：客户端工具型语音 Agent（ElevenLabs Conversational AI、OpenAI Realtime、Gemini Live 等）需要 agent_tool_call 报告钩子，以便评分器能看到其工具——请参阅 Core framing exception 和 reference/voice-channels.md。这是预期情况；直接添加，无需升级处理。其他所有情况仍须在此停止。

获得批准后再继续。

---

第 4 阶段：生成 .veris/veris.yaml

[Phase 4/7]

告诉用户：“我正在按照当前首选架构生成最终的 Veris 配置。”

阅读：

• reference/veris-yaml-schema.md
• templates/veris-yaml.md

规则

• 使用 actor.channels，而不是 persona.modality
• 使用 reference/service-mapping.md 中的规范服务名称
• 使用 agent_inbox，而不是 email_address
• 只有在有具体原因时才设置 actor.config.MAX_TURNS，通常是用于一次性函数集成
• 除非用户明确要求高级调优，否则不要添加 *_INTERVAL 参数
• 不要将密钥放入 veris.yaml
• 在 agent.environment 中放置稳定且非机密的默认值
• 只有在需要展开／组合时才在 agent.environment 中使用 ${VAR}；如果 Agent 可以直接读取运行时环境变量，优先使用 veris env vars set 设置

特定渠道规则

HTTP / WS / Email

• 包含 agent.code_path
• 包含 agent.entry_point
• 包含 agent.port

Function

• 包含 agent.code_path
• 不包含 agent.entry_point
• 不包含 agent.port
• 设置 actor.channels[0].type: function
• 设置 callable: ...

检查点

展示完整的 veris.yaml，解释各个部分，并在写入或定稿前征得批准。

---

第 5 阶段：生成 .veris/Dockerfile.sandbox 和支持文件

[第 5/7 阶段]

告诉用户：“我正在生成镜像构建文件，以及此集成所需的少量支持文件。”

阅读：

• templates/dockerfile-sandbox.md
• templates/start-sh.md

5.1 Dockerfile 规则

• 以以下内容开头：

ARG GVISOR_BASE
FROM ${GVISOR_BASE}

• 构建上下文是仓库根目录
• 在复制源代码前先复制依赖清单
• 只复制 Agent 实际需要的内容
• 以 WORKDIR /app 结尾
• 不要将 veris.yaml 打包进镜像

5.2 运行时说明

• 当前基础镜像已包含 Python、uv 和 Node.js
• 只有当仓库确实需要时，才安装额外的运行时或系统软件包
• 如果使用函数渠道，仍需像往常一样打包 Agent 代码和依赖；只是无需启动网络服务

5.3 支持文件

只创建必要的文件：

• start.sh：用于捆绑多个进程（例如与 Agent 一起运行的数据库）——这是容器编排，与 docker-compose.yaml 的作用相同
• 如果仓库包含默认忽略文件未覆盖的大型目录，则更新 .veris/.dockerignore

不要创建 Python“包装模块”来将 Agent 暴露为可调用对象、将 Veris actor 调用转换为 Agent 的原生格式，或以其他方式插入 actor 与 Agent 之间。使用 Agent 的真实接口。

5.4 不修改 Agent 代码

Agent 在 Veris 中的运行方式与其在生产环境中的运行方式完全一致。这意味着：

• 不要为了适配模拟而修补源代码
• 不要添加“模拟模式”标志或 Veris 专属分支
• 不要使用经过本地修改的 Agent 分叉副本

如果你发现自己想要修改 Agent 的源代码，请停下来。要么：

• 可以通过环境变量覆盖来实现（那么就通过 agent.environment 或 veris env vars set 来设置），或
• 这是 Agent 本身的实际问题（那么应由客户负责修复，而且也会影响生产环境），或
• Veris 无法适配按原样提供的 Agent（那么这是平台缺口——请上报）

显然，不要进行无关的重构。

唯一获准添加的源代码是语音 Agent 的客户端工具报告钩子（参见核心帧处理例外）。这并非对“不得修改代码”规则的反例，而是经过明确批准的例外：它在模拟之外不执行任何操作，不会改变 Agent 的行为，只用于让评分器看到那些不会进入跟踪记录的客户端工具。对于使用客户端工具的语音 Agent，请添加此钩子；不要将其扩展为其他源代码修改。

文件就位后，直接进入第 6 阶段。

---

阶段 6：配置运行时环境变量、验证并推送

[阶段 6/7]

告诉用户：“我正在将其转换为可推送的 Veris 环境。”

阅读：

• templates/env-vars.md
• phases/troubleshooting.md

6.1 制定环境变量计划

将环境变量分为：

1. 稳定的非机密默认值 → 放入 agent.environment
2. 机密信息／每个环境各自的值 → 使用 veris env vars set 设置
3. 仅限本地的便利值 → 可选地放入根目录 .env，或通过 shell 导出以用于本地冒烟测试

不要创建 .env.simulation。

6.2 生成准确命令

生成用户需要的准确 veris env vars set 命令。

如果用户提供了实际值并希望你代为设置，请运行这些命令。

Shell 插值陷阱： 使用 shell 变量运行 veris env vars set KEY="$VAR" --secret 时，请先确认源变量确实已设置（printenv VAR 或 test -n "$VAR"）。变量为空或未设置时会静默展开为 ""——CLI 会毫无报错地保存一个空机密，而 Agent 运行时会失败，并给出令人困惑的身份验证／提供方错误，而不是明确提示“缺少密钥”。

6.3 验证推送前提条件

推送前，请确认：

• 已安装 veris
• 身份验证／配置文件可用
• .veris/config.yaml 中有环境 ID
• .veris/veris.yaml 存在
• .veris/Dockerfile.sandbox 存在

可选但建议：

• 如果本地 docker build -f .veris/Dockerfile.sandbox . 冒烟测试可能很快发现明显问题，请运行该测试

6.4 推送

如果用户批准，请运行：

veris env push

或者，如果用户需要指定标签：

veris env push --tag <tag>

如果推送失败：

• 诊断失败的构建步骤
• 修复集成
• 重试

6.5 最终摘要

总结：

• 创建或修改的文件
• 选择的集成模式
• 模拟、打包、外部接入或跳过的服务
• 已设置的环境变量与留给用户设置的环境变量
• veris env push 是否成功，以及创建了哪个标签

然后建议运行以下命令：

• veris scenarios create
• veris simulations create

---

阶段 7：冒烟验证

[阶段 7/7]

告诉用户：“我将运行一个场景和一次模拟，以验证集成端到端正常工作。”

7.1 创建冒烟场景

veris scenarios create --num 1

目标是进行一次简短交互，测试 Agent 的主要接口。

7.2 运行一次模拟

veris simulations create --scenario-set-id <id>

等待其完成。

7.3 检查结果

检查模拟是否满足以下条件：

1. Agent 返回了实际内容——不是错误页、空内容或异常回溯
2. 调用了模拟服务——如果 Agent 应调用 Slack、Salesforce 等，请确认这些调用已出现
3. 没有启动崩溃——Agent 进程在整个过程中保持运行
4. 通道契约正确——参与者的消息到达 Agent，且响应以预期格式返回

7.4 诊断故障

如果冒烟测试失败：

• 检查 Agent 容器日志，查找启动错误或缺失的环境变量
• 验证 actor.channels 请求／响应映射是否符合实际 API 格式
• 确认模拟服务凭据和 DNS 别名正确
• 返回相关阶段进行修复并重新推送

7.5 确认完成

如果冒烟测试通过，请总结：

• 参与者发送了什么，以及 Agent 返回了什么
• 测试了哪些服务
• 对该集成已准备好进行完整场景生成的信心程度

然后建议下一步生成完整场景（veris scenarios create --num N）并运行模拟。

---

实用指南

优先采用当前惯例，而非过时的脚手架

如果 veris env create 生成了看起来过时的占位内容，请用本技能推荐的当前结构覆盖它。

如实说明技能的功能通道

仅当 Agent 已将某个可调用对象作为其公共接口的一部分公开时，才使用功能通道。不要仅仅因为这样看起来更简单，就强行将联网产品转换为可调用函数，也不要创建包装文件来虚构 Agent 原本没有的可调用对象。

如实说明技能是否为一次性 Agent

如果集成的 Agent 显然是一次性／无状态的，请通过设置 actor.config.MAX_TURNS: 1 明确体现这一点。

明确说明未自动化的事项

如果登录、机密信息或环境变量值仍需用户操作，请直言不讳。目标是尽可能推进，而不是掩盖阻碍。