### Set up Environment and Install Dependencies

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

Installs the 'encord-agents' and 'anthropic' libraries, and sets environment variables for Anthropic API key and Encord SSH key.

```shell
python -m venv venv
source venv/bin/activate
python -m pip install encord-agents anthropic
export ANTHROPIC_API_KEY="<your_api_key>"
export ENCORD_SSH_KEY_FILE="/path/to/your/private/key"
```

--------------------------------

### Install Encord Agents and FastAPI

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/fastapi.md

Installs the necessary Python packages for building Encord agents with FastAPI, including the standard FastAPI dependencies.

```shell
python -m pip install "fastapi[standard]" encord-agents
```

--------------------------------

### Environment Setup with Python and Shell Commands

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

Sets up a Python virtual environment, installs necessary dependencies including FastAPI, encord-agents, and anthropic, and configures environment variables for the Anthropic API key and Encord SSH key. This is essential for running the frame classification agent.

```shell
python -m venv venv                   # Create a virtual Python environment  
source venv/bin/activate              # Activate the virtual environment 
python -m pip install "fastapi[standard]" encord-agents anthropic # Install required dependencies  
export ANTHROPIC_API_KEY="<your_api_key>" # Set your Anthropic API key 
export ENCORD_SSH_KEY_FILE="/path/to/your/private/key"  # Define your Encord SSH key 
```

--------------------------------

### Install Dependencies

Source: https://github.com/encord-team/encord-agents/blob/main/docs/code_examples/celery/README.md

Installs the necessary Python packages for the Encord Agents Celery Queue Runner example from a requirements file.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install encord-agents with Vision Dependencies

Source: https://github.com/encord-team/encord-agents/blob/main/docs/installation.md

Installs 'encord-agents' along with additional dependencies required for working with visual files like images and videos. Recommended for most use cases involving visual data.

```shell
python -m pip install encord-agents[vision]
```

--------------------------------

### Install Dependencies and Set Environment Variables

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

Installs necessary Python packages for Encord Agents, Langchain, and OpenAI, and sets the required API keys for OpenAI and Encord SSH authentication.

```shell
python -m venv venv

source venv/bin/activate

python -m pip install encord-agents langchain-openai functions-framework openai

export OPENAI_API_KEY="<your-api-key>"
export ENCORD_SSH_KEY_FILE="/path/to/your/private/key"
```

--------------------------------

### Install Encord Agents via pip

Source: https://github.com/encord-team/encord-agents/blob/main/README.md

Installs the encord-agents library using pip. This is the primary method to get started with the library.

```shell
python -m pip install encord-agents
```

--------------------------------

### Run FastAPI Agent Locally

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

Command to start the FastAPI server in development mode with auto-reload enabled.

```shell
fastapi dev agent.py --port 8080
```

--------------------------------

### Run FastAPI Agent Locally

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/fastapi.md

Starts a local FastAPI development server for the Encord agent, specifying the SSH key file and the port for the API.

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

--------------------------------

### Install Dependencies and Set Environment Variables

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

Installs necessary Python packages including encord-agents, langchain-openai, fastapi, and openai. It also sets the OPENAI_API_KEY and ENCORD_SSH_KEY_FILE environment variables.

```shell
python -m venv venv
source venv/bin/activate
python -m pip install encord-agents langchain-openai "fastapi[standard]" openai
export OPENAI_API_KEY="<your-api-key>"
export ENCORD_SSH_KEY_FILE="/path/to/your/private/key"
```

--------------------------------

### Add encord-agents to Poetry Project

Source: https://github.com/encord-team/encord-agents/blob/main/docs/installation.md

Adds the 'encord-agents' library as a dependency to an existing project managed by Poetry.

```shell
poetry add encord-agents
```

--------------------------------

### Modal Cotracker3 Keypoint Tracking Agent

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

This example demonstrates using Modal with Encord Agents for keypoint tracking using the Cotracker3 algorithm. It requires cloning the Cotracker3 repository and installing additional dependencies. The agent is deployed on Modal and can be triggered by right-clicking on a keypoint in the Encord platform.

```python
import modal
import torch
import cv2
import numpy as np

from encord_agent.utils import user_data
from encord_agent.agents.cotracker3 import Cotracker3


stub = modal.Stub()


@stub.function(
    gpu="T4",
    secrets=[
        modal.Secret.from_name("encord_secrets")
    ],
    timeout=600,
    network_disk=1024,
)
def cotracker_function(frames: list[np.ndarray], points: np.ndarray):
    """Modal function to run Cotracker3"
    cotracker = Cotracker3()
    return cotracker.cotracker_run(frames, points)


@user_data.register_agent
def editor_cotracker3(
    frames: list[np.ndarray],
    points: np.ndarray,
):
    """Cotracker3 keypoint tracking"
    return modal.call_app(
        cotracker_function,
        frames=frames,
        points=points,
    )

```

--------------------------------

### Create and Activate Venv Environment

Source: https://github.com/encord-team/encord-agents/blob/main/docs/installation.md

Demonstrates how to create a new virtual environment named 'agents-venv' using Python's venv module and subsequently activate it.

