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 <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:

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.

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:

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.