Custom Agents

​

Overview

• Custom instructions — Define how the agent responds.
• Enterprise knowledge — Connect internal data sources.
• Tool integrations — Access external systems and APIs.
• Configurable behavior — Control tone, scope, and capabilities.

​

Agent Types

​

Prompt Agents

​

When to Use Prompt Agents

• Creating standardized documents (job descriptions, project proposals, marketing copy) that follow organizational templates.
• Generating consistent reports, summaries, or communications that maintain brand voice and formatting.
• Producing multiple content variations for A/B testing or different audiences.

• Translating content into multiple languages while maintaining context and tone.
• Summarizing lengthy documents, reports, or meeting transcripts with consistent structure.
• Converting technical documentation into user-friendly formats or different complexity levels.

• Processing uploaded files (.pdf, .docx, .csv, .xls) to extract insights, generate summaries, or create reports.
• Analyzing data patterns and generating standardized analytical reports.
• Creating executive summaries from complex datasets or research documents.

​

How Prompt Agents Work

• User-Collected Inputs: User inputs are incorporated into the prompt as variables to generate the required response. For example, a job description (JD) is created using user inputs about experience, responsibilities, and required skills.
• Administrator-Uploaded Knowledge: Administrators upload a file used as a template. For example, a JD is generated based on user-provided inputs and a pre-uploaded template that ensures consistency and formatting.

​

Import an Existing Prompt Agent

1. Click Import Agent in the upper-right corner.
2. Select the .ZIP file of the existing agent.
3. Click Import. The imported agent appears on the Agents page.

​

Create a Prompt Agent

​

Step 1: Details and Purpose

​

Step 2: Source Configuration

User Input

1. Click +Add context to add a context field.
2. Enter a context name and optional placeholder text. Placeholder text appears in the form field before the user provides input.
3. Select the Field type: single-line, multiline, or file upload.
4. Toggle Mandatory if the field is required, then click Done.
5. In the Parameters section, fields are pre-populated based on the agent’s purpose. Click +Add field to add more.
6. For each parameter field, enter a name, placeholder text, and a Description that explains the field’s purpose in detail — this helps the LLM identify and pre-populate the field from natural language queries. For example, if you need a field for organizational departments, name it and describe that it accepts internal department names so the LLM can match it from queries.
7. Select the Field type: single-line, multiline, single-select, multi-select, number, or file upload.
8. Toggle Allow Upload Files or Allow URL Content to enable file uploads or URL-based retrieval. This option is available only for single-line and multiline text fields.
9. Toggle Mandatory if required, then click Done.

Knowledge

1. Click + Upload to upload a knowledge file (template, reference document, etc.) that the agent uses to generate responses. You can reference uploaded files directly in prompts. For example: “Create a JD in the same format as the Sample JD template file.”
   If the file size exceeds the model’s context limit, an error is displayed listing affected models. When the limit is exceeded, all uploaded knowledge files are referenced for answering but not for generation.
2. Select the model from the Model selection drop-down. To learn more, see LLM Configuration.
3. Toggle Show to users to display the prompt to end users. When enabled, select Read-only or Editable.

Prompts

Multi Prompt

1. Click the edit option or anywhere in the prompt area to expand available options.
2. Edit the prompt selector’s field name and optional placeholder text. The Mandatory toggle is enabled by default and cannot be modified.
3. The Prompt Options list shows all created prompts — drag and drop to reorder.
4. Click Done.

Multi Response

1. Enable Allow users to generate multiple responses in the output settings.
2. Enable Skip Form Display to automatically bypass forms when all required entities are present in the initial query. This feature prevents conflicts with Multi-Response and shows messages for incompatible settings.
3. Click Continue.

​

Step 3: Business Rules

• Entity Rule: Automatically adds entities to queries based on detected keywords, even if the user doesn’t mention them explicitly.
• Answering Rule: Controls and customizes responses when specific conditions or keywords are met.

​

Step 4: Appearance and Behavior

​

