manage-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

manage-agent

管理Agent

Drive

amctl

to manage agent-manager resources end-to-end. Locks the non-obvious patterns of the CLI into a predictable shape so calls don't silently fail or return half-empty envelopes.

Your approach: Show a short plan before starting. Use ✓ for success, ✗ for failure. When something fails, diagnose the likely cause and propose a fix before trying another approach.

Flag shape is owned by
amctl <verb> --help
, not this skill. Skills can't stay in lockstep with CLI versions;

--help

always reflects the installed binary. This document carries the things

--help

won't tell you: when to call which verb, what its output really means, and where the CLI's surface is misleading.

通过

amctl

端到端管理agent-manager资源。将CLI中不直观的使用模式标准化，避免调用静默失败或返回不完整的响应包。

处理方式： 开始操作前先展示简短计划。用✓表示成功，✗表示失败。当操作失败时，先诊断可能的原因并提出修复方案，再尝试其他方法。

参数格式以
amctl <verb> --help
为准，而非本技能文档。技能无法与CLI版本保持同步；

--help

始终反映已安装的二进制文件的最新信息。本文档包含

--help

不会提及的内容：何时调用哪个命令、输出的实际含义，以及CLI界面存在误导性的地方。

Reference files

参考文件

references/troubleshooting.md
— symptom → cause → fix table for non-obvious CLI behavior (empty envelopes, misleading statuses, async deletes, crash-loop signatures, shell traps). Load when an
```
amctl
```
call surprises you.
references/triage.md
— diagnostic flow for "build is Completed but the agent isn't really running" (build → logs → metrics → traces). Load when verifying a fresh deploy or chasing a runtime-only failure.

references/troubleshooting.md
—— 针对CLI非直观行为（空响应包、误导性状态、异步删除、崩溃循环特征、Shell陷阱）的「症状→原因→修复」对照表。当
```
amctl
```
调用出现异常时加载此文件。
references/triage.md
—— 针对「构建已完成但Agent并未真正运行」问题的诊断流程（构建→日志→指标→追踪）。在验证新部署或排查仅运行时出现的故障时加载此文件。

Install

安装

command -v amctl

returns a path, skip.

Otherwise: ask the user whether they want to install it themselves or have you do it.

"
amctl
isn't installed. Would you like me to install it for you, or would you prefer to do it yourself?"

If they want you to install it: Run the bundled wrapper. It checks idempotency, execs the upstream installer, and prints a one-line status with the PATH outcome.

bash

bash <absolute-path-to-skill>/scripts/install-amctl.sh

After the installer finishes, stop and tell the user: open a new terminal so the updated

PATH

is picked up, then run:

bash

amctl login --url <instance-url>

amctl login

is an interactive browser-redirect flow. Always defer to the user's terminal — never attempt login from this session, even against localhost.

Once the user confirms login, verify with

amctl project list --json

— NOT

amctl context show

context show

only reflects the instance URL and looks identical for an unauthed half-configured context as for a logged-in one. The real auth canary is any project-scoped call: failure surfaces as

error.code: NO_ORG

如果

command -v amctl

返回路径，则跳过安装。

否则：询问用户是希望自行安装还是由助手代为安装。

"
amctl
尚未安装。您希望我帮您安装，还是您自行安装？"

若用户希望助手代为安装： 运行捆绑的包装脚本。它会检查幂等性、执行上游安装程序，并打印包含PATH结果的单行状态信息。

bash

bash <absolute-path-to-skill>/scripts/install-amctl.sh

安装完成后，务必告知用户：打开新终端以加载更新后的

PATH

，然后运行：

bash

amctl login --url <instance-url>

amctl login

是交互式浏览器重定向流程。始终让用户在自己的终端中操作——切勿尝试从当前会话登录，即使是针对localhost。

用户确认登录后，用

amctl project list --json

验证登录状态——不要使用
amctl context show
。

context show

仅显示实例URL，未授权的半配置上下文与已登录的上下文显示内容完全相同。真正的授权验证方法是调用任何项目范围的命令：失败时会返回

error.code: NO_ORG

。

Iron rules

铁则

