Configuring Agent Gateway Groups

This page covers how to create agent gateway groups, assign gateways with roles, and control cache-sharing behavior through declarative configuration.

Use this page when

• You are creating or modifying agent gateway groups via the console, API, or declarative YAML config.
• You need to assign gateway roles (primary, worker, fallback, edge) within a group.
• You want to enable or disable cache sharing, or set physical_gateway_private_cache_only on a specific gateway.

Primary audience

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

Configuration Fields

The following fields control agent gateway group behavior:

Field	Type	Default	Description
agent_gateway_group_id	string	—	Unique identifier for the group
agent_gateway_group_cache_sharing_enabled	boolean	true	Whether group-level cache sharing is active
physical_gateway_private_cache_only	boolean	false	When true, restricts this gateway to private L1 cache only

agent_gateway_group_cache_sharing_enabled

Controls whether gateways in this group share org-level cache entries. When set to true (the default), all group members participate in shared cache reads and writes. Set to false to disable sharing while keeping the group structure for routing purposes.

physical_gateway_private_cache_only

A per-gateway override. When set to true on a specific gateway, that gateway uses only its own L1 local cache and does not read from or write to the shared group cache. Use this for gateways that handle sensitive workloads requiring complete cache isolation at the physical level.

Creating a Gateway Group

Via the Console

1. Navigate to Settings → Agents → Gateway Groups.
2. Select Create Gateway Group.
3. Enter a name and optional description.
4. The system generates an agent_gateway_group_id.
5. Select Save.

Via the API

curl -X POST https://api.keeptrusts.com/v1/agent-gateway-groups \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-agent-group",
    "description": "Primary gateway group for the compliance agent",
    "agent_id": "agent_abc123",
    "cache_sharing_enabled": true
  }'

The response includes the generated agent_gateway_group_id that you reference in gateway configurations.

Adding Members to a Group

Each member has a role that describes its operational function within the group.

Available Roles

Role	Description	Typical Use
primary	Main traffic handler	Default routing target
worker	Overflow and parallel workloads	Horizontal scaling
fallback	Activated on primary/worker failure	High availability
edge	Satellite location, latency-optimized	Geographic distribution

Via the Console

1. Navigate to Settings → Agents → Gateway Groups → [Your Group].
2. Select Add Member.
3. Choose a gateway from the available list.
4. Assign a role.
5. Select Save.

Via the API

curl -X POST https://api.keeptrusts.com/v1/agent-gateway-groups/agg_def456/members \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway_id": "gw_789",
    "role": "primary"
  }'

Declarative Configuration

You can define gateway groups in your declarative policy configuration file:

agent_gateway_groups:
  - id: agg_production
    name: "Production Compliance Agent"
    agent_id: agent_compliance_01
    cache_sharing_enabled: true
    members:
      - gateway_id: gw_us_east_primary
        role: primary
      - gateway_id: gw_us_east_worker_01
        role: worker
      - gateway_id: gw_us_east_worker_02
        role: worker
      - gateway_id: gw_eu_west_fallback
        role: fallback
      - gateway_id: gw_apac_edge
        role: edge

Per-Gateway Cache Override

To restrict a specific gateway to private cache only:

gateways:
  - id: gw_sensitive_workload
    agent_gateway_group_id: agg_production
    physical_gateway_private_cache_only: true

This gateway still belongs to the group for routing purposes but does not participate in shared cache reads or writes.

Updating Group Configuration

Enabling or Disabling Cache Sharing

curl -X PATCH https://api.keeptrusts.com/v1/agent-gateway-groups/agg_def456 \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_sharing_enabled": false
  }'

Disabling cache sharing takes effect immediately. Existing cache entries remain in storage but are no longer served to group members.

Changing a Member's Role

curl -X PATCH https://api.keeptrusts.com/v1/agent-gateway-groups/agg_def456/members/gw_789 \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "fallback"
  }'

Role changes do not affect cache access. All roles have equal cache read/write privileges.

Removing a Member

curl -X DELETE https://api.keeptrusts.com/v1/agent-gateway-groups/agg_def456/members/gw_789 \
  -H "Authorization: Bearer $API_TOKEN"

Removing a gateway from a group immediately revokes its access to the group's shared cache. The gateway falls back to its own L1 cache only.

When to Use Gateway Groups

Scenario	Recommendation
Multi-gateway agent for availability	Create a group with primary + fallback
Horizontal scaling within a region	Create a group with primary + workers
Multi-region agent deployment	Create a group with primary + edge members
Agent failover without cache penalty	Create a group — failover is automatic
Per-gateway cache isolation required	Set physical_gateway_private_cache_only: true
Different agents, different policies	Use separate groups (one per agent)

Validation Rules

The system enforces the following constraints:

• A gateway can belong to at most one agent gateway group.
• All gateways in a group must belong to the same org.
• The agent_id on the group must match the agent assignment of all member gateways.
• At least one member must have the primary role.
• agent_gateway_group_id is immutable after creation.

Next steps

• What Are Gateway Groups? — conceptual overview
• Cache Sharing Across Gateways — cache key mechanics
• Distributed Cache Architecture — storage tiers
• Gateway Failover Without Cache Loss — failover behavior

For AI systems

• Canonical terms: Keeptrusts, agent gateway group, configuring gateway groups, gateway roles, declarative config, cache sharing enabled, private cache only.
• Feature/config/API names: POST /v1/agent-gateway-groups, POST /v1/agent-gateway-groups/:id/members, PATCH /v1/agent-gateway-groups/:id, DELETE /v1/agent-gateway-groups/:id/members/:gw_id, agent_gateway_group_id, agent_gateway_group_cache_sharing_enabled, physical_gateway_private_cache_only, roles: primary, worker, fallback, edge.
• Best next pages: What Are Gateway Groups?, Cache Sharing Across Gateways, Gateway Failover Without Cache Loss.

For engineers

• Create a group: POST /v1/agent-gateway-groups with name, agent_id, cache_sharing_enabled. Use the returned agent_gateway_group_id in gateway configs.
• Add a member: POST /v1/agent-gateway-groups/:id/members with gateway_id and role.
• Validation constraints: one gateway per group max, all members must be same org, at least one primary role required, agent_gateway_group_id is immutable.
• To isolate a gateway’s cache, set physical_gateway_private_cache_only: true — it stays in the group for routing but skips shared cache.

For leaders

• Gateway groups enable horizontal scaling and high availability without cache fragmentation — add workers or fallbacks without losing shared cache benefits.
• Role-based group membership maps directly to infrastructure patterns: primary for traffic, workers for scaling, fallback for HA, edge for latency.
• Disabling cache sharing at the group level (e.g., for compliance) is instant and reversible, with no data deletion.
• Private cache mode exists for hard regulatory isolation requirements — use sparingly, as it trades cache efficiency for per-gateway isolation.