Step 5: Publish

​

User Interaction

​

API Agents

​

Key Features

• Easy Setup: Step-by-step wizard in the Admin Console
• Flexible Configuration: Supports various API types, authentication methods, and data processing options
• Customizable Fields: Select and configure up to 10 fields for querying and display
• Intelligent Querying: Handles simple lookups, compound queries, and computational requests
• Data Processing: ID and meta-resolution for presenting meaningful information to end users
• Preview and Testing: Validate configurations before publishing
• Sharing Options: Share with specific users, groups, or the entire organization

​

Prerequisites

• Standard REST APIs with JSON response format from Systems of Records (SOR)
• Maximum 500 records per API call
• Stable API endpoints with consistent data schema

• Customer Relationship Management (CRM) platforms
• Enterprise Resource Planning (ERP) systems
• Human Resources Information Systems (HRIS)
• Database management systems with REST API access
• Business applications with well-defined data models

• Administrator access to the system you want to integrate
• API documentation for the Schema API and Action API
• cURL commands for the ID resolver and meta resolver

​

Create an API Agent

​

Step 1: Purpose of Agent

​

Step 2: Basic Details

​

Step 3: Connection Setup

​

Step 4: Actions

Step 4.1: Purpose

Step 4.2: Data

• API defining the fields: Select if you have an API that explicitly defines data fields. Helps with field names and pre-fills values for single-select and multi-select fields.
• Continue with Data API: Select if you don’t have a data-defining API. This skips the Schema API and Label Selection steps, going directly to the Data API tab.

1. On the Schema API tab, define the API manually or click CURL Import.
2. In the import pop-up, paste the URL and click Import.
3. Click Run. On success, click Continue. If an error occurs, an appropriate message is displayed.

1. On the Data API tab, click CURL Import.
2. Paste the URL and click Import.
3. Click Run. On success, click Understood.

1. Click + in the Field Value Resolver column.
2. In the Value Resolver pop-up:
   • If the resolver doesn’t find the JSON: Click Define API > CURL Import (or use a Dictionary), paste the URL, click Import, enter a sample input, click Run, then close the pop-up.
   • If the resolver finds the JSON: Click Goto Mapper > Map Value (select the field displayed to users, for example displayName) > Map ID (select the field passed to the API, for example accountId). Map color, icon, and icon color fields if available, then close the pop-up.

1. Click + in the Field Options column.
2. Enter Map Value (sent to the API) and Map Label (displayed to users) for each option.
   • If the schema API is mapped: click Map Value and Map Label to select JSON fields; remaining choices auto-populate.
   • If not mapped: enter values manually for each choice.
3. Close the pop-up.

1. Click + in the Field Meta Resolver column.
2. Click CURL Import or use a Dictionary.
3. Paste the URL and click Import.
4. Enter a Sample Input and click Run.
5. Output Fields are displayed. Close the pop-up. The ID resolver is now displayed.
6. Click Continue.

1. On the field value resolver or field meta resolver pop-up, toggle Use Dictionary.
2. Click + Create.
3. On the Name & API tab, enter the dictionary name, API call details, and pagination details if required.
4. Click Run API. The Field Selection tab is displayed.
5. Select the fields to be searched, the ID resolver field, the Schedule to Pool data frequency, and the meta resolver field.
6. Click Pool data into the dictionary. The Preview tab displays the pooled data.
7. Click Done. The dictionary is saved.