```shell
python -m venv agents-venv
```

```shell
source agents-venv/bin/activate
```

--------------------------------

### Install Dependencies (Python)

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/recaption_video.ipynb

Installs necessary libraries for the Encord Agents workflow, including encord-agents, langchain-openai, and openai.

```python
```python
!pip install encord-agents langchain-openai openai
```
```

--------------------------------

### Sequential Runner Execution Example

Source: https://github.com/encord-team/encord-agents/blob/main/docs/task_agents/sequential_runner.md

Provides a basic example of how to set up and execute tasks sequentially using the standard `Runner`. It shows the instantiation of `Runner`, defining an agent stage, and the final call to `runner()`.

```python
from encord_agents.runner import Runner
from encord.orm import LabelRowV2
from encord_agents.agent import AgentTask

runner = Runner()
@runner.stage("my_stage")
def my_agent(task: AgentTask, label_row: LabelRowV2):
    ...
runner()
```

--------------------------------

### Bash Script for System Operations

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/prelabel_videos_with_bounding_boxes.ipynb

A bash script intended for system operations or build processes. This snippet might be used for environment setup, dependency installation, or running specific commands within the encord-agents project.

```bash
#!/bin/bash
# Placeholder for system operation script
echo "Running system task..."
exit 0
```

--------------------------------

### Python Agent Initialization and Operation

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/hugging_face_agent_example.ipynb

Demonstrates the basic setup and execution of an agent within the Encord framework. It highlights how to initialize an agent and start its operation, which typically involves processing data or performing tasks based on its configuration.

```python
from encord.agents import EncordAgent

# Initialize the agent with a specific configuration or model
agent = EncordAgent(model_name="your_model_name")

# Start the agent's operation loop
agent.run()

print("Agent started successfully.")
```

--------------------------------

### Shell Command to Run Uvicorn Server for FastAPI App

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

This command starts a FastAPI server using uvicorn, enabling auto-reloading for development. It runs the 'main' FastAPI application instance on port 8080.

```shell
uvicorn main:app --reload --port 8080
```

--------------------------------

### Start Celery Worker

Source: https://github.com/encord-team/encord-agents/blob/main/docs/code_examples/celery/README.md

Launches a Celery worker process that listens for tasks on the RabbitMQ queue and executes them. Multiple workers can be started for parallel processing.

```python
python worker.py
```

--------------------------------

### Start RabbitMQ with Docker

Source: https://github.com/encord-team/encord-agents/blob/main/docs/code_examples/celery/README.md

Launches a RabbitMQ message broker instance using Docker, exposing the management interface and AMQP port. This is essential for Celery's distributed task queue.

```bash
docker run -d --hostname my-rabbit --name my-rabbit -p 5672:5672 -p 15672:15672 rabbitmq:management
```

--------------------------------

### Configuration Loading

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/sentiment_analysis.ipynb

This code demonstrates how to load configuration settings for the agents, likely from a file or environment variables. Proper configuration is essential for agent setup.

```python
import yaml

def load_configuration(file_path):
    """Loads agent configuration from a YAML file."""
    with open(file_path, 'r') as f:
        config = yaml.safe_load(f)
    return config
```

--------------------------------

### Create Local Project and Install Dependencies (Shell)

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/aws_lambda.md

This snippet demonstrates creating a local project directory, setting up a Python virtual environment, activating it, and installing the 'encord-agents' library.

```shell
mkdir my_project
cd my_project
python -m venv venv
source venv/bin/activate
pip install encord-agents
deactivate
```

--------------------------------

### Create and Activate Conda Environment

Source: https://github.com/encord-team/encord-agents/blob/main/docs/installation.md

Shows how to create a new Conda environment named 'agents' with Python version 3.10 or higher, and then activate it.

```shell
conda create -n agents python>=3.10
```

```shell
conda activate agents
```

--------------------------------

### Install Encord Agents and OpenAI Libraries

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/multistage_video_summarisation.ipynb

Installs the encord-agents library with vision support and the openai library using pip. This is a prerequisite for running the code.

```python
!python -m pip install encord-agents[vision] openai
```

--------------------------------

### CLI Execution Example

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/task_agent_route_on_annotator_name.ipynb

Example command to run the agent script from the command line, specifying the project hash.

```bash
python agent.py --project-hash "..."
```

--------------------------------

### Install encord-agents and transformers Libraries

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/sentiment_analysis.ipynb

Installs the necessary Python libraries for using Encord Agents and Hugging Face's transformers for sentiment analysis.

```python
!
```

```python
!python -m pip install -q encord-agents
!python -m pip install -q transformers
```

--------------------------------

### Run Encord Agent in Debug Mode

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

Starts the Encord agent in debug mode, targeting the 'agent' function and using 'agent.py' as the source file. This command is used for local development and debugging.

```shell
functions-framework --target=agent --debug --source agent.py
```

--------------------------------

### Local Python Environment Setup

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/aws_lambda.md

Optional steps to set up a local Python virtual environment for testing the Lambda function dependencies before building a Docker image. It involves creating a virtual environment, activating it, and installing packages from `requirements.txt`.

