Registering Agents

Creating, configuring, and deploying agents in Agent Studio

Builder Guide: Registering and Configuring Agents

This guide is for builders who create, configure, test, and deploy agents in Agent Studio. It covers the full agent lifecycle from initial creation through production deployment and monitoring.

Where to build: Agent Studio at http://localhost:3001 (log in as Builder / Bob).

Table of Contents

• Overview: Agent Types
• Agent Lifecycle
• Creating a New Agent
• Agent Designer Tabs
  • Prompt Tab
  • Model Tab
  • Tools Tab
  • Access Tab
  • Identity Tab
  • Interactions Tab
  • Memory Tab
  • Safety Tab
  • Deploy Tab
• Agent Configuration JSON Schema
• Risk Classification Guide
• Testing Agents in the Playground
• Deploying Agents
• Monitoring Agents
• Common Agent Configuration Patterns

Overview: Agent Types

The platform supports two runtime categories and three execution modes.

Runtime (Category Label)

Execution Mode (How It Runs)

The execution mode determines how the agent actually executes. You select it in the Identity tab.

All three modes share the same governance, security, and observability layers. Agents of any mode can interact via the A2A protocol and share tools through the MCP Gateway.

When to Choose Each Mode

Platform-Managed -- the default. Choose this when:

• You want the platform to handle everything (prompt, model, tools, memory).
• You are configuring agent behavior entirely through the 9-tab designer.
• You don't have external agent code to connect.

External Pro-Code -- choose this when:

• You have an existing LangGraph, CrewAI, AutoGen, or Pydantic AI agent.
• The agent requires custom logic beyond the platform's built-in tool loop.
• You want governance (guardrails, HITL, audit, tracing) without giving up control of execution.

External n8n (coming soon — temporarily disabled) -- choose this when:

• The workflow is primarily about connecting APIs and services.
• You want to use n8n's visual editor and 500+ connectors.
• Citizen developers need to modify the workflow without writing code.

For detailed best practices on building compatible external agents, see the External Agents Guide.

Agent Lifecycle

Every agent progresses through a defined set of statuses:

Draft --> Active --> Canary --> Active (full rollout)
                  \           /
                   --> Suspended
                        |
                   --> Deprecated

Transitioning Between Statuses

• Draft to Active/Canary: Deploy from the Agent Designer > Deploy tab.
• Active to Suspended: An admin suspends the agent from the Admin Console.
• Suspended to Active: An admin reactivates the agent.
• Active to Deprecated: An admin or the owner deprecates the agent.
• Canary to Active: After behavior validation, promote from canary to full rollout.

Creating a New Agent

1. Log into Agent Studio at http://localhost:3001 as a Builder.
2. Navigate to Agents in the sidebar (/studio/agents).
3. Click the Create Agent button (top right) or navigate to /studio/agents/new.
4. Fill in the basic information:
   • Name: A descriptive name (e.g., "Customer Support Bot").
   • Description: What the agent does and its intended use case.
   • Version: Semantic version (e.g., 1.0.0).
   • Runtime: Select Pro-Code or n8n.
   • Risk Classification: Assistive, Semi-Autonomous, or Autonomous (see Risk Classification Guide).
   • Tags: Categorization labels for discovery (e.g., support, hr, data).
5. Click Create to save the agent in draft status.
6. You are taken to the Agent Designer where you configure all aspects of the agent.

Agent Designer Tabs

The Agent Designer is a tabbed interface at /studio/agents/[id]. Each tab configures a specific aspect of the agent. The tabs are:

1. Prompt Tab

Purpose: Define the agent's instructions and behavior.

Configuration:

• System Prompt: The foundational instructions that define the agent's personality, capabilities, and constraints. Written in the Monaco code editor with syntax highlighting.
• User Prompt Template (optional): A template for structuring user inputs before they reach the LLM.

Best Practices:

