Skip to main content
Custom bots allow you to create specialized AI assistants tailored to specific use cases. By adding custom instructions, knowledge bases, and configuring behavior, you can build bots that understand your domain and respond consistently.

​
Prerequisites

Bot creation requires membership in the CreatingBotAllowed Cognito user group. Administrators can add users to this group via the AWS Console or CLI.
To grant bot creation permissions:
  1. Navigate to Amazon Cognito in the AWS Console
  2. Select your user pool (find the ID in CloudFormation outputs: AuthUserPoolIdxxxx)
  3. Add users to the CreatingBotAllowed group

​
Creating a Bot

​
Basic Information

Every bot requires:
  • Title: A clear, descriptive name
  • Description: What the bot does (shown in bot store)
  • Instruction: System prompt that defines bot behavior and personality
  • Be specific about the bot’s role and expertise
  • Define the tone and style of responses
  • Include any constraints or guidelines
  • Specify output format if needed
  • Keep instructions concise but comprehensive

​
Generation Parameters

Customize how the bot generates responses: 
{
  max_tokens: 2000,
  temperature: 0.6,
  top_p: 0.999,
  top_k: 128,
  stop_sequences: [],
  reasoning_params: {
    budget_tokens: 1024
  }
}

Conservative

Low temperature (0.1-0.3) for factual, consistent responses. Good for support bots.

Balanced

Medium temperature (0.5-0.7) for general-purpose bots with some creativity.

Creative

High temperature (0.8-1.0) for brainstorming and creative content generation.

Extended Thinking

Higher budget_tokens (10K-64K) for complex reasoning tasks with Claude 3.7.

​
Knowledge Integration

Enhance your bot with domain-specific knowledge using RAG (Retrieval-Augmented Generation). See the Knowledge Bases page for detailed information.

​
Agent Capabilities

Enable your bot to use tools and perform actions. See the Agents page for details on:
  • Internet search
  • Knowledge base queries
  • Calculator functions
  • Custom tool development

​
Model Selection

Control which models users can choose when using your bot: 
active_models = {
    "claude_v3_7_sonnet": True,
    "claude_v3_5_haiku": True,
    "amazon_nova_pro": True,
    "amazon_nova_lite": False,  # Disabled
    # ... other models
}
By default, all globally available models are enabled. Use this setting to restrict models for cost control or specific requirements.

​
Conversation Quick Starters

Provide example prompts to help users get started: 
conversation_quick_starters: [
  {
    title: "Generate Report",
    example: "Create a weekly status report based on the following data..."
  },
  {
    title: "Analyze Data",
    example: "Analyze this dataset and provide key insights..."
  }
]

​
Visibility and Sharing

Control who can access your bot:

​
Private (Default)

  • Only you can access the bot
  • Not visible in bot store
  • Ideal for personal assistants

​
Partial Sharing

  • Share with specific users or groups
  • Requires Cognito user IDs or group names
  • Good for team or department bots
shared_scope = "partial"
allowed_cognito_groups = ["Engineering", "ProductTeam"]
allowed_cognito_users = ["user123", "user456"]

​
Public

  • Available to all users in bot store
  • Can be pinned by administrators
  • Required for API publishing
Only bots with shared_scope = "all" can be published as APIs.

​
Guardrails

Apply content filters and safety controls using Amazon Bedrock Guardrails:
  • Content Filters: Block harmful content categories
  • Denied Topics: Prevent discussion of specific subjects
  • Word Filters: Block or redact specific words/phrases
  • Sensitive Information: Detect and redact PII
  • Contextual Grounding: Reduce hallucinations for RAG bots
bedrock_guardrails = {
    "is_guardrail_enabled": True,
    "guardrail_arn": "arn:aws:bedrock:...",
    "guardrail_version": "1"
}

​
Prompt Caching

Reduce costs and latency for bots with large system prompts or knowledge:
  • Automatically caches processed instruction prompts
  • Significant savings for frequently used bots
  • Enabled by default (can be disabled)
When prompt caching is enabled:
  1. The bot’s instruction and knowledge context are sent to Bedrock
  2. Bedrock caches the processed prompt for ~5 minutes
  3. Subsequent requests reuse the cached prompt
  4. You pay reduced rates for cached tokens
Savings: Up to 90% reduction in input token costs for cached content.

​
Sync Status

Bots with knowledge bases or guardrails require synchronization:
  • QUEUED: Waiting to process knowledge or guardrails
  • RUNNING: Currently processing
  • SUCCEEDED: Ready to use
  • FAILED: Error occurred (check status reason)
The bot is fully functional only when sync status is SUCCEEDED.

​
Bot Updates

Modify bot settings at any time: 
// PATCH /bot/{bot_id}
{
  title: "Updated Title",
  instruction: "New instructions...",
  generation_params: { /* updated params */ },
  agent: { /* updated tools */ }
}
Updating knowledge sources triggers a new sync. The bot remains usable with old knowledge until sync completes.

​
Usage Analytics

Track bot usage and performance:
  • Usage count per bot
  • Last used timestamp
  • User analytics (admin only)
Administrators can view detailed analytics including:
  • Total conversations per bot
  • Token usage and costs
  • Popular bots and trends

​
Example Bot Configurations

{
  "title": "Customer Support Assistant",
  "instruction": "You are a helpful customer support agent. Be empathetic, professional, and solution-oriented. Always ask clarifying questions if needed.",
  "generation_params": {
    "temperature": 0.3,  # Consistent, factual responses
    "max_tokens": 1000
  },
  "knowledge": {
    "filenames": ["support_docs.pdf", "faq.pdf"]
  },
  "display_retrieved_chunks": True  # Show sources
}

{
  "title": "Creative Writing Coach",
  "instruction": "You are a creative writing mentor. Help users develop stories, characters, and plots. Be encouraging and offer specific, actionable feedback.",
  "generation_params": {
    "temperature": 0.9,  # Creative, varied responses
    "max_tokens": 4000
  },
  "conversation_quick_starters": [
    {
      "title": "Character Development",
      "example": "Help me create a complex protagonist for a sci-fi novel"
    },
    {
      "title": "Plot Ideas",
      "example": "I need help brainstorming plot twists for my mystery story"
    }
  ]
}

{
  "title": "Data Analyst",
  "instruction": "You are a data analyst expert. Analyze data, identify patterns, and provide actionable insights. Always explain your reasoning.",
  "generation_params": {
    "temperature": 0.4,
    "max_tokens": 3000
  },
  "agent": {
    "tools": [
      {"tool_type": "plain", "name": "calculator"},
      {"tool_type": "internet", "name": "internet_search"}
    ]
  }
}

​
Best Practices

Clear Instructions

Write clear, specific instructions. Include examples of desired behavior and format.

Test Thoroughly

Test your bot with various inputs before sharing. Iterate on instructions based on results.

Organize Knowledge

Structure knowledge documents clearly. Use descriptive filenames and organize by topic.

Monitor Usage

Review usage analytics to understand how users interact with your bot and optimize accordingly.

​
Next Steps

Add Knowledge

Enhance your bot with RAG and custom documents

Enable Agents

Give your bot tools to perform actions

Share in Store

Make your bot available to other users

Publish API

Create a standalone API endpoint

Build docs developers (and LLMs) love

Get started for freeTalk to us