```shell
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

--------------------------------

### Install Encord Agents and OpenAI

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/llm_as_a_judge.ipynb

Installs the necessary libraries for using Encord Agents with vision capabilities and the OpenAI library for LLM integrations.

```python
```python
!pip install "encord-agents[vision]" openai
```
```

--------------------------------

### Install Encord Agents for Vision

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/yolo_example.ipynb

Installs the `encord-agents` library with vision dependencies required for image pre-labeling tasks.

```python
!python -m pip install "encord-agents[vision]"
```

--------------------------------

### Test the Encord Agent

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

Command to test the locally running Encord agent by providing a URL to a frame in the Encord platform.

```shell
source venv/bin/activate
encord-agents test local object_classification '<your_url>'
```

--------------------------------

### Install encord-agents library

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/task_agent_route_on_annotator_name.ipynb

Installs the necessary encord-agents library using pip. Ensure you have Python and pip available.

```python
!python -m pip install encord-agents
```

--------------------------------

### FastAPI Geometric Example with Object Hashes

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

A basic FastAPI example demonstrating how to utilize objectHashes. This agent can be triggered from the Encord app to perform custom actions on selected objects, such as running an OCR model.

```APIDOC
## POST /handle-object-hashes

### Description
Processes selected objects from an Encord frame. It receives frame data and a list of object instances, allowing for custom actions like running an OCR model on specific objects.

### Method
POST

### Endpoint
/handle-object-hashes

### Parameters
#### Request Body
- **frame_data** (FrameData) - Required - Contains information about the current frame.
- **lr** (LabelRowV2) - Required - The label row associated with the current frame.
- **object_instances** (list[ObjectInstance]) - Required - A list of selected object instances from the frame.

### Request Example
```json
{
  "frame_data": {
    "frame_index": 0,
    "frame_height": 1080,
    "frame_width": 1920,
    "image_base64": "/9j/4AAQSkZJRgABAQ...
  },
  "lr": {
    "title": "My Label Row",
    "objects": [
      {
        "name": "Bicycle",
        "//": {
          "type": "object",
          "featureHash": "..."
        },
        "box": {
          "x": 100,
          "y": 200,
          "w": 50,
          "h": 75
        }
      }
    ]
  },
  "object_instances": [
    {
      "object_id": "object_instance_id_1",
      "name": "Bicycle",
      "class_id": "class_id_1",
      "bounding_box": {
        "x_min": 0.1,
        "y_min": 0.2,
        "x_max": 0.3,
        "y_max": 0.4
      },
      "object_hashes": {
        "featureHash": "feature_hash_1"
      }
    }
  ]
}
```

### Response
#### Success Response (200)
- **message** (string) - A success message indicating the objects were processed.

#### Response Example
```json
{
  "message": "Objects processed successfully."
}
```
```

--------------------------------

### Install encord-agents and modal

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/modal.md

Installs the necessary Python packages for encord-agents and Modal within a virtual environment. This is a prerequisite for running Modal applications.

```shell
python -m venv venv
source venv/bin/activate
python -m pip install encord-agents modal
```

--------------------------------

### Basic Runner Initialization and Execution Example

Source: https://github.com/encord-team/encord-agents/blob/main/docs/task_agents/sequential_runner.md

Demonstrates the three core steps for using the Runner: initialization, defining stage logic using a decorator, and executing the runner. The runner can be run via the CLI or directly within Python code, allowing for task processing and movement between stages.

```python
from encord.objects.ontology_labels_impl import LabelRowV2
from encord_agents.tasks import Runner

# Step 1: Initialization
# Initialize the runner
# project hash is optional but allows you to "fail fast"
# if you misconfigure the stages.
runner = Runner(project_hash="<your_project_hash>")

# Step 2: Definition
# Define agent logic for a specific stage
@runner.stage(stage="my_stage_name")  # or stage="<stage_uuid>"
def process_task(lr: LabelRowV2) -> str | None:
    # Modify the label row as needed
    lr.set_priority(0.5)

    # Return the pathway name or UUID where the task should go next
    return "next_stage"

# Step 3: Execution
if __name__ == "__main__":
    # via the CLI
    runner.run() 

    # or via code
    runner(
        project_hash="<your_project_hash">,
        refresh_every=3600,  # seconds
        num_retries = 1,
        task_batch_size = 1,
    )
```

--------------------------------

### QueueRunner Execution with Stages

Source: https://github.com/encord-team/encord-agents/blob/main/docs/task_agents/runner_intro.md

Shows the setup for a `QueueRunner`, which allows for controlled task queuing for each stage. The specific execution logic and task queue management are detailed further in the `QueueRunner` documentation.

```python
from encord_agents.api import QueueRunner

runner = QueueRunner()

@runner.stage("stage_1")
def stage_1():
    return "next"

@runner.stage("stage_2")
def stage_2():
    return "next"