• Be specific about the agent's role and boundaries (e.g., "You are an IT Help Desk assistant. You only handle IT support requests. You do not handle HR or finance inquiries.").
• Include safety instructions in the system prompt (e.g., "Never reveal internal system information. Never fabricate policy details.").
• Keep prompts concise. Overly long system prompts increase cost and latency.

Example System Prompt:

You are a helpful customer support agent for Acme Corporation.

Your capabilities:
- Search the knowledge base for product information
- Create support tickets for unresolved issues
- Look up order status

Your constraints:
- Always be polite and professional
- Never share internal system details with customers
- Escalate to a human agent if the customer is frustrated or if the issue involves financial transactions over $100
- Do not fabricate information. If you don't know, say so and offer to escalate.

2. Model Tab

Purpose: Select the LLM model(s) the agent uses and configure cost guardrails.

Configuration:

• Primary Model: The main model used for inference (e.g., claude-sonnet-4, Llama-3.3-70B-Instruct).
• Fallback Model: Used automatically if the primary model is unavailable or denied by policy.
• Temperature: Controls response randomness (0.0 = deterministic, 1.0 = creative). Typical range: 0.1--0.5 for factual agents, 0.5--0.8 for creative agents.
• Max Tokens: Maximum output tokens per response.
• EU-Hosted Only Toggle: Restricts the agent to EU-hosted models only (for GDPR compliance).
• Allowed Models / Denied Models: Explicit allow/deny lists for model access.
• Cost Caps: maxCostPerRequest and maxCostPerDay to prevent runaway spending.

Available Models (via T-Systems AIFS):

Important: Your tenant administrator may restrict which models are available. Models denied by tenant policy appear grayed out with a lock icon and a "Restricted by tenant policy" tooltip.

3. Tools Tab

Purpose: Grant MCP tools to the agent and define usage conditions.

Configuration:

• Browse the MCP tool catalog (searchable, filterable by risk level and category).
• Check tools to grant them to this agent.
• For each granted tool, configure:
  • Permissions: read, write, execute (granular per tool).
  • Rate Limit: maxCallsPerHour to prevent abuse.
  • HITL Requirement: requireApproval: true for human oversight per invocation.
  • Time Window: Restrict tool usage to specific hours (e.g., 09:00--17:00).
• Dynamic Discovery: Enable/disable the agent's ability to discover tools not explicitly granted. Default: false (disabled).
• Max Tool Calls Per Execution: Circuit breaker to limit total tool invocations per agent execution. Default: 20.

Tool Risk Levels:

See the Tool Integration Guide for details on registering and integrating tools.

4. Access Tab

Purpose: Control which users can see and interact with this agent.

Configuration:

• Visibility Mode:
  • public -- All users in the tenant can see and use the agent.
  • restricted -- Only users matching specified groups, roles, or user IDs.
  • private -- Only the agent owners can see it (intended for development).
• Allowed Groups: Select IdP groups (e.g., hr-team, engineering, finance).
• Allowed Roles: Select roles (e.g., manager, director).
• Allowed Users: Specify individual user IDs.
• Owners: Builder user IDs who can edit the agent configuration.

The Access tab shows a live preview indicating how many users match the current entitlements.

See the Builder Access Control Guide for the full access control model.

5. Identity Tab

Purpose: Configure the agent's identity, execution mode, and external runtime connection.

This tab has three main sections:

Runtime & Execution Mode

• Runtime: Select Pro-Code or n8n (category label for filtering and badge color).
• Execution Mode: Select how the agent executes (see Overview: Agent Types).
  • Platform-Managed (default) -- platform handles everything.
  • External Pro-Code -- forward to your LangGraph/CrewAI/AutoGen endpoint.
  • External n8n -- forward to an n8n workflow webhook.

External Agent Configuration

When External Pro-Code or External n8n is selected, the following configuration panel appears:

SPIFFE Identity

