Skip to main content

Managing Agents Tutorial

This comprehensive tutorial covers all aspects of agent management in Knowledge Discovery, including creation, configuration, filtering, avatars, and deletion.

Prerequisites​

  • Valid access token (see Authentication)
  • Discovery Agent Manager role or higher
  • At least one configured data source (source ID)

Tutorial Overview​

In this tutorial, you'll learn to:

  1. Create a new agent
  2. Configure static and dynamic filters
  3. Update agent configuration
  4. Upload and manage agent avatars
  5. List and retrieve agents
  6. Delete agents

Part 1: Create an Agent​

Basic Agent Creation​

Let's create a simple agent for a customer support use case.

### Create Customer Support Agent
POST {{baseUrl}}/agent/agents
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
  "name": "Customer Support Agent",
  "description": "Specialized agent for customer support inquiries and troubleshooting",
  "modelName": "bedrock-amazon-nova-micro",
  "instructions": "You are a helpful customer support assistant. Provide clear, concise answers based on the documentation. If you cannot find relevant information, politely inform the customer and suggest contacting human support.",
  "sourceIds": ["your-source-id-here"],
  "accessRights": [
    { "type": "Group", "id": "support-team-group-id" }
  ]
}

Understanding Required Parameters​

ParameterRequiredDescription
nameYesDisplay name for the agent (1-200 characters)
descriptionYesDescription of the agent's purpose (1-1000 characters)
modelNameYesLLM model to use (e.g., bedrock-amazon-nova-micro)
instructionsNoSystem prompt providing context and behavior guidelines
sourceIdsNoArray of data source GUIDs the agent can query
accessRightsNoArray of users/groups who can access the agent
avatarUrlNoURL for the agent's avatar image
staticFilterExpressionNoPermanent filters applied to all queries
dynamicFilterTemplateNoTemplate for runtime-provided filters

Validation Rules​

Validation Requirements
  • Name: 1-200 characters, cannot be empty or whitespace only
  • Description: 1-1000 characters, cannot be empty or whitespace only
  • ModelName: Must be a supported model identifier. Available models:
    • bedrock-amazon-nova-micro
    • bedrock-claude-3-haiku
    • bedrock-llama3-2
    • bedrock-llama4-scout-17b-instruct
    • bedrock-llama4-maverick-17b-instruct
  • SourceIds: Must be valid source GUIDs that exist in your environment
  • AccessRights: User/Group IDs must be valid GUIDs

Part 2: Configure Static and Dynamic Filters​

Filters control which documents the agent can access. There are two types:

Static Filters​

Static filters are permanent and apply to all queries. Use these for:

  • Department-specific restrictions
  • Document type filtering
  • Security level requirements
### Create Agent with Static Filters
POST {{baseUrl}}/agent/agents
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
  "name": "Finance Department Agent",
  "description": "Agent with access restricted to finance documents",
  "modelName": "bedrock-amazon-nova-micro",
  "sourceIds": ["your-source-id"],
  "accessRights": [
    {"type": "Group", "id": "finance-group-id"}
  ],
  "staticFilterExpression": {
    "logicalOperator": "And",
    "conditions": [
      {
        "field": "Department",
        "type": "Text",
        "operator": "Equals",
        "value": "Finance"
      },
      {
        "field": "Status",
        "type": "Text",
        "operator": "Any",
        "values": ["Approved", "Published"]
      }
    ]
  }
}

Dynamic Filter Templates​

Dynamic filters allow users to provide filter values at query time. Use these for:

  • Date range selections
  • User-specific context
  • Runtime parameters
Template Structure

Dynamic filter templates have a similar structure to static filters but do not contain values. The field definitions specify which fields can be filtered, but the actual values are provided when the question is submitted. This allows users to customize filtering at query time.

### Create Agent with Dynamic Filter Template
POST {{baseUrl}}/agent/agents
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
  "name": "Document Search Agent",
  "description": "Agent that allows users to filter by date and category",
  "modelName": "bedrock-amazon-nova-micro",
  "sourceIds": ["your-source-id"],
  "dynamicFilterTemplate": {
    "logicalOperator": "And",
    "conditions": [
      {
        "field": "CreatedDate",
        "type": "Date"
      },
      {
        "field": "Category",
        "type": "Text"
      }
    ]
  }
}