```

--------------------------------

### Install Encord Agents with Vision Support

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/hugging_face_agent_example.ipynb

Installs the encord-agents library with the necessary dependencies for vision tasks. This is a prerequisite for using vision-related features.

```python
!python -m pip install encord-agents[vision]
```

--------------------------------

### Install Ultralytics YOLOv11

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/yolo_example.ipynb

Installs the Ultralytics library, which is required to use the YOLOv11 model for object detection.

```bash
!pip install ultralytics
```

--------------------------------

### Install Agent Dependencies

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/gcp.md

Installs necessary Python packages for running Encord agents and the functions-framework.

```requirements
functions-framework
encord-agents
```

--------------------------------

### Install Required Libraries

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/speech_sentiment_agent_single_speaker.ipynb

Installs the essential Python libraries for running the speech emotion recognition model: `encord-agents`, `transformers`, `librosa`, `torch`, and `numpy`. These libraries provide functionalities for agent management, accessing pre-trained models, audio processing, and numerical operations, respectively.

```python
!pip install encord-agents
!pip install transformers
!pip install librosa
!pip install torch
!pip install numpy
```

--------------------------------

### Parallel QueueRunner Execution Example

Source: https://github.com/encord-team/encord-agents/blob/main/docs/task_agents/sequential_runner.md

Demonstrates the structure for using `QueueRunner` for parallel task processing. It highlights changing the runner instantiation and the loop structure for processing tasks from a queue.

```python
from encord_agents.queue_runner import QueueRunner
from encord.orm import LabelRowV2
from encord_agents.agent import AgentTask

queue_runner = QueueRunner()

@queue_runner.stage("my_stage")
def my_agent(task: AgentTask, label_row: LabelRowV2):
    ...

for agent in queue_runner.get_agent_stages():
    your_task_queue = []
    for task in agent.get_tasks():
        your_task_queue.append(task)

    for task in your_task_queue:
        result = my_agent(task)
```

--------------------------------

### Create Encord Ontology from JSON

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

Defines an Encord Ontology structure using Python and creates the ontology via the Encord client. This script is used to replicate the ontology structure required for the frame classification example.

```python
import json
from encord.objects.ontology_structure import OntologyStructure
from encord_agents.core.utils import get_user_client

encord_client = get_user_client()
structure = OntologyStructure.from_dict(json.loads("{the_json_above}"))
ontology = encord_client.create_ontology(
    title="Your ontology title",
    structure=structure
)
print(ontology.ontology_hash)
```

--------------------------------

### Local Project Setup for Lambda with Docker

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/aws_lambda.md

This section outlines the initial steps for creating a local project directory for a Lambda function that will be containerized. It includes creating the project directory and a `requirements.txt` file to specify dependencies.

```shell
mkdir my_project
cd my_project
```

```text
boto3
encord-agents
```

--------------------------------

### Create Package Directory and Install Dependencies for AWS Lambda (Shell)

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/aws_lambda.md

This command installs 'encord-agents' and 'boto3' into a 'package' directory, specifying platform-specific binaries suitable for AWS Lambda. This ensures dependencies are compatible with the AWS environment.

```shell
mkdir package
pip install \
  --platform manylinux2014_x86_64 \
  --target=package \
  --implementation cp \
  --python-version 3.12 \
  --only-binary=:all: --upgrade \
  encord-agents boto3
```

--------------------------------

### Test Local Agent with Encord CLI

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

This command sequence tests a locally running Encord agent. It involves activating a virtual environment and then using the `encord-agents test local agent` command with a provided URL of a frame with objects.

```shell
source venv/bin/activate
encord-agents test local agent '<your_url>'
```

--------------------------------

### Test Frame Classification Agent Locally

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

Tests the frame classification agent locally using the `encord-agents test` command. It activates the virtual environment and then runs the agent against a specified frame URL. The URL should point to a specific frame in the Encord platform's label editor.

```shell
source venv/bin/activate
encord-agents test local frame_classification '<your_url>'
```

--------------------------------

### Run Agent Locally with Functions Framework

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/gcp.md

Starts a local development server using the functions-framework to test the Encord agent. Requires setting the ENCORD_SSH_KEY_FILE environment variable.

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

--------------------------------

### Python Video Caption Recaptioning Agent

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

This Python agent retrieves existing captions, sends the first frame and caption to an LLM for rephrasing, and updates the label row with the new captions. It requires `openai` and `encord-agents` libraries.

```python
from typing import Annotated

from encord.objects.ontology_labels_impl import LabelRowV2
from encord.objects.ontology_object_instance import ObjectInstance
from fastapi import Depends, FastAPI

from encord_agents.fastapi.cors import get_encord_app()
from encord_agents.fastapi.dependencies import (
    FrameData,
    dep_label_row,
    dep_objects,
)

# Initialize FastAPI app
app = get_encord_app()


@app.post("/handle-object-hashes")
def handle_object_hashes(
    frame_data: FrameData,
    lr: Annotated[LabelRowV2, Depends(dep_label_row)],
    object_instances: Annotated[list[ObjectInstance], Depends(dep_objects)],
) -> None:
    for object_inst in object_instances:
        print(object_inst)
```

--------------------------------

### Creating an Empty List in Python

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/mask_rcnn_on_videos.ipynb

This Python snippet shows how to create an empty list. Empty lists serve as a starting point for collecting data or building lists dynamically.

```python
my_empty_list = []
```

--------------------------------

### FastAPI Agent for Object Classification with Claude

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

The complete Python code for a FastAPI agent that processes image frames, uses Claude to classify generic objects, and updates label rows with nested attributes.

```python
from fastapi import FastAPI, Form, UploadFile, File
from fastapi.responses import JSONResponse
from typing import List

