Reasoning Engine API

The Reasoning Engine API provides the managed runtime for your customized agentic workflows in generative AI applications. You can create an application using orchestration frameworks such as LangChain, and deploy it with Reasoning Engine. This service has all the security, privacy, observability, and scalability benefits of Vertex AI integration.

For more conceptual information about Reasoning Engine, see Deploy the application.

Limitations

  • The Reasoning Engine API only supports Python orchestration frameworks.
  • The Reasoning Engine API is only supported in the us-central1 region.

Example syntax

Syntax to create and register a reasoning engine resource.

Python

class SimpleAdditionApp:
    def query() -> str:
        """
           ...

        """

        return
...

reasoning_engine = reasoning_engines.ReasoningEngine.create(
    SimpleAdditionApp(),
    display_name="",
    description="",
    requirements=[...],
    extra_packages=[...],
)

Parameter list

Parameters
display_name

Required: string

The display name of the ReasoningEngine.
description

Optional: string

The description of the ReasoningEngine.
spec

Required: ReasoningEngineSpec

Configurations of the ReasoningEngine.
package_spec

Required: PackageSpec

A user provided package specification, such as pickled objects and package requirements.
class_methods

Optional: protobuf.Struct

Declarations for object class methods.

PackageSpec

PackageSpec contains the reference to the Cloud Storage URI storing the OpenAPI YAML file.

Parameters
pickle_object_gcs_uri

Optional: string

The Cloud Storage URI of the pickled python object.
dependency_files_gcs_uri

Optional: string

The Cloud Storage URI of the dependency files with the tar.gz extension.
requirements_gcs_uri

Optional: string

The Cloud Storage URI of the requirements.txt file.
python_version

Optional: string

The Python version. Supported versions include Python 3.8, 3.9, 3.10, and 3.11. If not specified, the default value is 3.10.

QueryReasoningEngine

Parameters
input

protobuf.struct

The arguments inside input should be consistent with the query class method defined in the creation step.

Examples

Deploy a basic app configuration

The following example uses an application that adds two integers and a remote app with Reasoning Engine:

Python

To learn how to install or update the Vertex AI SDK for Python, see Install the Vertex AI SDK for Python. For more information, see the Python API reference documentation. 

import vertexai
from vertexai.preview import reasoning_engines

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# staging_bucket = "gs://YOUR_BUCKET_NAME"
vertexai.init(
    project=PROJECT_ID, location="us-central1", staging_bucket=staging_bucket
)

class SimpleAdditionApp:
    def query(self, a: int, b: int) -> str:
        """Query the application.
        Args:
            a: The first input number
            b: The second input number
        Returns:
            int: The additional result.
        """
        return f"{int(a)} + {int(b)} is {int(a + b)}"

# Locally test
app = SimpleAdditionApp()
app.query(a=1, b=2)

# Create a remote app with Reasoning Engine.
# This may take 1-2 minutes to finish.
reasoning_engine = reasoning_engines.ReasoningEngine.create(
    SimpleAdditionApp(),
    display_name="Demo Addition App",
    description="A simple demo addition app",
    requirements=["cloudpickle==3"],
    extra_packages=[],
)
# Example response:
# Using bucket YOUR_BUCKET_NAME
# Writing to gs://YOUR_BUCKET_NAME/reasoning_engine/reasoning_engine.pkl
# ...
# ReasoningEngine created. Resource name: projects/123456789/locations/us-central1/reasoningEngines/123456
# To use this ReasoningEngine in another session:
# reasoning_engine = vertexai.preview.reasoning_engines.ReasoningEngine('projects/123456789/locations/...

Deploy an advanced app configuration

This is an advanced example that uses LangChain's chain, prompt templates, and the Gemini API:

Python

To learn how to install or update the Vertex AI SDK for Python, see Install the Vertex AI SDK for Python. For more information, see the Python API reference documentation. 


from typing import List

import vertexai
from vertexai.preview import reasoning_engines

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# staging_bucket = "gs://YOUR_BUCKET_NAME"

vertexai.init(
    project=PROJECT_ID, location="us-central1", staging_bucket=staging_bucket
)

class LangchainApp:
    def __init__(self, project: str, location: str) -> None:
        self.project_id = project
        self.location = location

    def set_up(self) -> None:
        from langchain_core.prompts import ChatPromptTemplate
        from langchain_google_vertexai import ChatVertexAI

        system = (
            "You are a helpful assistant that answers questions "
            "about Google Cloud."
        )
        human = "{text}"
        prompt = ChatPromptTemplate.from_messages(
            [("system", system), ("human", human)]
        )
        chat = ChatVertexAI(project=self.project_id, location=self.location)
        self.chain = prompt | chat

    def query(self, question: str) -> Union[str, List[Union[str, Dict]]]:
        """Query the application.
        Args:
            question: The user prompt.
        Returns:
            str: The LLM response.
        """
        return self.chain.invoke({"text": question}).content

# Locally test
app = LangchainApp(project=PROJECT_ID, location="us-central1")
app.set_up()
print(app.query("What is Vertex AI?"))

