Api-Nova-Act-2025-08-22 - AWS SDK for PHP V3

Service ID: nova-act

Version: 2025-08-22

This page describes the parameters and results for the operations of the Nova Act Service (2025-08-22), and shows how to use the Aws\NovaAct\NovaActClient object to call the described operations. This documentation is specific to the 2025-08-22 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

CreateAct ( array $params = [] ): Creates a new AI task (act) within a session that can interact with tools and perform specific actions.
CreateSession ( array $params = [] ): Creates a new session context within a workflow run to manage conversation state and acts.
CreateWorkflowDefinition ( array $params = [] ): Creates a new workflow definition template that can be used to execute multiple workflow runs.
CreateWorkflowRun ( array $params = [] ): Creates a new execution instance of a workflow definition with specified parameters.
DeleteWorkflowDefinition ( array $params = [] ): Deletes a workflow definition and all associated resources.
DeleteWorkflowRun ( array $params = [] ): Terminates and cleans up a workflow run, stopping all associated acts and sessions.
GetWorkflowDefinition ( array $params = [] ): Retrieves the details and configuration of a specific workflow definition.
GetWorkflowRun ( array $params = [] ): Retrieves the current state, configuration, and execution details of a workflow run.
InvokeActStep ( array $params = [] ): Executes the next step of an act, processing tool call results and returning new tool calls if needed.
ListActs ( array $params = [] ): Lists all acts within a specific session with their current status and execution details.
ListModels ( array $params = [] ): Lists all available AI models that can be used for workflow execution, including their status and compatibility information.
ListSessions ( array $params = [] ): Lists all sessions within a specific workflow run.
ListWorkflowDefinitions ( array $params = [] ): Lists all workflow definitions in your account with optional filtering and pagination.
ListWorkflowRuns ( array $params = [] ): Lists all workflow runs for a specific workflow definition with optional filtering and pagination.
UpdateAct ( array $params = [] ): Updates an existing act's configuration, status, or error information.
UpdateWorkflowRun ( array $params = [] ): Updates the configuration or state of an active workflow run.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:

ListActs
ListSessions
ListWorkflowDefinitions
ListWorkflowRuns

Operations

CreateAct

$result = $client->createAct([/* ... */]);
$promise = $client->createActAsync([/* ... */]);

Creates a new AI task (act) within a session that can interact with tools and perform specific actions.

Parameter Syntax

$result = $client->createAct([
    'clientToken' => '<string>',
    'sessionId' => '<string>', // REQUIRED
    'task' => '<string>', // REQUIRED
    'toolSpecs' => [
        [
            'description' => '<string>', // REQUIRED
            'inputSchema' => [ // REQUIRED
                'json' => [
                ],
            ],
            'name' => '<string>', // REQUIRED
        ],
        // ...
    ],
    'workflowDefinitionName' => '<string>', // REQUIRED
    'workflowRunId' => '<string>', // REQUIRED
]);

Parameter Details

Members

clientToken

: Type: string

A unique, case-sensitive identifier that you provide to ensure the idempotency of the request.

sessionId

: Required: Yes
: Type: string

The unique identifier of the session to create the act in.

task

: Required: Yes
: Type: string

The task description that defines what the act should accomplish.

toolSpecs

: Type: Array of ToolSpec structures

A list of tool specifications that the act can invoke to complete its task.

workflowDefinitionName

: Required: Yes
: Type: string

The name of the workflow definition containing the session.

workflowRunId

: Required: Yes
: Type: string

The unique identifier of the workflow run containing the session.

Result Syntax

[
    'actId' => '<string>',
    'status' => 'RUNNING|PENDING_CLIENT_ACTION|PENDING_HUMAN_ACTION|SUCCEEDED|FAILED|TIMED_OUT',
]

Result Details

Members

actId

: Required: Yes
: Type: string

The unique identifier for the created act.

status

: Required: Yes
: Type: string

The initial status of the act after creation.

Errors

ServiceQuotaExceededException:: The request would exceed a service quota limit.
AccessDeniedException:: You don't have sufficient permissions to perform this action.
ConflictException:: The request could not be completed due to a conflict with the current state of the resource.
ThrottlingException:: The request was throttled due to too many requests. Please try again later.
ResourceNotFoundException:: The requested resource was not found.
InternalServerException:: An internal server error occurred. Please try again later.
ValidationException:: The input parameters for the request are invalid.

CreateSession

$result = $client->createSession([/* ... */]);
$promise = $client->createSessionAsync([/* ... */]);

Creates a new session context within a workflow run to manage conversation state and acts.

Parameter Syntax

$result = $client->createSession([
    'clientToken' => '<string>',
    'workflowDefinitionName' => '<string>', // REQUIRED
    'workflowRunId' => '<string>', // REQUIRED
]);