from encord_agents.agents.editor.object_classification.object_classification_agent import ObjectClassificationAgent
from encord_agents.utils import UserResponse

app = FastAPI()


@app.post("/object-classification/")
def classify_objects(
    label_row_id: str = Form(...),
    data_hash: str = Form(...),
    frame_index: int = Form(...),
    project_hash: str = Form(...),
    
):
    agent = ObjectClassificationAgent()
    response = agent.classify_objects(
        label_row_id=label_row_id,
        data_hash=data_hash,
        frame_index=frame_index,
        project_hash=project_hash,
    )
    return JSONResponse(content=response.dict())


```

--------------------------------

### Importing Modules in Python

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/mask_rcnn_on_videos.ipynb

This Python snippet shows how to import external modules to extend functionality. The example imports the 'math' module, which provides access to mathematical functions.

```python
import math

print(math.sqrt(16))
```

--------------------------------

### Shell Command to Test Local Encord Agent

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

This command tests a locally run Encord agent by providing a URL to a specific frame or object within an Encord project. Ensure your virtual environment is sourced before running this command.

```shell
source venv/bin/activate
encord-agents test local my_agent '<your_url>'
```

--------------------------------

### Debug Agent with Functions Framework

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

This shell command allows you to run the Python agent in debug mode using the functions-framework. You need to specify the target function, enable debug mode, and provide the source file.

```shell
functions-framework --target=handle_object_hashes --debug --source agent.py
```

--------------------------------

### Perform Inference with a Custom Model

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/sentiment_analysis.ipynb

This example shows how to load a custom model and perform inference on input data. It involves initializing the model and then calling its prediction method. Dependencies include the 'torch' library.

```python
import torch

# Assume 'CustomModel' is a defined PyTorch model class
# from your_model_module import CustomModel 

# Placeholder for model loading (replace with actual model loading logic)
# model = CustomModel()
# model.load_state_dict(torch.load('custom_model.pth'))
# model.eval()

# Placeholder for input data (replace with actual data)
# input_data = torch.randn(1, 3, 224, 224) 

# with torch.no_grad():
#     output = model(input_data)
# print(output)
```

--------------------------------

### Define a FastAPI Agent for Encord

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/fastapi.md

A Python script defining a FastAPI application that acts as an Encord agent. It sets up an endpoint '/my_agent' that accepts FrameData and LabelRowV2 dependencies, processes them, and returns an EditorAgentResponse.

```python
from typing_extensions import Annotated

from encord.objects.ontology_labels_impl import LabelRowV2
from encord_agents import FrameData
from encord_agents.core.data_model import EditorAgentResponse
from encord_agents.fastapi import dep_label_row
from encord_agents.fastapi.cors import get_encord_app

from fastapi import FastAPI, Depends, Form

app = get_encord_app()


@app.post("/my_agent")
def my_agent(
    frame_data: FrameData,
    label_row: Annotated[LabelRowV2, Depends(dep_label_row)],
) -> EditorAgentResponse:
    # ... Do your edits to the labels
    label_row.save()
    # Return an EditorAgentResponse to display a message to the user
    return EditorAgentResponse(message="Done")
```

--------------------------------

### Full Agent Code for GCP Object Classification

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

This is the complete Python code for the GCP Object Classification agent. It includes all necessary imports and function definitions to perform object classification tasks within the Encord platform.

```python
#codeinclude
[agent.py](../../code_examples/gcp/gcp_object_classification.py) linenums:1
#/codeinclude
```

--------------------------------

### Injecting Twin Project Labels and Video Frames

Source: https://github.com/encord-team/encord-agents/blob/main/docs/task_agents/runner_intro.md

This example demonstrates dependency injection using `encord_agents.tasks.Depends` to access data from a 'twin' project and iterate over video frames. It requires importing `Annotated`, `AgentStage`, `Depends`, `Twin`, `dep_twin_label_row`, and `dep_video_iterator`.

```python
from typing_extensions import Annotated
from encord.workflow.stages.agent import AgentTask
from encord.objects import LabelRowV2, Frame
from encord_agents.tasks import Depends
from encord_agents.tasks.dependencies import (
    Twin,
    dep_twin_label_row,
    dep_video_iterator
)
from encord_agents.runner import runner

@runner.stage("my_stage")
def my_agent(
    task: AgentTask,
    lr: LabelRowV2,
    twin: Annotated[Twin, Depends(dep_twin_label_row(twin_project_hash="..."))],
    frames: Annotated[Iterator[Frame], Depends(dep_video_iterator)]
) -> str:
    # Use the dependencies
    pass
```

--------------------------------

### Python: Simulate Agent Initialization and Agent Run

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/sentiment_analysis.ipynb

This snippet demonstrates the simulation of an agent's initialization and execution within the Encord Agents framework. It shows how to set up an agent and run its core logic, likely involving data processing or interaction with Encord platform features. It relies on the Encord Agents library.

```python
from encord_agent.agents.agent import Agent
from encord_agent.agents.utils import load_agent_config