Always pass
--json
. Errors come back as a structured envelope (
```
error.code
```
,
```
error.message
```
,
```
error.additionalData.details
```
). Success envelopes always carry
```
data
```
plus context (
```
instance
```
,
```
org
```
,
```
project
```
, sometimes
```
environment
```
,
```
agent
```
). Exception:
```
agent build logs
```
is raw text.
Run
amctl <verb> --help
before every call you haven't made this session, and always before
create
/
update
. Flag sets evolve. Never infer flag absence from this doc, prior conversation, or a sibling agent's example.
Always pass
--project <name>
explicitly on project-scoped commands. Be aware
```
amctl context link
```
exists and a user may have linked a directory (check
```
amctl context show
```
), but do not link/unlink yourself — keep every command self-describing.

Runtime commands (
logs
,
metrics
,
traces
,
trace
,
traces export
) require
--env <name>
. Use

--env default

for local dev.

Builds are identified by
buildName
(e.g.
```
hotel-booking-agent-1778760196718
```
), NOT
```
buildId
```
(UUID). Build commands take the agent name as a positional arg, not
```
--agent
```
.
amctl agent get
does not show deployment health. Its
```
status
```
field is usually empty. Verify liveness with
```
agent logs
```
or
```
agent metrics
```
. See
```
references/triage.md
```
.
Validation errors come batched in
```
error.additionalData.details
```
. Read the full list, fix everything, retry — don't fix one at a time.

始终传递
--json
参数。错误会以结构化响应包返回（
```
error.code
```
、
```
error.message
```
、
```
error.additionalData.details
```
）。成功响应包始终包含
```
data
```
及上下文信息（
```
instance
```
、
```
org
```
、
```
project
```
，有时还有
```
environment
```
、
```
agent
```
）。例外情况：
```
agent build logs
```
返回原始文本。
在会话中首次调用某个命令前，以及执行
create
/
update
命令前，务必运行
amctl <verb> --help
。参数集会不断演进。切勿根据本文档、之前的对话或其他Agent的示例推断参数是否存在。
在项目范围的命令中，始终显式传递
--project <name>
参数。注意
```
amctl context link
```
命令的存在，用户可能已将某个目录关联到项目（可通过
```
amctl context show
```
检查），但助手不要自行执行关联/取消关联操作——确保每个命令都是自描述的。
运行时命令（
logs
、
metrics
、
traces
、
trace
、
traces export
）需要
--env <name>
参数。本地开发环境使用
```
--env default
```
。
构建通过
buildName
标识（例如
```
hotel-booking-agent-1778760196718
```
），而非
```
buildId
```
（UUID）。构建命令将Agent名称作为位置参数，而非
```
--agent
```
参数。
amctl agent get
不显示部署健康状态。其
```
status
```
字段通常为空。通过
```
agent logs
```
或
```
agent metrics
```
验证Agent是否存活。详情请见
```
references/triage.md
```
。
验证错误会批量返回在
```
error.additionalData.details
```
中。读取完整的错误列表，一次性修复所有问题后重试——不要逐个修复。

Verb map

命令映射

What exists, what it's for, and where

--help

lives. For exact flags on any row, run

amctl <verb> --help

Verb	Use to	Notes
`amctl context show`	Inspect current instance / org / linked project.	Auth-blind: shows URL even when unauthed. Not a login check.
`amctl context link` / `unlink`	Bind a directory to a project / agent.	See iron rule 3.
`amctl project list` / `get`	Discover projects, confirm auth works.	`project list` is the login canary.
`amctl project create` / `delete`	Manage projects.	`delete` needs `-y` .
`amctl agent list` / `get`	Discover agents, read agent config.	`get` does NOT show liveness or deployment env — see iron rule 6.
`amctl agent create`	Create + auto-build + auto-deploy in one call.	Required flags vary by `--subtype` ( `chat-api` / `custom-api` ) and `--build-type` ( `buildpack` / `docker` ) and `--provisioning` (default / `external` ). Always `--help` first.
`amctl agent deploy`	Re-deploy a built image, optionally with new env.	`-y` to accept env-conflict prompt.
`amctl agent delete`	Remove an agent.	Async — `agent list` may still show it for 5–15s after `data.deleted: true` .
`amctl agent build list`	Enumerate builds, newest first.	Entries carry both `buildId` (UUID) and `buildName` . Use `buildName` everywhere downstream.
`amctl agent build get`	Status / percent / step list for one build.	`data.status` ∈ `Pending` / `Running` / `Completed` / `Failed` . Agent name is positional.
`amctl agent build create`	Trigger a fresh build without recreating the agent.	Optional commit pin.
`amctl agent build logs`	Raw text build log (image pull, buildpack, workload CR apply).	NOT JSON. May be empty for 10–30s after a fresh build — retry.
`amctl agent logs`	Runtime pod logs.	Requires `--env` . Filter with `--since` / `--level` / `--grep` / `--sort` — run `--help` for current set.
`amctl agent metrics`	CPU / memory time-series for the running pod.	Requires `--env` . Returns `data.{cpuLimits,cpuUsage,memoryLimits,memoryUsage}` , each an array of `{time, value}` .
`amctl agent traces`	List OTel traces from the agent's spans.	Requires `--env` . `--condition` narrows to built-in heuristics (errors, latency, token usage, tool failures, span count) — run `--help` for the current names and thresholds. Filtered response uses `data.count` ; unfiltered uses `data.totalCount` .
`amctl agent trace`	Span detail for a single `traceId` .	Add `--span <spanId>` for one span's full attrs / events. Note: trace detail uses `durationNs` , trace list uses `durationInNanos` .
`amctl agent traces export`	Bulk dump full span data for every trace in a window.	`--since` is required.

