Skip to main content

Agents in the Console

An agent is the durable identity that connects ownership, runtime configuration, gateways, tags, Context Fabric, monitoring, and audit evidence. Use Agents when several gateway instances or deployments represent one customer workload.

What an agent owns​

An agent record can carry:

  • a stable name and description;
  • owner and team context;
  • the selected configuration;
  • default-agent status;
  • managed-by metadata;
  • linked gateways;
  • tags;
  • Context Fabric state; and
  • health, event, allow, block, and cache signals.

An agent is not a model-provider credential and does not itself start a gateway. A gateway process must be bound to the agent and have a runnable provider configuration.

Create an agent​

  1. Open Agents and select Create agent.
  2. Enter a clear, durable identity. Prefer a workload name such as support-assistant-prod over a host name.
  3. Set ownership and team scope.
  4. Review the YAML document for identity, ownership, configuration, gateway IDs, and resource-tag fields.
  5. Save and open the new agent's detail view.

The form writes the agent document to the API. Creating the record does not prove that a gateway is connected or that a provider request succeeds.

Open the agent's Gateways tab to link or unlink gateway records. The console limits selection to compatible same-region gateways.

Before linking:

  • confirm the gateway's region and environment;
  • confirm that replacing an existing binding is intended;
  • identify which configuration version the gateway should run; and
  • preserve a rollback owner for production changes.

After linking, verify the binding on both the agent and gateway detail pages. Then send a representative supported request through the gateway. A displayed link is control-plane state, not end-to-end traffic proof.

Use the detail tabs​

TabUse it for
OverviewIdentity, ownership, configuration, status, health, and lifecycle context
MonitoringRequest, outcome, and cache signals for the selected agent
ContextContext Fabric pool and statistics
GatewaysSame-region gateway bindings
TagsResource classification and policy-aware metadata
AuditAgent-related Trail chronology

Use a narrow time window when investigating a change. Correlate the agent's configuration version, gateway, request ID, and Trail event rather than drawing a conclusion from one aggregate counter.

Edit and delete safely​

Use Edit to change the agent document. Review configuration, ownership, gateway references, and tags together because they can affect different operational teams.

The inventory supports bulk deletion, but protected default agents cannot be deleted through that action. Before deleting any other agent:

  1. Remove or migrate live gateway bindings.
  2. Confirm no token, automation, budget, tag workflow, or control manifest refers to it.
  3. Export required audit evidence.
  4. Confirm the replacement identity.
  5. Delete and verify the result in Trail.

Do not delete an agent merely to clear a transient health signal.

A production-ready agent​

An agent is ready only when all of these are true:

  • ownership and team scope are correct;
  • the intended configuration and version are selected;
  • required secrets resolve in the gateway environment;
  • the expected same-region gateway is bound and reporting;
  • Context Fabric and tags match the workload's data policy;
  • a representative request passes through the gateway; and
  • the resulting runtime and audit evidence can be found.

/healthz proves only gateway process health. It does not prove provider routing, policy evaluation, evidence delivery, or agent binding correctness.

CLI equivalent​

For automation, use:

kt agent list
kt agent get --agent-id agent_example
kt agent link-gateway \
  --agent-id agent_example \
  --gateway-id gateway_example

Use Agents CLI for the complete command workflow.

Next steps​