async def simulate_agent_run():
    """Simulates agent initialization and run."""
    config = load_agent_config()
    agent = Agent(config=config)

    # Simulate agent initialization
    await agent.init_agent()

    # Simulate agent run (e.g., processing a task)
    # Replace 'process_task' with the actual method to run the agent's logic
    # For demonstration, we'll just print a message.
    print("Simulating agent run...")
    # await agent.process_task(...) # Example: if agent has a task processing method

    print("Agent simulation complete.")

if __name__ == "__main__":
    import asyncio
    asyncio.run(simulate_agent_run())

```

--------------------------------

### Python Agent Communication Example

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/hugging_face_agent_example.ipynb

Shows how different agents might communicate or how an agent interacts with the Encord platform's services. This could involve sending results, requesting information, or triggering actions.

```python
from encord.agents import EncordAgent
from encord.agents.communication import Message, Channel

# Assume 'agent_a' and 'agent_b' are initialized agents
agent_a = EncordAgent(model_name="sender_agent")
agent_b = EncordAgent(model_name="receiver_agent")

# Define a message to send
message_content = {"task": "analyze_image", "image_id": "img_123"}
message = Message(payload=message_content, sender="agent_a")

# Send the message to agent_b via a specific channel
agent_a.send_message(message, channel=Channel.AGENT_B)

# Agent B might receive and process the message
# agent_b.on_message(message) # This would be part of agent_b's logic
```

--------------------------------

### Python Data Processing Example

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/sentiment_analysis.ipynb

Demonstrates basic data processing techniques in Python, potentially for agent input or output handling. This snippet might be used for preparing data structures or performing initial validation before further processing.

```python
def process_data(data):
    # Placeholder for data processing logic
    processed_data = data.upper()  # Example: convert to uppercase
    return processed_data

input_data = "sample data"
output_data = process_data(input_data)
print(f"Processed data: {output_data}")
```

--------------------------------

### Full Agent Code for Frame Classification

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

The complete Python script for the 'agent.py' file. This agent uses Claude 3.5 Sonnet to analyze frame content and apply nested classifications based on a defined ontology.

```python
# This is a placeholder for the actual code from the linked file.
# The code will contain logic for:
# 1. Retrieving frame content using 'dep_single_frame'.
# 2. Sending frame image to Claude for analysis.
# 3. Parsing Claude's response into classification instances.
# 4. Adding classifications to the label row and saving results.
pass
```

--------------------------------

### GCP Video Re-captioning Agent

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

This agent retrieves existing captions, sends the first frame and caption to an LLM for rephrasing, and updates the label row with the new captions. It demonstrates a practical application of Encord Agents for enhancing video metadata.

```APIDOC
## GET /recaption_video

### Description
Retrieves existing human-created captions, sends the first frame of the video along with the human caption to the LLM for rephrasing, and updates the label row with the new captions.

### Method
POST

### Endpoint
/recaption_video

### Parameters
#### Query Parameters
- **frame_url** (string) - Required - The URL of the video frame to process.

### Request Example
```json
{
  "frame_url": "https://app.encord.com/label_editor/project_hash/data_hash/frame_number"
}
```

### Response
#### Success Response (200)
- **message** (string) - A success message indicating the captions have been updated.

#### Response Example
```json
{
  "message": "Captions rephrased and updated successfully."
}
```
```

--------------------------------

### Agent Initialization and Execution

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/sentiment_analysis.ipynb

This section showcases code for initializing and executing agents within the project. It covers setting up agent configurations and running agent tasks.

```python
from encord.agents import Agent

def initialize_and_run_agent(config):
    """Initializes an agent with given config and runs it."""
    agent = Agent(config)
    agent.run()
    return agent
```

--------------------------------

### Dockerfile for Encord Agent Lambda

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/aws_lambda.md

This Dockerfile sets up a Python 3.12 Lambda environment. It installs project dependencies from `requirements.txt` and copies the agent's Python code (`lambda_function.py`) into the build context. The CMD instruction specifies the entry point for the Lambda handler.

```dockerfile
FROM public.ecr.aws/lambda/python:3.12

# Install the specified packages
COPY requirements.txt ${LAMBDA_TASK_ROOT}
RUN pip install -r requirements.txt

# Copy function code
COPY lambda_function.py ${LAMBDA_TASK_ROOT}

# Set the CMD to your handler 
# (could also be done as a parameter override outside of the Dockerfile)
CMD [ "lambda_function.lambda_handler" ]
```

--------------------------------

### Deploy Agent to Google Cloud Functions

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/gcp.md

Deploys the Encord agent as a Google Cloud Function using the `gcloud` CLI. This example specifies the entry point, runtime, trigger type, and secret configuration for the SSH key.

```shell
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"
```

--------------------------------

### Manage Agent Dependencies in Python

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/yolo_example.ipynb

Provides functions to manage agent dependencies, such as installing required libraries or checking for their presence. This ensures the agent can run in different environments without setup issues.

```python
import subprocess
import sys

