Create Bot Technical Documentation

This document provides comprehensive technical documentation for the AI Commons "Create My Bot" configuration page, describing the technical behavior of every field, toggle, and control.

Table of Contents

1. Scope and Evidence Model

This document begins at the Create My Bot configuration page. Its purpose is to describe the technical behavior of every visible field, toggle, radio option, slider, dropdown, source control, and submission control shown in the AI Commons interface.

This includes documentation of what happens when a control is:

• Left empty
• Enabled or disabled
• Set to an extreme value
• Combined with another control
• Configured incorrectly

2. System Model

The Create My Bot page controls multiple technical layers:

3. Title Field

The Title field is labeled Required and serves as the human-readable identifier for the AI Commons bot.

Technical Purpose

Title appears in owner/admin views and may also appear in discovery, sharing, conversation headers, direct-link views, logs, or usage reports depending on AI Commons implementation.

Empty Value Behavior

Because Title is required, an empty value prevents successful creation. Frontend behavior includes a disabled Create button. Server-side validation also rejects empty values even if frontend validation is bypassed.

Invalid and Boundary Values

Consequence of Changing Title Later

AI Commons allows the Title to be changed through Update. Renaming changes the display title but does not change the sharing link. The share URL is tied to a persistent internal bot identifier, so previously distributed links continue to work.

4. Description Field

Description is optional user-facing metadata that explains the bot's function. It is not a substitute for Instructions.

Technical Purpose

A description should communicate audience, subject, and major limitations, while Instructions contain operational behavior.

Empty Value Behavior

When left empty, AI Commons displays "No Description" in the My Bots list. The bot still creates normally and remains fully functional.

Contradictory Description and Instructions

AI Commons does not compare Description and Instructions fields or warn when they conflict. For example:

Description: "Answers questions about UCSB admissions"
Instructions: "Only answer questions about graduate admissions"

The Description may give users one expectation while the bot behaves differently through its Instructions. Description should accurately reflect the scope defined in Instructions.

Security and Privacy

5. Instructions Field

The Instructions field provides custom instructions that the bot follows during conversations. This is the primary behavioral configuration mechanism.

Technical Role

Instructions can define several aspects of bot behavior:

• Role: What role the bot should perform
• Task: What kind of questions or tasks it should handle
• Response Style: How responses should be written
• Output Format: Numbered steps, categories, code blocks, etc.
• Scope: Topics within or outside the bot's intended scope
• Out-of-scope Behavior: What to do with requests outside scope
• Tone: Professional, casual, encouraging, etc.
• Audience: Expected user expertise level

Empty Instructions

Instructions is not marked Required. If left empty, the bot will not follow intended behavior—there would be no custom instruction defining role, subject focus, formatting, tone, or special rules.

Instruction Priority and Conflict

Instructions should be internally consistent. Language models do not perform deterministic rule arbitration. If one sentence says "Only use the knowledge base" and another says "Always provide a complete answer," a missing-source question creates a conflict.

Better approach:

"Answer only when the configured authoritative sources support the answer.
If the answer is not supported, state that the information was not found
and do not infer or invent policy, dates, contacts, URLs, requirements,
or system status."

Sample Instructions

AI Commons provides three instruction samples:

Source-Precedence Rules

When multiple information sources are configured (Knowledge Base + Internet Search), Instructions can specify how to use them:

"Use the configured knowledge sources as the primary source for
AI Commons information. Use Internet Search when the requested
information is not available in the configured knowledge or when
current external information is required."

Prompt Injection Considerations

6. Agent Functionality

The Agent section adds tool-based capabilities to the bot. Without enabled Agent capabilities, the selected language model responds using information available directly in its prompt and configured Knowledge.

Available Agent Capabilities

These are independent controls. Internet Search can be enabled without Bedrock Agent, Bedrock Agent can be enabled without Internet Search, or both can be enabled for the same bot.

Tool Use Requirements

Typical Tool-Enabled Flow

User request → model interprets request → model requests tool
→ AI Commons executes tool → tool returns data → model uses returned data
→ final response