Parameter Details

Members

clientToken

: Type: string

A unique, case-sensitive identifier that you provide to ensure the idempotency of the request.

workflowDefinitionName

: Required: Yes
: Type: string

The name of the workflow definition containing the workflow run.

workflowRunId

: Required: Yes
: Type: string

The unique identifier of the workflow run to create the session in.

Result Syntax

[
    'sessionId' => '<string>',
]

Result Details

Members

sessionId

: Required: Yes
: Type: string

The unique identifier for the created session.

Errors

ServiceQuotaExceededException:: The request would exceed a service quota limit.
AccessDeniedException:: You don't have sufficient permissions to perform this action.
ConflictException:: The request could not be completed due to a conflict with the current state of the resource.
ThrottlingException:: The request was throttled due to too many requests. Please try again later.
ResourceNotFoundException:: The requested resource was not found.
InternalServerException:: An internal server error occurred. Please try again later.
ValidationException:: The input parameters for the request are invalid.

CreateWorkflowDefinition

$result = $client->createWorkflowDefinition([/* ... */]);
$promise = $client->createWorkflowDefinitionAsync([/* ... */]);

Creates a new workflow definition template that can be used to execute multiple workflow runs.

Parameter Syntax

$result = $client->createWorkflowDefinition([
    'clientToken' => '<string>',
    'description' => '<string>',
    'exportConfig' => [
        's3BucketName' => '<string>', // REQUIRED
        's3KeyPrefix' => '<string>',
    ],
    'name' => '<string>', // REQUIRED
]);

Parameter Details

Members

clientToken

: Type: string

A unique, case-sensitive identifier that you provide to ensure the idempotency of the request.

description

: Type: string

An optional description of the workflow definition's purpose and functionality.

exportConfig

: Type: WorkflowExportConfig structure

Configuration for exporting workflow execution data to Amazon Simple Storage Service.

name

: Required: Yes
: Type: string

The name of the workflow definition. Must be unique within your account and region.

Result Syntax

[
    'status' => 'ACTIVE|DELETING',
]

Result Details

Members

status

: Required: Yes
: Type: string

The current status of the workflow definition after creation.

Errors

ServiceQuotaExceededException:: The request would exceed a service quota limit.
AccessDeniedException:: You don't have sufficient permissions to perform this action.
ConflictException:: The request could not be completed due to a conflict with the current state of the resource.
ThrottlingException:: The request was throttled due to too many requests. Please try again later.
InternalServerException:: An internal server error occurred. Please try again later.
ValidationException:: The input parameters for the request are invalid.

CreateWorkflowRun

$result = $client->createWorkflowRun([/* ... */]);
$promise = $client->createWorkflowRunAsync([/* ... */]);

Creates a new execution instance of a workflow definition with specified parameters.

Parameter Syntax

$result = $client->createWorkflowRun([
    'clientInfo' => [ // REQUIRED
        'compatibilityVersion' => <integer>, // REQUIRED
        'sdkVersion' => '<string>',
    ],
    'clientToken' => '<string>',
    'logGroupName' => '<string>',
    'modelId' => '<string>', // REQUIRED
    'workflowDefinitionName' => '<string>', // REQUIRED
]);

Parameter Details

Members

clientInfo

: Required: Yes
: Type: ClientInfo structure

Information about the client making the request, including compatibility version and SDK version.

clientToken

: Type: string

A unique, case-sensitive identifier that you provide to ensure the idempotency of the request.

logGroupName

: Type: string

The CloudWatch log group name for storing workflow execution logs.

modelId

: Required: Yes
: Type: string

The ID of the AI model to use for workflow execution.

workflowDefinitionName

: Required: Yes
: Type: string

The name of the workflow definition to execute.

Result Syntax

[
    'status' => 'RUNNING|SUCCEEDED|FAILED|TIMED_OUT|DELETING',
    'workflowRunId' => '<string>',
]

Result Details

Members

status

: Required: Yes
: Type: string

The initial status of the workflow run after creation.

workflowRunId

: Required: Yes
: Type: string

The unique identifier for the created workflow run.

Errors

AccessDeniedException:: You don't have sufficient permissions to perform this action.
ConflictException:: The request could not be completed due to a conflict with the current state of the resource.
ThrottlingException:: The request was throttled due to too many requests. Please try again later.
ResourceNotFoundException:: The requested resource was not found.
InternalServerException:: An internal server error occurred. Please try again later.
ValidationException:: The input parameters for the request are invalid.

DeleteWorkflowDefinition

$result = $client->deleteWorkflowDefinition([/* ... */]);
$promise = $client->deleteWorkflowDefinitionAsync([/* ... */]);

Deletes a workflow definition and all associated resources. This operation cannot be undone.

