Prompt management

This page introduces a unified set of capabilities to define, save, retrieve, and manage prompts within your Google Cloud project using the Vertex AI SDK prompt management module.

Overview

Vertex AI offers tooling to help manage prompt templates and prompt data. Prompt templates can be versioned and used with generative models on Vertex AI. Each prompt can be assembled and versioned in Vertex AI Studio or the Vertex AI SDK.

Prompt management in the Vertex AI SDK includes full enterprise support, including support for Customer-Managed Encryption Keys (CMEK) and VPC Service Controls (VPCSC).

Prompt management capabilities

To use any of the generative AI capabilities from the Vertex AI SDK, do the following:

Install the latest version of the Vertex AI SDK.

pip install --upgrade google-cloud-aiplatform

Create a generative AI client using the following Python code sample:

    import vertexai
    from vertexai import types

    # Instantiate GenAI client from Vertex SDK
    # Replace with your project ID and location
    client = vertexai.Client(project='my-project', location='my-location')

After you've created a generative AI client, you can use any of the following prompt management capabilities in the Vertex AI SDK:

Create a local prompt.
Save a prompt to a Google Cloud project.
Get a saved prompt.
List prompts and versions.
Delete a prompt.
Restore a prompt version.

Create a local prompt

This section provides an example of how to define a types.Prompt variable for use throughout this page.

The Prompt class is used for defining, assembling, and using prompts. The prompt_data attribute is defined for the Prompt class and includes the following:

Attribute
`model`	Required: The model name.
`contents`	Required: The content of the conversation with the model. Only single-turn prompts are supported.
`generation_config`	Optional: Generation configuration
`tool_config`	Optional: This configuration is shared for all tools provided in the request.
`tools`	Optional: A list of `Tools` the model might use to generate the next response. A `Tool` is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of the knowledge and scope of the model.
`safety_settings`	Optional: The request settings for blocking unsafe content, which are enforced on `GenerateContentResponse.candidates`.
`system_instruction`	Optional: The user-provided system instructions for the model.
`variables`	Optional: If your prompt contains a template variable, provide the values to use for that variable. For example, if your prompt text contents are "Hello, {name}". Your variables list should include a dictionary of all possible values for the "{name}" variable. Example: "variables": [ {"name": {"text": "Alice"}}, {"name": {"text": "Bob"}}, ],

This code sample demonstrates how to define a types.Prompt variable.

  import vertexai
  from vertexai import types
  from google.genai import types

  prompt = types.Prompt(
      prompt_data=types.PromptData(
        contents=[genai_types.Content(parts=[genai_types.Part(text="Hello, {name}! How are you?")])],
        variables=[
          {"name": genai_types.Part(text="Alice")},
          {"name": genai_types.Part(text="Bob")},
        ],
        model="your-model",
      ),
  )

Save a prompt to a Google Cloud project

This section presents the parameters and an example for how to save a prompt to a Google Cloud project.

Parameters

This table describes the parameters used by the create method:

Parameters
`prompt`	The data for a specific prompt.
`config`	Optional: A `types.CreatePromptConfig` object representing the configuration for creating a prompt.

This table describes the parameters used by the create_version method:

Parameters
`prompt`	Required: The data for a specific prompt.
`config`	Optional: A `types.CreatePromptConfig` object representing the configuration for creating a prompt version.

A Prompt is returned by the create_version method.

Example

To save a prompt to a Google Cloud project, use the client.prompts.create and client.prompts.create_version methods.

The client.prompts.create method creates a prompt resource in a Google Cloud project. The client.prompts.create_version method creates a prompt version within that resource, and you can access the resource in the Google Cloud console.

The client.prompts.create method takes a Prompt object as input and creates a prompt in the Google Cloud project. The client.prompts.create_version method also requires passing in prompt_id, which is the ID of the prompt resource to create the version under. A new Prompt object is returned, which is associated with the Google Cloud project. Any updates made to a Prompt object are local until create or create_version is called.

The following code sample shows you how to save a prompt and a prompt version:

  # Save `Prompt` to a Google Cloud project.
  # Returns a new `Prompt` object associated with the saved prompt resource.
  prompt_resource = client.prompts.create(prompt=prompt)
  prompt_version_resource = client.prompts.create_version(prompt=prompt, prompt_id=prompt_resource.prompt_id)

Get a saved prompt

This section presents the parameters and an example for how to get a prompt and a prompt version.

There are two methods: client.prompts.get and client.prompts.get_version.

Parameters

This table describes the parameters used by the client.prompts.get method:

Parameters
`prompt_id`	Required: The ID for the prompt to retrieve.
`config`	Optional: A `types.GetPromptConfig` object representing the configuration for getting a prompt.

