sessions

Creates, updates, deletes, gets or lists a sessions resource.

Overview

Name	sessions
Type	Resource
Id	aws.bedrock_agent_runtime.sessions

Fields

The following fields are returned by SELECT queries:

get_session

Name	Datatype	Description
created_at	string (date-time)	The timestamp for when the session was created.
encryption_key_arn	string	The Amazon Resource Name (ARN) of the Key Management Service key used to encrypt the session data. For more information, see Amazon Bedrock session encryption. (pattern: <code>^arn:aws(|-cn|-us-gov):kms:[a-zA-Z0-9-]*:[0-9]{12}:key/[a-zA-Z0-9-]{36}$</code>)
last_updated_at	string (date-time)	The timestamp for when the session was last modified.
session_arn	string	The Amazon Resource Name (ARN) of the session. (pattern: <code>^arn:aws(-[^:]+)?:bedrock:[a-z0-9-]+:[0-9]{12}:session/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$</code>)
session_id	string	The unique identifier for the session in UUID format. (pattern: <code>^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$</code>)
session_metadata	object	A map of key-value pairs containing attributes persisted across the session.
session_status	string	The current status of the session. (ACTIVE, EXPIRED, ENDED)

list_sessions

Name	Datatype	Description
created_at	string (date-time)	The timestamp for when the session was created.
last_updated_at	string (date-time)	The timestamp for when the session was last modified.
session_arn	string	The Amazon Resource Name (ARN) of the session. (pattern: <code>^arn:aws(-[^:]+)?:bedrock:[a-z0-9-]+:[0-9]{12}:session/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$</code>)
session_id	string	The unique identifier for the session. (pattern: <code>^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$</code>)
session_status	string	The current status of the session. (ACTIVE, EXPIRED, ENDED)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_session	select	session_identifier, region		Retrieves details about a specific session. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.
list_sessions	select	region	maxResults, nextToken	Lists all sessions in your Amazon Web Services account. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.
create_session	insert	region		Creates a session to temporarily store conversations for generative AI (GenAI) applications built with open-source frameworks such as LangGraph and LlamaIndex. Sessions enable you to save the state of conversations at checkpoints, with the added security and infrastructure of Amazon Web Services. For more information, see Store and retrieve conversation history and context with Amazon Bedrock sessions. By default, Amazon Bedrock uses Amazon Web Services-managed keys for session encryption, including session metadata, or you can use your own KMS key. For more information, see Amazon Bedrock session encryption. You use a session to store state and conversation history for generative AI applications built with open-source frameworks. For Amazon Bedrock Agents, the service automatically manages conversation context and associates them with the agent-specific sessionId you specify in the InvokeAgent API operation. Related APIs: ListSessions GetSession EndSession DeleteSession
update_session	update	session_identifier, region		Updates the metadata or encryption settings of a session. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.
delete_session	delete	session_identifier, region		Deletes a session that you ended. You can't delete a session with an ACTIVE status. To delete an active session, you must first end it with the EndSession API operation. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.
end_session	exec	session_identifier, region		Ends the session. After you end a session, you can still access its content but you can’t add to it. To delete the session and it's content, you use the DeleteSession API operation. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.
invoke_agent	exec	agent_alias_id, agent_id, session_id, region	x-amz-source-arn	Amazon Bedrock Agents (now Amazon Bedrock Agents Classic) is no longer open to new customers. For capabilities similar to Bedrock Agents Classic, explore Amazon Bedrock AgentCore. Existing customers can continue to use the service as normal. For more information, see Amazon Bedrock Agents Classic availability change. Sends a prompt for the agent to process and respond to. Note the following fields for the request: To continue the same conversation with an agent, use the same sessionId value in the request. To activate trace enablement, turn enableTrace to true. Trace enablement helps you follow the agent's reasoning process that led it to the information it processed, the actions it took, and the final result it yielded. For more information, see Trace enablement. End a conversation by setting endSession to true. In the sessionState object, you can include attributes for the session or prompt or, if you configured an action group to return control, results from invocation of the action group. The response contains both chunk and trace attributes. The final response is returned in the bytes field of the chunk object. The InvokeAgent returns one chunk for the entire interaction. The attribution object contains citations for parts of the response. If you set enableTrace to true in the request, you can trace the agent's steps and reasoning process that led it to the response. If the action predicted was configured to return control, the response returns parameters for the action, elicited from the user, in the returnControl field. Errors are also surfaced in the response.
invoke_inline_agent	exec	session_id, region, foundationModel, instruction		Invokes an inline Amazon Bedrock agent using the configurations you provide with the request. Specify the following fields for security purposes. (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 InvokeInlineAgent request begins a new session. To override the default prompt behavior for agent orchestration and to use advanced prompts, include a promptOverrideConfiguration object. For more information, see Advanced prompts. 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.

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_alias_id	string	The alias of the agent to use.
agent_id	string	The unique identifier of the agent to use.
region	string	AWS region (default: us-east-1)
session_id	string	The unique identifier of the session. Use the same value across requests to continue the same conversation.
session_identifier	string	The unique identifier for the session to end. You can specify either the session's sessionId or its Amazon Resource Name (ARN).
maxResults	integer	The maximum number of results to return in the response. If the total number of results is greater than this value, use the token returned in the response in the nextToken field when making another request to return the next batch of results.
nextToken	string	If the total number of results is greater than the maxResults value provided in the request, enter the token returned in the nextToken field in the response in this field to return the next batch of results.
x-amz-source-arn	string	The ARN of the resource making the request.

SELECT examples

get_session

Retrieves details about a specific session. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

SELECT
created_at,
encryption_key_arn,
last_updated_at,
session_arn,
session_id,
session_metadata,
session_status
FROM aws.bedrock_agent_runtime.sessions
WHERE session_identifier = '{{ session_identifier }}' -- required
AND region = '{{ region }}' -- required
;

list_sessions

Lists all sessions in your Amazon Web Services account. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

SELECT
created_at,
last_updated_at,
session_arn,
session_id,
session_status
FROM aws.bedrock_agent_runtime.sessions
WHERE region = '{{ region }}' -- required
AND maxResults = '{{ maxResults }}'
AND nextToken = '{{ nextToken }}'
;

INSERT examples

create_session

Creates a session to temporarily store conversations for generative AI (GenAI) applications built with open-source frameworks such as LangGraph and LlamaIndex. Sessions enable you to save the state of conversations at checkpoints, with the added security and infrastructure of Amazon Web Services. For more information, see Store and retrieve conversation history and context with Amazon Bedrock sessions. By default, Amazon Bedrock uses Amazon Web Services-managed keys for session encryption, including session metadata, or you can use your own KMS key. For more information, see Amazon Bedrock session encryption. You use a session to store state and conversation history for generative AI applications built with open-source frameworks. For Amazon Bedrock Agents, the service automatically manages conversation context and associates them with the agent-specific sessionId you specify in the InvokeAgent API operation. Related APIs: ListSessions GetSession EndSession DeleteSession

INSERT INTO aws.bedrock_agent_runtime.sessions (
encryptionKeyArn,
sessionMetadata,
tags,
region
)
SELECT 
'{{ encryptionKeyArn }}',
'{{ sessionMetadata }}',
'{{ tags }}',
'{{ region }}'
RETURNING
created_at,
session_arn,
session_id,
session_status
;

Manifest

# Description fields are for documentation purposes
- name: sessions
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the sessions resource.
  - name: encryptionKeyArn
    value: "{{ encryptionKeyArn }}"
  - name: sessionMetadata
    value: "{{ sessionMetadata }}"
  - name: tags
    value: "{{ tags }}"
    description: |
      A map of tag keys and values

UPDATE examples

update_session

Updates the metadata or encryption settings of a session. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

UPDATE aws.bedrock_agent_runtime.sessions
SET 
sessionMetadata = '{{ sessionMetadata }}'
WHERE 
session_identifier = '{{ session_identifier }}' --required
AND region = '{{ region }}' --required
RETURNING
created_at,
last_updated_at,
session_arn,
session_id,
session_status;

DELETE examples

delete_session

Deletes a session that you ended. You can't delete a session with an ACTIVE status. To delete an active session, you must first end it with the EndSession API operation. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

DELETE FROM aws.bedrock_agent_runtime.sessions
WHERE session_identifier = '{{ session_identifier }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

end_session

Ends the session. After you end a session, you can still access its content but you can’t add to it. To delete the session and it's content, you use the DeleteSession API operation. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

EXEC aws.bedrock_agent_runtime.sessions.end_session 
@session_identifier='{{ session_identifier }}' --required, 
@region='{{ region }}' --required
;

invoke_agent

Amazon Bedrock Agents (now Amazon Bedrock Agents Classic) is no longer open to new customers. For capabilities similar to Bedrock Agents Classic, explore Amazon Bedrock AgentCore. Existing customers can continue to use the service as normal. For more information, see Amazon Bedrock Agents Classic availability change. Sends a prompt for the agent to process and respond to. Note the following fields for the request: To continue the same conversation with an agent, use the same sessionId value in the request. To activate trace enablement, turn enableTrace to true. Trace enablement helps you follow the agent's reasoning process that led it to the information it processed, the actions it took, and the final result it yielded. For more information, see Trace enablement. End a conversation by setting endSession to true. In the sessionState object, you can include attributes for the session or prompt or, if you configured an action group to return control, results from invocation of the action group. The response contains both chunk and trace attributes. The final response is returned in the bytes field of the chunk object. The InvokeAgent returns one chunk for the entire interaction. The attribution object contains citations for parts of the response. If you set enableTrace to true in the request, you can trace the agent's steps and reasoning process that led it to the response. If the action predicted was configured to return control, the response returns parameters for the action, elicited from the user, in the returnControl field. Errors are also surfaced in the response.

EXEC aws.bedrock_agent_runtime.sessions.invoke_agent 
@agent_alias_id='{{ agent_alias_id }}' --required, 
@agent_id='{{ agent_id }}' --required, 
@session_id='{{ session_id }}' --required, 
@region='{{ region }}' --required, 
@x-amz-source-arn='{{ x-amz-source-arn }}' 
@@json=
'{
"bedrockModelConfigurations": "{{ bedrockModelConfigurations }}", 
"enableTrace": {{ enableTrace }}, 
"endSession": {{ endSession }}, 
"inputText": "{{ inputText }}", 
"memoryId": "{{ memoryId }}", 
"promptCreationConfigurations": "{{ promptCreationConfigurations }}", 
"sessionState": "{{ sessionState }}", 
"streamingConfigurations": "{{ streamingConfigurations }}"
}'
;