When Agent Functionality is Disabled

When both Agent toggles are disabled, neither Internet Search nor the configured Bedrock Agent is available. The bot can still use:

• Normal conversational capabilities
• Instructions
• Conversation history
• Configured Knowledge Base
• The selected model's pre-trained knowledge

This configuration is appropriate for narrowly scoped internal bots whose answers should come from controlled Knowledge rather than live external systems.

7. Internet Search

The Internet Search toggle determines whether public-web search is available as a tool for the bot.

Search Providers

When Internet Search is ON, one provider must be selected:

DuckDuckGo Provider

DuckDuckGo is the lightweight trial search path designed for testing and low-volume use cases. It requires no API key or additional configuration.

• Search Mode: Moderate safe search filtering
• Maximum Results: Up to 20 results per query
• Best For: Development, testing, proof-of-concept, low-volume bots
• Cost: No additional API costs

Firecrawl Provider

Firecrawl is the business-tier search provider with enhanced capabilities and configurability. It requires an API key to be configured.

• API Key: Required (must be provided in configuration)
• Maximum Results: UI allows configuration from 1-50 results; backend schema accepts up to 100
• Best For: Production deployments, high-volume usage, business applications
• Features: More robust crawling, better rate limits, enhanced reliability

Internet Search OFF

With Internet Search disabled, the bot does not obtain public-web results through this feature. This configuration is useful when source control is more important than freshness—for example, a policy bot that should only reference approved internal documents.

Use Cases for Internet Search

8. Bedrock Agent Integration

When Bedrock Agent is enabled, the bot can invoke an existing Amazon Bedrock Agent during conversation processing.

Configuration Requirements

Bedrock Agent Capabilities

Bedrock Agents can provide:

• Action execution (calling APIs, databases, or services)
• Complex multi-step orchestration
• Integration with AWS services
• Custom business logic execution

Implementation Details

When a Bedrock Agent is configured and a user query requires agent capabilities, AI Commons invokes the agent using the following implementation-specific behavior:

Invocation Method

AI Commons calls the invoke_agent API with the configured Agent ID and Alias ID. This initiates the Bedrock Agent's processing pipeline for the user's request.

Trace Collection

Trace collection is enabled during agent invocation. This captures detailed information about the agent's execution, including:

• Which tools were invoked by the agent
• Input parameters passed to each tool
• Responses received from tools
• Reasoning steps taken by the agent
• Decision-making process and intermediate states

Response Assembly

AI Commons returns the agent's final output together with trace-derived artifacts. These artifacts include:

• Tool invocations: Details about which external tools or APIs were called
• Thinking artifacts: The agent's reasoning process and intermediate conclusions
• Execution trace: Full trace of the agent's multi-step workflow

Bedrock Agent vs. Internet Search

While both are Agent capabilities, they serve different purposes:

9. Knowledge Base Configuration

The Knowledge section configures what information the bot can retrieve to answer questions. This is separate from the model's pre-trained knowledge.

Knowledge Source Options

AI Commons supports multiple knowledge source types. When creating a new Knowledge Base-backed bot, you can configure the following sources:

S3 Configuration Details

• Path Format: S3 paths must follow the pattern s3://bucket/path/.../
• Trailing Slash: All S3 paths must end with a trailing slash (/)
• Prefix-Based: Paths act as prefixes; all objects under the prefix are included
• Validation: Invalid path format will prevent bot creation
• Maximum Sources: Up to 4 S3 data sources can be configured per bot

Web Crawler Configuration

• URLs: Specify up to 10 normal URLs as starting points
• Crawler Scope: Define how deep the crawler should follow links
• Include Patterns: Regex patterns for URLs to include during crawling
• Exclude Patterns: Regex patterns for URLs to exclude from crawling
• Use Case: Best for public documentation sites and knowledge bases

Existing Knowledge Base Mode

When selecting an Existing Knowledge Base, the configuration workflow differs significantly:

