Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Creating an AI agent using Yandex Cloud Functions

Written by
Updated at September 23, 2025

Learn how to use a function from Cloud Functions with the OpenAI Agents SDK to create an AI agent, i.e., a personalized assistant integrated with Yandex AI Studio text generation models to provide generative responses.

Follow this guide to create a simple AI agent that uses a function from Cloud Functions to get weather information, interact with the Yandex AI Studio language model, and, to add a touch of fun, respond to the user in haiku form.

On the diagram:

  1. The user sends a request to the AI agent. The Cloud Functions handler receives the request.
  2. The Cloud Functions handler creates and runs the AI agent.
  3. The AI agent requests additional weather data for a given city using the custom get_weather() function.
  4. The AI agent sends the user request together with the extra context to the AI Studio text generation model.
  5. A service account authorizes the AI agent to access the AI Studio Text Generation API using an API key.
  6. The service account grants access to the Yandex Lockbox secret with the service account API key to the function in Cloud Functions.
  7. The function in Cloud Functions retrieves the service account API key from the Yandex Lockbox secret.
  8. The AI Studio model sends the generated response to the AI agent.
  9. The AI agent returns the response to the user.

The AI agent you create in this tutorial will be deployed in Yandex Cloud using Yandex Cloud Functions. You will also create resources to arrange access to the AI Studio model: a service account, the service account API key, the Yandex Lockbox secret, and a function in Cloud Functions.

You can create these resources automatically or manually.

What an AI agent is and how to use it

An AI agent is an AI-powered software assistant which can follow instructions, give answers to questions, and interact with users or other systems within a given context. Unlike standard generative models, AI agents can:

  • Support personalized instructions and have a personality.
  • Use external sources and third-party tools to gather information.
  • Maintain conversation context.
  • Perform multi-step actions to solve complex tasks.

Why use serverless functions to work with AI agents

Functions offered by Cloud Functions provide multiple benefits when deploying AI agents:

  • Scalability: Automatic scaling to accommodate the load.
  • Cost-effectiveness: You only pay for the actual execution time.
  • No infrastructure management required: You do not need to configure or maintain servers.
  • Fast deployment: AI agents are easy to create and update.
  • Multiple integration options: Simple connection to APIs and other Yandex Cloud services.

Get your cloud ready

Sign up for Yandex Cloud and create a billing account:

  1. Navigate to the management console and log in to Yandex Cloud or create a new account.
  2. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one and link a cloud to it.

If you have an active billing account, you can navigate to the cloud page to create or select a folder for your infrastructure.

Learn more about clouds and folders here.

The infrastructure support cost for this tutorial includes:

Creating an AI agent automatically

Run a script to automatically create all the required resources in your selected folder and deploy a ready-to-use AI agent for you to experiment with.

To create an AI agent automatically:

  1. Install the Yandex Cloud CLI and get authenticated.

  2. Download and install Python.

  3. Clone the repository with scripts for creating the AI agent:

    git clone https://github.com/yandex-cloud-examples/yc-serverless-ai-agent

    The repository contains scripts for creating three types of AI agents:

    The create-simple-ai-agent.py script will create a simple AI agent which returns information about the weather in Tokyo in haiku form when you run it.

    The create-advanced-ai-agent.py script will create an advanced AI agent which responds to user requests in haiku form. When there is no user request, the agent returns a response to the default request.

    The create-complex-ai-agent.py script will create a translator agent which can handle user requests for text translation to the specified language while maintaining the style and tone.

  4. Make the script file executable. Here is an example:

    chmod +x create-simple-ai-agent.py

  5. Run the script:

    ./create-simple-ai-agent.py

    While the script is running, specify your cloud and folder details, then wait until the resources are created.

  6. Test the AI agent.

    Test the function in the management console.

    Test the function in the management console.

    You can also test the function by sending a user request to the AI agent via the Yandex Cloud CLI. To do this, run this command and specify the function ID you obtained when creating the AI agent:

    echo '{"query": "What's the weather in Paris?"}' > request.json \
  yc serverless function invoke <function_ID> --data-file request.json

    Test the function in the management console.

    You can also test the function by sending a user request to the AI agent via the Yandex Cloud CLI. To do this, run this command and specify the function ID you obtained when creating the AI agent:

    echo '{"text": "Hello, world!", "target_language": "Russian", "tone": "friendly"}' > translate.json \
  yc serverless function invoke <function_ID> --data-file translate.json

  7. If you no longer need the resources you created, delete them.

Creating an AI agent manually

To create an AI agent manually using a function from Cloud Functions:

  1. Create a service account.
  2. Create the service account API key.
  3. Create a Yandex Lockbox secret.
  4. Prepare a ZIP archive with the function code.
  5. Create a function.
  6. Test the function.

If you no longer need the resources you created, delete them.

Create a service account

  1. In the management console, select the folder where you are going to create your infrastructure.
  2. In the list of services, select Identity and Access Management.
  3. Click Create service account.
  4. Enter the service account name: function-sa.
  5. Click Add role and select the ai.languageModels.user role.
  6. Click Create.

