agent-runtime-gateway-smoke-test

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Runtime Gateway Smoke Test

Agent 运行时网关冒烟测试

Use this workflow when an agent task runs in a remote sandbox that calls back to a local API through a gateway. It verifies the whole path without relying on connected tools or private production data.

当 Agent 任务在远程沙箱中运行并通过网关回调本地 API 时，使用此工作流。它可以在不依赖已连接工具或私有生产数据的情况下验证完整链路。

When to Activate

启用条件

A local agent API needs an end-to-end runtime check.
A task stalls after dispatch and the gateway or tunnel may be unreachable.
A web app is temporarily pointed at a local API for agent testing.
A previous test left the web app pointing at a stopped API.

本地 Agent API 需要进行端到端运行时检查。
任务在分发后停滞，网关或隧道可能无法访问。
Web 应用临时指向本地 API 以进行 Agent 测试。
上一次测试后，Web 应用仍指向已停止的 API。

Required Inputs

所需输入

Repository-relative instructions for starting the API and web app.
The gateway route path and its expected anonymous response.
An isolated test agent, a tool-free prompt, and its exact expected answer.
A way to inspect task status and confirm a callback reached the local API.
Provider credentials, supplied through the project's normal secret store. Name the providers in shared documentation; never copy credential values into the skill or test report.

If these inputs are unavailable, report the missing input instead of guessing an endpoint or using a real account.

相对于代码仓库的 API 和 Web 应用启动说明。
网关路由路径及其预期的匿名响应。
一个隔离的测试 Agent、一个无工具提示词及其准确的预期答案。
一种检查任务状态并确认回调已到达本地 API 的方式。
通过项目常规密钥存储提供的提供商凭据。在共享文档中注明提供商名称；切勿将凭据值复制到 skill 或测试报告中。

如果缺少这些输入，应报告缺失的输入，而不是猜测端点或使用真实账户。

Authorization and Cleanup

授权与清理

Confirm authorization to expose the local test API through the selected tunnel provider, dispatch the test task, and temporarily change the web app route. Use an isolated local web app or test deployment; do not switch a shared production app as part of this smoke test. Keep tunnel access scoped to the required authenticated route.

Install cleanup before changing the route: on success, error, timeout, interruption, or cancellation, restore the recorded target and verify health before stopping the API and tunnel. Track only the process IDs or resources created by this test. If restoration fails, report it immediately and keep the evidence needed to recover; do not claim success.

确认已获得授权，可通过所选的隧道提供商暴露本地测试 API、分发测试任务并临时更改 Web 应用路由。使用隔离的本地 Web 应用或测试部署；在此冒烟测试中，不得切换共享的生产应用。将隧道访问权限限制在所需的已认证路由范围内。

在更改路由前先设置清理逻辑：无论测试成功、失败、超时、中断还是取消，都要恢复已记录的目标，并在停止 API 和隧道前验证其健康状态。仅跟踪本次测试创建的进程 ID 或资源。如果恢复失败，应立即报告并保留恢复所需的证据；不得声称测试成功。

Smoke Test

冒烟测试

Record and check the original route. Note the web app's current API target and verify it is healthy. Keep this value locally for restoration. Confirm the test agent and data are isolated from real users.
Start the local API and tunnel. Use a process manager that will keep both alive for the full test. Verify API health. Probe the gateway route anonymously and confirm the documented authentication response, usually
```
401
```
or
```
403
```
. Confirm the probe appears in the local API log; an edge response alone does not prove the API was reached.
Switch the web app only after both checks pass. Verify a request from the web app reaches the local API. Check the route again after any web server restart or configuration reload.
Run one tool-free task. Use a short prompt with an exact expected answer. Confirm the remote sandbox called the local gateway, the task reached a terminal state, and the returned answer matches. A queued or running task is not a pass.
Restore the original route. Set the web app back to its recorded API target, verify that target and a representative page load, then stop the test API and tunnel. If restoration fails, report the broken route immediately.

Example checks, with values supplied by the project:

curl --silent --show-error --output /dev/null --write-out '%{http_code}\n' "$LOCAL_API_HEALTH_URL"
curl --silent --show-error --output /dev/null --write-out '%{http_code}\n' "$PUBLIC_GATEWAY_PROBE_URL"