• Configuration Required: Only the existing KB ID is needed
• No Source Management: You cannot add, modify, or manage sources through this interface
• Read-Only Knowledge: The knowledge content is managed in the original KB, not through the bot
• Shared Knowledge: Multiple bots can reference the same existing KB
• Advanced Settings Disabled: Parsing, chunking, and embedding settings are inherited from the existing KB

Display Retrieved Chunks / Citation Behavior

The Display Retrieved Chunks control determines whether retrieved source references and citations are surfaced to end users in the chat interface.

When Enabled (ON):

• Retrieved chunks are displayed to users
• Source citations are included with responses
• Users can see which documents informed the answer
• Citations are stored as related documents in the conversation
• Increases transparency and allows source verification

When Disabled (OFF):

• Retrieval still occurs behind the scenes
• Retrieved context is used to generate responses
• Source references are not shown to users
• Citations are not stored in the conversation
• Cleaner UI, but less transparency about sources

Knowledge Creation and Update Behavior

When you create or modify knowledge sources, AI Commons triggers a sync and rebuild process rather than an immediate final save. Understanding this behavior is important for timing expectations:

On Initial Creation:

• Bot is created immediately with configuration saved
• Knowledge base sync/ingestion begins asynchronously
• Documents are fetched, parsed, chunked, and indexed
• The bot is usable immediately but retrieval improves as indexing completes

On Knowledge Updates:

• Changes trigger a rebuild of affected portions of the knowledge base
• New documents are added to the index
• Removed sources are cleaned from the index
• The process happens asynchronously; the bot remains operational

Existing KB Mode Restrictions:

When using an Existing Knowledge Base, knowledge editing is disabled because the KB is managed separately. You cannot add, remove, or modify sources through the bot's knowledge configuration interface.

Read-Only Settings After Knowledge Base Creation

Settings That Become Read-Only:

Settings That Remain Editable:

While the structural settings above are read-only, you can still modify:

• Knowledge Sources: Add, remove, or update uploaded files, S3 paths, and web crawler URLs (except in Existing KB mode)
• Citation Display: Toggle Display Retrieved Chunks ON/OFF
• Retrieval Settings: Adjust max retrieved results and search mode
• Content: Update document content by re-uploading or syncing from sources

Knowledge Processing Pipeline

10. Quick Starters

Quick Starters are pre-configured conversation prompts that appear when users begin a new conversation with the bot. They help users understand what the bot can do and provide easy starting points for common queries.

Field Requirements

Runtime Behavior

The behavior of a Quick Starter depends on whether a Response is configured:

Quick Starter WITHOUT Response (Response field empty)

• User clicks the Quick Starter button
• The starter title is submitted as the user's first message
• The bot generates a response live, as with any normal user query
• Generation uses the configured model, Instructions, and knowledge retrieval
• Use Case: Standard prompts where you want fresh, generated responses

Quick Starter WITH Response (Response field configured)

• User clicks the Quick Starter button
• The conversation begins with a pre-seeded assistant reply
• The pre-configured response is displayed immediately
• No live generation occurs for that first turn
• The conversation continues normally from that point
• Use Case: Fixed welcome messages, disclaimers, or scripted introductions

Best Practices

• Clear Titles: Use concise, action-oriented titles (e.g., "Check my order status")
• Representative Examples: Choose starters that represent common use cases
• Pre-seed Sparingly: Use pre-seeded responses only for fixed content like disclaimers
• Test Both Modes: Verify that empty-response starters generate appropriate live answers
• Update Regularly: Review Quick Starters when bot capabilities change

11. Generation Settings

Generation settings control how the model produces responses. These parameters affect response quality, creativity, and behavior.

Key Generation Parameters

Temperature Guidelines

Stop Sequences

Stop sequences are optional strings that, when generated, cause the model to stop producing output. They are useful for controlling response format and preventing unwanted continuation.

Storage Format

Stop sequences are stored as a comma-split list. When configuring multiple stop sequences, separate them with commas in the UI field.

Example stop sequences:
- "\n\nHuman:"
- "---END---"
- "\n\nSources:"