This table describes the parameters used by the client.prompts.get_version method:

Parameters
`prompt_id`	Required: The ID for the prompt to retrieve.
`version_id`	Required: The ID of the prompt version that you want to retrieve.
`config`	Optional: A `types.GetPromptConfig` object representing the configuration for getting a prompt.

A Prompt is returned by the get and get_version methods.

Examples

To get (load) a prompt that has been saved to the Google Cloud project, use the client.prompts.get method. This method takes the prompt ID as input and returns the corresponding Prompt object. This code sample shows how to load a saved prompt:

  # Get prompt
  retrieved_prompt = client.prompts.get(prompt_id=prompt_resource.prompt_id)

The following code sample shows you how to get a version of a prompt.

  retrieved_prompt_version = client.prompts.get_version(prompt_id='your-prompt-id', version_id='your-prompt-version-id')

The following code demonstrates how to transform your prompt to call generate_content in the generative AI SDK.

  from google import genai
  from google.genai import types as genai_types

  genai_client = genai.Client(vertexai=True, project="my-project", location="my-location")

  response = genai_client.models.generate_content(
      model=retrieved_prompt.prompt_data.model,
      contents=retrieved_prompt.assemble_contents(),
  )

List prompts and versions

This section presents the parameters and an example for how to list prompts and prompt versions.

There are two methods: client.prompts.list and client.prompts.list_versions.

Parameters

This table describes the parameters used by the list method:

Parameters
`config`	Optional: A `types.ListPromptsConfig` object representing the configuration for listing prompts.

This table describes the parameters used by the list_versions method:

Parameters
`prompt_id`	Required: The ID of the prompt to list versions for.
`config`	Optional: A `types.ListPromptsConfig` object representing the configuration for listing prompt versions.

Both the list and list_versions methods return an Iterator of types.PromptRef objects. The PromptRef contains a reference to a prompt.

Example

To see the prompt ID and model for all prompts saved in your Google Cloud project, use the list method.

The following code sample demonstrates how to retrieve a PromptRef for all saved prompts in the current project:

  prompt_refs = list(client.prompts.list())

  # Get a prompt from the list
  prompt1 = client.prompts.get(prompt_id=prompt_refs[0].prompt_id)

The following code sample demonstrates how to list prompt and version IDs for all prompt versions saved within the prompt:

  prompt_versions_metadata = client.prompts.list_versions(prompt_id="123456789")

  # Get a specific prompt version from the versions metadata list
  prompt1 = client.prompts.get_version(
      prompt_id=prompt_versions_metadata[0].prompt_id,
      version_id=prompt_versions_metadata[0].version_id
  )

Delete a prompt

This section presents the parameters and an example for how to delete a prompt.

There are two methods: delete and delete_version.

Parameters

This table describes the parameters used by the delete method:

Parameters
`prompt_id`	The ID of the prompt to delete.
`config`	Optional: A `types.DeletePromptConfig` object representing the configuration for deleting a prompt.

This table describes the parameters used by the delete_version method:

Parameters
`prompt_id`	The ID for the prompt to delete a version from.
`version_id`	The version of the prompt to delete.
`config`	Optional: A `types.DeletePromptConfig` object representing the configuration for deleting a prompt version.

Examples

To delete a prompt and all of its versions, use the delete method.

  client.prompts.delete(prompt_id=retrieved_prompt.prompt_id)

To delete a specific version from a prompt resource, use the delete_version method.

  client.prompts.delete_version(prompt_id=retrieved_prompt.prompt_id, version_id='your-version-id')

Restore a prompt version

This section presents the parameters and an example for how to restore a prompt version.

Parameters

This table describes the parameters used by the restore_version method:

Parameters
`prompt_id`	The ID for a specific prompt.
`version_id`	The version of the prompt to restore.
`config`	The configuration for restoring a prompt version.

A Prompt object is returned by the restore_version method.

Example

A prompt resource also contains version history that stores previous saved versions of the prompt. You can use the restore_version() method to restore an older version as the latest version of the prompt. This returns a Prompt object.

  # Restore to prompt version id 1
  restored_prompt = client.prompts.restore_version(prompt_id=retrieved_prompt.prompt_id, version_id='1')

What's next

To learn more about prompts supporting function calling, see Introduction to function calling to learn more.

Prompt management Stay organized with collections Save and categorize content based on your preferences.

Overview

Prompt management capabilities

Create a local prompt

Save a prompt to a Google Cloud project

Parameters

Example

Get a saved prompt

Parameters

Examples

List prompts and versions

Parameters

Example

Delete a prompt

Parameters

Examples

Restore a prompt version

Parameters

Example

What's next

Prompt management