If you do not have the Yandex Cloud CLI installed yet, install and initialize it.

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

  1. Create a service account named function-sa in the default folder:

    yc iam service-account create \
  --name function-sa

    Result:

    done (1s)
id: aje23dgspcpi********
folder_id: b1gt6g8ht345********
created_at: "2025-06-04T19:34:58.145514099Z"
name: function-sa

    Save the service account ID (the id field value) and the folder ID (the folder_id field value) as you will need them later.

    For more information about the yc iam service-account create command, see the CLI reference.

  2. Assign the ai.languageModels.user role for the folder to the created service account by specifying the folder and service account IDs you saved in the previous step:

    yc resource-manager folder add-access-binding <folder_ID> \
  --role ai.languageModels.user \
  --subject serviceAccount:<service_account_ID>

    Result:

    done (2s)
effective_deltas:
  - action: ADD
    access_binding:
      role_id: ai.languageModels.user
      subject:
        id: aje23dgspcpi********
        type: serviceAccount

    For more information about the yc resource-manager folder add-access-binding command, see the CLI reference.

To create a service account, use the create REST API method for the ServiceAccount resource or the ServiceAccountService/Create gRPC API call.

To assign the service account the ai.languageModels.user role for the folder, use the updateAccessBindings REST API method for the Folder resource or the FolderService/UpdateAccessBindings gRPC API call.

Create the service account API key

  1. In the management console, select the folder where you are deploying your infrastructure.

  2. In the list of services, select Identity and Access Management and then select the function-sa service account you created earlier.

  3. In the top panel, click Create new key and select Create API key.

  4. In the Scope field, select the yc.ai.languageModels.execute scope.

  5. Optionally, set the API key expiration date under Expires at.

  6. Click Create.

  7. Save the secret key as you will need it to create a function.

    Alert

    After you close this dialog, the key value will no longer be available.

  1. Create an API key for the function-sa service account:

    yc iam api-key create \
  --service-account-name function-sa \
  --scopes yc.ai.languageModels.execute

    Result:

    api_key:
  id: ajemcpt92i9j********
  service_account_id: aje23dgspcpi********
  created_at: "2025-06-04T19:41:28.960624728Z"
  scope: yc.ai.languageModels.execute
  scopes:
    - yc.ai.languageModels.execute
secret: AQVN1mZ6kUkzDCjhNJxmjDX6WeJdOlJv********

    Save the key value as you will not be able to get it again.

    For more information about the yc iam api-key create command, see the CLI reference.

To create an API key, use the create REST API method for the ApiKey resource or the ApiKeyService/Create gRPC API call.

Create a Yandex Lockbox secret

  1. In the management console, select the folder where you are deploying your infrastructure.
  2. In the list of services, select Lockbox and click Create secret.
  3. In the Name field, specify the secret name: api-key-secret.
  4. In the Secret type field, select Custom.
  5. In the Key field, enter the secret key: api-key.
  6. In the Value field, paste the secret key you obtained in the previous step.
  7. Click Create.

  1. Create a Yandex Lockbox secret named api-key-secret in the default folder by specifying the secret key obtained in the previous step:

    yc lockbox secret create \
  --name api-key-secret \
  --payload "[{'key': 'api-key', 'text_value': '<secret_key>'}]"

    Result:

    done (1s)
id: e6q7c0n0n7ji********
folder_id: b1gt6g8ht345********
created_at: "2025-06-04T19:50:38.690Z"
name: api-key-secret
status: ACTIVE
current_version:
  id: e6qhmal099ki********
  secret_id: e6q7c0n0n7ji********
  created_at: "2025-06-04T19:50:38.690Z"
  status: ACTIVE
  payload_entry_keys:
    - api-key

    For more information about the yc lockbox secret create command, see the CLI reference.

To create a secret, use the create REST API method for the Secret resource or the SecretService/Create gRPC API call.

Grant read permissions for the secret contents to the service account

  1. In the management console, select the folder where you are deploying your infrastructure.

  2. In the list of services, select Lockbox and then select the secret named api-key-secret you created earlier.

  3. On the left-hand panel, select Access bindings and click Assign roles. In the window that opens:

    1. In the search bar, enter the name of the function-sa service account you created and select it.
    2. Click Add role and select lockbox.payloadViewer.
    3. Click Save.

  1. Assign the lockbox.payloadViewer role for api-key-secret to the function-sa service account:

    yc lockbox secret add-access-binding \
    --name api-key-secret \
    --service-account-name function-sa \
    --role lockbox.payloadViewer

    For more information about the yc lockbox secret add-access-binding command, see the CLI reference.

To assign a role for a secret to a service account, use the setAccessBindings REST API method for the Secret resource or the SecretService/SetAccessBindings gRPC API call.

Prepare a ZIP archive with the function code

  1. Save the following code to a file named index.py:

    import os

from openai import AsyncOpenAI

from agents import (
    Agent,
    OpenAIChatCompletionsModel,
    Runner,
    function_tool,
    set_tracing_disabled,
)

BASE_URL = os.getenv("BASE_URL")
API_KEY = os.getenv("API_KEY")
MODEL_NAME = os.getenv("MODEL_NAME")