The first command should return the project's healthy status. The second should return the documented anonymous authentication status and appear in the local API log. Do not put a credential in either URL.

记录并检查原始路由。 记下 Web 应用当前的 API 目标并验证其健康状态。在本地保留该值用于恢复。确认测试 Agent 和数据与真实用户隔离。
启动本地 API 和隧道。 使用能够在整个测试期间保持二者持续运行的进程管理器。验证 API 健康状态。以匿名方式探测网关路由，并确认文档中规定的认证响应，通常为
```
401
```
或
```
403
```
。确认探测请求出现在本地 API 日志中；仅收到边缘节点的响应并不能证明 API 已被访问。
仅在两项检查均通过后切换 Web 应用。 验证来自 Web 应用的请求已到达本地 API。在 Web 服务器重启或配置重新加载后，再次检查路由。
运行一个无工具任务。 使用简短提示词和准确的预期答案。确认远程沙箱已调用本地网关、任务已进入终态，且返回的答案与预期一致。任务处于排队或运行状态不算通过。
恢复原始路由。 将 Web 应用设置回已记录的 API 目标，验证该目标及一个代表性页面的加载情况，然后停止测试 API 和隧道。如果恢复失败，应立即报告路由中断问题。

示例检查命令，值由项目提供：

curl --silent --show-error --output /dev/null --write-out '%{http_code}\n' "$LOCAL_API_HEALTH_URL"
curl --silent --show-error --output /dev/null --write-out '%{http_code}\n' "$PUBLIC_GATEWAY_PROBE_URL"

第一条命令应返回项目规定的健康状态。第二条命令应返回文档中规定的匿名认证状态，并且探测请求应出现在本地 API 日志中。不要在任何 URL 中放入凭据。

Connected Tool Follow-up

已连接工具的后续测试

Run a separate test only after the tool-free task passes. Use an explicit test connection and grants. Report connection presence and actions granted as different facts. Do not infer that an empty action search means no app is connected. Do not execute a write action against a real account as a smoke test.

仅在无工具任务通过后，再单独运行测试。使用明确的测试连接和授权。应将“连接存在”和“已授权操作”作为不同事实分别报告。不要根据操作搜索结果为空而推断没有应用连接。冒烟测试不得对真实账户执行写入操作。

Failure Handling

失败处理

Observation	Next check
Web page loads but API requests fail	Compare the configured API target with the listening process and restore the original route.
Gateway probe gets a connection error or `404`	Check tunnel lifetime, route path, and local API health before dispatching a task.
Gateway probe gets `401` or `403` , but no local log entry	The response may come from the tunnel edge; verify the callback path.
Task stays queued or running	Check whether another dispatcher claimed it and whether the sandbox reached the local gateway.
Task finishes with the wrong answer	Capture the task status and redacted error; do not call the smoke test successful.

观察到的现象	下一项检查
Web 页面可以加载，但 API 请求失败	对比配置的 API 目标与正在监听的进程，并恢复原始路由。
网关探测出现连接错误或 `404`	在分发任务前，检查隧道有效期、路由路径和本地 API 健康状态。
网关探测返回 `401` 或 `403` ，但没有本地日志记录	响应可能来自隧道边缘节点；请验证回调路径。
任务持续处于排队或运行状态	检查是否有其他调度器认领了任务，以及沙箱是否已到达本地网关。
任务完成但答案错误	捕获任务状态和脱敏后的错误；不得将冒烟测试判定为成功。

Output Contract

输出约定

Return a short report with:

Local API healthy: yes or no
Gateway probe status and local log confirmation
Remote callback observed: yes or no
Tool-free task terminal status and whether the exact answer matched
Original web API route restored and healthy: yes or no
One unresolved blocker or next action, if any

Keep account details, credential values, personal paths, public tunnel URLs, and raw private logs out of the report. Keep the source operator notes local.

返回一份简短报告，包含：

本地 API 健康：是或否
网关探测状态及本地日志确认结果
已观察到远程回调：是或否
无工具任务的终态，以及准确答案是否匹配
原始 Web API 路由已恢复且健康：是或否
尚未解决的阻塞问题或下一步操作（如有）

报告中不得包含账户详情、凭据值、个人路径、公共隧道 URL 或原始私有日志。源操作说明应保留在本地。