Multiple sequences: "\n\nHuman:,---END---,\n\nSources:"

Model-Specific Behavior

• Claude models: Stop sequences are applied as specified
• Amazon Nova models: Stop sequences are applied as specified
• Qwen models: Stop sequences are not used in the current implementation
• OpenAI GPT-OSS models: Stop sequences are not used in the current implementation

Reasoning Budget

The Reasoning Budget controls how many tokens can be allocated to extended reasoning processes for models that support explicit reasoning steps.

Configuration

• Range: 1,024 through maxTokens
• Default: 1,024 tokens
• Purpose: Allocates computational budget for internal reasoning before generating the final answer

Model-Specific Implementation

The Reasoning Budget maps to different backend parameters depending on the model:

Qwen Models

For Qwen models, the Reasoning Budget maps to reasoning_effort only when reasoning is explicitly enabled. If reasoning mode is not enabled for the request, the budget parameter is not used.

GPT-OSS Models

For GPT-OSS models, reasoning_effort is always derived from the Reasoning Budget, regardless of whether explicit reasoning mode is requested. The budget value influences how much internal processing the model performs.

Budget Overflow Handling

Model-Specific Generation Quirks

Different model families have specific behaviors and limitations:

Amazon Nova Models

• Top K Clamping: Nova models effectively clamp Top K values above 128 to 128
• Effective Range: While the UI accepts 0-500, values above 128 have no additional effect
• Recommendation: Use Top K values between 0-128 for Nova models

Qwen and GPT-OSS Models

• Stop Sequences: Not used in the current Qwen/OpenAI GPT-OSS inference paths
• Alternative: Use Instructions to specify output termination patterns instead

12. Advanced Settings

Advanced Settings control the knowledge-index architecture and retrieval behavior. These settings significantly impact answer quality and system performance.

Embedding Models

The embedding model converts text into vector representations for semantic search. Different embedding models have different strengths:

Parsing Methods

How documents are initially processed before chunking:

• Foundation Model Parsing: Uses AI to understand document structure and extract meaningful content with semantic awareness
• Default Parsing: Standard text extraction without AI enhancement

Analyzer Control

The Analyzer controls how text is tokenized and indexed for keyword search in hybrid retrieval mode.

• Purpose: Enables keyword matching alongside semantic similarity
• Default: Standard text analysis (tokenization, stemming, stop word removal)
• Custom Options: Can be configured to handle domain-specific terminology or language-specific processing
• Impact: Affects the quality of keyword matches in hybrid search mode

Chunking Strategy

Determines how documents are split into retrievable chunks. The chunking strategy directly impacts:

• What information can be retrieved together
• How precisely the system can answer questions
• Whether related information stays together
• Retrieval performance and accuracy

Fixed-Size Chunking

Splits documents into equal-sized chunks with optional overlap between consecutive chunks.

Best for: Uniform content, predictable structure, when consistent chunk size matters

Hierarchical Chunking

Creates parent-child chunk relationships where child chunks contain detailed content and parent chunks provide broader context.

Best for: Complex documents, nested information structures, when you need both detail and context

Semantic Chunking

Splits content at natural semantic boundaries (paragraphs, sections, topic shifts) rather than fixed token counts.

Best for: Maintaining context, coherent passages, documents with clear semantic structure

Chunking Configuration Summary

Retrieval Settings

13. Guardrails Configuration

Guardrails provide safety and content filtering capabilities to ensure bot responses meet organizational policies and safety standards. They analyze both user inputs and bot outputs to detect and filter harmful or inappropriate content.

Content Filter Categories

AI Commons supports the following harmful content categories for filtering:

Grounding and Relevance Checks

In addition to content filters, guardrails can enforce response quality requirements when used with a Knowledge Base:

Sensitivity Levels and Configuration

Each guardrail can be configured with a sensitivity threshold that determines how aggressively content is filtered or checked.

Content Filter Sensitivity (Hate, Insults, Sexual, Violence, Misconduct)