Filter Syntax Reference​

Logical Operators​

  • And - All conditions must be true
  • Or - At least one condition must be true
  • Not - Negates the conditions

Field Types​

  • Text - String values
  • Number - Numeric values (integers, decimals)
  • Date - ISO 8601 date/datetime values
  • Boolean - True/false values

Comparison Operators​

OperatorApplies ToDescriptionExample
EqualsText, Number, Date, BooleanExact match"Status" Equals "Active"
NotEqualsText, Number, DateNot equal to"Status" NotEquals "Deleted"
ContainsTextString contains substring"Title" Contains "Report"
LikeTextPattern matching with wildcards"Name" Like "%invoice%"
AnyText, NumberValue in list"Status" Any ["Active", "Pending"]
GreaterThanNumber, DateGreater than"Amount" GreaterThan 1000
LessThanNumber, DateLess than"CreatedDate" LessThan "2024-01-01"
GreaterThanOrEqualsNumber, DateGreater than or equals"Priority" GreaterThanOrEquals 3
LessThanOrEqualsNumber, DateLess than or equals"UpdatedDate" LessThanOrEquals "2024-12-31"

Complex Filter Examples​

{
  "logicalOperator": "AND",
  "conditions": [
    {
      "field": "primary_type",
      "type": "text",
      "operator": "any",
      "values": ["Document", "File"]
    },
    {
      "field": "created",
      "type": "date",
      "operator": "greaterThan",
      "value": "2023-01-01"
    },
    {
      "logicalOperator": "NOT",
      "conditions": [
        {
          "field": "is_trashed",
          "type": "boolean",
          "operator": "equals",
          "value": true
        }
      ]
    }
  ]
}

Static and Dynamic Filtering Example​

Combine static and dynamic filters with nested logic:

### Create Agent with Complex Filtering
POST {{baseUrl}}/agent/agents
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
  "name": "Compliance Document Agent",
  "description": "Agent for compliance documents with complex filtering",
  "modelName": "bedrock-amazon-nova-micro",
  "sourceIds": ["your-source-id"],
  "staticFilterExpression": {
    "logicalOperator": "And",
    "conditions": [
      {
        "field": "Department",
        "type": "Text",
        "operator": "Equals",
        "value": "Compliance"
      },
      {
        "field": "ApprovalStatus",
        "type": "Text",
        "operator": "Equals",
        "value": "Approved"
      }
    ]
  },
  "dynamicFilterTemplate": {
    "logicalOperator": "And",
    "conditions": [
      {
        "field": "PublishedDate",
        "type": "Date"
      },
      {
        "field": "RiskLevel",
        "type": "Number"
      },
      {
        "field": "Category",
        "type": "Text"
      }
    ]
  }
}

Part 3: Update Agent Configuration​

Agents can be updated using the PUT endpoint. This is a full replacement operation.

### Update Agent Configuration
PUT {{baseUrl}}/agent/agents/{{agentId}}
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
  "name": "Customer Support Agent (Updated)",
  "description": "Enhanced customer support agent with expanded capabilities",
  "modelName": "bedrock-amazon-nova-micro",
  "instructions": "You are an expert customer support assistant with access to comprehensive product documentation. Provide detailed, accurate answers and include relevant links when appropriate.",
  "sourceIds": ["source-1", "source-2"],
  "accessRights": [
    {"type": "Group", "id": "support-team-group-id"},
    {"type": "Group", "id": "customer-success-group-id"}
  ],
  "staticFilterExpression": {
    "logicalOperator": "And",
    "conditions": [
      {
        "field": "Category",
        "type": "Text",
        "operator": "Any",
        "values": ["Support", "FAQ", "Troubleshooting"]
      }
    ]
  }
}
Versioning

Each update creates a new version of the agent. The version number increments automatically. Previous versions are retained but marked as not latest.

Part 4: Upload and Manage Agent Avatars​

Agents can have custom avatar images. Avatars are uploaded separately and referenced by URL.

Upload Avatar (Pre-signed URL method)​

