> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encord.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GCP Cloud Functions

<Info>
  The following example shows the general structure of how to build a GCP cloud function.
  For concrete implementations of agents with specific abilities, see the [examples section](/agents-documentation/Custom-Agents/Examples).
</Info>

## STEP 1: Create a Project

1. Create a new Encord Project:

```shell theme={"dark"}
mkdir my_project
cd my_project
```

2. Create and source a new virtual environment.

```
python -m venv venv
source venv/bin/activate
```

3. Create a requirements file.

```requirements title="requirements.txt" theme={"dark"}
functions-framework
encord-agents
```

4. Install dependencies.

```shell theme={"dark"}
python -m pip install -r requirements.txt
```

## STEP 2: Define the Agent

Create a `main.py` file using the following template:

```python title="main.py" theme={"dark"}
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()
```

Complete the `my_agent` function with the logic you want to execute when the agent is triggered.

<Tip>
  You can inject multiple different [dependencies](/agents-documentation/Reference/Custom-Agents/Agents-Reference-Custom-Agents#dependencies-2) into the function if necessary.
</Tip>

You can find multiple examples of what can be done with Custom Agents [here](/agents-documentation/Custom-Agents/Examples).

## STEP 3: Test the Agent

Trigger the agent by running it locally.

```shell theme={"dark"}
ENCORD_SSH_KEY_FILE=/path/to/your_private_key \
    functions-framework --target=my_agent --debug --source main.py
```

<Info>
  This means starting an API at `localhost:8080/my_agent` that expects a POST request with `JSON` data with the following format:

  ```json theme={"dark"}
  {
      "projectHash": "<project_hash>",
      "dataHash": "<data_hash>",
      "frame": <frame_number>
  }
  ```
</Info>

To test the agent endpoint, open the [Label Editor](/platform-documentation/Annotate/annotate-label-editor) in your browser on a frame where you want to run the agent. Then, copy the URL.

Open a new terminal in the `my_project` directory and run:

```shell theme={"dark"}
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](https://www.howtogeek.com/439199/15-special-characters-you-need-to-know-for-bash/#amp-background-process) if it is not within a string (or escaped).
</Warning>

Refresh the Label Editor in your browser to see the effect.

## STEP 4: Deployment

To go from development to production, you must deploy your agent on the Google infrastructure.

The following example shows how you can deploy the agent to the cloud. Notice how secrets (the access key that the agent should use) are set.

```shell theme={"dark"}
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"
```

See the official [Google run function deploy docs](https://cloud.google.com/functions/docs/create-deploy-gcloud) for more information.

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. See [Google Secrets docs](https://cloud.google.com/functions/docs/configuring/secrets)