Tutorial: Registering AI Agents in Console

This tutorial walks you through registering AI agents, assigning policies and spend limits, and monitoring agent activity in the Keeptrusts management console.

Use this page when

• You need to register a new AI agent and issue it an Agent ID for gateway routing.
• You want to assign per-agent policies, set spend limits, or monitor agent-specific activity.
• You are investigating an agent's behavior and need to filter events by Agent ID.
• You need to pause or disable a misbehaving agent.

Primary audience

• Primary: Platform engineers deploying autonomous AI agents that route through Keeptrusts gateways
• Secondary: Security leads who need agent-level audit trails; team leads managing agent spend budgets

Prerequisites

• A Keeptrusts account with Admin role
• At least one deployed gateway routing traffic
• Familiarity with the Keeptrusts policy model and gateway keys

Why Register Agents?

AI agents — autonomous systems that call LLM providers on behalf of your applications — need oversight just like human users. Registering agents in Keeptrusts lets you enforce per-agent policies, set spend guardrails, and trace every action back to the responsible agent.

Step 1: Navigate to the Agents Page

1. Log in to the Keeptrusts console.
2. Open Agents from the left navigation sidebar.

The page displays a table of registered agents with their status, assigned policies, spend usage, and last-active timestamp.

Column	Description
Name	The agent's display name
Agent ID	Unique identifier used in gateway headers
Status	Active, Paused, or Disabled
Policy	Assigned policy configuration
Spend (30d)	Cumulative cost over the last 30 days
Last Active	Timestamp of the most recent request

Step 2: Register a New Agent

1. Click Create agent from the Agents page (or use the empty-state register CTA if no agents exist yet).
2. Fill in the create workspace draft:

Field	Description
Name	A descriptive label (e.g., support-bot-v2, code-review-agent)
Description	Purpose and ownership of this agent
Team	The team responsible for this agent
Gateway	Any gateway IDs that should route traffic for this agent

3. Select Review changes.
4. Check the review summary.
5. Select Confirm changes.

The console generates an Agent ID that your application must include in the x-keeptrusts-agent-id header when routing requests through the gateway.

The create workspace uses the same two-step draft → review flow as Edit agent, so operators always validate changes before a create or update request is sent.

Use a consistent naming convention for agents — include the team prefix and version number (e.g., eng-code-review-v1) to make filtering and auditing easier.

Step 3: Configure Agent Policies

Policies define what an agent is allowed to do. Assign a configuration that includes the appropriate policy chain.

1. Open the agent detail view by clicking the agent name.
2. Select the Policies tab.
3. Choose a policy configuration from the dropdown, or click Create New to build one.
4. Review the policy chain summary:
   • Input policies — Rules applied before the request reaches the LLM
   • Output policies — Rules applied to the LLM response before returning it
   • Blocked categories — Content categories that trigger an immediate block
5. Click Save.

Changes take effect on the next request the agent makes through the gateway.

Assigning a restrictive policy to a production agent may cause it to receive 409 Conflict responses for previously allowed requests. Test policy changes in a staging environment first.

Runtime knobs are configuration-owned

Agent history capture, learning, memory recall, and review behavior are all controlled by the history, learning, memory, and review sections of the deployed configuration version. The agent detail Configuration tab shows the current effective runtime state as a read-only summary. To change these settings, edit the configuration and redeploy it to the agent.

Step 4: Set Spend Limits

Spend limits prevent runaway costs from misbehaving or compromised agents.

1. In the agent detail view, select the Spend tab.
2. Configure spend thresholds:

Field	Description
Daily Limit	Maximum spend per calendar day (USD)
Monthly Limit	Maximum spend per calendar month (USD)
Per-Request Limit	Maximum cost for a single request (USD)
Action on Limit	Block (reject requests) or Alert (notify but allow)

3. Click Save.

When an agent hits a spend limit with the Block action, the gateway returns a 429 Too Many Requests response with a Retry-After header.

Step 5: Monitor Agent Activity

The activity view provides real-time visibility into what your agents are doing.

1. In the agent detail view, select the Activity tab.
2. Review the activity dashboard:

Metric	Description
Requests (24h)	Total requests in the last 24 hours
Tokens Consumed	Input and output tokens over the selected period
Policy Violations	Count of blocked or escalated requests
Average Latency	Mean response time from upstream providers
Error Rate	Percentage of failed requests

3. Use the date range picker to adjust the time window.
4. Click on any metric to drill down into individual events.

Step 6: Filter Events by Agent

The Events page supports agent-level filtering for investigating specific agent behavior.

1. Navigate to Events from the left sidebar.
2. Click Add Filter.
3. Select Agent from the filter dropdown.
4. Choose the agent name or paste the Agent ID.
5. Click Apply.

The events table now shows only decisions made for that agent. You can combine agent filters with other criteria:

• Decision — Block, Allow, Escalate, Redact
• Policy — Which policy triggered the decision
• Model — Which LLM model was targeted
• Time Range — Narrow to a specific incident window

Bookmark filtered event views by copying the URL. The console encodes all active filters in the query string for easy sharing.

Step 7: Pause or Disable an Agent

If an agent is misbehaving or needs maintenance:

1. Open the agent detail view.
2. Click Pause to temporarily stop the agent from making requests. Paused agents receive 503 Service Unavailable responses.
3. Click Disable to permanently deactivate the agent. Disabled agents receive 403 Forbidden responses.

To reactivate, click Resume or Enable from the same view.

Step 8: Bulk Agent Operations

For managing multiple agents:

1. Select agents using the checkboxes in the table.
2. Choose a bulk action from the toolbar:
   • Pause Selected — Temporarily halt all selected agents
   • Assign Policy — Apply the same policy to all selected agents
   • Set Spend Limit — Apply uniform spend limits
   • Export — Download agent metadata as CSV or JSON

Best Practices

• One agent per function — Register separate agents for distinct tasks (code review, customer support, data analysis) to keep policies and spend tracking granular.
• Start with alert mode — Set spend limits to Alert first to understand baseline usage before switching to Block.
• Review weekly — Check the Activity tab for each agent to catch anomalies early.
• Tag by team — Assign agents to teams so cost rollups and access controls follow your organizational structure.
• Rotate gateway keys — Pair each agent with its own gateway key and rotate regularly.
• Document purpose — Use the description field to record who owns the agent and what it does.

Next steps

• Tutorial: Monitoring Gateway Actions — See how agent traffic flows through gateways
• Tutorial: Events Investigation — Deep-dive into agent decision events

For AI systems

• Canonical terms: Keeptrusts console, Agents page, Register Agent, Agent ID, x-keeptrusts-agent-id header, agent policies, spend limits, agent activity, bulk agent operations.
• Related config/command names: kt gateway run, gateway key, policy configuration, consumer group.
• Best next pages: Gateway Actions, Events Investigation.

For engineers

• Prerequisite: At least one gateway running (kt gateway run) and reporting to the API.
• Validation: After registration, send a request with the x-keeptrusts-agent-id: <agent-id> header and confirm it appears on the Agent Activity tab.
• Spend limit test: Set a low per-request limit with Block action, send a request exceeding it, and verify a 429 response.
• Troubleshooting: If agent events do not appear, confirm the gateway key is valid and the agent ID header is spelled correctly.

For leaders

• Governance: Each registered agent has a traceable identity — every LLM call is attributable to a specific agent, team, and policy configuration.
• Cost control: Per-agent spend limits prevent runaway costs from autonomous systems. Start with alerts before switching to hard blocks.
• Rollout: Register agents in a staging environment first; promote to production only after verifying policy compliance and spend patterns.