1. Click + Create URL.
2. Enter a static URL (for example, https://team.atlassian.net/browse/).
3. In the Variable Mapper, select the dynamic key from the response object.
4. Click Done. Click Continue.

Step 4.3: Query Filters

1. In the Allow Query column, select queryable fields (all are selected by default).
2. Check Allow multiple values for fields that support multi-value queries.
3. Check Mandatory for fields that users must specify before data is returned. This option is disabled if the corresponding Allow Query field is not selected.
4. Edit Field_Filter_Key if the key differs between push and retrieval operations. Keys are generated based on the API response.
5. Click Configure to generate sample queries based on the field filter settings.
6. Click Upload API documentation, paste the API documentation, and click Save. Query parameters are auto-populated.
7. Click Sample Query to extract variables.
8. Build the API payload based on the API type:
   • GET: Configure the query parameters section (editable inline). Add additional parameters as needed.
   • POST: Configure the body payload.
   Ensure the configuration includes only variables in place of entities. This allows APIs to be dynamically generated at runtime.
9. Click Run to generate the configuration builder script. The script runs on the sample query and displays the API response.
10. Click Run Queries to test all generated queries. Success or error messages are displayed per query.
11. Optionally, click Script to view and edit failed queries. You can proceed without fixing — only successful and similar queries will work after publishing.
12. Click Continue.

• Entity Rule: Automatically adds entities to queries when specific keywords are detected. Example: Interpreting “active deals” as deals in stages “presentation,” “working progress,” or “contract in progress.”
• Answering Rule: Controls and customizes responses when specific conditions are met. Example: Responding with “contact sales” for any pricing-related questions.

Step 4.4: Sample Queries

​

Step 5: Business Rules

​

Step 6: Publish

​

Writing API Payloads with JavaScript

(function (headers, body, queryParams) {
    // Write your code here
    return { headers, queryParams, body }
})(headers, body, queryParams);

• queryParams: Array of objects — { key: 'jql', value: '...', enabled: true }. Elements with enabled: false are ignored.
• headers: Same structure as queryParams — { key: 'Content-Type', value: 'application/json', enabled: true }.
• body: The JSON payload expected by the API.

entities : {
    fieldId : {
        filterKey : fieldFilterKey,   // from field filter configuration
        dataType  : "text" | "number" | "date" | "singleSelect" | "multiselect" | "object" | "objectArray",
        // Simple queries:      value
        // Range queries:       min, max, value
        // Multi-value queries: values[]
    }
}

(function (headers, body, queryParams) {
    const jqlParts = [];
    for (const entityKey in entities) {
        const entity = entities[entityKey];
        if (entity.value) jqlParts.push(`${entity.filterKey} = ${entity.value}`);
        if (entity.values) {
            const valuesString = entity.values.map(v => `'${v}'`).join(', ');
            jqlParts.push(`${entity.filterKey} IN (${valuesString})`);
        }
        if (entity.min) jqlParts.push(`${entity.filterKey} >= ${entity.min}`);
        if (entity.max) jqlParts.push(`${entity.filterKey} <= ${entity.max}`);
    }
    const jqlQuery = jqlParts.join(' AND ');
    queryParams.push({ key: 'jql', value: jqlQuery, enabled: true });
    return { headers, queryParams, body }
})(headers, body, queryParams);

(function (headers, body, queryParams) {
    const filterGroups = { filters: [] };
    for (const entityKey in entities) {
        const entity = entities[entityKey];
        if (entity.min) filterGroups.filters.push({ propertyName: entity.filterKey, operator: 'GTE', value: entity.min });
        if (entity.max) filterGroups.filters.push({ propertyName: entity.filterKey, operator: 'LTE', value: entity.max });
        if (entity.value) filterGroups.filters.push({ propertyName: entity.filterKey, operator: 'EQ', value: entity.value });
        if (entity.values && entity.values.length > 0) filterGroups.filters.push({ propertyName: entity.filterKey, operator: 'IN', value: entity.values });
    }
    body.filterGroups = [filterGroups];
    body.properties = ['dealname', 'hubspot_owner_id', 'amount', 'dealstage', 'pipeline', 'hs_priority', 'hs_updated_by_user_id'];
    return { headers, queryParams, body }
})(headers, body, queryParams);

​

User Interaction

​

Search Agents

• Search AI: Configure and index content from knowledge bases, files, and websites. Use when you need full control over content sources within your environment.
• Amazon Q: Index enterprise data in your AWS cloud using 90+ connectors for AWS and non-AWS systems. Provides comprehensive search while maintaining data sovereignty.

​

Prerequisites

1. Create a Search AI application.
2. Configure content sources.
3. Fine-tune search settings.
4. Enable Answers.
5. Train the application.
6. Enable the Client Channel with the appropriate API scopes: Answer Generation, Permission Entity Management, Document Management, and Facets.

• An existing Amazon Q Business application with indexed enterprise content
• Appropriate AWS credentials and permissions
• Access to AWS data accessor configuration details

​

Create a Search Agent

​

Step 1: Details and Purpose

​

Step 2: Configure Search Index

​

Step 3: Appearance and Behavior

​

Step 4: Publish

​

Agentic Flow Agents

​

Create an Agentic Flow Agent

​

Step 1: Details and Purpose

• Agent Name: Enter a unique, meaningful name.
• Purpose: Defines the intended functionality for query routing and training. Specifies the default prompt and sample queries for accurate routing.

​

Step 2: Build Agentic Flow

1. Review the auto-generated Prompt based on the agent’s purpose. The system auto-generates workflow steps. For example, a financial advisor workflow might include: perform research, check who owns the shares, and decide to sell or hold based on research.
2. Click Get Flow to review the generated flow.
3. Customize your flow:
   • Add a step: Click + Add above or below any existing step.
   • Edit or delete a step: Hover over the step and select the edit or delete option.
   • Reorder steps: Drag and drop steps to the desired position.
4. Click Run to execute all configured steps sequentially.
5. Click Continue.

​

Step 3: Appearance and Behavior

​

Step 4: Publish

​

Example: Finance Advisor

​

Autonomous Agents

​

Create an Autonomous Agent

• Icon: Choose from the predefined library or upload a custom icon.
• Agent Name: Enter a unique, meaningful name.
• Purpose of Agent: Define the intended functionality for query routing and training.

1. Click +Add Query to add test queries.
2. Enable Allow End User Notification to enable notification configuration and agent trigger setup. See Notifications.
3. Enable Clear End-User Chat History to delete chat history after a specified period.
4. Click Publish to proceed.

​

Import an Existing Autonomous Agent

1. Click Import Agent in the upper-right corner.
2. Select the .ZIP file of the existing agent.
3. Click Import. The agent appears on the Autonomous Agents page.

​

Usage

​

Bot Agents

​

Import an Existing Bot Agent

1. Click Import Agent in the upper-right corner.
2. Select the .ZIP file of the existing agent.
3. Click Import. The agent appears on the Bot Agents page.

​

Create a Bot Agent

1. In the AI for Service Platform, open your virtual assistant. Navigate to Deploy > Channels > Add More > Webhook.
2. Select the required app from the Webhook dialog.
3. Copy the Bot client ID and Bot secret ID for use in Step 2 below.
4. Under Configured Channels, click the bot name and enable the channel.

​

Step 1: Details and Purpose

​

Step 2: Add Bot

1. Enter the following in the Add Bot section:
   • Post URL: API endpoint (auto-populated).
   • Access Token: Authentication token (auto-populated).
   • Webhook URL: URL from the Bot Webhook dialog.
   • Bot client ID: Copied from the Bot Webhook dialog.
   • Bot secret ID: Copied from the Bot Webhook dialog.
   
2. Click Connect account.

​

Step 3: Appearance and Behavior

1. Click +Add Query to add test queries.
2. Enable Allow End User Notification to enable notification configuration. See Notifications.
3. Enable Clear End-User Chat History to delete chat history after a specified period.
4. Click Publish to proceed.

​

Step 4: Publish

​

User Interaction

• Alert API — Integrate conversation hold and resume functionality within AI for Service Bots.
• Notify API — Send interactive notifications to users.

​

Workflow Agents

​

Import an Existing Workflow Agent

1. Click Import Agent in the upper-right corner.
2. Select the .ZIP file of the existing agent.
3. Click Import. The agent appears on the Workflow Agents page.

​

Create a Workflow Agent

​

Step 1: Details and Purpose

​

Step 2: Configure Workflow Flow

1. In the Workflow Platform, open the agent and click Agent endpoint in the left navigation.
2. Select Async push and click the settings icon.
3. Paste the POST URL and Access Token into the Sync/Async mode setup page.
4. Click Save.

1. On the Define API page, click CURL Import.
2. In the Workflow Platform, navigate to the agent’s Agent endpoint and copy the appropriate cURL (sync cURL for sync mode, async cURL for async mode).
3. Paste the cURL into the Import URL dialog and click Import.
4. Click Run to fetch API details.
5. Retrieve the API key: in the Workflow Platform, go to API Keys > Create new key > Generate Key, then click Copy and Close.
6. Paste the API key into the API key value field and click Continue.
7. Review the API response output keys — these map to the values displayed to end users.
8. Click Continue.

​

Step 3: Appearance and Behavior

1. Click +Add Query to add test queries.
2. Enable Allow End User Notification to enable notification configuration. See Notifications.
3. Enable Clear End-User Chat History to delete chat history after a specified period.
4. Click Publish to proceed.

​

Step 4: Publish

​

Manage Input and Output

• Input Variables: Provide initial data to the agent flow.
• Output Variables: Store and return derived values from the flow. Define output variables to capture the results you want the agent to return.

​

User Interaction

​

MCP Agents

​

How MCP Agents Work

1. Tool Discovery: During MCP server configuration, the MCP Client discovers available tools on the server, enabling the application to learn server capabilities. You then assign these tools to agents for dynamic decision-making.
2. Intent Detection: When a user sends a query, the system sends the tool list and query to the LLM for intent detection and tool invocation. The LLM identifies the tool to use and forms a structured tool call.
3. Tool Invocation: The MCP Client sends a structured request to the MCP Server with the tool name and required parameters.
4. Execution: The MCP Server executes the tool logic and sends results back to the MCP Client.
5. Response Generation: The agent uses the tool’s output to formulate a natural language response via the LLM.

​

Create an MCP Agent

1. Define the agent’s details and purpose:
   • Icon: Choose from the predefined library or upload a custom icon.
   • Agent Name: Enter a unique, meaningful name.
   • Purpose of Agent: Define the intended functionality for query routing and training.
2. In the Configure MCP section, the platform displays all tools available from both workspace and account connections.
3. Select the specific tools you want the agent to use.
4. Configure each tool’s input parameters (see Configuring Tool Parameters).
5. (Optional) Business Rules: Set entity or answering rules triggered by specific keywords.
6. Click Save and Publish.

​

Configuring Tool Parameters

​

Static Values

• Show in End-User Form: Make the field visible to end users.
• Set as Editable: Allow end users to modify the value.
• Set as Read-Only: Display the value but prevent changes.

​

Dynamic Values

• Extract from Query: The system extracts values from the user’s natural language input via entity extraction.
• Form Field Collection: If the system cannot extract a value, it displays the field in the end-user form to collect the value directly.

​

Configuring a Tool

1. During agent creation or editing, select the tool to configure.
2. For each parameter, review:

   Field	Description
   Group	Logical grouping or category of the parameter
   Field Name	Unique identifier for the parameter
   Description	Purpose and expected input
   Field Type	Expected data type (string, number, boolean, etc.)
   Required/Optional	Whether the parameter is mandatory

   
3. Choose the input type:
   • Static Values: Enter the value; select form visibility; choose editable or read-only.
   • Dynamic Values: Select Extract from Query to use entity extraction.
4. Save the tool configuration.

​

Enabling and Disabling Tools

• Enabled: The agent can invoke the tool during interactions.
• Disabled: The agent cannot use the tool, but the configuration is retained.

​

End-User Experience

1. The platform displays a form with the required input fields for the selected tool.
2. Data types in the form match those defined by the MCP server.
3. Values extracted from the user’s query via entity extraction are pre-filled.
4. The Continue button remains disabled until all mandatory fields are complete.
5. When the user clicks Continue, the agent executes the corresponding MCP action.
6. Results are displayed as a natural language response.

1. User asks: “Send an email to john@example.com about tomorrow’s meeting.”
2. Agent displays a form:
   • Recipient: Pre-filled with john@example.com (extracted from query)
   • Subject: Empty field (mandatory)
   • Body: Empty field (mandatory)
3. User fills in subject and body, clicks Continue.
4. Agent invokes the Gmail tool through the MCP server with all parameters.
5. Result displayed: “I’ve sent the email to john@example.com successfully.”

​

Manage MCP Agents

1. Navigate to MCP Agents and select the agent.
2. Click Edit.
3. Update any of the following: agent name, description, tool selections, tool parameter configurations, or tool enable/disable status.
4. Click Save. Changes take effect immediately on the next user interaction.

1. During agent creation or editing, click Add MCP Tools.
2. Select tools from your first MCP connection.
3. Click Add MCP Tools again and select tools from a different connection.
4. Configure each tool’s parameters independently.
5. Save the agent.

1. Refresh the MCP connection.
2. Navigate to the affected agent and click Edit.
3. Review tool configurations for changes.
4. Reselect or reconfigure tools as needed.
5. Save the agent.

​

MCP Connections

• Without MCP: Each tool integration requires separate, custom logic per system.
• With MCP: All systems are accessed through a single, consistent interface — dramatically simplifying development and reducing complexity.

​

Key Features

​

Connection Levels

​

Workspace-Level Connections

• Accessible only within a specific workspace.
• Available to all agents within that workspace.
• Not visible or accessible outside the workspace.

​

Account-Level Connections

• Created under Connections in the Account Hub.
• Accessible across all workspaces, including personal workspaces.
• When viewed from within a workspace: displayed in read-only mode; authentication profiles and URLs are hidden for security.

​

Create an MCP Connection

​

Manage MCP Connections

1. Navigate to Connections and locate the connection.
2. Click Refresh.

1. Navigate to Connections, select the connection, and click Edit.
2. Update server endpoints, authentication credentials, or custom headers.
3. Click Save. The system validates the updated configuration and retrieves the current tool list.

1. Navigate to Connections, locate the connection, and click Delete.
2. Confirm the deletion.

​

Enterprise Knowledge

​

Search AI Connector

1. Navigate to Enterprise Knowledge > Search AI.
2. Select your Search AI application.
3. Configure retrieval settings:
   • Top K results — Number of chunks to retrieve
   • Similarity threshold — Minimum relevance score
   • Source filtering — Limit to specific content sources

​

Agentic Apps Connector

1. Navigate to Enterprise Knowledge > Agentic Apps.
2. Select the agentic app to connect.
3. Configure access permissions.

​

Amazon Q Connector

1. Navigate to Enterprise Knowledge > Amazon Q.
2. Configure AWS credentials.
3. Select the Amazon Q application.
4. Set access permissions.

​

Publishing Your Agent

• Everyone in the Account: Make the agent available to all users.
• Limited Users: Grant access to specific workspace users or groups defined in workspace publish settings.

• Always Enabled: The agent remains active and cannot be disabled by users.
• Users Choice: Users can enable or disable the agent as needed.

​

Agent Management

​

Versioning

• View version history
• Compare versions
• Roll back to previous versions
• Tag versions for releases

​

Access Control

​

Monitoring

• Conversation volume
• Response quality metrics
• Error rates
• User satisfaction

​

Best Practices

​

Instructions

• Be specific about agent scope and limitations.
• Include examples of good responses.
• Define escalation paths for edge cases.
• Specify tone and communication style.

​

Knowledge

• Keep knowledge sources up to date.
• Use specific source filtering for accuracy.
• Test retrieval quality regularly.
• Monitor for outdated information.

​

Testing

• Test edge cases and error scenarios.
• Validate tool integrations.
• Check guardrail effectiveness.
• Get feedback from target users.