CLI

verdictan agent

An agent is the saved identity and configuration for an application in the control plane. A gateway is the program that receives the application's requests. Use verdictan agent to manage agent records and to link each agent to the gateways that serve it.

Before you start

Set VERDICTAN_API_TOKEN, or sign in with verdictan auth login.
Get the permission for each subcommand:

Subcommand Permission
list agents:list
get agents:read
create agents:create
update agents:update
delete agents:delete
link-gateway agents:bind_gateway
unlink-gateway agents:unbind_gateway
An agent that belongs to a team also needs that permission for the team's agents. Without it, the API answers HTTP 404 with agents.not_found, as if the agent did not exist.
Agent IDs are UUIDs. Gateway IDs are the gateway_id values from verdictan gateway list --remote.

Subcommand	Permission
`list`	`agents:list`
`get`	`agents:read`
`create`	`agents:create`
`update`	`agents:update`
`delete`	`agents:delete`
`link-gateway`	`agents:bind_gateway`
`unlink-gateway`	`agents:unbind_gateway`

Create and link an agent

Find your agent:
```
verdictan agent list
```
Each line shows <id> <name> <status>.

If your agent is not in the list, create it:

verdictan agent create \
  --name "Support Bot" \
  --description "Answers support questions"

The command prints created agent <id>. Copy the ID.

Find a gateway with verdictan gateway list --remote. Copy its ID. Then link the gateway to the agent:

AGENT_ID="replace-with-your-agent-id"
GATEWAY_ID="replace-with-your-gateway-id"
verdictan agent link-gateway \
  --agent-id "$AGENT_ID" \
  --gateway-id "$GATEWAY_ID"

Verify the link:

verdictan agent get --agent-id "$AGENT_ID" --json | jq '.gateway_ids'

The array contains your gateway ID.

A link changes control-plane records only. It does not install or start a gateway process. Continue with verdictan gateway run, or follow the Quickstart for the complete setup.

Command reference

verdictan agent list [--status <status>] [--json]
verdictan agent get --agent-id <id> [--json]
verdictan agent create --name <name> [--description <text>] [--json]
verdictan agent update --agent-id <id> [--name <name>] [--description <text>] [--status <status>] [--json]
verdictan agent delete --agent-id <id> --yes [--json]
verdictan agent link-gateway --agent-id <id> --gateway-id <id> [--json]
verdictan agent unlink-gateway --agent-id <id> --gateway-id <id> --yes [--json]

list sends GET /v1/agents. The API returns one page of at most 50 agents, newest first. The CLI does not request more pages. With --json, the response also has next_cursor, which is set when more agents exist.

get prints the ID, name, description, status, and timestamps. With --json, the response also has fields such as gateway_ids, configuration_id, published_endpoints, resource_tags, and is_default.

Options

Flag	Applies to	Description
`--agent-id <id>`	All except `list` and `create`	Required. The agent ID.
`--status <status>`	`list`, `update`	For `list`, return only agents with this status. For `update`, set the status. The values are `active`, `inactive`, and `suspended`.
`--name <name>`	`create`, `update`	Agent name. It must be unique in the organization. Required for `create`.
`--description <text>`	`create`, `update`	Description.
`--gateway-id <id>`	`link-gateway`, `unlink-gateway`	Required. The gateway ID to link or unlink.
`--yes`	`delete`, `unlink-gateway`	Confirm the change. Without it, the command stops with `pass --yes to confirm ...` and changes nothing.
`--json`	All	Print the API response as JSON, not the text summary.
`--config <path>`, `--api-url <url>`, `--profile <name>`, `--region <region>`	All	Connection and profile overrides. The default profile is `default`.

Disable or remove an agent

To stop using an agent and keep its record, change its status:

verdictan agent update --agent-id "$AGENT_ID" --status inactive

To remove one gateway link:

verdictan agent unlink-gateway --agent-id "$AGENT_ID" --gateway-id "$GATEWAY_ID" --yes

When you unlink the last gateway of the agent, the API also disables the agent's published publications.

Delete the agent only when you no longer need its configuration and published endpoints:

verdictan agent delete --agent-id "$AGENT_ID" --yes

These commands change organization resources immediately. Check the IDs before you run them.

Limits and failure behavior

One gateway serves one agent. Linking a gateway that serves a different agent returns HTTP 409 with gateway_already_bound. Unlink it from the other agent first.
link-gateway is idempotent for the same agent and gateway. A second call does not create a second link.
When you link a gateway, the API can publish the agent's draft publications.
delete fails with HTTP 409 and agents.publications_active while the agent has published publications. Pause or drain the agent first. Draining publications do not stop the delete.
update stops with nothing to update: provide --name, --description, or --status when you pass none of those flags.
delete and unlink-gateway do not prompt. They need --yes.
Do not delete an agent to remove a link. Use unlink-gateway.

Troubleshooting

Symptom	Cause	Fix
missing api token (set VERDICTAN_API_TOKEN or run `verdictan auth login`)	No token in the environment or the profile.	Set `VERDICTAN_API_TOKEN`, or run `verdictan auth login`.
`api authentication failed (401)`	The token is invalid or expired.	Sign in again, or use a valid token.
`api authorization failed (403)`	The credential does not have the permission for the subcommand.	Check the permission table in Before you start.
`api request failed with status 400`	The agent ID is not a UUID (`agents.invalid_id`).	Copy the ID from `verdictan agent list`.
`api request failed with status 404`	The agent does not exist in the organization, or it belongs to a team that you have no permission for.	Check the ID, the profile, and your team permissions.
`api validation failed (422)` on `list`	`--status` is not `active`, `inactive`, or `suspended`.	Use one of those values.
`api validation failed (422)` on `link-gateway`	The gateway ID is not in this organization (`agents.invalid_gateway`).	Copy the ID from `verdictan gateway list --remote`.
`api conflict (409)`	The name is already in use (`agents.duplicate_name`), the gateway serves another agent, or the agent has active publications.	Choose a different name, unlink the gateway from the other agent, or disable the publications.
`api request failed with status 500` on `update`	`--status` is not `active`, `inactive`, or `suspended`.	Use one of those values.
The link succeeds, but the gateway receives no traffic.	A link does not start or configure the gateway process.	Examine the gateway runtime and the agent that it serves.

Next steps

Agents: create and review the same agent records in the Console.
verdictan gateway: install and run the gateway that serves a linked agent.
verdictan control: declare agents and gateway links in a control manifest.

Before you start​

Create and link an agent​

Command reference​

Options​

Disable or remove an agent​

Limits and failure behavior​

Troubleshooting​

Next steps​