Parameter Syntax

$result = $client->deleteWorkflowDefinition([
    'workflowDefinitionName' => '<string>', // REQUIRED
]);

Parameter Details

Members

workflowDefinitionName

: Required: Yes
: Type: string

The name of the workflow definition to delete.

Result Syntax

[
    'status' => 'ACTIVE|DELETING',
]

Result Details

Members

status

: Required: Yes
: Type: string

The status of the workflow definition after deletion request.

Errors

AccessDeniedException:: You don't have sufficient permissions to perform this action.
ConflictException:: The request could not be completed due to a conflict with the current state of the resource.
ResourceNotFoundException:: The requested resource was not found.
ThrottlingException:: The request was throttled due to too many requests. Please try again later.
InternalServerException:: An internal server error occurred. Please try again later.
ValidationException:: The input parameters for the request are invalid.

DeleteWorkflowRun

$result = $client->deleteWorkflowRun([/* ... */]);
$promise = $client->deleteWorkflowRunAsync([/* ... */]);

Terminates and cleans up a workflow run, stopping all associated acts and sessions.

Parameter Syntax

$result = $client->deleteWorkflowRun([
    'workflowDefinitionName' => '<string>', // REQUIRED
    'workflowRunId' => '<string>', // REQUIRED
]);

Parameter Details

Members

workflowDefinitionName

: Required: Yes
: Type: string

The name of the workflow definition containing the workflow run.

workflowRunId

: Required: Yes
: Type: string

The unique identifier of the workflow run to delete.

Result Syntax

[
    'status' => 'RUNNING|SUCCEEDED|FAILED|TIMED_OUT|DELETING',
]

Result Details

Members

status

: Required: Yes
: Type: string

The status of the workflow run after deletion request.

Errors

AccessDeniedException:: You don't have sufficient permissions to perform this action.
ConflictException:: The request could not be completed due to a conflict with the current state of the resource.
ResourceNotFoundException:: The requested resource was not found.
ThrottlingException:: The request was throttled due to too many requests. Please try again later.
InternalServerException:: An internal server error occurred. Please try again later.
ValidationException:: The input parameters for the request are invalid.

GetWorkflowDefinition

$result = $client->getWorkflowDefinition([/* ... */]);
$promise = $client->getWorkflowDefinitionAsync([/* ... */]);

Retrieves the details and configuration of a specific workflow definition.

Parameter Syntax

$result = $client->getWorkflowDefinition([
    'workflowDefinitionName' => '<string>', // REQUIRED
]);

Parameter Details

Members

workflowDefinitionName

: Required: Yes
: Type: string

The name of the workflow definition to retrieve.

Result Syntax

[
    'arn' => '<string>',
    'createdAt' => <DateTime>,
    'description' => '<string>',
    'exportConfig' => [
        's3BucketName' => '<string>',
        's3KeyPrefix' => '<string>',
    ],
    'name' => '<string>',
    'status' => 'ACTIVE|DELETING',
]

Result Details

Members

arn

: Required: Yes
: Type: string

The Amazon Resource Name (ARN) of the workflow definition.

createdAt

: Required: Yes
: Type: timestamp (string|DateTime or anything parsable by strtotime)

The timestamp when the workflow definition was created.

description

: Type: string

The description of the workflow definition.

exportConfig

: Type: WorkflowExportConfig structure

The export configuration for the workflow definition.

name

: Required: Yes
: Type: string

The name of the workflow definition.

status

: Required: Yes
: Type: string

The current status of the workflow definition.

Errors

AccessDeniedException:: You don't have sufficient permissions to perform this action.
ResourceNotFoundException:: The requested resource was not found.
ThrottlingException:: The request was throttled due to too many requests. Please try again later.
InternalServerException:: An internal server error occurred. Please try again later.
ValidationException:: The input parameters for the request are invalid.

GetWorkflowRun

$result = $client->getWorkflowRun([/* ... */]);
$promise = $client->getWorkflowRunAsync([/* ... */]);

Retrieves the current state, configuration, and execution details of a workflow run.

Parameter Syntax

$result = $client->getWorkflowRun([
    'workflowDefinitionName' => '<string>', // REQUIRED
    'workflowRunId' => '<string>', // REQUIRED
]);

Parameter Details

Members

workflowDefinitionName

: Required: Yes
: Type: string

The name of the workflow definition containing the workflow run.

workflowRunId

: Required: Yes
: Type: string

The unique identifier of the workflow run to retrieve.

Result Syntax

[
    'endedAt' => <DateTime>,
    'logGroupName' => '<string>',
    'modelId' => '<string>',
    'startedAt' => <DateTime>,
    'status' => 'RUNNING|SUCCEEDED|FAILED|TIMED_OUT|DELETING',
    'workflowRunArn' => '<string>',
    'workflowRunId' => '<string>',
]

