agents

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

Overview

Name	`agents`
Type	Resource
Id	`aws.bedrock_agent.agents`

Fields

The following fields are returned by SELECT queries:

get_agent
list_agents

Name	Datatype	Description
`agent_arn`	`string`	The Amazon Resource Name (ARN) of the agent. (pattern: <code>arn:aws:bedrock:[a-z0-9-]{1,20}:[0-9]{12}:agent/[0-9a-zA-Z]{10}</code>)
`agent_collaboration`	`string`	The agent's collaboration settings. (SUPERVISOR, SUPERVISOR_ROUTER, DISABLED)
`agent_id`	`string`	The unique identifier of the agent. (pattern: <code>[0-9a-zA-Z]{10}</code>)
`agent_name`	`string`	The name of the agent. (pattern: <code>([0-9a-zA-Z][_-]?){1,100}</code>)
`agent_resource_role_arn`	`string`	The Amazon Resource Name (ARN) of the IAM role with permissions to invoke API operations on the agent. (pattern: <code>arn:aws(-[^:]+)?:iam::([0-9]{12})?:role/.+</code>)
`agent_status`	`string`	The status of the agent and whether it is ready for use. The following statuses are possible: CREATING – The agent is being created. PREPARING – The agent is being prepared. PREPARED – The agent is prepared and ready to be invoked. NOT_PREPARED – The agent has been created but not yet prepared. FAILED – The agent API operation failed. UPDATING – The agent is being updated. DELETING – The agent is being deleted. (CREATING, PREPARING, PREPARED, NOT_PREPARED, DELETING, FAILED, VERSIONING, UPDATING)
`agent_version`	`string`	The version of the agent. (pattern: <code>DRAFT</code>)
`client_token`	`string`	A unique, case-sensitive identifier to ensure that the API request completes no more than one time. If this token matches a previous request, Amazon Bedrock ignores the request, but does not return an error. For more information, see Ensuring idempotency. (pattern: <code>[a-zA-Z0-9](-*[a-zA-Z0-9]){0,256}</code>)
`created_at`	`string (date-time)`	The time at which the agent was created.
`custom_orchestration`	`object`	Details of custom orchestration.
`customer_encryption_key_arn`	`string`	The Amazon Resource Name (ARN) of the KMS key that encrypts the agent. (pattern: <code>arn:aws(\|-cn\|-us-gov):kms:[a-zA-Z0-9-]*:[0-9]{12}:key/[a-zA-Z0-9-]{36}</code>)
`description`	`string`	The description of the agent.
`failure_reasons`	`array`	Contains reasons that the agent-related API that you invoked failed.
`foundation_model`	`string`	The foundation model used for orchestration by the agent. (pattern: <code>(arn:aws(-[^:]{1,12})?:(bedrock\|sagemaker):[a-z0-9-]{1,20}:([0-9]{12})?:([a-z-]+/)?)?([a-zA-Z0-9.-]{1,63}){0,2}(([:][a-z0-9-]{1,63}){0,2})?(/[a-z0-9]{1,12})?</code>)
`guardrail_configuration`	`object`	Details about a guardrail associated with a resource.
`idle_session_ttl_in_seconds`	`integer`	The number of seconds for which Amazon Bedrock keeps information about a user's conversation with the agent. A user interaction remains active for the amount of time specified. If no conversation occurs during this time, the session expires and Amazon Bedrock deletes any data provided before the timeout.
`instruction`	`string`	Instructions that tell the agent what it should do and how it should interact with users.
`memory_configuration`	`object`	Details of the memory configuration.
`orchestration_type`	`string`	Specifies the orchestration strategy for the agent. (DEFAULT, CUSTOM_ORCHESTRATION)
`prepared_at`	`string (date-time)`	The time at which the agent was last prepared.
`prompt_override_configuration`	`object`	Contains configurations to override prompts in different parts of an agent sequence. For more information, see Advanced prompts.
`recommended_actions`	`array`	Contains recommended actions to take for the agent-related API that you invoked to succeed.
`updated_at`	`string (date-time)`	The time at which the agent was last updated.