invoke_inline_agent

Invokes an inline Amazon Bedrock agent using the configurations you provide with the request. Specify the following fields for security purposes. (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 InvokeInlineAgent request begins a new session. To override the default prompt behavior for agent orchestration and to use advanced prompts, include a promptOverrideConfiguration object. For more information, see Advanced prompts. 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.

EXEC aws.bedrock_agent_runtime.sessions.invoke_inline_agent 
@session_id='{{ session_id }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"actionGroups": "{{ actionGroups }}", 
"agentCollaboration": "{{ agentCollaboration }}", 
"agentName": "{{ agentName }}", 
"bedrockModelConfigurations": "{{ bedrockModelConfigurations }}", 
"collaboratorConfigurations": "{{ collaboratorConfigurations }}", 
"collaborators": "{{ collaborators }}", 
"customOrchestration": "{{ customOrchestration }}", 
"customerEncryptionKeyArn": "{{ customerEncryptionKeyArn }}", 
"enableTrace": {{ enableTrace }}, 
"endSession": {{ endSession }}, 
"foundationModel": "{{ foundationModel }}", 
"guardrailConfiguration": "{{ guardrailConfiguration }}", 
"idleSessionTTLInSeconds": {{ idleSessionTTLInSeconds }}, 
"inlineSessionState": "{{ inlineSessionState }}", 
"inputText": "{{ inputText }}", 
"instruction": "{{ instruction }}", 
"knowledgeBases": "{{ knowledgeBases }}", 
"orchestrationType": "{{ orchestrationType }}", 
"promptCreationConfigurations": "{{ promptCreationConfigurations }}", 
"promptOverrideConfiguration": "{{ promptOverrideConfiguration }}", 
"streamingConfigurations": "{{ streamingConfigurations }}"
}'
;