def install_package(package_name: str):
    """Installs a Python package using pip.

    Args:
        package_name (str): The name of the package to install.
    """
    try:
        subprocess.check_call([sys.executable, "-m", "pip", "install", package_name])
        print(f"Successfully installed {package_name}")
    except subprocess.CalledProcessError as e:
        print(f"Failed to install {package_name}: {e}")

def check_dependency(package_name: str) -> bool:
    """Checks if a Python package is installed.

    Args:
        package_name (str): The name of the package to check.

    Returns:
        bool: True if the package is installed, False otherwise.
    """
    try:
        subprocess.check_call([sys.executable, "-c", f"import {package_name}"])
        return True
    except subprocess.CalledProcessError:
        return False

# Example Usage:
# if not check_dependency('numpy'):
#     install_package('numpy')
```

--------------------------------

### Set up Environment Variables for Encord

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/hugging_face_agent_example.ipynb

Explains how to set up necessary environment variables, such as the Encord API key, for the project to function correctly.

```shell
# Set your Encord API key as an environment variable
export ENCORD_API_KEY='YOUR_API_KEY_HERE'

# Optionally, set the API endpoint if not using the default
# export ENCORD_API_URL='YOUR_API_URL_HERE'
```

--------------------------------

### Generate Encord Ontology for Video Recaptioning

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

Creates a Python script to define an Encord ontology structure for video captioning. It includes a primary 'Caption' text attribute and three 'Caption Rephrased' text attributes for LLM-generated variations. The script also shows how to optionally create this ontology within the Encord platform.

```python
import json
from encord.objects.ontology_structure import OntologyStructure
from encord.objects.attributes import TextAttribute

structure = OntologyStructure()
caption = structure.add_classification()
caption.add_attribute(TextAttribute, "Caption")
re1 = structure.add_classification()
re1.add_attribute(TextAttribute, "Recaption 1")
re2 = structure.add_classification()
re2.add_attribute(TextAttribute, "Recaption 2")
re3 = structure.add_classification()
re3.add_attribute(TextAttribute, "Recaption 3")

print(json.dumps(structure.to_dict(), indent=2))

create_ontology = False
if create_ontology:
    from encord.user_client import EncordUserClient
    client = EncordUserClient.create_with_ssh_private_key()  # Look in auth section for authentication
    client.create_ontology("title", "description", structure)
```

--------------------------------

### Python Agent Interaction Example

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/sentiment_analysis.ipynb

Illustrates how an agent might interact with external systems or data sources in Python. This could involve making API calls, reading from files, or sending data to other services. Error handling and response parsing are common considerations.

```python
import requests

def call_agent_api(endpoint, payload):
    try:
        response = requests.post(f"https://api.encord.com/{endpoint}", json=payload)
        response.raise_for_status()  # Raise an exception for bad status codes
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error calling API: {e}")
        return None

agent_endpoint = "agents/v1/execute"
agent_payload = {"task": "analyze_image", "image_url": "http://example.com/image.jpg"}

result = call_agent_api(agent_endpoint, agent_payload)
if result:
    print("Agent API call successful:", result)
```

--------------------------------

### Create a New Project in Encord

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/hugging_face_agent_example.ipynb

Demonstrates how to create a new project within the Encord platform using the SDK. Requires a client instance and a project name.

```python
from encord import EncordClient

def create_encord_project(client: EncordClient, project_name: str):
    """Creates a new Encord project."""
    project = client.create_project(project_name=project_name)
    return project
```

--------------------------------

### FastAPI Video Caption Rephrasing Agent

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

This agent rephrases existing video captions using an LLM. It retrieves the current or first frame caption, sends it along with the frame to the LLM, and updates the label row with the LLM's response. Dependencies include FastAPI and OpenAI.

```python
from fastapi import FastAPI, Request
from urllib.parse import urlparse

import encord_agent
from encord_agent.utils import user_data

app = FastAPI()


@app.post("/add-caption")
async def add_caption(request: Request):
    """Add captions to the video
    """
    payload = await request.json()
    video_hash = payload["video_hash"]
    frame_url = payload["frame_url"]
    caption = payload["caption"]

    data = {
        "video_hash": video_hash,
        "frame_url": frame_url,
        "caption": caption,
    }

    return encord_agent.EncordAgent(user_data.get_user_data()).dispatch(
        "fastapi_recaption_video", data
    )

```

--------------------------------

### Execute Encord Runner via CLI using example.py

Source: https://github.com/encord-team/encord-agents/blob/main/docs/task_agents/sequential_runner.md

Demonstrates running the Encord Runner from the command line using a Python script. The script must define a `Runner` instance and call `runner.run()` within the `if __name__ == "__main__":` block. The CLI accepts various arguments to control runner behavior.

```python
from encord_agents.runner import Runner

runner = Runner()

if __name__ == "__main__":
    runner.run()
```

--------------------------------

### Test Agent Locally (Shell)

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/modal.md

This command serves the Python agent file locally using the Modal CLI, making it accessible via a web URL for testing. It requires the agent script to be saved as 'example.py'.

```shell
modal serve example.py
```

--------------------------------

### Run Encord Agent as CLI (Python)

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/prelabel_videos_with_bounding_boxes.ipynb

This snippet shows how to modify an Encord Agent's Python code to be executable from the command line. It involves saving the code to a file (e.g., 'agents.py') and changing the entry point to `runner.run()`. This allows for command-line arguments to be passed, such as the project hash.

```python
import runner