client = AsyncOpenAI(base_url=BASE_URL, api_key=API_KEY)
set_tracing_disabled(disabled=True)


@function_tool
def get_weather(city: str):
    print(f"[debug] getting weather for {city}")
    return f"The weather in {city} is sunny."


async def handler(event, context):
    agent = Agent(
        name="Assistant",
        instructions="You only respond in haikus.",
        model=OpenAIChatCompletionsModel(model=MODEL_NAME, openai_client=client),
        tools=[get_weather],
    )

    result = await Runner.run(agent, "What's the weather in Tokyo?")

    return {
        "statusCode": 200,
        "body": result.final_output,
    }

  2. Save the following code to a file named requirements.txt:

    openai-agents

  3. Add the index.py and requirements.txt files into the openai-function.zip archive.

Create a function

  1. In the management console, select the folder where you are deploying your infrastructure.
  2. In the list of services, select Cloud Functions.
  3. Create a function:
    1. Click Create function.
    2. In the window that opens, enter ai-agent-function as the function name.
    3. Click Create.
  4. Create a function version:
    1. Select Python 3.12 as the runtime environment, disable Add files with code examples, and click Continue.
    2. In the Method field, select ZIP archive and attach the openai-function.zip file you created earlier.
    3. Specify the entry point: index.handler.
    4. Under Parameters, specify:
      • Timeout: 5 minutes.
      • Memory: 128 MB.
      • Service account: Select the function-sa service account.
      • Environment variables:

        • MODEL_NAME: URI of the Yandex AI Studio text generation model.

          Example: gpt://<folder_ID>/yandexgpt/latest.

          Where <folder_ID> is the ID of the folder you are creating the infrastructure in.

        • BASE_URL: Yandex AI Studio URL, https://llm.api.cloud.yandex.net/v1.

      • Lockbox secrets:
        • In the Environment variable field, specify API_KEY and select the previously created api-key-secret, its version, and api-key.
      • If you prefer to opt out of logging so as not to pay for Cloud Logging, disable the Write logs option to disable logging.
    5. Click Save changes.

  1. Create a function named ai-agent-function in the default folder:

    yc serverless function create \
 --name ai-agent-function

    Result:

    id: d4edhic2qf3i********
folder_id: b1gt6g8ht345********
created_at: "2025-06-04T20:02:14.741Z"
name: ai-agent-function
http_invoke_url: https://functions.yandexcloud.net/d4edhic2qf3i********
status: ACTIVE

    For more information about the yc serverless function create command, see the CLI reference.

  2. Create a version of the ai-agent-function function:

    yc serverless function version create \
  --function-name ai-agent-function \
  --memory=128m \
  --execution-timeout=5m \
  --runtime=python312 \
  --entrypoint=index.handler \
  --service-account-id=<service_account_ID> \
  --environment MODEL_NAME="gpt://<folder_ID>/yandexgpt/latest",BASE_URL="https://llm.api.cloud.yandex.net/v1" \
  --secret name=api-key-secret,key=api-key,environment-variable=API_KEY \
  --source-path=./openai-function.zip \
  --no-logging

    Where:

    • --service-account-id: ID of the function-sa service account you saved previously.
    • <folder_ID>: ID of the folder you saved when creating the service account.

    Result:

    done (16s)
id: d4e1vnnvhk5p********
function_id: d4edhic2qf3i********
created_at: "2025-06-04T20:09:59.675Z"
runtime: python312
entrypoint: index.handler
resources:
  memory: "134217728"
execution_timeout: 300s
service_account_id: aje23dgspcpi********
image_size: "14958592"
status: ACTIVE
tags:
  - $latest
environment:
  BASE_URL: https://llm.api.cloud.yandex.net/v1
  MODEL_NAME: gpt://b1gt6g8ht345********/yandexgpt/latest
secrets:
  - id: e6q7c0n0n7ji********
    version_id: e6qhmal099ki********
    key: api-key
    environment_variable: API_KEY
log_options:
  disabled: true
  folder_id: b1gt6g8ht345********
concurrency: "1"

    For more information about the yc serverless function version create command, see the CLI reference.

To create a function, use the create REST API method for the Function resource or the FunctionService/Create gRPC API call.

To create a function version, use the createVersion REST API method for the Function resource or the FunctionService/CreateVersion gRPC API call.

Test the function

  1. In the management console, select the folder where you created the infrastructure.

  2. In the list of services, select Cloud Functions and then select the function you created.

  3. Navigate to the Testing tab.

  4. Click Run test and check out the testing results.

    If the request is successful, the function status will change to Done and the output will contain the 200 status code and model response. Here is an example:

    {
    "statusCode": 200,
    "body": "In Tokyo's sky,\nSunshine beams so bright and clear,\nWarmth fills the air."
}

How to delete the resources you created

To stop paying for the resources you created:

  1. Delete the function.
  2. Delete the secret.
  3. If you logged data to a log group, delete it.
Previous
Python
Next
Configuring Postfix to send emails via Yandex Cloud Postbox