Name	Datatype	Description
`agent_id`	`string`	The unique identifier of the agent. (pattern: <code>[0-9a-zA-Z]{10}</code>)
`agent_name`	`string`	The name of the agent. (pattern: <code>([0-9a-zA-Z][_-]?){1,100}</code>)
`agent_status`	`string`	The status of the agent. (CREATING, PREPARING, PREPARED, NOT_PREPARED, DELETING, FAILED, VERSIONING, UPDATING)
`description`	`string`	The description of the agent.
`guardrail_configuration`	`object`	Details about a guardrail associated with a resource.
`latest_agent_version`	`string`	The latest version of the agent. (pattern: <code>(DRAFT\|[0-9]{0,4}[1-9][0-9]{0,4})</code>)
`updated_at`	`string (date-time)`	The time at which the agent was last updated.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get_agent`	`select`	`agent_id`, `region`		Gets information about an agent.
`list_agents`	`select`	`region`		Lists the agents belonging to an account and information about each agent.
`create_agent`	`insert`	`region`, `agentName`		Creates an agent that orchestrates interactions between foundation models, data sources, software applications, user conversations, and APIs to carry out tasks to help customers. Specify the following fields for security purposes. agentResourceRoleArn – The Amazon Resource Name (ARN) of the role with permissions to invoke API operations on an agent. (Optional) customerEncryptionKeyArn – The Amazon Resource Name (ARN) of a KMS key to encrypt the creation of the agent. (Optional) idleSessionTTLinSeconds – Specify the number of seconds for which the agent should maintain session information. After this time expires, the subsequent InvokeAgent request begins a new session. To enable your agent to retain conversational context across multiple sessions, include a memoryConfiguration object. For more information, see Configure memory. To override the default prompt behavior for agent orchestration and to use advanced prompts, include a promptOverrideConfiguration object. For more information, see Advanced prompts. If your agent fails to be created, the response returns a list of failureReasons alongside a list of recommendedActions for you to troubleshoot. The agent instructions will not be honored if your agent has only one knowledge base, uses default prompts, has no action group, and user input is disabled.
`update_agent`	`update`	`agent_id`, `region`, `agentName`, `foundationModel`, `agentResourceRoleArn`		Updates the configuration of an agent.
`delete_agent`	`delete`	`agent_id`, `region`	`skipResourceInUseCheck`	Deletes an agent.
`prepare_agent`	`exec`	`agent_id`, `region`		Creates a DRAFT version of the agent that can be used for internal testing.

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
`agent_id`	`string`	The unique identifier of the agent for which to create a DRAFT version.
`region`	`string`	AWS region (default: us-east-1)
`skipResourceInUseCheck`	`boolean`	By default, this value is false and deletion is stopped if the resource is in use. If you set it to true, the resource will be deleted even if the resource is in use.

`SELECT` examples

get_agent
list_agents

Gets information about an agent.

SELECT
agent_arn,
agent_collaboration,
agent_id,
agent_name,
agent_resource_role_arn,
agent_status,
agent_version,
client_token,
created_at,
custom_orchestration,
customer_encryption_key_arn,
description,
failure_reasons,
foundation_model,
guardrail_configuration,
idle_session_ttl_in_seconds,
instruction,
memory_configuration,
orchestration_type,
prepared_at,
prompt_override_configuration,
recommended_actions,
updated_at
FROM aws.bedrock_agent.agents
WHERE agent_id = '{{ agent_id }}' -- required
AND region = '{{ region }}' -- required
;

Lists the agents belonging to an account and information about each agent.

SELECT
agent_id,
agent_name,
agent_status,
description,
guardrail_configuration,
latest_agent_version,
updated_at
FROM aws.bedrock_agent.agents
WHERE region = '{{ region }}' -- required
;

`INSERT` examples

create_agent
Manifest

Creates an agent that orchestrates interactions between foundation models, data sources, software applications, user conversations, and APIs to carry out tasks to help customers. Specify the following fields for security purposes. agentResourceRoleArn – The Amazon Resource Name (ARN) of the role with permissions to invoke API operations on an agent. (Optional) customerEncryptionKeyArn – The Amazon Resource Name (ARN) of a KMS key to encrypt the creation of the agent. (Optional) idleSessionTTLinSeconds – Specify the number of seconds for which the agent should maintain session information. After this time expires, the subsequent InvokeAgent request begins a new session. To enable your agent to retain conversational context across multiple sessions, include a memoryConfiguration object. For more information, see Configure memory. To override the default prompt behavior for agent orchestration and to use advanced prompts, include a promptOverrideConfiguration object. For more information, see Advanced prompts. If your agent fails to be created, the response returns a list of failureReasons alongside a list of recommendedActions for you to troubleshoot. The agent instructions will not be honored if your agent has only one knowledge base, uses default prompts, has no action group, and user input is disabled.

INSERT INTO aws.bedrock_agent.agents (
agentName,
clientToken,
instruction,
foundationModel,
description,
orchestrationType,
customOrchestration,
idleSessionTTLInSeconds,
agentResourceRoleArn,
customerEncryptionKeyArn,
tags,
promptOverrideConfiguration,
guardrailConfiguration,
memoryConfiguration,
agentCollaboration,
region
)
SELECT 
'{{ agentName }}' /* required */,
'{{ clientToken }}',
'{{ instruction }}',
'{{ foundationModel }}',
'{{ description }}',
'{{ orchestrationType }}',
'{{ customOrchestration }}',
{{ idleSessionTTLInSeconds }},
'{{ agentResourceRoleArn }}',
'{{ customerEncryptionKeyArn }}',
'{{ tags }}',
'{{ promptOverrideConfiguration }}',
'{{ guardrailConfiguration }}',
'{{ memoryConfiguration }}',
'{{ agentCollaboration }}',
'{{ region }}'
RETURNING
agent
;

# Description fields are for documentation purposes
- name: agents
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the agents resource.
  - name: agentName
    value: "{{ agentName }}"
  - name: clientToken
    value: "{{ clientToken }}"
  - name: instruction
    value: "{{ instruction }}"
  - name: foundationModel
    value: "{{ foundationModel }}"
  - name: description
    value: "{{ description }}"
  - name: orchestrationType
    value: "{{ orchestrationType }}"
    valid_values: ['DEFAULT', 'CUSTOM_ORCHESTRATION']
  - name: customOrchestration
    description: |
      Details of custom orchestration.
    value:
      executor:
        lambda: "{{ lambda }}"
  - name: idleSessionTTLInSeconds
    value: {{ idleSessionTTLInSeconds }}
  - name: agentResourceRoleArn
    value: "{{ agentResourceRoleArn }}"
  - name: customerEncryptionKeyArn
    value: "{{ customerEncryptionKeyArn }}"
  - name: tags
    value: "{{ tags }}"
  - name: promptOverrideConfiguration
    description: |
      Contains configurations to override prompts in different parts of an agent sequence. For more information, see Advanced prompts.
    value:
      promptConfigurations:
        - promptType: "{{ promptType }}"
          promptCreationMode: "{{ promptCreationMode }}"
          promptState: "{{ promptState }}"
          basePromptTemplate: "{{ basePromptTemplate }}"
          inferenceConfiguration:
            temperature: {{ temperature }}
            topP: {{ topP }}
            topK: {{ topK }}
            maximumLength: {{ maximumLength }}
            stopSequences:
              - "{{ stopSequences }}"
          parserMode: "{{ parserMode }}"
          foundationModel: "{{ foundationModel }}"
          additionalModelRequestFields: "{{ additionalModelRequestFields }}"
      overrideLambda: "{{ overrideLambda }}"
  - name: guardrailConfiguration
    description: |
      Details about a guardrail associated with a resource.
    value:
      guardrailIdentifier: "{{ guardrailIdentifier }}"
      guardrailVersion: "{{ guardrailVersion }}"
  - name: memoryConfiguration
    description: |
      Details of the memory configuration.
    value:
      enabledMemoryTypes:
        - "{{ enabledMemoryTypes }}"
      storageDays: {{ storageDays }}
      sessionSummaryConfiguration:
        maxRecentSessions: {{ maxRecentSessions }}
  - name: agentCollaboration
    value: "{{ agentCollaboration }}"
    valid_values: ['SUPERVISOR', 'SUPERVISOR_ROUTER', 'DISABLED']

`UPDATE` examples

update_agent

Updates the configuration of an agent.

UPDATE aws.bedrock_agent.agents
SET 
agentName = '{{ agentName }}',
instruction = '{{ instruction }}',
foundationModel = '{{ foundationModel }}',
description = '{{ description }}',
orchestrationType = '{{ orchestrationType }}',
customOrchestration = '{{ customOrchestration }}',
idleSessionTTLInSeconds = {{ idleSessionTTLInSeconds }},
agentResourceRoleArn = '{{ agentResourceRoleArn }}',
customerEncryptionKeyArn = '{{ customerEncryptionKeyArn }}',
promptOverrideConfiguration = '{{ promptOverrideConfiguration }}',
guardrailConfiguration = '{{ guardrailConfiguration }}',
memoryConfiguration = '{{ memoryConfiguration }}',
agentCollaboration = '{{ agentCollaboration }}'
WHERE 
agent_id = '{{ agent_id }}' --required
AND region = '{{ region }}' --required
AND agentName = '{{ agentName }}' --required
AND foundationModel = '{{ foundationModel }}' --required
AND agentResourceRoleArn = '{{ agentResourceRoleArn }}' --required
RETURNING
agent;

`DELETE` examples

delete_agent

Deletes an agent.

DELETE FROM aws.bedrock_agent.agents
WHERE agent_id = '{{ agent_id }}' --required
AND region = '{{ region }}' --required
AND skipResourceInUseCheck = '{{ skipResourceInUseCheck }}'
;

Lifecycle Methods

prepare_agent

Creates a DRAFT version of the agent that can be used for internal testing.

EXEC aws.bedrock_agent.agents.prepare_agent 
@agent_id='{{ agent_id }}' --required, 
@region='{{ region }}' --required
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​

Lifecycle Methods​