Result Details

Members

endedAt

: Type: timestamp (string|DateTime or anything parsable by strtotime)

The timestamp when the workflow run completed execution, if applicable.

logGroupName

: Type: string

The CloudWatch log group name for this workflow run's logs.

modelId

: Required: Yes
: Type: string

The ID of the AI model being used for this workflow run.

startedAt

: Required: Yes
: Type: timestamp (string|DateTime or anything parsable by strtotime)

The timestamp when the workflow run started execution.

status

: Required: Yes
: Type: string

The current execution status of the workflow run.

workflowRunArn

: Required: Yes
: Type: string

The Amazon Resource Name (ARN) of the workflow run.

workflowRunId

: Required: Yes
: Type: string

The unique identifier of the workflow run.

Errors

AccessDeniedException:: You don't have sufficient permissions to perform this action.
ConflictException:: The request could not be completed due to a conflict with the current state of the resource.
ResourceNotFoundException:: The requested resource was not found.
ThrottlingException:: The request was throttled due to too many requests. Please try again later.
InternalServerException:: An internal server error occurred. Please try again later.
ValidationException:: The input parameters for the request are invalid.

InvokeActStep

$result = $client->invokeActStep([/* ... */]);
$promise = $client->invokeActStepAsync([/* ... */]);

Executes the next step of an act, processing tool call results and returning new tool calls if needed.

Parameter Syntax

$result = $client->invokeActStep([
    'actId' => '<string>', // REQUIRED
    'callResults' => [ // REQUIRED
        [
            'callId' => '<string>',
            'content' => [ // REQUIRED
                [
                    'text' => '<string>',
                ],
                // ...
            ],
        ],
        // ...
    ],
    'previousStepId' => '<string>',
    'sessionId' => '<string>', // REQUIRED
    'workflowDefinitionName' => '<string>', // REQUIRED
    'workflowRunId' => '<string>', // REQUIRED
]);

Parameter Details

Members

actId

: Required: Yes
: Type: string

The unique identifier of the act to invoke the next step for.

callResults

: Required: Yes
: Type: Array of CallResult structures

The results from previous tool calls that the act requested.

previousStepId

: Type: string

The identifier of the previous step, used for tracking execution flow.

sessionId

: Required: Yes
: Type: string

The unique identifier of the session containing the act.

workflowDefinitionName

: Required: Yes
: Type: string

The name of the workflow definition containing the act.

workflowRunId

: Required: Yes
: Type: string

The unique identifier of the workflow run containing the act.

Result Syntax

[
    'calls' => [
        [
            'callId' => '<string>',
            'input' => [
            ],
            'name' => '<string>',
        ],
        // ...
    ],
    'stepId' => '<string>',
]

Result Details

Members

calls

: Required: Yes
: Type: Array of Call structures

A list of tool calls that the act wants to execute in this step.

stepId

: Required: Yes
: Type: string

The unique identifier for this execution step.

Errors

ServiceQuotaExceededException:: The request would exceed a service quota limit.
AccessDeniedException:: You don't have sufficient permissions to perform this action.
ConflictException:: The request could not be completed due to a conflict with the current state of the resource.
ResourceNotFoundException:: The requested resource was not found.
ThrottlingException:: The request was throttled due to too many requests. Please try again later.
InternalServerException:: An internal server error occurred. Please try again later.
ValidationException:: The input parameters for the request are invalid.

ListActs

$result = $client->listActs([/* ... */]);
$promise = $client->listActsAsync([/* ... */]);

Lists all acts within a specific session with their current status and execution details.

Parameter Syntax

$result = $client->listActs([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'sessionId' => '<string>',
    'sortOrder' => 'Ascending|Descending',
    'workflowDefinitionName' => '<string>', // REQUIRED
    'workflowRunId' => '<string>',
]);

Parameter Details

Members

maxResults

: Type: int

The maximum number of acts to return in a single response.

nextToken

: Type: string

The token for retrieving the next page of results.

sessionId

: Type: string

The unique identifier of the session to list acts for.

sortOrder

: Type: string

The sort order for the returned acts (ascending or descending).

workflowDefinitionName

: Required: Yes
: Type: string

The name of the workflow definition containing the session.

workflowRunId

: Type: string

The unique identifier of the workflow run containing the session.

Result Syntax

