Dorod-Sky/skyvern/client/agent/client.py

# This file was auto-generated by Fern from our API Definition.

import typing
from ..core.client_wrapper import SyncClientWrapper
from ..types.run_engine import RunEngine
from ..types.proxy_location import ProxyLocation
from ..types.task_run_request_data_extraction_schema import TaskRunRequestDataExtractionSchema
from ..core.request_options import RequestOptions
from ..types.task_run_response import TaskRunResponse
from ..core.serialization import convert_and_respect_annotation_metadata
from ..core.pydantic_utilities import parse_obj_as
from ..errors.bad_request_error import BadRequestError
from ..errors.unprocessable_entity_error import UnprocessableEntityError
from json.decoder import JSONDecodeError
from ..core.api_error import ApiError
from ..types.workflow_run_response import WorkflowRunResponse
from .types.agent_get_run_response import AgentGetRunResponse
from ..core.jsonable_encoder import jsonable_encoder
from ..errors.not_found_error import NotFoundError
from ..core.client_wrapper import AsyncClientWrapper

# this is used as the default value for optional parameters
OMIT = typing.cast(typing.Any, ...)


class AgentClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._client_wrapper = client_wrapper

    def run_task(
        self,
        *,
        prompt: str,
        user_agent: typing.Optional[str] = None,
        url: typing.Optional[str] = OMIT,
        engine: typing.Optional[RunEngine] = OMIT,
        title: typing.Optional[str] = OMIT,
        proxy_location: typing.Optional[ProxyLocation] = OMIT,
        data_extraction_schema: typing.Optional[TaskRunRequestDataExtractionSchema] = OMIT,
        error_code_mapping: typing.Optional[typing.Dict[str, typing.Optional[str]]] = OMIT,
        max_steps: typing.Optional[int] = OMIT,
        webhook_url: typing.Optional[str] = OMIT,
        totp_identifier: typing.Optional[str] = OMIT,
        totp_url: typing.Optional[str] = OMIT,
        browser_session_id: typing.Optional[str] = OMIT,
        publish_workflow: typing.Optional[bool] = OMIT,
        include_action_history_in_verification: typing.Optional[bool] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> TaskRunResponse:
        """
        Run a task

        Parameters
        ----------
        prompt : str

            The goal or task description for Skyvern to accomplish

        user_agent : typing.Optional[str]

        url : typing.Optional[str]

            The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL

        engine : typing.Optional[RunEngine]

            The engine that powers the agent task. The default value is `skyvern-2.0`, the latest Skyvern agent that performs pretty well with complex and multi-step tasks. `skyvern-1.0` is good for simple tasks like filling a form, or searching for information on Google. The `openai-cua` engine uses OpenAI's CUA model. The `anthropic-cua` uses Anthropic's Claude Sonnet 3.7 model with the computer use tool.

        title : typing.Optional[str]
            The title for the task

        proxy_location : typing.Optional[ProxyLocation]

            Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud.

            Available geotargeting options:
            - RESIDENTIAL: the default value. Skyvern Cloud uses a random US residential proxy.
            - RESIDENTIAL_ES: Spain
            - RESIDENTIAL_IE: Ireland
            - RESIDENTIAL_GB: United Kingdom
            - RESIDENTIAL_IN: India
            - RESIDENTIAL_JP: Japan
            - RESIDENTIAL_FR: France
            - RESIDENTIAL_DE: Germany
            - RESIDENTIAL_NZ: New Zealand
            - RESIDENTIAL_ZA: South Africa
            - RESIDENTIAL_AR: Argentina
            - RESIDENTIAL_ISP: ISP proxy
            - US-CA: California
            - US-NY: New York
            - US-TX: Texas
            - US-FL: Florida
            - US-WA: Washington
            - NONE: No proxy

        data_extraction_schema : typing.Optional[TaskRunRequestDataExtractionSchema]

            The schema for data to be extracted from the webpage. If you're looking for consistent data schema being returned by the agent, it's highly recommended to use https://json-schema.org/.

        error_code_mapping : typing.Optional[typing.Dict[str, typing.Optional[str]]]

            Custom mapping of error codes to error messages if Skyvern encounters an error.

        max_steps : typing.Optional[int]

            Maximum number of steps the task can take. Task will fail if it exceeds this number. Cautions: you are charged per step so please set this number to a reasonable value. Contact sales@skyvern.com for custom pricing.

        webhook_url : typing.Optional[str]

            URL to send task status updates to after a run is finished. Refer to https://docs.skyvern.com/running-tasks/webhooks-faq for more details.

        totp_identifier : typing.Optional[str]

            Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://docs.skyvern.com/credentials/totp#option-3-push-code-to-skyvern for more details.

        totp_url : typing.Optional[str]

            URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://docs.skyvern.com/credentials/totp#option-2-get-code-from-your-endpoint for more details.

        browser_session_id : typing.Optional[str]

            Run the task or workflow in the specific Skyvern browser session. Having a browser session can persist the real-time state of the browser, so that the next run can continue from where the previous run left off.

        publish_workflow : typing.Optional[bool]
            Whether to publish this task as a reusable workflow. Only available for skyvern-2.0.

        include_action_history_in_verification : typing.Optional[bool]
            Whether to include action history when verifying that the task is complete

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        TaskRunResponse
            Successfully run task

        Examples
        --------
        from skyvern import Skyvern

        client = Skyvern(
            api_key="YOUR_API_KEY",
        )
        client.agent.run_task(
            prompt="Find the top 3 posts on Hacker News.",
        )
        """
        _response = self._client_wrapper.httpx_client.request(
            "v1/run/tasks",
            method="POST",
            json={
                "prompt": prompt,
                "url": url,
                "engine": engine,
                "title": title,
                "proxy_location": proxy_location,
                "data_extraction_schema": convert_and_respect_annotation_metadata(
                    object_=data_extraction_schema, annotation=TaskRunRequestDataExtractionSchema, direction="write"
                ),
                "error_code_mapping": error_code_mapping,
                "max_steps": max_steps,
                "webhook_url": webhook_url,
                "totp_identifier": totp_identifier,
                "totp_url": totp_url,
                "browser_session_id": browser_session_id,
                "publish_workflow": publish_workflow,
                "include_action_history_in_verification": include_action_history_in_verification,
            },
            headers={
                "x-user-agent": str(user_agent) if user_agent is not None else None,
            },
            request_options=request_options,
            omit=OMIT,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    TaskRunResponse,
                    parse_obj_as(
                        type_=TaskRunResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 400:
                raise BadRequestError(
                    typing.cast(
                        typing.Optional[typing.Any],
                        parse_obj_as(
                            type_=typing.Optional[typing.Any],  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        typing.Optional[typing.Any],
                        parse_obj_as(
                            type_=typing.Optional[typing.Any],  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    def run_workflow(
        self,
        *,
        workflow_id: str,
        template: typing.Optional[bool] = None,
        max_steps_override: typing.Optional[int] = None,
        user_agent: typing.Optional[str] = None,
        parameters: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] = OMIT,
        title: typing.Optional[str] = OMIT,
        proxy_location: typing.Optional[ProxyLocation] = OMIT,
        webhook_url: typing.Optional[str] = OMIT,
        totp_url: typing.Optional[str] = OMIT,
        totp_identifier: typing.Optional[str] = OMIT,
        browser_session_id: typing.Optional[str] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> WorkflowRunResponse:
        """
        Run a workflow

        Parameters
        ----------
        workflow_id : str
            ID of the workflow to run. Workflow ID starts with `wpid_`.

        template : typing.Optional[bool]

        max_steps_override : typing.Optional[int]

        user_agent : typing.Optional[str]

        parameters : typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]]
            Parameters to pass to the workflow

        title : typing.Optional[str]
            The title for this workflow run

        proxy_location : typing.Optional[ProxyLocation]

            Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud.

            Available geotargeting options:
            - RESIDENTIAL: the default value. Skyvern Cloud uses a random US residential proxy.
            - RESIDENTIAL_ES: Spain
            - RESIDENTIAL_IE: Ireland
            - RESIDENTIAL_GB: United Kingdom
            - RESIDENTIAL_IN: India
            - RESIDENTIAL_JP: Japan
            - RESIDENTIAL_FR: France
            - RESIDENTIAL_DE: Germany
            - RESIDENTIAL_NZ: New Zealand
            - RESIDENTIAL_ZA: South Africa
            - RESIDENTIAL_AR: Argentina
            - RESIDENTIAL_ISP: ISP proxy
            - US-CA: California
            - US-NY: New York
            - US-TX: Texas
            - US-FL: Florida
            - US-WA: Washington
            - NONE: No proxy

        webhook_url : typing.Optional[str]
            URL to send workflow status updates to after a run is finished. Refer to https://docs.skyvern.com/running-tasks/webhooks-faq for webhook questions.

        totp_url : typing.Optional[str]

            URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://docs.skyvern.com/credentials/totp#option-2-get-code-from-your-endpoint for more details.

        totp_identifier : typing.Optional[str]

            Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://docs.skyvern.com/credentials/totp#option-3-push-code-to-skyvern for more details.

        browser_session_id : typing.Optional[str]
            ID of a Skyvern browser session to reuse, having it continue from the current screen state

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        WorkflowRunResponse
            Successfully run workflow

        Examples
        --------
        from skyvern import Skyvern

        client = Skyvern(
            api_key="YOUR_API_KEY",
        )
        client.agent.run_workflow(
            workflow_id="wpid_123",
        )
        """
        _response = self._client_wrapper.httpx_client.request(
            "v1/run/workflows",
            method="POST",
            params={
                "template": template,
            },
            json={
                "workflow_id": workflow_id,
                "parameters": parameters,
                "title": title,
                "proxy_location": proxy_location,
                "webhook_url": webhook_url,
                "totp_url": totp_url,
                "totp_identifier": totp_identifier,
                "browser_session_id": browser_session_id,
            },
            headers={
                "x-max-steps-override": str(max_steps_override) if max_steps_override is not None else None,
                "x-user-agent": str(user_agent) if user_agent is not None else None,
            },
            request_options=request_options,
            omit=OMIT,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    WorkflowRunResponse,
                    parse_obj_as(
                        type_=WorkflowRunResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 400:
                raise BadRequestError(
                    typing.cast(
                        typing.Optional[typing.Any],
                        parse_obj_as(
                            type_=typing.Optional[typing.Any],  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        typing.Optional[typing.Any],
                        parse_obj_as(
                            type_=typing.Optional[typing.Any],  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    def get_run(self, run_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> AgentGetRunResponse:
        """
        Get run information (task run, workflow run)

        Parameters
        ----------
        run_id : str
            The id of the task run or the workflow run.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        AgentGetRunResponse
            Successfully got run

        Examples
        --------
        from skyvern import Skyvern

        client = Skyvern(
            api_key="YOUR_API_KEY",
        )
        client.agent.get_run(
            run_id="tsk_123",
        )
        """
        _response = self._client_wrapper.httpx_client.request(
            f"v1/runs/{jsonable_encoder(run_id)}",
            method="GET",
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    AgentGetRunResponse,
                    parse_obj_as(
                        type_=AgentGetRunResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 404:
                raise NotFoundError(
                    typing.cast(
                        typing.Optional[typing.Any],
                        parse_obj_as(
                            type_=typing.Optional[typing.Any],  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        typing.Optional[typing.Any],
                        parse_obj_as(
                            type_=typing.Optional[typing.Any],  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    def cancel_run(
        self, run_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.Optional[typing.Any]:
        """
        Cancel a run (task or workflow)

        Parameters
        ----------
        run_id : str
            The id of the task run or the workflow run to cancel.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.Optional[typing.Any]
            Successful Response

        Examples
        --------
        from skyvern import Skyvern

        client = Skyvern(
            api_key="YOUR_API_KEY",
        )
        client.agent.cancel_run(
            run_id="run_id",
        )
        """
        _response = self._client_wrapper.httpx_client.request(
            f"v1/runs/{jsonable_encoder(run_id)}/cancel",
            method="POST",
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    typing.Optional[typing.Any],
                    parse_obj_as(
                        type_=typing.Optional[typing.Any],  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        typing.Optional[typing.Any],
                        parse_obj_as(
                            type_=typing.Optional[typing.Any],  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    def retry_run_webhook(
        self, run_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.Optional[typing.Any]:
        """
        Retry sending the webhook for a run

        Parameters
        ----------
        run_id : str
            The id of the task run or the workflow run.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.Optional[typing.Any]
            Successful Response

        Examples
        --------
        from skyvern import Skyvern

        client = Skyvern(
            api_key="YOUR_API_KEY",
        )
        client.agent.retry_run_webhook(
            run_id="tsk_123",
        )
        """
        _response = self._client_wrapper.httpx_client.request(
            f"v1/runs/{jsonable_encoder(run_id)}/retry_webhook",
            method="POST",
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    typing.Optional[typing.Any],
                    parse_obj_as(
                        type_=typing.Optional[typing.Any],  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        typing.Optional[typing.Any],
                        parse_obj_as(
                            type_=typing.Optional[typing.Any],  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)


class AsyncAgentClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._client_wrapper = client_wrapper

    async def run_task(
        self,
        *,
        prompt: str,
        user_agent: typing.Optional[str] = None,
        url: typing.Optional[str] = OMIT,
        engine: typing.Optional[RunEngine] = OMIT,
        title: typing.Optional[str] = OMIT,
        proxy_location: typing.Optional[ProxyLocation] = OMIT,
        data_extraction_schema: typing.Optional[TaskRunRequestDataExtractionSchema] = OMIT,
        error_code_mapping: typing.Optional[typing.Dict[str, typing.Optional[str]]] = OMIT,
        max_steps: typing.Optional[int] = OMIT,
        webhook_url: typing.Optional[str] = OMIT,
        totp_identifier: typing.Optional[str] = OMIT,
        totp_url: typing.Optional[str] = OMIT,
        browser_session_id: typing.Optional[str] = OMIT,
        publish_workflow: typing.Optional[bool] = OMIT,
        include_action_history_in_verification: typing.Optional[bool] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> TaskRunResponse:
        """
        Run a task

        Parameters
        ----------
        prompt : str

            The goal or task description for Skyvern to accomplish

        user_agent : typing.Optional[str]

        url : typing.Optional[str]

            The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL

        engine : typing.Optional[RunEngine]

            The engine that powers the agent task. The default value is `skyvern-2.0`, the latest Skyvern agent that performs pretty well with complex and multi-step tasks. `skyvern-1.0` is good for simple tasks like filling a form, or searching for information on Google. The `openai-cua` engine uses OpenAI's CUA model. The `anthropic-cua` uses Anthropic's Claude Sonnet 3.7 model with the computer use tool.

        title : typing.Optional[str]
            The title for the task

        proxy_location : typing.Optional[ProxyLocation]

            Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud.

            Available geotargeting options:
            - RESIDENTIAL: the default value. Skyvern Cloud uses a random US residential proxy.
            - RESIDENTIAL_ES: Spain
            - RESIDENTIAL_IE: Ireland
            - RESIDENTIAL_GB: United Kingdom
            - RESIDENTIAL_IN: India
            - RESIDENTIAL_JP: Japan
            - RESIDENTIAL_FR: France
            - RESIDENTIAL_DE: Germany
            - RESIDENTIAL_NZ: New Zealand
            - RESIDENTIAL_ZA: South Africa
            - RESIDENTIAL_AR: Argentina
            - RESIDENTIAL_ISP: ISP proxy
            - US-CA: California
            - US-NY: New York
            - US-TX: Texas
            - US-FL: Florida
            - US-WA: Washington
            - NONE: No proxy

        data_extraction_schema : typing.Optional[TaskRunRequestDataExtractionSchema]

            The schema for data to be extracted from the webpage. If you're looking for consistent data schema being returned by the agent, it's highly recommended to use https://json-schema.org/.

        error_code_mapping : typing.Optional[typing.Dict[str, typing.Optional[str]]]

            Custom mapping of error codes to error messages if Skyvern encounters an error.

        max_steps : typing.Optional[int]

            Maximum number of steps the task can take. Task will fail if it exceeds this number. Cautions: you are charged per step so please set this number to a reasonable value. Contact sales@skyvern.com for custom pricing.

        webhook_url : typing.Optional[str]

            URL to send task status updates to after a run is finished. Refer to https://docs.skyvern.com/running-tasks/webhooks-faq for more details.

        totp_identifier : typing.Optional[str]

            Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://docs.skyvern.com/credentials/totp#option-3-push-code-to-skyvern for more details.

        totp_url : typing.Optional[str]

            URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://docs.skyvern.com/credentials/totp#option-2-get-code-from-your-endpoint for more details.

        browser_session_id : typing.Optional[str]

            Run the task or workflow in the specific Skyvern browser session. Having a browser session can persist the real-time state of the browser, so that the next run can continue from where the previous run left off.

        publish_workflow : typing.Optional[bool]
            Whether to publish this task as a reusable workflow. Only available for skyvern-2.0.

        include_action_history_in_verification : typing.Optional[bool]
            Whether to include action history when verifying that the task is complete

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        TaskRunResponse
            Successfully run task

        Examples
        --------
        import asyncio

        from skyvern import AsyncSkyvern

        client = AsyncSkyvern(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.agent.run_task(
                prompt="Find the top 3 posts on Hacker News.",
            )


        asyncio.run(main())
        """
        _response = await self._client_wrapper.httpx_client.request(
            "v1/run/tasks",
            method="POST",
            json={
                "prompt": prompt,
                "url": url,
                "engine": engine,
                "title": title,
                "proxy_location": proxy_location,
                "data_extraction_schema": convert_and_respect_annotation_metadata(
                    object_=data_extraction_schema, annotation=TaskRunRequestDataExtractionSchema, direction="write"
                ),
                "error_code_mapping": error_code_mapping,
                "max_steps": max_steps,
                "webhook_url": webhook_url,
                "totp_identifier": totp_identifier,
                "totp_url": totp_url,
                "browser_session_id": browser_session_id,
                "publish_workflow": publish_workflow,
                "include_action_history_in_verification": include_action_history_in_verification,
            },
            headers={
                "x-user-agent": str(user_agent) if user_agent is not None else None,
            },
            request_options=request_options,
            omit=OMIT,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    TaskRunResponse,
                    parse_obj_as(
                        type_=TaskRunResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 400:
                raise BadRequestError(
                    typing.cast(
                        typing.Optional[typing.Any],
                        parse_obj_as(
                            type_=typing.Optional[typing.Any],  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        typing.Optional[typing.Any],
                        parse_obj_as(
                            type_=typing.Optional[typing.Any],  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    async def run_workflow(
        self,
        *,
        workflow_id: str,
        template: typing.Optional[bool] = None,
        max_steps_override: typing.Optional[int] = None,
        user_agent: typing.Optional[str] = None,
        parameters: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] = OMIT,
        title: typing.Optional[str] = OMIT,
        proxy_location: typing.Optional[ProxyLocation] = OMIT,
        webhook_url: typing.Optional[str] = OMIT,
        totp_url: typing.Optional[str] = OMIT,
        totp_identifier: typing.Optional[str] = OMIT,
        browser_session_id: typing.Optional[str] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> WorkflowRunResponse:
        """
        Run a workflow

        Parameters
        ----------
        workflow_id : str
            ID of the workflow to run. Workflow ID starts with `wpid_`.

        template : typing.Optional[bool]

        max_steps_override : typing.Optional[int]

        user_agent : typing.Optional[str]

        parameters : typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]]
            Parameters to pass to the workflow

        title : typing.Optional[str]
            The title for this workflow run

        proxy_location : typing.Optional[ProxyLocation]

            Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud.

            Available geotargeting options:
            - RESIDENTIAL: the default value. Skyvern Cloud uses a random US residential proxy.
            - RESIDENTIAL_ES: Spain
            - RESIDENTIAL_IE: Ireland
            - RESIDENTIAL_GB: United Kingdom
            - RESIDENTIAL_IN: India
            - RESIDENTIAL_JP: Japan
            - RESIDENTIAL_FR: France
            - RESIDENTIAL_DE: Germany
            - RESIDENTIAL_NZ: New Zealand
            - RESIDENTIAL_ZA: South Africa
            - RESIDENTIAL_AR: Argentina
            - RESIDENTIAL_ISP: ISP proxy
            - US-CA: California
            - US-NY: New York
            - US-TX: Texas
            - US-FL: Florida
            - US-WA: Washington
            - NONE: No proxy

        webhook_url : typing.Optional[str]
            URL to send workflow status updates to after a run is finished. Refer to https://docs.skyvern.com/running-tasks/webhooks-faq for webhook questions.

        totp_url : typing.Optional[str]

            URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://docs.skyvern.com/credentials/totp#option-2-get-code-from-your-endpoint for more details.

        totp_identifier : typing.Optional[str]

            Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://docs.skyvern.com/credentials/totp#option-3-push-code-to-skyvern for more details.

        browser_session_id : typing.Optional[str]
            ID of a Skyvern browser session to reuse, having it continue from the current screen state

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        WorkflowRunResponse
            Successfully run workflow

        Examples
        --------
        import asyncio

        from skyvern import AsyncSkyvern

        client = AsyncSkyvern(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.agent.run_workflow(
                workflow_id="wpid_123",
            )


        asyncio.run(main())
        """
        _response = await self._client_wrapper.httpx_client.request(
            "v1/run/workflows",
            method="POST",
            params={
                "template": template,
            },
            json={
                "workflow_id": workflow_id,
                "parameters": parameters,
                "title": title,
                "proxy_location": proxy_location,
                "webhook_url": webhook_url,
                "totp_url": totp_url,
                "totp_identifier": totp_identifier,
                "browser_session_id": browser_session_id,
            },
            headers={
                "x-max-steps-override": str(max_steps_override) if max_steps_override is not None else None,
                "x-user-agent": str(user_agent) if user_agent is not None else None,
            },
            request_options=request_options,
            omit=OMIT,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    WorkflowRunResponse,
                    parse_obj_as(
                        type_=WorkflowRunResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 400:
                raise BadRequestError(
                    typing.cast(
                        typing.Optional[typing.Any],
                        parse_obj_as(
                            type_=typing.Optional[typing.Any],  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        typing.Optional[typing.Any],
                        parse_obj_as(
                            type_=typing.Optional[typing.Any],  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    async def get_run(
        self, run_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> AgentGetRunResponse:
        """
        Get run information (task run, workflow run)

        Parameters
        ----------
        run_id : str
            The id of the task run or the workflow run.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        AgentGetRunResponse
            Successfully got run

        Examples
        --------
        import asyncio

        from skyvern import AsyncSkyvern

        client = AsyncSkyvern(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.agent.get_run(
                run_id="tsk_123",
            )


        asyncio.run(main())
        """
        _response = await self._client_wrapper.httpx_client.request(
            f"v1/runs/{jsonable_encoder(run_id)}",
            method="GET",
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    AgentGetRunResponse,
                    parse_obj_as(
                        type_=AgentGetRunResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 404:
                raise NotFoundError(
                    typing.cast(
                        typing.Optional[typing.Any],
                        parse_obj_as(
                            type_=typing.Optional[typing.Any],  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        typing.Optional[typing.Any],
                        parse_obj_as(
                            type_=typing.Optional[typing.Any],  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    async def cancel_run(
        self, run_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.Optional[typing.Any]:
        """
        Cancel a run (task or workflow)

        Parameters
        ----------
        run_id : str
            The id of the task run or the workflow run to cancel.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.Optional[typing.Any]
            Successful Response

        Examples
        --------
        import asyncio

        from skyvern import AsyncSkyvern

        client = AsyncSkyvern(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.agent.cancel_run(
                run_id="run_id",
            )


        asyncio.run(main())
        """
        _response = await self._client_wrapper.httpx_client.request(
            f"v1/runs/{jsonable_encoder(run_id)}/cancel",
            method="POST",
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    typing.Optional[typing.Any],
                    parse_obj_as(
                        type_=typing.Optional[typing.Any],  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        typing.Optional[typing.Any],
                        parse_obj_as(
                            type_=typing.Optional[typing.Any],  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    async def retry_run_webhook(
        self, run_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.Optional[typing.Any]:
        """
        Retry sending the webhook for a run

        Parameters
        ----------
        run_id : str
            The id of the task run or the workflow run.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.Optional[typing.Any]
            Successful Response

        Examples
        --------
        import asyncio

        from skyvern import AsyncSkyvern

        client = AsyncSkyvern(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.agent.retry_run_webhook(
                run_id="tsk_123",
            )


        asyncio.run(main())
        """
        _response = await self._client_wrapper.httpx_client.request(
            f"v1/runs/{jsonable_encoder(run_id)}/retry_webhook",
            method="POST",
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    typing.Optional[typing.Any],
                    parse_obj_as(
                        type_=typing.Optional[typing.Any],  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        typing.Optional[typing.Any],
                        parse_obj_as(
                            type_=typing.Optional[typing.Any],  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)