# Create a remote app with Reasoning Engine
# Deployment of the app should take a few minutes to complete.
reasoning_engine = reasoning_engines.ReasoningEngine.create(
    LangchainApp(project=PROJECT_ID, location="us-central1"),
    requirements=[
        "google-cloud-aiplatform[langchain,reasoningengine]",
        "cloudpickle==3.0.0",
        "pydantic==2.7.4",
    ],
    display_name="Demo LangChain App",
    description="This is a simple LangChain app.",
    # sys_version="3.10",  # Optional
    extra_packages=[],
)
# Example response:
# Model_name will become a required arg for VertexAIEmbeddings starting...
# ...
# Create ReasoningEngine backing LRO: projects/123456789/locations/us-central1/reasoningEngines/...
# ReasoningEngine created. Resource name: projects/123456789/locations/us-central1/reasoningEngines/...
# ...

Query Reasoning Engine

Query a reasoning engine.

This example uses the SimpleAdditionApp class from the Deploy a basic app configuration example.

REST

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your project ID.
  • LOCATION: The region to process the request. Must be us-central1.
  • REASONING_ENGINE_ID: The ID of the reasoning engine.
  • INPUT: protobuf.struct: The arguments inside input should match the arguments inside of the def query(self, question: str) method defined during the Deploy a basic app configuration.

HTTP method and URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID:query

Request JSON body: 

{
  "input": {
    INPUT
  }
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json, and execute the following command: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID:query"

PowerShell

Save the request body in a file named request.json, and execute the following command: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID:query" | Select-Object -Expand Content

Python

To learn how to install or update the Vertex AI SDK for Python, see Install the Vertex AI SDK for Python. For more information, see the Python API reference documentation. 

import vertexai
from vertexai.preview import reasoning_engines

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# reasoning_engine_id = "1234567890123456"
vertexai.init(project=PROJECT_ID, location="us-central1")
reasoning_engine = reasoning_engines.ReasoningEngine(reasoning_engine_id)

# Replace with kwargs for `.query()` method.
response = reasoning_engine.query(a=1, b=2)
print(response)
# Example response:
# 1 + 2 is 3

List Reasoning Engines

List reasoning engines in a project.

REST

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your project ID.
  • PROJECT_ID: Your project ID.
  • LOCATION: The region to process the request. Must be us-central1.

HTTP method and URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines

To send your request, choose one of these options:

curl

Execute the following command: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines"

PowerShell

Execute the following command: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines" | Select-Object -Expand Content

Python

To learn how to install or update the Vertex AI SDK for Python, see Install the Vertex AI SDK for Python. For more information, see the Python API reference documentation. 

import vertexai
from vertexai.preview import reasoning_engines

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

reasoning_engine_list = reasoning_engines.ReasoningEngine.list()
print(reasoning_engine_list)
# Example response:
# [<vertexai.reasoning_engines._reasoning_engines.ReasoningEngine object at 0x71a0e5cb99c0>
# resource name: projects/123456789/locations/us-central1/reasoningEngines/111111111111111111,
# <vertexai.reasoning_engines._reasoning_engines.ReasoningEngine object at 0x71a0e5cbac80>
# resource name: projects/123456789/locations/us-central1/reasoningEngines/222222222222222222]

Get Reasoning Engine

Get details of a reasoning engine.

REST

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your project ID.
  • PROJECT_ID: Your project ID.
  • LOCATION: The region to process the request. Must be us-central1.
  • REASONING_ENGINE_ID: The ID of the reasoning engine.

HTTP method and URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID

To send your request, choose one of these options:

curl

Execute the following command: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID"

PowerShell

Execute the following command: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID" | Select-Object -Expand Content

Python

To learn how to install or update the Vertex AI SDK for Python, see Install the Vertex AI SDK for Python. For more information, see the Python API reference documentation. 

import vertexai
from vertexai.preview import reasoning_engines

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# reasoning_engine_id = "1234567890123456"
vertexai.init(project=PROJECT_ID, location="us-central1")

reasoning_engine = reasoning_engines.ReasoningEngine(reasoning_engine_id)
print(reasoning_engine)
# Example response:
# <vertexai.reasoning_engines._reasoning_engines.ReasoningEngine object at 0x757999a63c40>
# resource name: projects/[PROJECT_ID]/locations/us-central1/reasoningEngines/1234567890123456

Delete Reasoning Engine

Delete a reasoning engine.

REST

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your project ID.
  • LOCATION: The region to process the request. Must be us-central1.
  • REASONING_ENGINE_ID: The ID of the reasoning engine.

HTTP method and URL: 

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID

To send your request, choose one of these options:

curl

Execute the following command: 

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID"

PowerShell

Execute the following command: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID" | Select-Object -Expand Content

Python

To learn how to install or update the Vertex AI SDK for Python, see Install the Vertex AI SDK for Python. For more information, see the Python API reference documentation. 

import vertexai
from vertexai.preview import reasoning_engines

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# reasoning_engine_id = "1234567890123456"
vertexai.init(project=PROJECT_ID, location="us-central1")

reasoning_engine = reasoning_engines.ReasoningEngine(reasoning_engine_id)
reasoning_engine.delete()
# Example response:
# Deleting ReasoningEngine:projects/[PROJECT_ID]/locations/us-central1/reasoningEngines/1234567890123456
# ...
# ... resource projects/[PROJECT_ID]/locations/us-central1/reasoningEngines/1234567890123456 deleted.

What's next