[
    'actSummaries' => [
        [
            'actId' => '<string>',
            'endedAt' => <DateTime>,
            'sessionId' => '<string>',
            'startedAt' => <DateTime>,
            'status' => 'RUNNING|PENDING_CLIENT_ACTION|PENDING_HUMAN_ACTION|SUCCEEDED|FAILED|TIMED_OUT',
            'traceLocation' => [
                'location' => '<string>',
                'locationType' => 'S3',
            ],
            'workflowRunId' => '<string>',
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Members

actSummaries

: Required: Yes
: Type: Array of ActSummary structures

A list of summary information for acts in the session.

nextToken

: Type: string

The token for retrieving the next page of results, if available.

Errors

AccessDeniedException:: You don't have sufficient permissions to perform this action.
ConflictException:: The request could not be completed due to a conflict with the current state of the resource.
ThrottlingException:: The request was throttled due to too many requests. Please try again later.
ResourceNotFoundException:: The requested resource was not found.
InternalServerException:: An internal server error occurred. Please try again later.
ValidationException:: The input parameters for the request are invalid.

ListModels

$result = $client->listModels([/* ... */]);
$promise = $client->listModelsAsync([/* ... */]);

Lists all available AI models that can be used for workflow execution, including their status and compatibility information.

Parameter Syntax

$result = $client->listModels([
    'clientCompatibilityVersion' => <integer>, // REQUIRED
]);

Parameter Details

Members

clientCompatibilityVersion

: Required: Yes
: Type: int

The client compatibility version to filter models by compatibility.

Result Syntax

[
    'compatibilityInformation' => [
        'clientCompatibilityVersion' => <integer>,
        'message' => '<string>',
        'supportedModelIds' => ['<string>', ...],
    ],
    'modelAliases' => [
        [
            'aliasName' => '<string>',
            'latestModelId' => '<string>',
            'resolvedModelId' => '<string>',
        ],
        // ...
    ],
    'modelSummaries' => [
        [
            'minimumCompatibilityVersion' => <integer>,
            'modelId' => '<string>',
            'modelLifecycle' => [
                'status' => 'ACTIVE|LEGACY|DEPRECATED|PREVIEW',
            ],
        ],
        // ...
    ],
]

Result Details

Members

compatibilityInformation

: Required: Yes
: Type: CompatibilityInformation structure

Information about client compatibility and supported models.

modelAliases

: Required: Yes
: Type: Array of ModelAlias structures

A list of model aliases that provide stable references to model versions.

modelSummaries

: Required: Yes
: Type: Array of ModelSummary structures

A list of available AI models with their status and compatibility information.

Errors

AccessDeniedException:: You don't have sufficient permissions to perform this action.
ThrottlingException:: The request was throttled due to too many requests. Please try again later.
InternalServerException:: An internal server error occurred. Please try again later.

ListSessions

$result = $client->listSessions([/* ... */]);
$promise = $client->listSessionsAsync([/* ... */]);

Lists all sessions within a specific workflow run.

Parameter Syntax

$result = $client->listSessions([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'sortOrder' => 'Ascending|Descending',
    'workflowDefinitionName' => '<string>', // REQUIRED
    'workflowRunId' => '<string>', // REQUIRED
]);

Parameter Details

Members

maxResults

: Type: int

The maximum number of sessions to return in a single response.

nextToken

: Type: string

The token for retrieving the next page of results.

sortOrder

: Type: string

The sort order for the returned sessions (ascending or descending).

workflowDefinitionName

: Required: Yes
: Type: string

The name of the workflow definition containing the workflow run.

workflowRunId

: Required: Yes
: Type: string

The unique identifier of the workflow run to list sessions for.

Result Syntax

[
    'nextToken' => '<string>',
    'sessionSummaries' => [
        [
            'sessionId' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members

nextToken

: Type: string

The token for retrieving the next page of results, if available.

sessionSummaries

: Required: Yes
: Type: Array of SessionSummary structures

A list of summary information for sessions in the workflow run.

Errors

AccessDeniedException:: You don't have sufficient permissions to perform this action.
ConflictException:: The request could not be completed due to a conflict with the current state of the resource.
ThrottlingException:: The request was throttled due to too many requests. Please try again later.
ResourceNotFoundException:: The requested resource was not found.
InternalServerException:: An internal server error occurred. Please try again later.
ValidationException:: The input parameters for the request are invalid.

ListWorkflowDefinitions

$result = $client->listWorkflowDefinitions([/* ... */]);
$promise = $client->listWorkflowDefinitionsAsync([/* ... */]);

Lists all workflow definitions in your account with optional filtering and pagination.

Parameter Syntax

$result = $client->listWorkflowDefinitions([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'sortOrder' => 'Ascending|Descending',
]);

Parameter Details

Members

maxResults

: Type: int

The maximum number of workflow definitions to return in a single response.

nextToken

: Type: string

The token for retrieving the next page of results.

sortOrder

: Type: string

The sort order for the returned workflow definitions (ascending or descending).

Result Syntax

[
    'nextToken' => '<string>',
    'workflowDefinitionSummaries' => [
        [
            'createdAt' => <DateTime>,
            'status' => 'ACTIVE|DELETING',
            'workflowDefinitionArn' => '<string>',
            'workflowDefinitionName' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members

nextToken

: Type: string

The token for retrieving the next page of results, if available.

workflowDefinitionSummaries

: Required: Yes
: Type: Array of WorkflowDefinitionSummary structures

A list of summary information for workflow definitions.

Errors

AccessDeniedException:: You don't have sufficient permissions to perform this action.
ThrottlingException:: The request was throttled due to too many requests. Please try again later.
InternalServerException:: An internal server error occurred. Please try again later.
ValidationException:: The input parameters for the request are invalid.

ListWorkflowRuns

$result = $client->listWorkflowRuns([/* ... */]);
$promise = $client->listWorkflowRunsAsync([/* ... */]);

Lists all workflow runs for a specific workflow definition with optional filtering and pagination.

Parameter Syntax

$result = $client->listWorkflowRuns([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'sortOrder' => 'Ascending|Descending',
    'workflowDefinitionName' => '<string>', // REQUIRED
]);

Parameter Details

Members

maxResults

: Type: int

The maximum number of workflow runs to return in a single response.

nextToken

: Type: string

The token for retrieving the next page of results.

sortOrder

: Type: string

The sort order for the returned workflow runs (ascending or descending).

workflowDefinitionName

: Required: Yes
: Type: string

The name of the workflow definition to list workflow runs for.

Result Syntax

[
    'nextToken' => '<string>',
    'workflowRunSummaries' => [
        [
            'endedAt' => <DateTime>,
            'startedAt' => <DateTime>,
            'status' => 'RUNNING|SUCCEEDED|FAILED|TIMED_OUT|DELETING',
            'traceLocation' => [
                'location' => '<string>',
                'locationType' => 'S3',
            ],
            'workflowRunArn' => '<string>',
            'workflowRunId' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members

nextToken

: Type: string

The token for retrieving the next page of results, if available.

workflowRunSummaries

: Required: Yes
: Type: Array of WorkflowRunSummary structures

A list of summary information for workflow runs.

Errors

AccessDeniedException:: You don't have sufficient permissions to perform this action.
ConflictException:: The request could not be completed due to a conflict with the current state of the resource.
ThrottlingException:: The request was throttled due to too many requests. Please try again later.
ResourceNotFoundException:: The requested resource was not found.
InternalServerException:: An internal server error occurred. Please try again later.
ValidationException:: The input parameters for the request are invalid.

UpdateAct

$result = $client->updateAct([/* ... */]);
$promise = $client->updateActAsync([/* ... */]);

Updates an existing act's configuration, status, or error information.

Parameter Syntax

$result = $client->updateAct([
    'actId' => '<string>', // REQUIRED
    'error' => [
        'message' => '<string>', // REQUIRED
        'type' => '<string>',
    ],
    'sessionId' => '<string>', // REQUIRED
    'status' => 'RUNNING|PENDING_CLIENT_ACTION|PENDING_HUMAN_ACTION|SUCCEEDED|FAILED|TIMED_OUT', // REQUIRED
    'workflowDefinitionName' => '<string>', // REQUIRED
    'workflowRunId' => '<string>', // REQUIRED
]);

Parameter Details

Members

actId

: Required: Yes
: Type: string

The unique identifier of the act to update.

error

: Type: ActError structure

Error information to associate with the act, if applicable.

sessionId

: Required: Yes
: Type: string

The unique identifier of the session containing the act.

status

: Required: Yes
: Type: string

The new status to set for the act.

workflowDefinitionName

: Required: Yes
: Type: string

The name of the workflow definition containing the act.

workflowRunId

: Required: Yes
: Type: string

The unique identifier of the workflow run containing the act.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

AccessDeniedException:: You don't have sufficient permissions to perform this action.
ConflictException:: The request could not be completed due to a conflict with the current state of the resource.
ResourceNotFoundException:: The requested resource was not found.
ThrottlingException:: The request was throttled due to too many requests. Please try again later.
InternalServerException:: An internal server error occurred. Please try again later.
ValidationException:: The input parameters for the request are invalid.

UpdateWorkflowRun

$result = $client->updateWorkflowRun([/* ... */]);
$promise = $client->updateWorkflowRunAsync([/* ... */]);

Updates the configuration or state of an active workflow run.

Parameter Syntax

$result = $client->updateWorkflowRun([
    'status' => 'RUNNING|SUCCEEDED|FAILED|TIMED_OUT|DELETING', // REQUIRED
    'workflowDefinitionName' => '<string>', // REQUIRED
    'workflowRunId' => '<string>', // REQUIRED
]);

Parameter Details

Members

status

: Required: Yes
: Type: string

The new status to set for the workflow run.

workflowDefinitionName

: Required: Yes
: Type: string

The name of the workflow definition containing the workflow run.

workflowRunId

: Required: Yes
: Type: string

The unique identifier of the workflow run to update.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

AccessDeniedException:: You don't have sufficient permissions to perform this action.
ConflictException:: The request could not be completed due to a conflict with the current state of the resource.
ResourceNotFoundException:: The requested resource was not found.
ThrottlingException:: The request was throttled due to too many requests. Please try again later.
InternalServerException:: An internal server error occurred. Please try again later.
ValidationException:: The input parameters for the request are invalid.

Shapes

AccessDeniedException

Description

You don't have sufficient permissions to perform this action.

Members

message

: Required: Yes
: Type: string

You don't have sufficient permissions to perform this action. Verify your IAM permissions and try again.

ActError

Description

Error information when an act fails to execute successfully.

Members

message

: Required: Yes
: Type: string

A human-readable description of the error that occurred.

type

: Type: string

The type or category of error that occurred.

ActSummary

Description

Summary information about an act, including its status and execution timing.

Members

actId

: Required: Yes
: Type: string

The unique identifier of the act.

endedAt

: Type: timestamp (string|DateTime or anything parsable by strtotime)

The timestamp when the act completed execution, if applicable.

sessionId

: Required: Yes
: Type: string

The unique identifier of the session containing this act.

startedAt

: Required: Yes
: Type: timestamp (string|DateTime or anything parsable by strtotime)

The timestamp when the act started execution.

status

: Required: Yes
: Type: string

The current execution status of the act.

traceLocation

: Type: TraceLocation structure

The location where trace information for this act is stored.

workflowRunId

: Required: Yes
: Type: string

The unique identifier of the workflow run containing this act.

Call

Description

A request for the client to execute a specific tool with given parameters.

Members

callId

: Required: Yes
: Type: string

A unique identifier for this tool call, used to match results back to requests.

input

: Required: Yes
: Type: document (null|bool|string|numeric) or an (array|associative array) whose members are all valid documents

The input parameters for the tool call, formatted according to the tool's schema.

name

: Required: Yes
: Type: string

The name of the tool to invoke, following the pattern 'tool.{toolName}' or 'browser.{browserAction}'.

CallResult

Description

The result returned from executing a tool call.

Members

callId

: Type: string

The identifier of the tool call that this result corresponds to.

content

: Required: Yes
: Type: Array of CallResultContent structures

The content returned by the tool execution, which can include text or other media types.

CallResultContent

Description

Content returned from a tool call execution.

Members

text

: Type: string

Text content returned from the tool execution.

ClientInfo

Description

Information about the client making API requests, used for compatibility checking.

Members

compatibilityVersion

: Required: Yes
: Type: int

The compatibility version of the client, used to ensure API compatibility.

sdkVersion

: Type: string

The version of the SDK being used by the client.

CompatibilityInformation

Description

Information about client compatibility and supported model versions.

Members

clientCompatibilityVersion

: Required: Yes
: Type: int

The client compatibility version that was requested.

message

: Type: string

Additional information about compatibility requirements or recommendations.

supportedModelIds

: Required: Yes
: Type: Array of strings

A list of model IDs that are supported for the client compatibility version.

ConflictException

Description

The request could not be completed due to a conflict with the current state of the resource.

Members

message

: Required: Yes
: Type: string

The requested operation conflicts with the current state of the resource.

resourceId

: Required: Yes
: Type: string

The identifier of the resource that caused the conflict.

resourceType

: Required: Yes
: Type: string

The type of resource that caused the conflict.

InternalServerException

Description

An internal server error occurred. Please try again later.

Members

message

: Required: Yes
: Type: string

The service encountered an internal error. Try again later.

reason

: Type: string

The reason for the internal server error.

retryAfterSeconds

: Type: int

The number of seconds to wait before retrying the request.

ModelAlias

Description

An alias that provides a stable reference to a model version.

Members

aliasName

: Required: Yes
: Type: string

The name of the model alias.

latestModelId

: Required: Yes
: Type: string

The model ID that this alias currently points to.

resolvedModelId

: Type: string

The resolved model ID after alias resolution.

ModelLifecycle

Description

Lifecycle information for an AI model.

Members

status

: Required: Yes
: Type: string

The current lifecycle status of the model.

ModelSummary

Description

Summary information about an available AI model.

Members

minimumCompatibilityVersion

: Required: Yes
: Type: int

The minimum client compatibility version required to use this model.

modelId

: Required: Yes
: Type: string

The unique identifier of the model.

modelLifecycle

: Required: Yes
: Type: ModelLifecycle structure

The lifecycle information for the model.

ResourceNotFoundException

Description

The requested resource was not found.

Members

message

: Required: Yes
: Type: string

The specified resource was not found.

resourceId

: Required: Yes
: Type: string

The identifier of the resource that wasn't found.

resourceType

: Required: Yes
: Type: string

The type of resource that wasn't found.

SensitiveDocument

Members

ServiceQuotaExceededException

Description

The request would exceed a service quota limit.

Members

message

: Required: Yes
: Type: string

The request would exceed one or more service quotas for your account.

quotaCode

: Required: Yes
: Type: string

The code for the specific quota that was exceeded.

resourceId

: Required: Yes
: Type: string

The identifier of the resource that exceeded the quota.

resourceType

: Required: Yes
: Type: string

The type of resource that exceeded the quota.

serviceCode

: Required: Yes
: Type: string

The service code for the quota that was exceeded.

SessionSummary

Description

Summary information about a session within a workflow run.

Members

sessionId

: Required: Yes
: Type: string

The unique identifier of the session.

ThrottlingException

Description

The request was throttled due to too many requests. Please try again later.

Members

message

: Required: Yes
: Type: string

The request was denied due to request throttling.

quotaCode

: Type: string

The quota code related to the throttling.

retryAfterSeconds

: Type: int

The number of seconds to wait before retrying the throttled request.

serviceCode

: Type: string

The service code where throttling occurred.

ToolInputSchema

Description

The schema definition for tool input parameters.

Members

json

: Type: document (null|bool|string|numeric) or an (array|associative array) whose members are all valid documents

The JSON schema that defines the expected input format for the tool.

ToolInputSchemaDocument

Members

ToolSpec

Description

Specification for a tool that acts can invoke, including its name, description, and input schema.

Members

description

: Required: Yes
: Type: string

A description of what the tool does and how it should be used.

inputSchema

: Required: Yes
: Type: ToolInputSchema structure

The JSON schema that defines the expected input format for the tool.

name

: Required: Yes
: Type: string

The unique name of the tool that acts will use to invoke it.

TraceLocation

Description

Information about where trace data is stored for debugging and monitoring.

Members

location

: Required: Yes
: Type: string

The specific location where the trace data is stored.

locationType

: Required: Yes
: Type: string

The type of storage location for the trace data.

ValidationException

Description

The input parameters for the request are invalid.

Members

fieldList

: Type: Array of ValidationExceptionField structures

The list of fields that failed validation.

message

: Required: Yes
: Type: string

The input fails to satisfy the constraints specified by the service.

reason

: Required: Yes
: Type: string

The reason for the validation failure.

ValidationExceptionField

Description

Information about a field that failed validation.

Members

message

: Required: Yes
: Type: string

A description of the validation error for this field.

name

: Required: Yes
: Type: string

The name of the field that failed validation.

WorkflowDefinitionSummary

Description

Summary information about a workflow definition, used in list operations.

Members

createdAt

: Required: Yes
: Type: timestamp (string|DateTime or anything parsable by strtotime)

The timestamp when the workflow definition was created.

status

: Required: Yes
: Type: string

The current status of the workflow definition.

workflowDefinitionArn

: Required: Yes
: Type: string

The Amazon Resource Name (ARN) of the workflow definition.

workflowDefinitionName

: Required: Yes
: Type: string

The name of the workflow definition.

WorkflowExportConfig

Description

Configuration settings for exporting workflow execution data and logs to Amazon Simple Storage Service (Amazon S3).

Members

s3BucketName

: Required: Yes
: Type: 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

: Type: string

An optional prefix for Amazon S3 object keys to organize exported data.

WorkflowRunSummary

Description

Summary information about a workflow run, including execution status and timing.

Members

endedAt

: Type: timestamp (string|DateTime or anything parsable by strtotime)

The timestamp when the workflow run completed execution, if applicable.

startedAt

: Required: Yes
: Type: timestamp (string|DateTime or anything parsable by strtotime)

The timestamp when the workflow run started execution.

status

: Required: Yes
: Type: string

The current execution status of the workflow run.

traceLocation

: Type: TraceLocation structure

The location where trace information for this workflow run is stored.

workflowRunArn

: Required: Yes
: Type: string

The Amazon Resource Name (ARN) of the workflow run.

workflowRunId

: Required: Yes
: Type: string

The unique identifier of the workflow run.

Nova Act Service 2025-08-22

Operation Summary

Paginators

Operations

CreateAct

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

CreateSession

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

CreateWorkflowDefinition

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

CreateWorkflowRun

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

DeleteWorkflowDefinition

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

DeleteWorkflowRun

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

GetWorkflowDefinition

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

GetWorkflowRun

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

InvokeActStep

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

ListActs

Parameter Syntax

Parameter Details

Members