• Range: 0 - 3 (integers)
• Type: Integer values only
• Meaning:
  • 0: Filter disabled (default)
  • 1: Low sensitivity - only blocks clearly harmful content
  • 2: Medium sensitivity - balanced filtering
  • 3: High sensitivity - aggressive filtering, may have false positives

Grounding Check Sensitivity (Contextual Grounding, Relevance)

• Range: 0.0 - 0.99 (decimals)
• Type: Decimal/float values
• Meaning:
  • 0 or 0.0: Check disabled (default)
  • 0.01 - 0.49: Lower thresholds - more lenient, fewer blocks
  • 0.50 - 0.79: Medium thresholds - balanced checking
  • 0.80 - 0.99: Higher thresholds - stricter checking, more blocks

Guardrail Activation Rule

Activation Examples:

Guardrails and Knowledge Base Interaction

The effectiveness and behavior of guardrails can depend on whether a Knowledge Base is configured:

Without Knowledge Base:

• Content Filters: Work normally - detect harmful content in inputs and outputs
• Contextual Grounding: Cannot function meaningfully (no retrieved context to check against)
• Relevance Check: Limited effectiveness (no knowledge base to establish relevance)
• Recommendation: Focus on content filters only

With Knowledge Base:

• Content Filters: Work normally - detect harmful content
• Contextual Grounding: Fully functional - verifies responses are supported by KB content
• Relevance Check: Fully functional - ensures responses address queries based on KB
• Recommendation: Can use all guardrail types effectively

Performance and Cost Considerations

Best Practices:

• Start with content filters at medium sensitivity (2) for public-facing bots
• Enable grounding checks only when using a Knowledge Base and accuracy is critical
• Test sensitivity thresholds with real traffic to find the right balance
• Monitor false positive rates and adjust sensitivity as needed
• Consider whether all five content categories are necessary for your use case

14. Model Activation

Model Activation determines which foundation models are available for this bot. This functions as an allowlist: multiple models can be activated simultaneously, and users can choose among the activated models when chatting with the bot.

Available Model Tiers

Fallback Behavior When Models Are Removed

Fallback Scenarios:

Best Practices for Model Management:

• Communicate Changes: Notify users before removing models they may be actively using
• Test Fallback: Ensure the first model in your allowlist is a suitable default for most use cases
• Maintain Consistency: Avoid frequent changes to the active model list in production bots
• Monitor Usage: Track which models users select to inform deactivation decisions

Multi-Model Considerations

When to Enable Multiple Models:

• Diverse Use Cases: Bot serves both simple and complex tasks
• Cost Optimization: Let users choose cost-effective models for routine queries
• Performance Trade-offs: Offer fast models for quick responses, powerful models for deep analysis
• Modality Requirements: Some users need multimodal (image/video), others need text-only

When to Limit to One Model:

• Consistent Experience: All users should get identical behavior
• Specialized Bot: Bot is tuned for one specific model's capabilities
• Simplified Testing: Easier to validate Instructions with a single model
• Controlled Costs: Prevent users from selecting expensive models unnecessarily

Model Selection Guidelines

Relationship to Agent Tools

When Internet Search or Bedrock Agent is enabled, activated models must be compatible with Tool use. A model suitable for conversational generation is not automatically guaranteed to support the specific tool invocation architecture.

Cost and Latency Considerations

Model selection is both a functional and operational decision. Compare:

• Answer correctness
• Instruction following accuracy
• Retrieval-grounded accuracy
• Tool performance
• Response latency
• Token consumption
• Cost per successful task

Goal: Choose models whose capability is appropriate to the work users actually perform, not necessarily the most powerful model for every request.

Summary

The Create My Bot configuration page provides comprehensive control over bot behavior, capabilities, and safety. Key takeaways:

• Instructions define behavioral rules; Knowledge provides factual content
• Agent tools extend capabilities beyond static knowledge
• Generation settings control response quality and creativity
• Advanced settings impact retrieval accuracy and performance
• Guardrails ensure safety and policy compliance
• Model selection balances capability, cost, and latency