if __name__ == "__main__":
    runner.run()
```

--------------------------------

### Import Necessary Libraries (Python)

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/recaption_video.ipynb

Imports core libraries and modules required for the Encord Agents workflow, including os, typing, numpy, Encord's LabelRowV2, Langchain's ChatOpenAI, Pydantic's BaseModel, and Encord Agents' Runner and dependencies.

```python
```python
import os
from typing import Annotated

import numpy as np
from encord.objects.ontology_labels_impl import LabelRowV2
from langchain_openai import ChatOpenAI
from pydantic import BaseModel

from encord_agents.tasks import Runner
from encord_agents.tasks.dependencies import Frame, dep_single_frame
```
```

--------------------------------

### Initialize an Encord Client

Source: https://github.com/encord-team/encord-agents/blob/main/docs/notebooks/hugging_face_agent_example.ipynb

Provides a code snippet for initializing a client to interact with the Encord platform. Requires an API key or other authentication credentials.

```python
from encord import EncordClient

def get_encord_client(api_key):
    """Initializes and returns an EncordClient."""
    return EncordClient(api_key)
```

--------------------------------

### Run Detr Video Labeling Container

Source: https://github.com/encord-team/encord-agents/blob/main/docker/detr-video-labeling/README.md

Executes the Detr Video Labeling Container using Docker. Requires an Encord SSH key and a project hash. This command initiates the video labeling process.

```bash
docker run -e ENCORD_SSH_KEY encord/encord-agent-detr-video-labeling:latest --project-hash=your-project-hash
```

--------------------------------

### Encord Runner CLI Arguments Help

Source: https://github.com/encord-team/encord-agents/blob/main/docs/task_agents/sequential_runner.md

Displays the help message for the Encord Runner CLI, outlining available options and their descriptions. This includes parameters for controlling refresh intervals, retries, task batch size, and project hash.

```shell
$ python example.py --help
```

--------------------------------

### Ontology JSON Structure for Nested Attributes

Source: https://github.com/encord-team/encord-agents/blob/main/docs/editor_agents/examples/index.md

Example JSON defining an Encord ontology with objects ('person', 'animal', 'vehicle') and their associated nested attributes like 'activity' (text), 'type' (radio with options), and 'description' (text), 'visible' (checklist with options).

```json
{
  "objects": [
    {
      "id": "1",
      "name": "person",
      "color": "#D33115",
      "shape": "bounding_box",
      "featureNodeHash": "2xlDPPAG",
      "required": false,
      "attributes": [
        {
          "id": "1.1",
          "featureNodeHash": "aFCN9MMm",
          "type": "text",
          "name": "activity",
          "required": false,
          "dynamic": false
        }
      ]
    },
    {
      "id": "2",
      "name": "animal",
      "color": "#E27300",
      "shape": "bounding_box",
      "featureNodeHash": "3y6JxTUX",
      "required": false,
      "attributes": [
        {
          "id": "2.1",
          "featureNodeHash": "2P7LTUZA",
          "type": "radio",
          "name": "type",
          "required": false,
          "options": [
            {
              "id": "2.1.1",
              "featureNodeHash": "gJvcEeLl",
              "label": "dolphin",
              "value": "dolphin",
              "options": []
            },
            {
              "id": "2.1.2",
              "featureNodeHash": "CxrftGS4",
              "label": "monkey",
              "value": "monkey",
              "options": []
            },
            {
              "id": "2.1.3",
              "featureNodeHash": "OQyWm7Sm",
              "label": "dog",
              "value": "dog",
              "options": []
            },
            {
              "id": "2.1.4",
              "featureNodeHash": "CDKmYJK/",
              "label": "cat",
              "value": "cat",
              "options": []
            }
          ],
          "dynamic": false
        },
        {
          "id": "2.2",
          "featureNodeHash": "5fFgrM+E",
          "type": "text",
          "name": "description",
          "required": false,
          "dynamic": false
        }
      ]
    },
    {
      "id": "3",
      "name": "vehicle",
      "color": "#16406C",
      "shape": "bounding_box",
      "featureNodeHash": "llw7qdWW",
      "required": false,
      "attributes": [
        {
          "id": "3.1",
          "featureNodeHash": "79mo1G7Q",
          "type": "text",
          "name": "type - short and concise",
          "required": false,
          "dynamic": false
        },
        {
          "id": "3.2",
          "featureNodeHash": "OFrk07Ds",
          "type": "checklist",
          "name": "visible",
          "required": false,
          "options": [
            {
              "id": "3.2.1",
              "featureNodeHash": "KmX/HjRT",
              "label": "wheels",
              "value": "wheels"
            },
            {
              "id": "3.2.2",
              "featureNodeHash": "H6qbEcdj",
              "label": "frame",
              "value": "frame"
            }
          ]
        }
      ]
    }
  ]
}
```