2025/12/02 - Nova Act Service - 16 new api methods
Changes Initial release of Nova Act SDK. The Nova Act service enables customers to build and manage fleets of agents for automating production UI workflows with high reliability, fastest time-to-value, and ease of implementation at scale.
Creates a new AI task (act) within a session that can interact with tools and perform specific actions.
See also: AWS API Documentation
Request Syntax
client.create_act(
workflowDefinitionName='string',
workflowRunId='string',
sessionId='string',
task='string',
toolSpecs=[
{
'name': 'string',
'description': 'string',
'inputSchema': {
'json': {...}|[...]|123|123.4|'string'|True|None
}
},
],
clientToken='string'
)
string
[REQUIRED]
The name of the workflow definition containing the session.
string
[REQUIRED]
The unique identifier of the workflow run containing the session.
string
[REQUIRED]
The unique identifier of the session to create the act in.
string
[REQUIRED]
The task description that defines what the act should accomplish.
list
A list of tool specifications that the act can invoke to complete its task.
(dict) --
Specification for a tool that acts can invoke, including its name, description, and input schema.
name (string) -- [REQUIRED]
The unique name of the tool that acts will use to invoke it.
description (string) -- [REQUIRED]
A description of what the tool does and how it should be used.
inputSchema (dict) -- [REQUIRED]
The JSON schema that defines the expected input format for the tool.
json (:ref:`document<document>`) --
The JSON schema that defines the expected input format for the tool.
string
A unique, case-sensitive identifier that you provide to ensure the idempotency of the request.
This field is autopopulated if not provided.
dict
Response Syntax
{
'actId': 'string',
'status': 'RUNNING'|'PENDING_CLIENT_ACTION'|'PENDING_HUMAN_ACTION'|'SUCCEEDED'|'FAILED'|'TIMED_OUT'
}
Response Structure
(dict) --
actId (string) --
The unique identifier for the created act.
status (string) --
The initial status of the act after creation.
Lists all workflow runs for a specific workflow definition with optional filtering and pagination.
See also: AWS API Documentation
Request Syntax
client.list_workflow_runs(
workflowDefinitionName='string',
maxResults=123,
nextToken='string',
sortOrder='Ascending'|'Descending'
)
string
[REQUIRED]
The name of the workflow definition to list workflow runs for.
integer
The maximum number of workflow runs to return in a single response.
string
The token for retrieving the next page of results.
string
The sort order for the returned workflow runs (ascending or descending).
dict
Response Syntax
{
'workflowRunSummaries': [
{
'workflowRunArn': 'string',
'workflowRunId': 'string',
'status': 'RUNNING'|'SUCCEEDED'|'FAILED'|'TIMED_OUT'|'DELETING',
'startedAt': datetime(2015, 1, 1),
'endedAt': datetime(2015, 1, 1),
'traceLocation': {
'locationType': 'S3',
'location': 'string'
}
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
workflowRunSummaries (list) --
A list of summary information for workflow runs.
(dict) --
Summary information about a workflow run, including execution status and timing.
workflowRunArn (string) --
The Amazon Resource Name (ARN) of the workflow run.
workflowRunId (string) --
The unique identifier of the workflow run.
status (string) --
The current execution status of the workflow run.
startedAt (datetime) --
The timestamp when the workflow run started execution.
endedAt (datetime) --
The timestamp when the workflow run completed execution, if applicable.
traceLocation (dict) --
The location where trace information for this workflow run is stored.
locationType (string) --
The type of storage location for the trace data.
location (string) --
The specific location where the trace data is stored.
nextToken (string) --
The token for retrieving the next page of results, if available.
Lists all sessions within a specific workflow run.
See also: AWS API Documentation
Request Syntax
client.list_sessions(
workflowDefinitionName='string',
workflowRunId='string',
maxResults=123,
nextToken='string',
sortOrder='Ascending'|'Descending'
)
string
[REQUIRED]
The name of the workflow definition containing the workflow run.
string
[REQUIRED]
The unique identifier of the workflow run to list sessions for.
integer
The maximum number of sessions to return in a single response.
string
The token for retrieving the next page of results.
string
The sort order for the returned sessions (ascending or descending).
dict
Response Syntax
{
'sessionSummaries': [
{
'sessionId': 'string'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
sessionSummaries (list) --
A list of summary information for sessions in the workflow run.
(dict) --
Summary information about a session within a workflow run.
sessionId (string) --
The unique identifier of the session.
nextToken (string) --
The token for retrieving the next page of results, if available.
Updates the configuration or state of an active workflow run.
See also: AWS API Documentation
Request Syntax
client.update_workflow_run(
workflowDefinitionName='string',
workflowRunId='string',
status='RUNNING'|'SUCCEEDED'|'FAILED'|'TIMED_OUT'|'DELETING'
)
string
[REQUIRED]
The name of the workflow definition containing the workflow run.
string
[REQUIRED]
The unique identifier of the workflow run to update.
string
[REQUIRED]
The new status to set for the workflow run.
dict
Response Syntax
{}
Response Structure
(dict) --
Terminates and cleans up a workflow run, stopping all associated acts and sessions.
See also: AWS API Documentation
Request Syntax
client.delete_workflow_run(
workflowDefinitionName='string',
workflowRunId='string'
)
string
[REQUIRED]
The name of the workflow definition containing the workflow run.
string
[REQUIRED]
The unique identifier of the workflow run to delete.
dict
Response Syntax
{
'status': 'RUNNING'|'SUCCEEDED'|'FAILED'|'TIMED_OUT'|'DELETING'
}
Response Structure
(dict) --
status (string) --
The status of the workflow run after deletion request.
Lists all acts within a specific session with their current status and execution details.
See also: AWS API Documentation
Request Syntax
client.list_acts(
workflowDefinitionName='string',
workflowRunId='string',
sessionId='string',
maxResults=123,
nextToken='string',
sortOrder='Ascending'|'Descending'
)
string
[REQUIRED]
The name of the workflow definition containing the session.
string
The unique identifier of the workflow run containing the session.
string
The unique identifier of the session to list acts for.
integer
The maximum number of acts to return in a single response.
string
The token for retrieving the next page of results.
string
The sort order for the returned acts (ascending or descending).
dict
Response Syntax
{
'actSummaries': [
{
'workflowRunId': 'string',
'sessionId': 'string',
'actId': 'string',
'status': 'RUNNING'|'PENDING_CLIENT_ACTION'|'PENDING_HUMAN_ACTION'|'SUCCEEDED'|'FAILED'|'TIMED_OUT',
'startedAt': datetime(2015, 1, 1),
'endedAt': datetime(2015, 1, 1),
'traceLocation': {
'locationType': 'S3',
'location': 'string'
}
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
actSummaries (list) --
A list of summary information for acts in the session.
(dict) --
Summary information about an act, including its status and execution timing.
workflowRunId (string) --
The unique identifier of the workflow run containing this act.
sessionId (string) --
The unique identifier of the session containing this act.
actId (string) --
The unique identifier of the act.
status (string) --
The current execution status of the act.
startedAt (datetime) --
The timestamp when the act started execution.
endedAt (datetime) --
The timestamp when the act completed execution, if applicable.
traceLocation (dict) --
The location where trace information for this act is stored.
locationType (string) --
The type of storage location for the trace data.
location (string) --
The specific location where the trace data is stored.
nextToken (string) --
The token for retrieving the next page of results, if available.
Updates an existing act's configuration, status, or error information.
See also: AWS API Documentation
Request Syntax
client.update_act(
workflowDefinitionName='string',
workflowRunId='string',
sessionId='string',
actId='string',
status='RUNNING'|'PENDING_CLIENT_ACTION'|'PENDING_HUMAN_ACTION'|'SUCCEEDED'|'FAILED'|'TIMED_OUT',
error={
'message': 'string',
'type': 'string'
}
)
string
[REQUIRED]
The name of the workflow definition containing the act.
string
[REQUIRED]
The unique identifier of the workflow run containing the act.
string
[REQUIRED]
The unique identifier of the session containing the act.
string
[REQUIRED]
The unique identifier of the act to update.
string
[REQUIRED]
The new status to set for the act.
dict
Error information to associate with the act, if applicable.
message (string) -- [REQUIRED]
A human-readable description of the error that occurred.
type (string) --
The type or category of error that occurred.
dict
Response Syntax
{}
Response Structure
(dict) --
Deletes a workflow definition and all associated resources. This operation cannot be undone.
See also: AWS API Documentation
Request Syntax
client.delete_workflow_definition(
workflowDefinitionName='string'
)
string
[REQUIRED]
The name of the workflow definition to delete.
dict
Response Syntax
{
'status': 'ACTIVE'|'DELETING'
}
Response Structure
(dict) --
status (string) --
The status of the workflow definition after deletion request.
Creates a new workflow definition template that can be used to execute multiple workflow runs.
See also: AWS API Documentation
Request Syntax
client.create_workflow_definition(
name='string',
description='string',
exportConfig={
's3BucketName': 'string',
's3KeyPrefix': 'string'
},
clientToken='string'
)
string
[REQUIRED]
The name of the workflow definition. Must be unique within your account and region.
string
An optional description of the workflow definition's purpose and functionality.
dict
Configuration for exporting workflow execution data to Amazon Simple Storage Service.
s3BucketName (string) -- [REQUIRED]
The name of your Amazon S3 bucket, that Nova Act uses to export your workflow data. Note that the IAM role used to access Nova Act must also have write permissions to this bucket.
s3KeyPrefix (string) --
An optional prefix for Amazon S3 object keys to organize exported data.
string
A unique, case-sensitive identifier that you provide to ensure the idempotency of the request.
This field is autopopulated if not provided.
dict
Response Syntax
{
'status': 'ACTIVE'|'DELETING'
}
Response Structure
(dict) --
status (string) --
The current status of the workflow definition after creation.
Retrieves the details and configuration of a specific workflow definition.
See also: AWS API Documentation
Request Syntax
client.get_workflow_definition(
workflowDefinitionName='string'
)
string
[REQUIRED]
The name of the workflow definition to retrieve.
dict
Response Syntax
{
'name': 'string',
'arn': 'string',
'createdAt': datetime(2015, 1, 1),
'description': 'string',
'exportConfig': {
's3BucketName': 'string',
's3KeyPrefix': 'string'
},
'status': 'ACTIVE'|'DELETING'
}
Response Structure
(dict) --
name (string) --
The name of the workflow definition.
arn (string) --
The Amazon Resource Name (ARN) of the workflow definition.
createdAt (datetime) --
The timestamp when the workflow definition was created.
description (string) --
The description of the workflow definition.
exportConfig (dict) --
The export configuration for the workflow definition.
s3BucketName (string) --
The name of your Amazon S3 bucket, that Nova Act uses to export your workflow data. Note that the IAM role used to access Nova Act must also have write permissions to this bucket.
s3KeyPrefix (string) --
An optional prefix for Amazon S3 object keys to organize exported data.
status (string) --
The current status of the workflow definition.
Lists all available AI models that can be used for workflow execution, including their status and compatibility information.
See also: AWS API Documentation
Request Syntax
client.list_models(
clientCompatibilityVersion=123
)
integer
[REQUIRED]
The client compatibility version to filter models by compatibility.
dict
Response Syntax
{
'modelSummaries': [
{
'modelId': 'string',
'modelLifecycle': {
'status': 'ACTIVE'|'LEGACY'|'DEPRECATED'|'PREVIEW'
},
'minimumCompatibilityVersion': 123
},
],
'modelAliases': [
{
'aliasName': 'string',
'latestModelId': 'string',
'resolvedModelId': 'string'
},
],
'compatibilityInformation': {
'clientCompatibilityVersion': 123,
'supportedModelIds': [
'string',
],
'message': 'string'
}
}
Response Structure
(dict) --
modelSummaries (list) --
A list of available AI models with their status and compatibility information.
(dict) --
Summary information about an available AI model.
modelId (string) --
The unique identifier of the model.
modelLifecycle (dict) --
The lifecycle information for the model.
status (string) --
The current lifecycle status of the model.
minimumCompatibilityVersion (integer) --
The minimum client compatibility version required to use this model.
modelAliases (list) --
A list of model aliases that provide stable references to model versions.
(dict) --
An alias that provides a stable reference to a model version.
aliasName (string) --
The name of the model alias.
latestModelId (string) --
The model ID that this alias currently points to.
resolvedModelId (string) --
The resolved model ID after alias resolution.
compatibilityInformation (dict) --
Information about client compatibility and supported models.
clientCompatibilityVersion (integer) --
The client compatibility version that was requested.
supportedModelIds (list) --
A list of model IDs that are supported for the client compatibility version.
(string) --
message (string) --
Additional information about compatibility requirements or recommendations.
Retrieves the current state, configuration, and execution details of a workflow run.
See also: AWS API Documentation
Request Syntax
client.get_workflow_run(
workflowDefinitionName='string',
workflowRunId='string'
)
string
[REQUIRED]
The name of the workflow definition containing the workflow run.
string
[REQUIRED]
The unique identifier of the workflow run to retrieve.
dict
Response Syntax
{
'workflowRunArn': 'string',
'workflowRunId': 'string',
'status': 'RUNNING'|'SUCCEEDED'|'FAILED'|'TIMED_OUT'|'DELETING',
'startedAt': datetime(2015, 1, 1),
'endedAt': datetime(2015, 1, 1),
'modelId': 'string',
'logGroupName': 'string'
}
Response Structure
(dict) --
workflowRunArn (string) --
The Amazon Resource Name (ARN) of the workflow run.
workflowRunId (string) --
The unique identifier of the workflow run.
status (string) --
The current execution status of the workflow run.
startedAt (datetime) --
The timestamp when the workflow run started execution.
endedAt (datetime) --
The timestamp when the workflow run completed execution, if applicable.
modelId (string) --
The ID of the AI model being used for this workflow run.
logGroupName (string) --
The CloudWatch log group name for this workflow run's logs.
Creates a new session context within a workflow run to manage conversation state and acts.
See also: AWS API Documentation
Request Syntax
client.create_session(
workflowDefinitionName='string',
workflowRunId='string',
clientToken='string'
)
string
[REQUIRED]
The name of the workflow definition containing the workflow run.
string
[REQUIRED]
The unique identifier of the workflow run to create the session in.
string
A unique, case-sensitive identifier that you provide to ensure the idempotency of the request.
This field is autopopulated if not provided.
dict
Response Syntax
{
'sessionId': 'string'
}
Response Structure
(dict) --
sessionId (string) --
The unique identifier for the created session.
Creates a new execution instance of a workflow definition with specified parameters.
See also: AWS API Documentation
Request Syntax
client.create_workflow_run(
workflowDefinitionName='string',
modelId='string',
clientToken='string',
logGroupName='string',
clientInfo={
'compatibilityVersion': 123,
'sdkVersion': 'string'
}
)
string
[REQUIRED]
The name of the workflow definition to execute.
string
[REQUIRED]
The ID of the AI model to use for workflow execution.
string
A unique, case-sensitive identifier that you provide to ensure the idempotency of the request.
This field is autopopulated if not provided.
string
The CloudWatch log group name for storing workflow execution logs.
dict
[REQUIRED]
Information about the client making the request, including compatibility version and SDK version.
compatibilityVersion (integer) -- [REQUIRED]
The compatibility version of the client, used to ensure API compatibility.
sdkVersion (string) --
The version of the SDK being used by the client.
dict
Response Syntax
{
'workflowRunId': 'string',
'status': 'RUNNING'|'SUCCEEDED'|'FAILED'|'TIMED_OUT'|'DELETING'
}
Response Structure
(dict) --
workflowRunId (string) --
The unique identifier for the created workflow run.
status (string) --
The initial status of the workflow run after creation.
Executes the next step of an act, processing tool call results and returning new tool calls if needed.
See also: AWS API Documentation
Request Syntax
client.invoke_act_step(
workflowDefinitionName='string',
workflowRunId='string',
sessionId='string',
actId='string',
callResults=[
{
'callId': 'string',
'content': [
{
'text': 'string'
},
]
},
],
previousStepId='string'
)
string
[REQUIRED]
The name of the workflow definition containing the act.
string
[REQUIRED]
The unique identifier of the workflow run containing the act.
string
[REQUIRED]
The unique identifier of the session containing the act.
string
[REQUIRED]
The unique identifier of the act to invoke the next step for.
list
[REQUIRED]
The results from previous tool calls that the act requested.
(dict) --
The result returned from executing a tool call.
callId (string) --
The identifier of the tool call that this result corresponds to.
content (list) -- [REQUIRED]
The content returned by the tool execution, which can include text or other media types.
(dict) --
Content returned from a tool call execution.
text (string) --
Text content returned from the tool execution.
string
The identifier of the previous step, used for tracking execution flow.
dict
Response Syntax
{
'calls': [
{
'callId': 'string',
'input': {...}|[...]|123|123.4|'string'|True|None,
'name': 'string'
},
],
'stepId': 'string'
}
Response Structure
(dict) --
calls (list) --
A list of tool calls that the act wants to execute in this step.
(dict) --
A request for the client to execute a specific tool with given parameters.
callId (string) --
A unique identifier for this tool call, used to match results back to requests.
input (:ref:`document<document>`) --
The input parameters for the tool call, formatted according to the tool's schema.
name (string) --
The name of the tool to invoke, following the pattern 'tool.{toolName}' or 'browser.{browserAction}'.
stepId (string) --
The unique identifier for this execution step.
Lists all workflow definitions in your account with optional filtering and pagination.
See also: AWS API Documentation
Request Syntax
client.list_workflow_definitions(
maxResults=123,
nextToken='string',
sortOrder='Ascending'|'Descending'
)
integer
The maximum number of workflow definitions to return in a single response.
string
The token for retrieving the next page of results.
string
The sort order for the returned workflow definitions (ascending or descending).
dict
Response Syntax
{
'workflowDefinitionSummaries': [
{
'workflowDefinitionArn': 'string',
'workflowDefinitionName': 'string',
'createdAt': datetime(2015, 1, 1),
'status': 'ACTIVE'|'DELETING'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
workflowDefinitionSummaries (list) --
A list of summary information for workflow definitions.
(dict) --
Summary information about a workflow definition, used in list operations.
workflowDefinitionArn (string) --
The Amazon Resource Name (ARN) of the workflow definition.
workflowDefinitionName (string) --
The name of the workflow definition.
createdAt (datetime) --
The timestamp when the workflow definition was created.
status (string) --
The current status of the workflow definition.
nextToken (string) --
The token for retrieving the next page of results, if available.