列出所有可用命令、用途以及

--help

的位置。如需查看某行命令的具体参数，请运行

amctl <verb> --help

。

命令	用途	说明
`amctl context show`	检查当前实例/组织/关联的项目。	不验证授权：即使未授权也会显示URL。不能作为登录检查。
`amctl context link` / `unlink`	将目录与项目/Agent绑定。	参见铁则3。
`amctl project list` / `get`	发现项目，确认授权是否有效。	`project list` 是验证登录状态的可靠方法。
`amctl project create` / `delete`	管理项目。	`delete` 命令需要 `-y` 参数。
`amctl agent list` / `get`	发现Agent，读取Agent配置。	`get` 命令不显示Agent存活状态或部署环境——参见铁则6。
`amctl agent create`	一键完成创建+自动构建+自动部署。	必填参数因 `--subtype` （ `chat-api` / `custom-api` ）、 `--build-type` （ `buildpack` / `docker` ）和 `--provisioning` （默认/ `external` ）而异。务必先运行 `--help` 查看。
`amctl agent deploy`	重新部署已构建的镜像，可选择配置新环境变量。	使用 `-y` 参数接受环境变量冲突提示。
`amctl agent delete`	删除Agent。	异步操作——返回 `data.deleted: true` 后， `agent list` 可能仍会显示该Agent 5-15秒。
`amctl agent build list`	列出所有构建记录，按时间倒序排列。	每条记录包含 `buildId` （UUID）和 `buildName` 。后续操作均使用 `buildName` 。
`amctl agent build get`	查看单个构建的状态/进度/步骤列表。	`data.status` 的取值为 `Pending` / `Running` / `Completed` / `Failed` 。Agent名称为位置参数。
`amctl agent build create`	触发新的构建，无需重新创建Agent。	可选提交版本固定参数。
`amctl agent build logs`	原始文本格式的构建日志（镜像拉取、buildpack、工作负载CR应用）。	不是JSON格式。新构建后10-30秒内日志可能为空——请重试。
`amctl agent logs`	运行时Pod日志。	需要 `--env` 参数。可使用 `--since` / `--level` / `--grep` / `--sort` 过滤——运行 `--help` 查看当前支持的参数集。
`amctl agent metrics`	运行中Pod的CPU/内存时间序列数据。	需要 `--env` 参数。返回 `data.{cpuLimits,cpuUsage,memoryLimits,memoryUsage}` ，每个字段是包含 `{time, value}` 的数组。
`amctl agent traces`	列出Agent链路的OTel追踪数据。	需要 `--env` 参数。 `--condition` 参数可按内置规则筛选（错误、延迟、令牌使用、工具失败、链路数量）——运行 `--help` 查看当前支持的规则名称和阈值。过滤后的响应使用 `data.count` ；未过滤的响应使用 `data.totalCount` 。
`amctl agent trace`	单个 `traceId` 的链路详情。	添加 `--span <spanId>` 参数可查看单个链路的完整属性/事件。注意：链路详情使用 `durationNs` ，链路列表使用 `durationInNanos` 。
`amctl agent traces export`	批量导出指定时间窗口内所有链路的完整数据。	`--since` 参数为必填项。

