Access Control (Builder)

Configure all 4 access control dimensions for your agents

Builder Guide: Configuring Agent Access Control

This guide is for builders who create and configure agents in Agent Studio. It explains how to set up the four dimensions of access control when building an agent.

All four dimensions follow a default-deny principle. If access is not explicitly granted, it is denied.

Where to configure: Agent Studio > Agent Designer (/studio/agents/[id]) > Access, Tools, Interactions, and Model tabs.

Table of Contents

• Overview: Four Access Control Dimensions
• Dimension 1: User Access (Entitlements)
• Dimension 2: Tool Access (Tool Grants)
• Dimension 3: Agent-to-Agent Access (Interaction Policy)
• Dimension 4: Model Access
• Complete Agent Config Example
• Deploy Pipeline Access Review
• Best Practices

Overview: Four Access Control Dimensions

Every agent has four independent access control layers, each configured in the Agent Designer:

These dimensions are enforced at different layers of the platform:

• Dimension 1 is enforced at the API Gateway (L1). The GET /api/agents endpoint only returns agents the requesting user is entitled to see.
• Dimension 2 is enforced at the MCP Gateway (L5). Tool invocations are checked against the agent's tool grants.
• Dimension 3 is enforced at the Agent Orchestrator (L2). Delegation requests are checked against interaction policies.
• Dimension 4 is enforced at the Model Access PEP (L7), sitting in front of T-Systems AIFS.

Dimension 1: User Access (Entitlements)

Controls which users within the tenant can discover, see, and interact with the agent.

Configuration Interface

Located in Agent Designer > Access tab.

Visibility Modes

Entitlements Fields

interface AgentEntitlements {
  visibility: 'public' | 'restricted' | 'private';
  allowedGroups?: string[];   // IdP groups, e.g. ['hr-team', 'finance']
  allowedUsers?: string[];    // Specific platform user IDs
  allowedRoles?: string[];    // IdP roles, e.g. ['manager', 'director']
  owners: string[];           // Builder user IDs who can edit this agent
  ownerGroups?: string[];     // Builder groups who can edit
}

JSON Config Example

{
  "entitlements": {
    "visibility": "restricted",
    "allowedGroups": ["hr-team", "executives"],
    "allowedRoles": ["manager"],
    "allowedUsers": [],
    "owners": ["user-builder-1"],
    "ownerGroups": ["engineering"]
  }
}

This configuration means:

• Members of the hr-team or executives groups can see and use the agent.
• Any user with the manager role can see and use the agent.
• user-builder-1 can edit the agent configuration.
• Members of the engineering group can also edit the agent.

How Groups and Roles Are Populated

Groups and roles come from the tenant's identity provider (IdP). In the Agent Designer, the group picker is populated from the GET /api/groups endpoint, which returns IdP groups synced via SCIM 2.0 or cached via JIT provisioning. You select from real IdP groups -- this is not free-text input.

The Access tab shows a live preview: "This agent is visible to X users based on current entitlements."

Cedar Policy Equivalent

permit(
  principal,
  action == Action::"chat",
  resource
) when {
  resource.type == "agent" &&
  resource.visibility == "restricted" &&
  principal.tenant_id == resource.tenant_id &&
  principal.groups.containsAny(resource.allowed_groups)
};

Dimension 2: Tool Access (Tool Grants)

Controls which MCP tools the agent can discover and invoke at runtime.

Configuration Interface

Located in Agent Designer > Tools tab. The tab shows the MCP tool catalog, which is searchable and filterable by risk level. You check tools to grant them to the agent.

Tool Grants Fields

interface AgentToolGrants {
  tools: ToolGrant[];
  dynamicDiscovery: boolean;         // default: false
  maxToolCallsPerExecution: number;  // default: 20
}

interface ToolGrant {
  toolId: string;
  permissions: ('read' | 'write' | 'execute')[];
  conditions?: {
    maxCallsPerHour?: number;        // Rate limit per tool
    requireApproval?: boolean;       // HITL approval for each invocation
    timeWindow?: {
      start: string;                 // e.g. "09:00"
      end: string;                   // e.g. "17:00"
    };
  };
}

Tool Risk Levels

Every tool in the MCP Registry has a risk classification. The risk level determines the default behavior when granting:

JSON Config Example

{
  "toolGrants": {
    "tools": [
      {
        "toolId": "tool-db-query",
        "permissions": ["read", "execute"],
        "conditions": {
          "maxCallsPerHour": 100
        }
      },
      {
        "toolId": "tool-send-email",
        "permissions": ["execute"],
        "conditions": {
          "requireApproval": true,
          "timeWindow": { "start": "09:00", "end": "17:00" }
        }
      },
      {
        "toolId": "tool-jira-read",
        "permissions": ["read"]
      }
    ],
    "dynamicDiscovery": false,
    "maxToolCallsPerExecution": 20
  }
}

This configuration means:

• The agent can query the database (read-only, up to 100 calls per hour).
• The agent can send emails, but only during business hours (09:00--17:00) and each send requires human approval.
• The agent can read Jira tickets with no conditions.
• The agent cannot discover tools not in this list (dynamicDiscovery: false).
• The agent is limited to 20 total tool calls per execution as a circuit breaker.

What Happens at Runtime

1. Agent calls mcp.tool.invoke(toolId, input).
2. MCP Gateway looks up the agent's tool grants.
3. If the tool is not in the grants list, the gateway returns a 403 error and the tool is invisible to the agent.
4. If the tool has conditions, they are evaluated (rate limit checked in Redis, time window checked, approval triggered if required).
5. If conditions pass, the call is forwarded to the tool. The decision is logged in the audit trail.

Cedar Policy Equivalent

permit(
  principal,
  action == Action::"invoke",
  resource
) when {
  principal.type == "agent" &&
  resource.type == "tool" &&
  principal.tenant_id == resource.tenant_id &&
  principal.granted_tools.contains(resource.tool_id)
};

// Block high-risk tool without HITL approval
forbid(
  principal,
  action == Action::"invoke",
  resource
) when {
  resource.type == "tool" &&
  resource.risk_level == "high" &&
  context.hitl_approval != true
};

Dimension 3: Agent-to-Agent Access (Interaction Policy)

Controls which other agents this agent can invoke via A2A (Agent-to-Agent) protocol, and which agents can invoke this one.

Configuration Interface

Located in Agent Designer > Interactions tab. The tab shows multi-select dropdowns for "Can invoke" and "Can be invoked by," along with a visual mini-graph of the interaction topology.

Interaction Policy Fields

interface AgentInteractionPolicy {
  canInvoke: AgentInvokeGrant[];
  invocableBy: AgentCallerGrant[];
  discoverable: boolean;            // default: true for active agents
}

interface AgentInvokeGrant {
  agentId: string;
  maxDelegationsPerExecution: number;  // Prevent infinite loops
  requireApproval?: boolean;
}

interface AgentCallerGrant {
  agentId: string;
}

JSON Config Example

{
  "interactionPolicy": {
    "canInvoke": [
      {
        "agentId": "agent-data-analyst",
        "maxDelegationsPerExecution": 3,
        "requireApproval": false
      },
      {
        "agentId": "agent-email-sender",
        "maxDelegationsPerExecution": 1,
        "requireApproval": true
      }
    ],
    "invocableBy": [
      { "agentId": "agent-orchestrator-1" },
      { "agentId": "agent-project-manager" }
    ],
    "discoverable": true
  }
}

This configuration means:

• This agent can invoke the data analyst agent (up to 3 delegations per execution) and the email sender agent (1 delegation, requires human approval).
• This agent can be invoked by the orchestrator and the project manager agents.
• This agent is discoverable by other agents in the A2A registry.

Interaction Patterns

Hub-and-Spoke: A central orchestrator agent can call specialist agents, but specialists cannot call each other. Configure canInvoke on the orchestrator and invocableBy on the specialists.

Peer Network: Agents in the same domain can call each other. Each agent lists the others in both canInvoke and invocableBy.

Hierarchical: Agents can only call agents at the same or lower risk classification. This prevents privilege escalation (an assistive agent should not invoke an autonomous agent).

Loop Prevention

The platform enforces multiple loop prevention mechanisms:

• maxDelegationsPerExecution: Hard cap on how many times this agent can delegate to a specific target within one execution.
• Execution depth counter: Incremented on each delegation. Maximum depth is 5 by default.
• Cycle detection: If an agent appears twice in the same trace's delegation chain, the call is blocked.

