Skip to main content
This workflow guides you through creating an agent (AI or human) and managing its configuration. Related: Source: Feature Inventory, Source: Feature Inventory

​
Goal

Create a new agent (AI or human), configure its capabilities and settings, and manage it over time.

​
Preconditions

  • Access to a Veratrace instance
  • Valid AWS Cognito authentication
  • Appropriate permissions to create and manage agents (Administrator or Editor role)
  • Backend API running at http://localhost:8080 (development)
Source: Source: Feature Inventory

​
Permissions

Required roles: Administrator or Editor (inferred from mock roles)
Source: Source: Feature Inventory

​
UI Steps

Create agent form showing type selection, capabilities, and configuration options

​
Step 1: Navigate to Create Page

  1. Click Agents in the navigation sidebar
  2. Click Create Agent button or navigate directly to /agents/create
UI Route: /agents/create Component: CreateAgentPage (wraps AddEditAgentPage) Source: /Users/vincentgraham/clearline-ui/src/app/routes/routerConfig.jsx (line 114-115)

​
Step 2: Configure Agent Basics

  1. Enter Name - Agent name (required)
  2. Select Type - AI or HUMAN (required)
  3. Toggle Active - Whether agent is active (default: true)
UI Route: /agents/create Component: AddEditAgentPage Source: /Users/vincentgraham/clearline-ui/src/features/agents/pages/CreateAgentPage/CreateAgentPage.jsx

​
Step 3: Configure AI Agent (if Type is AI)

  1. Select Model - AI model identifier (e.g., “gpt-4”, “gpt-3.5-turbo”, “claude-3”)
  2. Select Capabilities - AI-specific capabilities:
    • Text generation
    • Code generation
    • Image analysis
    • Data analysis
    • Translation
    • Summarization
    • Content creation
    • Automated responses
UI Route: /agents/create Component: AddEditAgentPage Source: /Users/vincentgraham/clearline-ui/src/features/agents/types/agent.js (line 28-37)

​
Step 4: Configure Human Agent (if Type is HUMAN)

  1. Select Capabilities - Human-specific capabilities:
    • Customer support
    • Sales assistance
    • Project management
    • Strategic planning
    • Relationship building
    • Complex problem solving
    • Creative thinking
    • Leadership
    • Training/mentoring
    • Quality assurance
UI Route: /agents/create Component: AddEditAgentPage Source: /Users/vincentgraham/clearline-ui/src/features/agents/types/agent.js (line 39-49)

​
Step 5: Set Priority

  1. Select Priority - high, medium, or low
UI Route: /agents/create Component: AddEditAgentPage Source: /Users/vincentgraham/clearline-ui/src/features/agents/types/agent.js (line 52-56)

​
Step 6: Save Agent

  1. Click Save or Create button
  2. Agent is created and saved
UI Route: /agents/create Component: AddEditAgentPage Source: /Users/vincentgraham/clearline-ui/src/features/agents/api/agents.js

​
Step 7: Edit Agent (Optional)

  1. Navigate to /agents/:agentId/edit
  2. Modify agent configuration
  3. Click Save to update
UI Route: /agents/:agentId/edit Component: AddEditAgentPage Source: /Users/vincentgraham/clearline-ui/src/app/routes/routerConfig.jsx (line 118-119)

​
Backend API Calls

​
Create Agent

Endpoint: POST /instances/:instanceId/agents Called when: User clicks “Save” or “Create” button Request: 
{
  "name": "AI Assistant",
  "type": "AI",
  "active": true,
  "capabilities": ["text_generation", "code_generation"],
  "model": "gpt-4",
  "priority": "high",
  "metadata": {}
}
Response: Created agent object Source: /Users/vincentgraham/clearline-ui/src/features/agents/api/agents.js (line 72-100)

​
Update Agent

Endpoint: PUT /instances/:instanceId/agents/:agentId Called when: User clicks “Save” in edit mode Request: Same as Create Agent Response: Updated agent object Source: /Users/vincentgraham/clearline-ui/src/features/agents/api/agents.js (line 133-161)

​
Get Agent

Endpoint: GET /instances/:instanceId/agents/:agentId Called when: Loading agent for editing Response: Agent object Source: /Users/vincentgraham/clearline-ui/src/features/agents/api/agents.js (line 108-124)

​
List Agents

Endpoint: GET /instances/:instanceId/agents Called when: Loading agents list page Query Parameters:
  • type - Filter by type (AI, HUMAN)
  • active - Filter by active status
  • name - Search by name
  • page, size, sort - Pagination and sorting
Response: Paginated response with agent list Source: /Users/vincentgraham/clearline-ui/src/features/agents/api/agents.js (line 21-64)

​
Delete Agent

Endpoint: DELETE /instances/:instanceId/agents/:agentId Called when: User deletes an agent Response: 204 No Content Source: /Users/vincentgraham/clearline-ui/src/features/agents/api/agents.js (line 169-191)

​
Audit/Evidence Implications

Source: Source: Feature Inventory

​
Troubleshooting

​
Error: “Instance configuration not available”

Cause: Instance config not loaded or invalid Solution:
  • Verify authentication is complete
  • Check instance ID is valid
  • Refresh page and retry
Source: /Users/vincentgraham/clearline-ui/src/features/agents/api/agents.js (line 24-26)

​
Error: “Failed to create agent”

Cause: Invalid agent data or backend error Solution:
  • Verify all required fields are filled (name, type)
  • Check agent type-specific requirements (model for AI agents)
  • Review backend logs for details
Source: /Users/vincentgraham/clearline-ui/src/features/agents/api/agents.js (line 90-97)

​
Error: “Failed to update agent”

Cause: Invalid agent data or backend error Solution:
  • Verify agent ID is valid
  • Check all fields are valid
  • Review backend logs
Source: /Users/vincentgraham/clearline-ui/src/features/agents/api/agents.js (line 151-158)

​
Agent Not Appearing in List

Cause: Filter settings or pagination Solution:
  • Clear filters on agents list page
  • Check pagination (navigate to next page)
  • Verify agent was created successfully
Source: /Users/vincentgraham/clearline-ui/src/features/agents/api/agents.js (line 21-64)