ai_agents

Creates, updates, deletes, gets or lists an ai_agents resource.

Overview

Name	ai_agents
Type	Resource
Id	aws.qconnect.ai_agents

Fields

The following fields are returned by SELECT queries:

get_ai_agent

Name	Datatype	Description
ai_agent	object	The data of the AI Agent.
version_number	integer (int64)	The version number of the AI Agent version (returned if an AI Agent version was specified via use of a qualifier for the aiAgentId on the request).

list_ai_agents

Name	Datatype	Description
name	string	The name of the AI Agent. (pattern: <code>[a-zA-Z0-9\s_.,-]+.*</code>)
ai_agent_arn	string	The Amazon Resource Name (ARN) of the AI agent. (pattern: <code>arn:[a-z-]?:wisdom:[a-z0-9-]?:[0-9]{12}:[a-z-]*?/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}(?:/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}){0,2}</code>)
ai_agent_id	string	The identifier of the AI Agent. (pattern: <code>[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}</code>)
assistant_arn	string	The Amazon Resource Name (ARN) of the Amazon Q in Connect assistant. (pattern: <code>arn:[a-z-]?:wisdom:[a-z0-9-]?:[0-9]{12}:[a-z-]*?/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}(?:/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}){0,2}</code>)
assistant_id	string	The identifier of the Amazon Q in Connect assistant. Can be either the ID or the ARN. URLs cannot contain the ARN. (pattern: <code>[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}</code>)
configuration	object	A typed union that specifies the configuration based on the type of AI Agent.
description	string	The description of the AI Agent. (pattern: <code>[a-zA-Z0-9\s_.,-]+.*</code>)
modified_time	string (date-time)	The time the AI Agent was last modified.
origin	string	The origin of the AI Agent. SYSTEM for a default AI Agent created by Q in Connect or CUSTOMER for an AI Agent created by calling AI Agent creation APIs. (SYSTEM, CUSTOMER)
status	string	The status of the AI Agent. (CREATE_IN_PROGRESS, CREATE_FAILED, ACTIVE, DELETE_IN_PROGRESS, DELETE_FAILED, DELETED)
tags	object	The tags used to organize, track, or control access for this resource.
type_	string	The type of the AI Agent. (MANUAL_SEARCH, ANSWER_RECOMMENDATION, SELF_SERVICE, EMAIL_RESPONSE, EMAIL_OVERVIEW, EMAIL_GENERATIVE_ANSWER, ORCHESTRATION, NOTE_TAKING, CASE_SUMMARIZATION)
visibility_status	string	The visibility status of the AI Agent. (SAVED, PUBLISHED)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_ai_agent	select	assistant_id, ai_agent_id, region		Gets an Amazon Q in Connect AI Agent.
list_ai_agents	select	assistant_id, region	nextToken, maxResults, origin	Lists AI Agents.
create_ai_agent	insert	assistant_id, region, name, type, configuration, visibilityStatus		Creates an Amazon Q in Connect AI Agent.
update_ai_agent	update	assistant_id, ai_agent_id, region, visibilityStatus		Updates an AI Agent.
update_assistant_ai_agent	update	assistant_id, region, aiAgentType, configuration		Updates the AI Agent that is set for use by default on an Amazon Q in Connect Assistant.
remove_assistant_ai_agent	update	assistant_id, aiAgentType, region	orchestratorUseCase	Removes the AI Agent that is set for use by default on an Amazon Q in Connect Assistant.
delete_ai_agent	delete	assistant_id, ai_agent_id, region		Deletes an Amazon Q in Connect AI Agent.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
aiAgentType	string	The type of the AI Agent being removed for use by default from the Amazon Q in Connect Assistant.
ai_agent_id	string	The identifier of the Amazon Q in Connect AI Agent. Can be either the ID or the ARN. URLs cannot contain the ARN.
assistant_id	string	The identifier of the Amazon Q in Connect assistant. Can be either the ID or the ARN. URLs cannot contain the ARN.
region	string	AWS region (default: us-east-1)
maxResults	integer	The maximum number of results to return per page.
nextToken	string	The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results.
orchestratorUseCase	string	The orchestrator use case for the AI Agent being removed.
origin	string	The origin of the AI Agents to be listed. SYSTEM for a default AI Agent created by Q in Connect or CUSTOMER for an AI Agent created by calling AI Agent creation APIs.

SELECT examples

get_ai_agent

Gets an Amazon Q in Connect AI Agent.

SELECT
ai_agent,
version_number
FROM aws.qconnect.ai_agents
WHERE assistant_id = '{{ assistant_id }}' -- required
AND ai_agent_id = '{{ ai_agent_id }}' -- required
AND region = '{{ region }}' -- required
;

list_ai_agents

Lists AI Agents.

