Execute Agent Action

Execute the specified agent action. The authenticated user must have permission to execute the action.

Before executing an action, you must retrieve the parameters required to run the action. After execution, you can poll the status of the action and retrieve the output.

POST/api/{version}/services/ai/agent_actions/actions/execute

Headers

Name	Description
`Accept`	`application/json` (default) or `application/xml`
`Content-Type`	`application/json`

Body Parameters

In the body of the request, include a JSON object with the following:

Name	Description
`agent_name` conditional	The name of the agent to execute the action. Can be omitted if you are using `user_message` instead.
`action_name` conditional	The name of the action to execute. Can be omitted if you are using `user_message` instead.
`user_message` conditional	The message a Vault user sent to Veeva AI Chat. Required if `agent_name` and `action_name` are omitted.
`document_id` conditional	Required if the agent is scoped to documents: The ID of the document, in the format `{id}` or `{id}_{major}_{minor}`. For example, `123` or `123_0_1`. If specifying a document ID without a version, performs the action on the latest version of the document that the authenticated user has access to. If specifying a document ID with a major and minor version, performs the action on the specified version.
`object` conditional	Required if the agent is scoped to objects: The name of the object.
`objecttype` conditional	Required if the agent is scoped to objects: The name of the object type.
`record_id` conditional	Required if the agent is scoped to objects: The ID of the object record.
`chat_id` optional	The chat ID of an existing Veeva AI Chat.
`external_id` optional	Identify this request with an external ID. Must be unique across executed actions. Vault will fail to execute an action if the `external_id` is the same as an in-progress or past action execution.

Request

curl --location 'https://myvault.veevavault.com/api/v25.2/services/ai/agent_actions/actions/execute' \
--header 'Authorization: {SESSION_ID}' \
--header 'Accept: application/json' \
--header 'X-VaultAPI-ClientID: veeva-vault-api-reference-example' \
--header 'Content-Type: application/json' \
--data '    {
        "agent_name": "quick_check__v",
        "action_name": "spelling_grammar__v",
        "document_id": "1234"
    }'

Response

{
    "responseStatus": "SUCCESS",
    "actionResponse": {
        "actionStatus": "IN_PROGRESS",
        "executionId": "VAB000000001001",
        "urls": [
            "/api/v25.2/services/ai/agent_actions/status?execution_id=VAB000000001001"
        ]
    }
}

Response Details

On SUCCESS, the response contains the executing action's status, the execution ID, and provides a URL to the Retrieve Agent Action Execution Status endpoint, which will provide the action's output when the action is complete.