### Upload Agent Avatar (Update with Avatar URL)
PUT {{baseUrl}}/agent/agents/{{agentId}}
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
  "name": "Customer Support Agent",
  "description": "Agent with custom avatar",
  "modelName": "bedrock-amazon-nova-micro",
  "avatarUrl": "https://your-storage.com/avatars/agent-avatar.png",
  "sourceIds": ["source-id"]
}

Retrieve Avatar with Pre-signed URL​

When listing or retrieving agents, you can request pre-signed URLs for avatars:

### Retrieve Agent with Pre-signed Avatar URL
GET {{baseUrl}}/agent/agents/{{agentId}}?includePresignedUrl=true
Authorization: Bearer {{accessToken}}

Part 5: List and Retrieve Agents​

List All Accessible Agents​

### List All Accessible Agents
GET {{baseUrl}}/agent/agents
Authorization: Bearer {{accessToken}}

Response Structure:

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Customer Support Agent",
    "description": "Specialized agent for customer support inquiries",
    "modelName": "bedrock-amazon-nova-micro",
    "avatarUrl": "https://example.com/avatar.png",
    "instructions": "You are a helpful customer support assistant...",
    "sourceIds": ["source-id-1", "source-id-2"],
    "accessRights": [
      {
        "type": "Group",
        "id": "group-id-123"
      },
      {
        "type": "User",
        "id": "user-id-456"
      }
    ],
    "version": 2,
    "latest": true,
    "staticFilterExpression": {
      "logicalOperator": "And",
      "conditions": [
        {
          "field": "Department",
          "type": "Text",
          "operator": "Equals",
          "value": "Support"
        }
      ]
    },
    "dynamicFilterTemplate": {
      "logicalOperator": "And",
      "conditions": [
        {
          "field": "CreatedDate",
          "type": "Date"
        }
      ]
    }
  }
]

Filter by Source ID​

### Filter Agents by Source ID
GET {{baseUrl}}/agent/agents?sourceId=your-source-id
Authorization: Bearer {{accessToken}}

Retrieve Specific Agent​

### Retrieve Specific Agent
GET {{baseUrl}}/agent/agents/{{agentId}}
Authorization: Bearer {{accessToken}}

Response Structure:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Customer Support Agent",
  "description": "Specialized agent for customer support inquiries",
  "modelName": "bedrock-amazon-nova-micro",
  "avatarUrl": "https://example.com/avatar.png",
  "instructions": "You are a helpful customer support assistant. Provide clear, concise answers based on the documentation.",
  "sourceIds": ["source-id-1", "source-id-2"],
  "accessRights": [
    {
      "type": "Group",
      "id": "group-id-123"
    },
    {
      "type": "User",
      "id": "user-id-456"
    }
  ],
  "version": 2,
  "latest": true,
  "staticFilterExpression": {
    "logicalOperator": "And",
    "conditions": [
      {
        "field": "Department",
        "type": "Text",
        "operator": "Equals",
        "value": "Support"
      }
    ]
  },
  "dynamicFilterTemplate": {
    "logicalOperator": "And",
    "conditions": [
      {
        "field": "CreatedDate",
        "type": "Date"
      },
      {
        "field": "Category",
        "type": "Text"
      }
    ]
  }
}

Part 6: Delete Agent​

### Delete Agent
DELETE {{baseUrl}}/agent/agents/{{agentId}}
Authorization: Bearer {{accessToken}}
Cascading Effects

Deleting an agent does not delete historical questions/answers associated with it. However, new questions cannot be submitted to a deleted agent.

Best Practices​

1. Idempotency Considerations​

The PUT endpoint replaces the entire agent configuration. Always:

  • Retrieve current configuration first
  • Modify only what needs changing
  • Send complete updated configuration

2. Version Management​

  • Each update increments the version number
  • Previous versions are retained
  • Always use the latest version for new questions

3. Error Handling​

Always implement comprehensive error handling:

  • 400 Bad Request - Validation errors (check request payload)
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Agent doesn't exist
  • 409 Conflict - Concurrent modification (retry with latest version)

Summary​

In this tutorial, you learned how to:

✅ Create agents with comprehensive configurations
✅ Configure static filters for permanent restrictions
✅ Set up dynamic filter templates for runtime filtering
✅ Update agent configurations safely
✅ Manage agent avatars
✅ List and retrieve agents
✅ Delete agents properly