• SPIFFE ID: Automatically generated cryptographic identity in the format: spiffe://<trust-domain>/<tenant-id>/agent/<agent-id>.
• Used for mutual TLS authentication between agents and services.

6. Interactions Tab

Purpose: Define which other agents this agent can call (and which can call it).

Configuration:

• Can Invoke: List of agents this agent can delegate tasks to.
  • For each target agent, set maxDelegationsPerExecution (e.g., 3) and optionally requireApproval.
• Invocable By: List of agents that are allowed to invoke this agent.
• Discoverable: Whether this agent is visible in the A2A registry.

The Interactions tab includes a mini-graph visualization showing the interaction topology.

Interaction Patterns:

• Hub-and-Spoke: A central orchestrator calls specialist agents, but specialists cannot call each other.
• Peer Network: Agents in the same domain can call each other bidirectionally.
• Hierarchical: Agents can only call agents at the same or lower risk classification (prevents privilege escalation).

7. Memory Tab

Purpose: Configure the agent's memory capabilities.

Configuration:

• TTL (Time-to-Live): Number of days before memory entries expire. Range: 1--365. Default varies by type.
• Enable or disable each memory type with toggle switches.

Guidance:

• Most agents need Short-Term memory (enabled by default).
• Enable Long-Term memory for agents that should remember context across conversations.
• Enable Graph memory only for agents that need to understand entity relationships.
• Enable Procedural memory for agents that learn and improve their workflows over time.

8. Safety Tab

Purpose: Configure risk classification and guardrails.

Configuration:

• Risk Classification: assistive, semi-autonomous, or autonomous (see Risk Classification Guide).
• Input Guardrails: Policies applied to user inputs before they reach the LLM.
  • pii-detection -- Detects personally identifiable information.
  • prompt-injection -- Detects prompt injection attempts.
  • sql-injection-check -- Detects SQL injection in inputs.
  • size-limit -- Enforces maximum input size.
• Output Guardrails: Policies applied to LLM outputs before they reach the user.
  • toxicity-filter -- Blocks toxic or harmful content.
  • hallucination-check -- Flags potentially hallucinated facts.
  • pii-leak-prevention -- Redacts PII from outputs.
  • pii-redaction -- Redacts specific PII patterns.
  • confidentiality-filter -- Blocks disclosure of confidential information.
  • data-leak-prevention -- Prevents leaking internal data.
  • financial-accuracy -- Validates financial calculations.
  • suggestion-only -- Ensures agent outputs are framed as suggestions, not directives.
• HITL (Human-in-the-Loop):
  • enabled -- Whether HITL is active for this agent.
  • riskThreshold -- Risk score threshold (0.0--1.0) above which actions require human approval.
  • escalationChain -- Ordered list of user IDs to escalate to when approval is needed.

9. Deploy Tab

Purpose: Deploy the agent to a target environment.

Configuration:

• Target Environment: dev, staging, or production.
• Canary Percentage: What percentage of traffic the new version receives during canary deployment (e.g., 5%).

Deploy Pipeline Stages:

When you deploy an agent, it goes through these stages:

1. Code/Config -- Validates the agent configuration.
2. Access Review -- Checks all four access control dimensions for consistency.
3. Build & Sign -- Builds the agent artifact and signs it with Sigstore.
4. Eval Suite -- Runs the agent's evaluation test suite (if configured).
5. Safety Gate -- Verifies risk classification and guardrail adequacy.
6. Canary (N%) -- Routes N% of traffic to the new version.
7. Behavior Check -- Monitors behavioral baselines during canary.
8. Full Rollout -- Promotes to 100% traffic if checks pass.

Agent Configuration JSON Schema

Below is the complete TypeScript interface for agent form state, which maps directly to the JSON configuration stored for each agent:

interface AgentFormState {
  name: string;
  description: string;
  version: string;
  tags: string[];
  riskClassification: 'assistive' | 'semi-autonomous' | 'autonomous';
  runtime: 'procode' | 'n8n';
  executionMode: 'platform-managed' | 'external-procode' | 'external-n8n';
  externalConfig: {
    endpointUrl: string;          // HTTP endpoint of external agent
    authType: 'bearer' | 'api-key' | 'none';
    authSecretRef: string;        // Reference to credential (not raw secret)
    inputFormat: 'langserve' | 'openai-compatible' | 'a2a' | 'n8n-webhook' | 'custom';
    responseExtractor: string;    // JSONPath for custom format
    healthCheckUrl: string;       // Readiness check URL
    timeoutMs: number;            // Request timeout (default: 30000)
    n8nWorkflowId: string;        // Linked n8n workflow ID
    costModel: string;            // Model name for cost estimation
  };
  systemPrompt: string;
  model: {
    primary: string;        // Model ID (e.g., 'claude-sonnet-4')
    fallback: string;       // Fallback model ID
    temperature: number;    // 0.0 - 1.0
    maxTokens: number;      // Max output tokens
  };
  modelAccess: {
    allowedModels: string[];
    allowedModelTags: string[];     // e.g., ['eu-hosted']
    deniedModels: string[];
    maxCostPerRequest: number;      // Dollar cap per LLM call
    maxCostPerDay: number;          // Daily spend cap
    maxTokensPerRequest: number;
    euHostedOnly: boolean;
  };
  memory: {
    shortTerm: boolean;
    longTerm: boolean;
    graph: boolean;
    procedural: boolean;
    ttlDays: number;
  };
  hitl: {
    enabled: boolean;
    riskThreshold: number;          // 0.0 - 1.0
    escalationChain: string[];      // User IDs
  };
  guardrails: {
    inputPolicies: string[];        // Policy names
    outputPolicies: string[];
  };
  entitlements: {
    visibility: 'public' | 'restricted' | 'private';
    allowedGroups: string[];
    allowedRoles: string[];
    allowedUsers: string[];
    owners: string[];
  };
  interactionPolicy: {
    canInvoke: {
      agentId: string;
      maxDelegationsPerExecution: number;
      requireApproval?: boolean;
    }[];
    invocableBy: { agentId: string }[];
    discoverable: boolean;
  };
  maxDelegationDepth: number;       // Default: 5
  deployEnvironment: 'dev' | 'staging' | 'production';
  canaryPercentage: number;         // 0 - 100
}

Risk Classification Guide

Every agent must be classified into one of three risk levels. The classification affects the guardrails, HITL requirements, and model access policies applied:

Assistive

Definition: The agent provides information, suggestions, or analysis but does not take actions in external systems. All outputs are advisory.

Characteristics:

• Read-only tool access (no write or execute on external systems).
• No external communications (emails, Slack messages).
• Low risk of harm from incorrect outputs.
• HITL is optional.

Examples: Code review assistant, documentation summarizer, search agent, FAQ bot.

Default Restrictions:

• Budget-tier models recommended (cost efficiency).
• Dynamic tool discovery disabled.
• No agent-to-agent delegation by default.

Semi-Autonomous

Definition: The agent can take actions in external systems but requires human approval for high-impact operations. It operates within defined guardrails.

Characteristics:

• Can read and write to external systems (databases, ticketing, CRM).
• External communications may be permitted with HITL approval.
• HITL is recommended and typically enabled.
• Risk threshold typically set between 0.5 and 0.7.

Examples: Customer support bot (creates tickets), HR benefits advisor (accesses HRIS), invoice processor (writes to ERP).

Default Restrictions:

• Standard or premium models allowed.
• HITL required for write operations above risk threshold.
• Cost caps recommended.

Autonomous

Definition: The agent operates independently with minimal human oversight. It can execute complex multi-step workflows, make decisions, and take actions without per-action approval.

Characteristics:

• Full read/write/execute access to granted tools.
• May send external communications autonomously.
• HITL enabled but with a high threshold (only critical actions escalated).
• Requires admin approval for deployment.