End-to-end recipe

端到端流程

The flow for "create an agent and confirm it's actually serving traffic." For exact flags at each step, run

amctl <verb> --help

against your installed binary.

Example plan to announce before you start:

text

I'll create the agent and confirm it's actually serving traffic.
Here's what I'll do:
✦ Confirm amctl is installed and you're logged in
✦ Run `amctl agent create --help` to lock onto the current flag set
✦ Create the agent (auto-builds + auto-deploys to `default`)
✦ Poll the build until Completed or Failed
✦ Confirm liveness via logs / metrics
✦ Pull a recent trace once there's traffic

Create. Run
```
amctl agent create --help
```
to see the current required flag set for your
```
--subtype
```
/
```
--build-type
```
/
```
--provisioning
```
combination, then call
```
amctl agent create <name> --project ... --json
```
. The create call auto-builds and auto-deploys to the lowest environment (
```
default
```
locally).

Poll the build.

amctl agent build list <agent> --project <p> --json

returns newest-first; pull

data.builds[0].buildName

. Poll

amctl agent build get <agent> <buildName> --project <p> --json

until

data.status

Completed

Failed

. In zsh, name the loop variable anything except

status

— zsh reserves

$status

as a read-only alias for

$?

Confirm liveness.
```
agent get
```
won't tell you. Tail
```
amctl agent logs <agent> --project --env default --since 5m --json
```
and look for app-level output past the otel-tracing init container, or check
```
amctl agent metrics ...
```
for ≥1
```
memoryUsage
```
sample. If you see neither after ~3 min, run the full diagnostic in
```
references/triage.md
```
.
Watch traces once there's traffic.
```
amctl agent traces <agent> --project --env default --since 1h --json
```
. Empty list = agent hasn't run, window too narrow, or auto-instrumentation was disabled at create. Drill into a specific trace with
```
amctl agent trace <agent> <traceId> ...
```
.

When anything in this flow returns a surprising envelope, check

references/troubleshooting.md

before reaching for a workaround.

创建Agent并确认其实际提供服务的流程。每个步骤的具体参数，请针对已安装的二进制文件运行

amctl <verb> --help

查看。

开始操作前需告知用户的示例计划：

text

我将创建Agent并确认其实际提供服务。具体步骤如下：
✦ 确认amctl已安装且您已登录
✦ 运行`amctl agent create --help`锁定当前参数集
✦ 创建Agent（自动构建并自动部署到`default`环境）
✦ 轮询构建状态直至完成或失败
✦ 通过日志/指标确认Agent存活
✦ 有流量后拉取最新追踪数据

创建Agent。 根据您的
```
--subtype
```
/
```
--build-type
```
/
```
--provisioning
```
组合，运行
```
amctl agent create --help
```
查看当前必填参数集，然后调用
```
amctl agent create <name> --project ... --json
```
。创建命令会自动构建并部署到最低环境（本地为
```
default
```
）。

轮询构建状态。

amctl agent build list <agent> --project <p> --json

返回按时间倒序的构建记录；提取

data.builds[0].buildName

。轮询

amctl agent build get <agent> <buildName> --project <p> --json

直至

data.status

变为

Completed

或

Failed

。在zsh中，循环变量不要命名为

status

——zsh将

$status

作为

$?

的只读别名。

确认Agent存活。
```
agent get
```
无法告知您状态。通过
```
amctl agent logs <agent> --project --env default --since 5m --json
```
查看日志，寻找otel-tracing初始化容器之后的应用级输出，或通过
```
amctl agent metrics ...
```
查看是否有≥1条
```
memoryUsage
```
样本。如果3分钟后仍未看到任何内容，请运行
```
references/triage.md
```
中的完整诊断流程。
有流量后查看追踪数据。 运行
```
amctl agent traces <agent> --project --env default --since 1h --json
```
。空列表表示Agent未运行、时间窗口过窄或创建时禁用了自动 instrumentation。可通过
```
amctl agent trace <agent> <traceId> ...
```
查看具体链路详情。

当流程中任何步骤返回异常响应包时，请先查看

references/troubleshooting.md

，再尝试其他解决方法。