SELECT
name,
ai_agent_arn,
ai_agent_id,
assistant_arn,
assistant_id,
configuration,
description,
modified_time,
origin,
status,
tags,
type_,
visibility_status
FROM aws.qconnect.ai_agents
WHERE assistant_id = '{{ assistant_id }}' -- required
AND region = '{{ region }}' -- required
AND nextToken = '{{ nextToken }}'
AND maxResults = '{{ maxResults }}'
AND origin = '{{ origin }}'
;

INSERT examples

create_ai_agent

Creates an Amazon Q in Connect AI Agent.

INSERT INTO aws.qconnect.ai_agents (
clientToken,
name,
type,
configuration,
visibilityStatus,
tags,
description,
assistant_id,
region
)
SELECT 
'{{ clientToken }}',
'{{ name }}' /* required */,
'{{ type }}' /* required */,
'{{ configuration }}' /* required */,
'{{ visibilityStatus }}' /* required */,
'{{ tags }}',
'{{ description }}',
'{{ assistant_id }}',
'{{ region }}'
RETURNING
ai_agent
;

Manifest

# Description fields are for documentation purposes
- name: ai_agents
props:
  - name: assistant_id
    value: "{{ assistant_id }}"
    description: Required parameter for the ai_agents resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the ai_agents resource.
  - name: clientToken
    value: "{{ clientToken }}"
  - name: name
    value: "{{ name }}"
  - name: type
    value: "{{ type }}"
    valid_values: ['MANUAL_SEARCH', 'ANSWER_RECOMMENDATION', 'SELF_SERVICE', 'EMAIL_RESPONSE', 'EMAIL_OVERVIEW', 'EMAIL_GENERATIVE_ANSWER', 'ORCHESTRATION', 'NOTE_TAKING', 'CASE_SUMMARIZATION']
  - name: configuration
    description: |
      A typed union that specifies the configuration based on the type of AI Agent.
    value:
      manualSearchAIAgentConfiguration:
        answerGenerationAIPromptId: "{{ answerGenerationAIPromptId }}"
        answerGenerationAIGuardrailId: "{{ answerGenerationAIGuardrailId }}"
        associationConfigurations:
          - associationId: "{{ associationId }}"
            associationType: "{{ associationType }}"
            associationConfigurationData:
              knowledgeBaseAssociationConfigurationData:
                contentTagFilter: "{{ contentTagFilter }}"
                maxResults: {{ maxResults }}
                overrideKnowledgeBaseSearchType: "{{ overrideKnowledgeBaseSearchType }}"
        locale: "{{ locale }}"
      answerRecommendationAIAgentConfiguration:
        intentLabelingGenerationAIPromptId: "{{ intentLabelingGenerationAIPromptId }}"
        queryReformulationAIPromptId: "{{ queryReformulationAIPromptId }}"
        answerGenerationAIPromptId: "{{ answerGenerationAIPromptId }}"
        answerGenerationAIGuardrailId: "{{ answerGenerationAIGuardrailId }}"
        associationConfigurations:
          - associationId: "{{ associationId }}"
            associationType: "{{ associationType }}"
            associationConfigurationData:
              knowledgeBaseAssociationConfigurationData:
                contentTagFilter: "{{ contentTagFilter }}"
                maxResults: {{ maxResults }}
                overrideKnowledgeBaseSearchType: "{{ overrideKnowledgeBaseSearchType }}"
        locale: "{{ locale }}"
        suggestedMessages:
          - "{{ suggestedMessages }}"
      selfServiceAIAgentConfiguration:
        selfServicePreProcessingAIPromptId: "{{ selfServicePreProcessingAIPromptId }}"
        selfServiceAnswerGenerationAIPromptId: "{{ selfServiceAnswerGenerationAIPromptId }}"
        selfServiceAIGuardrailId: "{{ selfServiceAIGuardrailId }}"
        associationConfigurations:
          - associationId: "{{ associationId }}"
            associationType: "{{ associationType }}"
            associationConfigurationData:
              knowledgeBaseAssociationConfigurationData:
                contentTagFilter: "{{ contentTagFilter }}"
                maxResults: {{ maxResults }}
                overrideKnowledgeBaseSearchType: "{{ overrideKnowledgeBaseSearchType }}"
      emailResponseAIAgentConfiguration:
        emailResponseAIPromptId: "{{ emailResponseAIPromptId }}"
        emailQueryReformulationAIPromptId: "{{ emailQueryReformulationAIPromptId }}"
        locale: "{{ locale }}"
        associationConfigurations:
          - associationId: "{{ associationId }}"
            associationType: "{{ associationType }}"
            associationConfigurationData:
              knowledgeBaseAssociationConfigurationData:
                contentTagFilter: "{{ contentTagFilter }}"
                maxResults: {{ maxResults }}
                overrideKnowledgeBaseSearchType: "{{ overrideKnowledgeBaseSearchType }}"
      emailOverviewAIAgentConfiguration:
        emailOverviewAIPromptId: "{{ emailOverviewAIPromptId }}"
        locale: "{{ locale }}"
      emailGenerativeAnswerAIAgentConfiguration:
        emailGenerativeAnswerAIPromptId: "{{ emailGenerativeAnswerAIPromptId }}"
        emailQueryReformulationAIPromptId: "{{ emailQueryReformulationAIPromptId }}"
        locale: "{{ locale }}"
        associationConfigurations:
          - associationId: "{{ associationId }}"
            associationType: "{{ associationType }}"
            associationConfigurationData:
              knowledgeBaseAssociationConfigurationData:
                contentTagFilter: "{{ contentTagFilter }}"
                maxResults: {{ maxResults }}
                overrideKnowledgeBaseSearchType: "{{ overrideKnowledgeBaseSearchType }}"
      orchestrationAIAgentConfiguration:
        orchestrationAIPromptId: "{{ orchestrationAIPromptId }}"
        orchestrationAIGuardrailId: "{{ orchestrationAIGuardrailId }}"
        toolConfigurations:
          - toolName: "{{ toolName }}"
            toolType: "{{ toolType }}"
            title_: "{{ title_ }}"
            toolId: "{{ toolId }}"
            description: "{{ description }}"
            instruction:
              instruction: "{{ instruction }}"
              examples:
                - "{{ examples }}"
            overrideInputValues: "{{ overrideInputValues }}"
            outputFilters: "{{ outputFilters }}"
            inputSchema: "{{ inputSchema }}"
            outputSchema: "{{ outputSchema }}"
            annotations:
              title_: "{{ title_ }}"
              destructiveHint: {{ destructiveHint }}
            userInteractionConfiguration:
              isUserConfirmationRequired: {{ isUserConfirmationRequired }}
        connectInstanceArn: "{{ connectInstanceArn }}"
        locale: "{{ locale }}"
      noteTakingAIAgentConfiguration:
        noteTakingAIPromptId: "{{ noteTakingAIPromptId }}"
        noteTakingAIGuardrailId: "{{ noteTakingAIGuardrailId }}"
        locale: "{{ locale }}"
      caseSummarizationAIAgentConfiguration:
        caseSummarizationAIPromptId: "{{ caseSummarizationAIPromptId }}"
        caseSummarizationAIGuardrailId: "{{ caseSummarizationAIGuardrailId }}"
        locale: "{{ locale }}"
  - name: visibilityStatus
    value: "{{ visibilityStatus }}"
    valid_values: ['SAVED', 'PUBLISHED']
  - name: tags
    value: "{{ tags }}"
  - name: description
    value: "{{ description }}"