Examples: Data pipeline orchestrator, automated deployment agent, continuous monitoring agent.

Default Restrictions:

• Admin approval required for production deployment.
• Behavioral baseline monitoring enabled.
• Comprehensive audit logging.
• Cannot be invoked by assistive agents (prevents privilege escalation).

Testing Agents in the Playground

Before deploying, test your agent in the Studio Playground:

1. Navigate to Playground (/studio/playground).
2. Select the agent to test.
3. Send test messages and observe:
   • Response quality and relevance.
   • Tool invocations (which tools were called, inputs/outputs).
   • Response latency and token usage.
   • Guardrail triggers (were any inputs or outputs blocked?).
   • HITL triggers (did the agent correctly escalate high-risk actions?).
4. Review the execution trace for each interaction.
5. Iterate on the system prompt, tool grants, and guardrails based on test results.

Deploying Agents

Initiating a Deployment

1. Open the agent in the Agent Designer.
2. Navigate to the Deploy tab.
3. Select the target environment (dev, staging, or production).
4. Set the canary percentage (recommended: 5% for initial production deployments).
5. Click Deploy.

Canary Deployments

Canary deployments route a small percentage of traffic to the new version while the rest continues to use the current version.

1. Deploy with a canary percentage (e.g., 5%).
2. Monitor the canary version in the Monitoring tab:
   • Compare success rate, latency, and cost against the previous version.
   • Check for guardrail trigger rate increases.
   • Review the behavioral baseline comparison.
3. If the canary looks good, promote to full rollout.
4. If issues are detected, roll back to the previous version.

Rollback

If a deployment causes issues:

1. Navigate to Deployments (/studio/deployments).
2. Find the active deployment.
3. Click Rollback to revert to the previous version.
4. The rollback is immediate and does not require a new deployment pipeline run.

Monitoring Agents

Key Metrics

After deployment, monitor your agent's performance:

Where to Monitor

• Studio > Monitoring (/studio/monitoring): Agent-specific metrics with time-series charts.
• Studio > Traces (/studio/traces): Individual execution traces with span-level detail. Filter by agent, status, date range, latency, and cost.
• Admin > Dashboard (/admin/dashboard): Platform-wide health overview.
• Admin > FinOps (/admin/finops): Cost attribution and spend tracking.

Common Agent Configuration Patterns

Pattern 1: Simple FAQ Bot (Assistive)

{
  "name": "FAQ Bot",
  "runtime": "procode",
  "riskClassification": "assistive",
  "model": { "primary": "gpt-4.1-nano", "temperature": 0.2, "maxTokens": 1024 },
  "memory": { "shortTerm": true, "longTerm": false, "graph": false, "procedural": false, "ttlDays": 1 },
  "hitl": { "enabled": false },
  "entitlements": { "visibility": "public" },
  "toolGrants": {
    "tools": [
      { "toolId": "tool-kb", "permissions": ["read", "execute"] }
    ],
    "dynamicDiscovery": false,
    "maxToolCallsPerExecution": 5
  },
  "modelAccess": { "maxCostPerDay": 5.00 }
}

Pattern 2: Business Process Agent (Semi-Autonomous)

{
  "name": "Invoice Processor",
  "runtime": "n8n",
  "riskClassification": "semi-autonomous",
  "model": { "primary": "claude-sonnet-4", "fallback": "Llama-3.3-70B-Instruct", "temperature": 0.0, "maxTokens": 2048 },
  "memory": { "shortTerm": true, "longTerm": true, "graph": false, "procedural": true, "ttlDays": 365 },
  "hitl": { "enabled": true, "riskThreshold": 0.6, "escalationChain": ["user-builder-1", "user-admin-1"] },
  "guardrails": {
    "inputPolicies": ["pii-detection"],
    "outputPolicies": ["financial-accuracy"]
  },
  "entitlements": {
    "visibility": "restricted",
    "allowedGroups": ["finance"],
    "allowedRoles": ["manager", "director"]
  },
  "toolGrants": {
    "tools": [
      { "toolId": "tool-ocr", "permissions": ["read", "execute"] },
      { "toolId": "tool-erp", "permissions": ["read", "write", "execute"], "conditions": { "requireApproval": true, "maxCallsPerHour": 50 } }
    ],
    "dynamicDiscovery": false,
    "maxToolCallsPerExecution": 30
  },
  "modelAccess": { "allowedModelTags": ["eu-hosted"], "maxCostPerDay": 15.00 }
}

