Skip to content

Google Cloud Run Functions

Warning

⚠️ Before we begin, please make sure that you have authentication covered.

Info

This example shows the general structure of how to build a GCP cloud function. For concrete implementations of agents with specific abilities, please see the examples section.

Create a project

Create a new project:

mkdir my_project
cd my_project

Create and source a new virtual environment.

python -m venv venv
source venv/bin/activate

Make a requirements file:

requirements.txt
functions-framework
encord-agents

Install the dependencies.

Warning

Make sure you sourced the environment above. Otherwise, the dependencies will be installed globally. 

python -m pip install -r requirements.txt

Develop your agent

Create a main.py file with the following template:

main.py
from encord.objects.ontology_labels_impl import LabelRowV2

from encord_agents.core.data_model import FrameData
from encord_agents.gcp import editor_agent


@editor_agent()
def my_agent(frame_data: FrameData, label_row: LabelRowV2) -> None:
    ...
    # label_row.save()

Fill in the function my_agent with what you want to happen when your agent is triggered.

💡 Notice that you can inject multiple different dependencies into the function if you want.

You can find multiple examples of what can be done with editor agents here.

Test the agent

First, run the agent locally, such that it can be triggered.

ENCORD_SSH_KEY_FILE=/path/to/your_private_key \
    functions-framework --target=my_agent --debug --source main.py

Info

Effectively, this means starting an API that lives at localhost:8080/my_agent and expects a POST request with JSON data of the following format: 

{
    "project_hash": "<project_hash>",
    "data_hash": "<data_hash>",
    "frame": <frame_number>
}

To hit that agent endpoint, open the Label Editor in your browser on a frame for which you want to test your agent. Copy the URL.

Open a new terminal in the my_project directory. Then, run

source venv/bin/activate
encord-agents test local my_agent '<the_pasted_url>'

Warning

Notice the single quotes around <the_pasted_url>. They are important and should be there because you might copy a url with, e.g., an & character that have a special meaning if it is not within a string (or escaped).

Refresh the label editor in your browser to see the effect that you applied to the label_row: LabelRowV2 happening.

Deployment

To go from development to production, you need to deploy your agent on the Google infrastructure. This is an example of how you could deploy the agent to the cloud.

gcloud functions deploy my_agent \
    --entry-point my_agent \
    --runtime python311 \
    --trigger-http \
    --allow-unauthenticated \
    --gen2 \
    --region europe-west2 \
    --set-secrets="ENCORD_SSH_KEY=SERVICE_ACCOUNT_KEY:latest"

Notice how we set secrets (the ssh key that the agent should use).

Here are the official Google run function deploy docs. There are a couple of things that you need to pay attention to:

  • You must make sure to authenticate gcloud and select the appropriate project first
  • You should configure a secret with the ssh_key content. Please see Google Secrets docs