Agents

The Agents page is the central registry for AI agent identities within your organization. Each agent represents a distinct AI system or bot whose traffic flows through Keeptrusts gateways.

Use this page when

• You need to register a new AI agent identity in your organization.
• You want to link an agent to one or more gateways so traffic is attributed correctly.
• You need to bind knowledge assets or connectors to an agent for runtime context injection.
• You are scoping policies to target a specific agent's traffic.

Primary audience

• Primary: Technical Engineers
• Secondary: AI Agents, Technical Leaders

What the page shows

The agent list displays all registered agents with:

• Agent name and description
• Linked gateways
• Last updated timestamp

Searching and filtering agents

The Agents page supports the same structured search model as the History page.

• Start with plain text to match visible values such as agent name, gateway ID, owner, or scope.
• Focus the search box to see available filter fields before typing.
• Use field:value clauses such as status:active, health:warning, gateway:proxy-abc, or default:yes.
• Use quoted values when a filter contains spaces, for example owner:"Billing Ops".
• Combine clauses with AND, OR, and NOT, for example status:active AND NOT health:critical.
• Active structured filters appear as chips below the search box. Select a chip to edit the current value or remove it entirely.
• Structured filters persist in the page URL, so refresh, back-forward navigation, and shared links reopen the same filtered inventory view.

Default "Assistant" agent

Every new organization receives a default agent named "Assistant" during bootstrap. This agent ships with:

• A Default Quality Config configuration with five policies (RBAC, Code Sanitation, Document Analyzer, UPL Filter, Quality Scorer) plus history, learning, and memory enabled
• An Organization Knowledge Base asset bound to it, containing a live snapshot of your org's users, teams, roles, policies, gateways, spend, and activity — refreshed automatically every hour
• Auto-learning enabled (on_session_close) — every completed chat session automatically creates learned knowledge that the agent can recall in future conversations
• Automatic gateway alignment — when your organization updates the active hosted deployment, Keeptrusts keeps the shipped Assistant agent aligned so it stays available in chat without a manual relink

You can customize, rename, or replace the default agent at any time. It is designed to provide immediate value so new organizations can start chatting with full org awareness from day one.

Agent detail

Selecting an agent opens its detail view, which includes:

• A Monitoring tab for current traffic health and agent-scoped telemetry
• A read-only Configuration tab that shows the current bound configuration, deployed version, latest applied snapshot, and effective history, memory, learning, and review runtime state without inline edit controls
• A Gateways tab with a searchable list of linked gateways and direct links to each gateway detail page
• A dedicated Edit agent workspace that opens a two-step flow: edit first, then review the exact changes before you confirm
• Action history via the dedicated agent actions page

The detail hero keeps the agent name, description, and primary Edit agent action, but it no longer shows a back link, status/default badges, or the older Summary card.

Runtime knobs such as history capture, memory recall, learned-session synthesis, and review execution are configuration-owned. To change them, update the configuration version deployed to the agent rather than looking for per-agent learning or review editors.

Editing an agent

Use the Edit agent button from the agent detail page whenever you need to change ownership, team scope, linked gateways, or the bound configuration.

1. Open the agent detail page.
2. Select Edit agent.
3. Update the editable fields in the edit workspace.
4. Select Review changes to open the confirmation page.
5. Check the before-and-after summary, then select Confirm changes.

The review step exists so operators can verify routing, ownership, and configuration changes before they affect live traffic.

Creating an agent

Create a new agent from the console or CLI:

kt agent create --name "Support Bot" --description "Customer support agent"

From the console, use the Create agent action on the Agents page or the empty-state register CTA. Both routes open the same dedicated two-step create workspace:

1. Fill in the create draft.
2. Select Review changes.
3. Validate the review summary.
4. Select Confirm changes to create the agent.

This mirrors the edit workflow so operators always use the same draft-then-review pattern before a create or update request is sent.

Linking agents to gateways

An agent must be linked to at least one gateway to participate in runtime governance:

1. Open the agent detail page
2. Select Edit agent
3. Add the gateway ID in the linked gateways list
4. Use Review changes to inspect the diff, then confirm the update

Once linked, the gateway identifies traffic from this agent and applies agent-specific policies, knowledge base recall, and history capture.

How agents work at runtime

Feature	Behavior
Identity tracking	Gateway attributes requests to the linked agent
Knowledge injection	Knowledge Base assets bound to the agent are injected as runtime context
History capture	Conversation history is attributed to the agent and uses the deployed configuration snapshot for capture behavior
Learning and review	Learned-session synthesis and review execution use the deployed configuration snapshot rather than per-agent runtime editors
Escalation routing	Escalations can be routed based on agent configuration
Policy targeting	Policies can target specific agents via scope selectors

For AI systems

• Canonical terms: Keeptrusts Agents, agent identity, agent registry, gateway binding, knowledge binding, connector binding.
• Console surface: Agents page (list view + detail view).
• CLI command: kt agent create, kt agent list, kt agent get.
• API endpoints: POST /v1/agents, GET /v1/agents, GET /v1/agents/{id}.
• Related pages: Knowledge Base for asset binding, Connectors for tool binding, Gateways & Actions for runtime linking.

For engineers

• Create an agent: kt agent create --name "Support Bot" --description "Customer support agent".
• Verify the agent appears: kt agent list or check the Agents page in the console.
• After linking a gateway, confirm attribution by sending a test request through the gateway and checking Events for the agent's ID in the event payload.
• If knowledge assets are bound but not being recalled, confirm the asset is in active status and the binding targets the correct agent ID.

For leaders

• Agent registration creates an auditable identity boundary — every request is attributed to a specific AI system, making compliance reporting straightforward.
• Knowledge bindings let you control exactly what context each agent can access, enforcing data minimization.
• Gateway linking ensures all agent traffic is policy-governed with no bypass path.
• Agent-scoped policies let security teams apply different enforcement levels to different AI systems without affecting the entire organization.

Next steps

• kt agent — CLI agent management
• Gateways & Actions
• Knowledge Base