Cedar Policy Equivalent

// Allow delegation if both sides agree
permit(
  principal,
  action == Action::"delegate",
  resource
) when {
  principal.type == "agent" &&
  resource.type == "agent" &&
  principal.tenant_id == resource.tenant_id &&
  principal.invoke_grants.contains(resource.id) &&
  resource.invocable_by.contains(principal.id)
};

// Block privilege escalation
forbid(
  principal,
  action == Action::"delegate",
  resource
) when {
  principal.type == "agent" &&
  resource.type == "agent" &&
  principal.risk_classification == "assistive" &&
  resource.risk_classification == "autonomous"
};

// Enforce max delegation depth
forbid(
  principal,
  action == Action::"delegate",
  resource
) when { context.callDepth > 5 };

Dimension 4: Model Access

Controls which LLM models the agent can use via T-Systems AIFS, along with cost guardrails.

Configuration Interface

Located in Agent Designer > Model tab. The model dropdown shows an availability indicator per model: a green checkmark for allowed models, a lock icon with a "Restricted by tenant policy" tooltip for denied models.

Model Access Fields

interface AgentModelAccess {
  allowedModels?: string[];        // Explicit model IDs
  allowedModelTags?: string[];     // e.g. ['eu-hosted', 'open-source', 'budget-tier']
  deniedModels?: string[];         // Explicit deny (overrides allow)
  maxCostPerRequest?: number;      // Dollar cap per single LLM call
  maxCostPerDay?: number;          // Daily spend cap for this agent
  maxTokensPerRequest?: number;    // Token cap per call
}

JSON Config Example

{
  "modelAccess": {
    "allowedModels": ["claude-sonnet-4", "Llama-3.3-70B-Instruct"],
    "allowedModelTags": ["eu-hosted"],
    "deniedModels": ["o3", "gemini-2.5-pro"],
    "maxCostPerRequest": 0.50,
    "maxCostPerDay": 25.00,
    "maxTokensPerRequest": 4096
  }
}

This configuration means:

• The agent can use claude-sonnet-4 and Llama-3.3-70B-Instruct explicitly, plus any model tagged eu-hosted.
• The agent is explicitly denied access to o3 and gemini-2.5-pro (deny overrides allow).
• Each LLM call is capped at $0.50 and 4,096 tokens.
• The agent's total daily spend is capped at $25.00.

Available Models and Tags

Models available through T-Systems AIFS, with their hosting and cost classifications:

Common model tags for allowedModelTags:

• eu-hosted -- Only models hosted within T-Systems EU infrastructure
• open-source -- Only open-source models
• budget-tier -- Only budget-tier cost models

Tenant-Level Restrictions

Your tenant administrator may set tenant-level model policies that restrict all agents in the tenant. These restrictions appear as locked/grayed-out models in the Model tab with a "Restricted by tenant policy" tooltip.

Agent-level policies can only further restrict access within what the tenant allows. You cannot grant access to a model that the tenant policy denies.

Fallback Behavior

When the primary model is denied by policy, the platform automatically tries the agent's configured fallback model:

Agent configured: primary = claude-sonnet-4, fallback = Llama-3.3-70B-Instruct

Scenario: Tenant policy denies external models
  1. Agent calls claude-sonnet-4 -> Model Access PEP -> DENIED (external)
  2. Platform auto-retries with Llama-3.3-70B-Instruct -> ALLOWED (eu-self-hosted)
  3. Agent gets response from fallback model
  4. Audit log records: "Primary model denied, fallback used"

Always configure a fallback model, especially if your primary model could be restricted by tenant policy.

Cedar Policy Equivalent

// Budget agents: budget/standard tier only
forbid(
  principal,
  action == Action::"model:invoke",
  resource
) when {
  principal.type == "agent" &&
  principal.riskClassification == "assistive" &&
  resource.costTier in ["premium", "reasoning"]
};

// Daily cost cap enforcement
forbid(
  principal,
  action == Action::"model:invoke",
  resource
) when {
  principal.type == "agent" &&
  context.agentDailySpend >= principal.maxCostPerDay
};

Complete Agent Config Example

Below is a complete AgentConfig showing all four access control dimensions configured together:

{
  "systemPrompt": "You are an HR assistant that helps employees with benefits questions.",
  "model": {
    "primary": "claude-sonnet-4",
    "fallback": "Llama-3.3-70B-Instruct",
    "temperature": 0.3,
    "maxTokens": 2048
  },
  "tools": [
    { "id": "tool-hr-db", "name": "HR Database Query", "mcpEndpoint": "mcp://hr-db" }
  ],
  "memory": {
    "shortTerm": true,
    "longTerm": true,
    "graph": false,
    "procedural": false,
    "ttlDays": 30
  },
  "hitl": {
    "enabled": true,
    "riskThreshold": 60,
    "escalationChain": ["user-hr-manager"]
  },
  "guardrails": {
    "inputPolicies": ["pii-detection", "prompt-injection"],
    "outputPolicies": ["pii-leak-prevention", "hallucination-check"]
  },
  "entitlements": {
    "visibility": "restricted",
    "allowedGroups": ["hr-team", "executives"],
    "allowedRoles": ["manager"],
    "owners": ["user-builder-1"]
  },
  "toolGrants": {
    "tools": [
      {
        "toolId": "tool-hr-db",
        "permissions": ["read", "execute"],
        "conditions": { "maxCallsPerHour": 50 }
      }
    ],
    "dynamicDiscovery": false,
    "maxToolCallsPerExecution": 10
  },
  "interactionPolicy": {
    "canInvoke": [],
    "invocableBy": [
      { "agentId": "agent-orchestrator-1" }
    ],
    "discoverable": true
  },
  "modelAccess": {
    "allowedModels": ["claude-sonnet-4", "Llama-3.3-70B-Instruct"],
    "allowedModelTags": ["eu-hosted"],
    "deniedModels": [],
    "maxCostPerRequest": 0.25,
    "maxCostPerDay": 10.00,
    "maxTokensPerRequest": 2048
  }
}

Deploy Pipeline Access Review

When deploying an agent, the pipeline includes an Access Review gate that validates all four dimensions before allowing the deployment to proceed.

What the Access Review Checks

Best Practices

Principle of Least Privilege

• Start with private visibility during development. Switch to restricted for testing with a specific group, then public only if the agent is truly for everyone.
• Grant only the tools the agent actually needs. Avoid granting tools "just in case."
• Set dynamicDiscovery: false (the default) to prevent the agent from discovering tools you did not intend it to use.
• Deny expensive reasoning models (o3, gemini-2.5-pro) unless the agent specifically requires advanced reasoning.

Cost Management

• Always set maxCostPerDay to prevent runaway spending. Start conservative and increase as needed.
• Use maxTokensPerRequest to prevent single expensive calls.
• For assistive agents that handle simple tasks, restrict to budget-tier models (gpt-4.1-nano, Llama-3.3-70B-Instruct).

Interaction Safety

• Avoid granting canInvoke with wildcard access. Always list specific agent IDs.
• Keep maxDelegationsPerExecution low (1--3) to limit the blast radius of unexpected behavior.
• Never allow assistive agents to invoke autonomous agents. The platform blocks this by default, but verify your interaction topology in the Interactions tab mini-graph.

Data Sovereignty

• If your tenant handles EU-regulated data, use the allowedModelTags: ["eu-hosted"] setting or the "EU-hosted only" toggle in the Model tab. This restricts the agent to self-hosted models (Llama-3.3-70B-Instruct, Qwen3-32B-FP8, DeepSeek-R1-Distill-Llama-70B, Qwen2.5-VL-72B-Instruct).
• Always configure a fallback model that is EU-hosted, even if your primary model is external.

Audit and Debugging

• All access control decisions (allow and deny) are logged in the Decision Audit Log and appear as yellow spans in the Trace Explorer.
• If your agent fails to call a tool, check the trace for a "tool grant check" span. It will show the reason for denial.
• If a model is grayed out in the Model tab, hover over it for the "Why is this model unavailable?" tooltip.

Related Documentation

• Admin Identity Guide -- How admins configure IdP, groups, and roles
• Admin Model Policies Guide -- How admins set tenant-level model restrictions
• Troubleshooting Guide -- Resolving common access control issues
• Access Control Reference -- Full technical specification of the 4-dimension model
• Architecture Reference -- Platform layer details and enforcement points