# Manage Agent

> Use when an agent needs to drive the full agent-manager lifecycle through `amctl` — install the CLI, log in, create/deploy an agent, list projects and agents, watch build progress, fetch build/runtime logs and metrics, and pull traces.

- Skill: `wso2/manage-agent` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add wso2/manage-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wso2/manage-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: wso2 (https://skillmd.com/u/wso2)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wso2/manage-agent

---


# manage-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.

## 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.

## Install

If `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`.

## Iron rules

1. **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.
2. **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.
3. **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.
4. **Runtime commands (`logs`, `metrics`, `traces`, `trace`, `traces export`) require `--env <name>`.** Use `--env default` for local dev.
5. **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`.
6. **`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`.
7. **Validation errors come batched** in `error.additionalData.details`. Read the full list, fix everything, retry — don't fix one at a time.

## 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. |

## 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
```

1. **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 <p> ... --json`. The create call auto-builds and auto-deploys to the lowest environment (`default` locally).
2. **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` is `Completed` or `Failed`. In zsh, name the loop variable anything except `status` — zsh reserves `$status` as a read-only alias for `$?`.
3. **Confirm liveness.** `agent get` won't tell you. Tail `amctl agent logs <agent> --project <p> --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`.
4. **Watch traces once there's traffic.** `amctl agent traces <agent> --project <p> --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.