The following example shows the general structure of how to build a FastAPI application. For concrete implementations of agents with specific abilities, see the examples section.

​
STEP 1: Create a Project

  1. Create a new Encord Project:
mkdir my_project
cd my_project
  1. Create and source a new virtual environment.
python -m venv venv
source venv/bin/activate
  1. Install dependencies.
python -m pip install "fastapi[standard]" encord-agents

​
STEP 2: Define the Agent

Create a main.py file using the following template:

main.py
from typing_extensions import Annotated

from encord.objects.ontology_labels_impl import LabelRowV2
from encord_agents import FrameData
from encord_agents.fastapi import dep_label_row
from encord_agents.fastapi.cors import EncordCORSMiddleware

from fastapi import FastAPI, Depends, Form

app = FastAPI()
app.add_middleware(EncordCORSMiddleware)

@app.post("/my_agent")
def my_agent(
    frame_data: FrameData,
    label_row: Annotated[LabelRowV2, Depends(dep_label_row)],
):
    # ... Do your edits to the labels
    label_row.save()

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

You can inject multiple different dependencies into the function if necessary.

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

​
STEP 3: Test the Agent

Trigger the agent by running it locally.

ENCORD_SSH_KEY_FILE=/path/to/your_private_key \
    fastapi dev main.py --port 8080

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

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

To test the agent endpoint, open the 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:

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

The single quotes around <the_pasted_url> 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.

​
STEP 4: Deployment

This section is under construction.

Meanwhile, refer to the official FastAPI documentation.