Pattern 3: Autonomous Pipeline Orchestrator

{
  "name": "Research Analyst",
  "runtime": "n8n",
  "riskClassification": "autonomous",
  "model": { "primary": "claude-sonnet-4", "temperature": 0.1, "maxTokens": 4096 },
  "memory": { "shortTerm": true, "longTerm": true, "graph": true, "procedural": true, "ttlDays": 90 },
  "hitl": { "enabled": true, "riskThreshold": 0.5, "escalationChain": ["user-builder-1"] },
  "guardrails": {
    "inputPolicies": ["sql-injection-check"],
    "outputPolicies": ["data-leak-prevention"]
  },
  "entitlements": {
    "visibility": "restricted",
    "allowedGroups": ["engineering"],
    "allowedRoles": ["engineer", "admin"]
  },
  "interactionPolicy": {
    "canInvoke": [
      { "agentId": "agent-demo-1", "maxDelegationsPerExecution": 5 }
    ],
    "invocableBy": [{ "agentId": "agent-1" }],
    "discoverable": true
  },
  "modelAccess": { "allowedModelTags": ["eu-hosted"], "maxCostPerDay": 20.00 }
}

Pattern 4: External LangGraph Agent (Pro-Code)

{
  "name": "Research Agent",
  "runtime": "procode",
  "executionMode": "external-procode",
  "riskClassification": "semi-autonomous",
  "externalConfig": {
    "endpointUrl": "http://localhost:8100/invoke",
    "inputFormat": "langserve",
    "authType": "bearer",
    "authSecretRef": "vault:tenant-1/langgraph-api-key",
    "costModel": "claude-sonnet-4",
    "timeoutMs": 60000,
    "healthCheckUrl": "http://localhost:8100/health"
  },
  "hitl": { "enabled": true, "riskThreshold": 0.7 },
  "guardrails": {
    "inputPolicies": ["pii-detection", "prompt-injection"],
    "outputPolicies": ["toxicity-filter", "pii-leak-prevention"]
  },
  "entitlements": { "visibility": "restricted", "allowedGroups": ["engineering"] }
}

Note: The model configuration is not needed for external agents since the external runtime controls model selection. The costModel in externalConfig tells the platform which model the external agent uses so it can calculate cost from reported token usage.

Pattern 5: External n8n Workflow Agent

{
  "name": "Ticket Router",
  "runtime": "n8n",
  "executionMode": "external-n8n",
  "riskClassification": "assistive",
  "externalConfig": {
    "endpointUrl": "http://n8n:5678/webhook/ticket-router",
    "inputFormat": "n8n-webhook",
    "authType": "none",
    "timeoutMs": 30000
  },
  "guardrails": {
    "inputPolicies": ["pii-detection"],
    "outputPolicies": ["pii-leak-prevention"]
  },
  "entitlements": { "visibility": "public" }
}

Related Documentation

• External Agents Guide -- Best practices for building compatible LangGraph, CrewAI, and n8n agents
• Builder Access Control Guide -- Configuring all four access control dimensions
• Tool Integration Guide -- Registering and integrating MCP tools
• Using Agents Guide -- How consumers interact with your agents
• Getting Started Guide -- Initial setup and environment configuration
• LLM Provider Configuration -- T-Systems AIFS models and SDK usage
• Architecture Reference -- Platform layer details