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. Create a Graph RAG agent (optional)
  3. Configure static and dynamic filters
  4. Configure guardrails for content safety
  5. Update agent configuration
  6. Upload and manage agent avatars
  7. List and retrieve agents
  8. 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": "amazon.nova-micro-v1:0",
  "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., amazon.nova-micro-v1:0)
instructionsNoSystem prompt providing context and behavior guidelines
sourceIdsNoArray of data source IDs the agent can query. Primarily used for Alfresco and other integration endpoints (see Integration Endpoints Tutorial). For system integrations, use staticFilterExpression instead.
accessRightsYesArray of user/group IDs who can access the agent
avatarUrlNoURL for the agent's avatar image
staticFilterExpressionNoPermanent filters applied to all queries
dynamicFilterTemplateNoTemplate for runtime-provided filters
guardrailsNoArray of guardrail objects to apply content filtering and safety measures
ragParametersNoRAG retrieval settings (limit, chunk merging, reranking)
RAG Parameters

The optional ragParameters object fine-tunes the Retrieval-Augmented Generation (RAG) pipeline for the agent:

ParameterTypeDescription
limitintegerMaximum number of document chunks to retrieve from the knowledge base
adjacentChunkRangeintegerNumber of adjacent chunks to include around each retrieved chunk for additional context
adjacentChunkMergebooleanWhether to merge adjacent chunks into a single context block
rerankerEnabledbooleanWhether to apply a reranker model to re-score and reorder retrieved chunks for improved relevance
rerankerTopNintegerMaximum number of chunks to retain after reranking

All ragParameters fields are optional — omit the object or individual fields to use system defaults.

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. You can retrieve the list of available models using the /models endpoint in the Agent API. Each model includes a status field (Active, Deprecated, or Unavailable), an optional eolDate, and an optional replacementModelName for migrating off deprecated models.
  • SourceIds: Must be valid source GUIDs that exist in your environment
  • AccessRights: User/Group IDs must be valid GUIDs

Part 1B: Create a Graph RAG Agent​

Graph RAG agents use a knowledge graph domain for retrieval instead of the standard document-centric RAG approach. Use a Graph RAG agent when your workflow requires graph-based relationships between entities.

When to Use Graph RAG​

  • Use Graph RAG when you have a provisioned knowledge graph domain and need to retrieve entity relationships
  • Use standard RAG (Part 1 above) for document-centric retrieval or when no knowledge graph domain exists

Graph RAG-Specific Fields​

To create a Graph RAG agent, add two additional fields to the standard agent creation request:

FieldRequiredDescription
agentTypeYesSet to "graphRag"
knowledgeGraphDomainIdYesUUID of the provisioned knowledge graph domain

All other fields (name, description, modelName, instructions, sourceIds, accessRights, ragParameters) work the same as for standard agents.

Example: Create a Graph RAG Agent​

POST {{baseUrl}}/agent/agents
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
  "name": "Claims Investigation Graph Agent",
  "description": "Graph RAG agent for navigating claim relationships and related evidence.",
  "modelName": "anthropic.claude-3-haiku-20240307-v1:0",
  "instructions": "Answer using the configured knowledge graph domain. Explain relationship chains when important.",
  "sourceIds": ["550e8400-e29b-41d4-a716-446655440000"],
  "agentType": "graphRag",
  "knowledgeGraphDomainId": "11111111-2222-3333-4444-555555555555"
}
Knowledge Graph Domain Requirement

The Knowledge Discovery Agent API expects the knowledge graph domain to already exist. There is currently no endpoint to create or discover knowledgeGraphDomainId values through this API.

Response Structure Differences​

When retrieving answers from a Graph RAG agent (using the standard Q&A endpoints), the response includes graphReferences instead of documentReferences:

{
  "id": "c9d6f822-e88c-48a7-bfb9-1f91e7214b40",
  "question": "How is claim CLM-204 linked to vendor ACME Medical?",
  "answer": "Claim CLM-204 is linked through invoice INV-1523...",
  "graphReferences": [
    {
      "entityId": "claim-clm-204",
      "entityType": "Claim",
      "relationships": [
        {
          "relatedEntityId": "vendor-acme-medical",
          "relatedEntityType": "Vendor",
          "relationshipType": "submittedBy",
          "rankScore": 0.98
        }
      ]
    }
  ]
}

Graph RAG agents are queried through the same endpoints as standard agents. See the Conversations Tutorial for information on multi-turn conversations with Graph RAG agents.

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": "amazon.nova-micro-v1:0",
  "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": "amazon.nova-micro-v1:0",
  "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": "amazon.nova-micro-v1:0",
  "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: Configure Guardrails​

Guardrails provide content filtering and safety measures for agent responses. They help ensure that agent interactions remain appropriate and aligned with organizational policies.

Available Guardrails​

To get the list of available guardrails, use the GET /agent/guardrails endpoint:

### Get Available Guardrails
GET {{baseUrl}}/agent/guardrails
Authorization: Bearer {{accessToken}}

The response contains guardrail groups with available guardrails:

{
  "guardrailGroups": [
    {
      "displayName": "Profanity",
      "description": "Filters profane content.",
      "guardrails": [
        {"name": "HAIP-Profanity", "severity": null, "isRecommended": false}
      ]
    },
    {
      "displayName": "Violence",
      "description": "Filters content related to violence.",
      "guardrails": [
        {"name": "HAIP-Violence-Low", "severity": "low", "isRecommended": false},
        {"name": "HAIP-Violence-Medium", "severity": "medium", "isRecommended": false},
        {"name": "HAIP-Violence-High", "severity": "high", "isRecommended": false}
      ]
    },
    {
      "displayName": "Contextual grounding",
      "description": "Provides contextual grounding validation for responses.",
      "guardrails": [
        {"name": "HAIP-Contextual-Grounding", "severity": null, "isRecommended": false}
      ]
    }
  ]
}

Create Agent with Guardrails​

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

{
  "name": "Safe Customer Support Agent",
  "description": "Customer support agent with content safety guardrails",
  "modelName": "bedrock-amazon-nova-micro",
  "sourceIds": ["your-source-id"],
  "guardrails": [
    {"name": "HAIP-Contextual-Grounding"},
    {"name": "HAIP-Profanity"},
    {"name": "HAIP-Violence-High"}
  ]
}

Guardrail Blocking Behavior​

When an active guardrail blocks a question or its generated answer, the API returns a standard response with a fixed message instead of the actual answer:

"This request was limited by one or more guardrails. Try rephrasing it, or contact support if assistance is needed."

In the response, the relevant status field is set to Blocked:

  • For single-shot questions: responseCompleteness is Blocked
  • For conversations: status is Blocked

This allows your application to detect blocked responses and surface appropriate messaging to the user.

Part 4: 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": "amazon.nova-micro-v1:0",
  "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"]
      }
    ]
  },
  "guardrails": [
    {"name": "HAIP-Contextual-Grounding"},
    {"name": "HAIP-Profanity"}
  ]
}
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 5: 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": "amazon.nova-micro-v1:0",
  "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 6: 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": "amazon.nova-micro-v1:0",
    "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"
        }
      ]
    },
    "guardrails": [
      {"name": "HAIP-Contextual-Grounding"},
      {"name": "HAIP-Profanity"}
    ]
  }
]

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": "amazon.nova-micro-v1:0",
  "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"
      }
    ]
  },
  "guardrails": [
    {"name": "HAIP-Contextual-Grounding"},
    {"name": "HAIP-Profanity"}
  ]
}

Part 7: 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
✅ Configure guardrails for content safety and moderation
✅ Update agent configurations safely
✅ Manage agent avatars
✅ List and retrieve agents
✅ Delete agents properly