UPDATE examples

update_ai_agent

Updates an AI Agent.

UPDATE aws.qconnect.ai_agents
SET 
clientToken = '{{ clientToken }}',
visibilityStatus = '{{ visibilityStatus }}',
configuration = '{{ configuration }}',
description = '{{ description }}'
WHERE 
assistant_id = '{{ assistant_id }}' --required
AND ai_agent_id = '{{ ai_agent_id }}' --required
AND region = '{{ region }}' --required
AND visibilityStatus = '{{ visibilityStatus }}' --required
RETURNING
ai_agent;

update_assistant_ai_agent

Updates the AI Agent that is set for use by default on an Amazon Q in Connect Assistant.

UPDATE aws.qconnect.ai_agents
SET 
aiAgentType = '{{ aiAgentType }}',
configuration = '{{ configuration }}',
orchestratorUseCase = '{{ orchestratorUseCase }}'
WHERE 
assistant_id = '{{ assistant_id }}' --required
AND region = '{{ region }}' --required
AND aiAgentType = '{{ aiAgentType }}' --required
AND configuration = '{{ configuration }}' --required
RETURNING
assistant;

remove_assistant_ai_agent

Removes the AI Agent that is set for use by default on an Amazon Q in Connect Assistant.

UPDATE aws.qconnect.ai_agents
SET 
-- No updatable properties
WHERE 
assistant_id = '{{ assistant_id }}' --required
AND aiAgentType = '{{ aiAgentType }}' --required
AND region = '{{ region }}' --required
AND orchestratorUseCase = '{{ orchestratorUseCase}}';

DELETE examples

delete_ai_agent

Deletes an Amazon Q in Connect AI Agent.

DELETE FROM aws.qconnect.ai_agents
WHERE assistant_id = '{{ assistant_id }}' --required
AND ai_agent_id = '{{ ai_agent_id }}' --required
AND region = '{{ region }}' --required
;