Skip to main content

kt agent

The kt agent command group manages control-plane agent records and their gateway bindings. These commands require API authentication; set KEEPTRUSTS_API_TOKEN or sign in with kt auth login first.

Read operations require the matching agent list/read action. Mutations use the more specific create, update, delete, bind-gateway, or unbind-gateway action. An organization-wide write role does not make a missing resource ID valid.

List agents​

kt agent list
kt agent list --status active
kt agent list --json

list also accepts the standard connection, profile, and region overrides. Use --json when you need configuration, gateway, tag, or publication fields that the compact table does not print.

Get one agent​

kt agent get --agent-id agent_abc123
kt agent get --agent-id agent_abc123 --json

Create an agent​

kt agent create --name "Customer Support Bot" --description "Handles tier-1 support queries"

Update an agent​

kt agent update --agent-id agent_abc123 --name "Customer Support Agent v2"

You can update the name, description, or status. The command fails when no field is supplied.

Delete an agent​

kt agent delete --agent-id agent_abc123 --yes

--yes is required; deletion does not prompt interactively.

kt agent link-gateway --agent-id agent_abc123 --gateway-id gw_xyz
kt agent list --json

Confirm that the intended agent now contains gw_xyz in gateway_ids. Linking is idempotent at the API layer for an existing pair.

kt agent unlink-gateway --agent-id agent_abc123 --gateway-id gw_xyz --yes

Unlinking also requires --yes. Linking changes the control-plane binding; it does not start or install a gateway process on the current machine.

After unlinking, inspect kt agent list --json again. Do not delete an agent as a substitute for unlinking one gateway.

Verify and troubleshoot​

kt auth whoami
kt agent get --agent-id agent_abc123 --json
kt agent list --json
  • 401 means the API token is missing, invalid, or expired.
  • 403 means the current identity lacks the specific agent action.
  • 404 usually means the ID is absent in the current organization or requested region.
  • A successful binding with no running traffic means only that control-plane state changed. Check the gateway process and its selected agent separately.

Next steps​