Vertesia Documentation

Getting Started with Agent Runner

Try out the features of Agent Runner.

IMPORTANT: the feature is currently in version alpha as of 27 Jan, 2025. This feature may undergo changes in the future as we work to improve its functionality and user experience. We appreciate your understanding and welcome your feedback to help us make it even better.

Introduction

Agent Runner is an automation solution that allows you to develop agentic workflows. It allows you to automate activities with large language models (LLMs), content resources, or external systems. You can develop custom logic to fit your business processes or organizational requirements.

This quickstart guide shows you how to initialize a new Agent Runner project in Typescript and run it locally. Then, it explains the file structure and shows you how to develop your first workflows.

Prerequisites

Before getting started, you need to have the following tools installed on your desktop and some additional tasks to perform:

  1. node — You need to have Node.js 22 version for writing workflows. Newer versions are not officially supported yet.
  2. vertesia — You need to install Vertesia CLI, which is used to initialize the agent as an NPM project.
  3. Vertesia Project — You need to have a valid account in Vertesia. The NPM project relies on Vertesia Secure Token Service (STS) to interact with private resources. If you don't have an account, you can go to https://cloud.vertesia.io/ and sign up for a new account. This will also give you access to the Agent Runner SDK because it is reserved for registered users.
  4. gcloud — You need to install the Google Cloud CLI locally to fetch the mTLS certificates for connecting to Temporal Cloud.
  5. temporal — You need to install the Temporal CLI locally to test the workflow executions.
  6. docker — You need to install Docker Desktop and have the docker CLI exported to your terminal

Set up Vertesia CLI

You need to install and set up vertesia CLI before using creating the project.

npm install -g @vertesia/cli

Create a new profile using the staging environment. As of 27 Jan 2025, agent can only be used in the staging environment. It is not available in preview or production yet.

vertesia profiles create

Initialize An Agent Project

Create a new directory, e.g. test-agent:

# Replace it with you project name
project="test-agent"

mkdir "$project"
cd "$project"

Run the following command to initialize a new NPM project:

npm init @vertesia/agent

Follow the instructions on the screen to choose the package manager (npm, yarn, pnpm), the package version, etc. You also need to define an organization and an agent name. The organization must be unique inside Vertesia and is usually the name of your Vertesia account. The agent name identifies the project in your account.

The generated project is a Typescript project and uses Temporal as the workflow system.

File Structure

The most important files inside the project are workflows.ts and activities.ts. They represent respectively the workflows and the functions to be executed inside the workflows.

src
├── activities.ts
├── debug-replayer.ts
├── main.ts
└── workflows.ts

1 directory, 4 files

For now, the agent only contains a simple workflow called helloWorkflow:

import * as activities from "./activities.js";

// ...

export async function helloWorkflow() {
    log.info("Entering Hello workflow");
    await helloActivity();
}

Start The Agent

Now, you can install the dependencies and build the source code:

pnpm install
pnpm run build

Then, you need to connect to Google Cloud using the Google Cloud SDK. It is necessary for fetching the mTLS certificates for connecting to Temporal Cloud

gcloud auth application-default login

Start the agent:

npm start

Now, your agent is up and running locally. You can see it from the logs:

[18:08:31.107] INFO (llm-studio/92672): Worker created with options:
    options: {
      "taskQueue": "agents/vertesia/vertesia-agent/desktop-agent-vertesia_vertesia-agent",
      "debugMode": true,
      "activities": {},
      "workflowBundle": {
        "codePath": "/Users/xxx/github/vertesia/vertesia-agent/lib/workflows-bundle.js"
      },
      "connection": {
        "nativeClient": {},
        "referenceHolders": {}
      },
      "namespace": "dev.i16ci"
    }

Since the agent is running, you can start a new workflow to test whether it is working correctly.

Start a New Workflow

Configure the Temporal CLI

export "TEMPORAL_NAMESPACE=dev.i16ci"
export "TEMPORAL_ADDRESS=dev.i16ci.tmprl.cloud:7233"
export "TEMPORAL_TLS_CERT=/tmp/tmprl_dev_zeno-worker_crt.pem"
export "TEMPORAL_TLS_KEY=/tmp/tmprl_dev_zeno-worker_key.pem"

Start a new workflow using the temporal CLI:

# replace by your organization name
org="vertesia"
# replace by your agent name
agent="test-gent"

temporal workflow start \
    -t "agents/${org}/${agent}/desktop-agent-${org}_${agent}" \
    --type helloWorkflow \
    -w hello-world
# Running execution:
#   WorkflowId  hello-world
#   RunId       0a931e37-f55b-4740-bd99-fb8412be7604
#   Type        helloWorkflow
#   Namespace   dev.i16ci
#   TaskQueue   agents/vertesia/vertesia-agent/desktop-agent-vertesia_vertesia-agent

This workflow request will be handled by your agent running locally.

temporal workflow result --workflow-id hello-world
# Results:
#   Status          COMPLETED
#   Result          {"metadata":{"encoding":"YmluYXJ5L251bGw="}}
#   ResultEncoding  binary/null

Developping New Workflows

You can develop new workflows and activities in the files workflows.ts and activities.ts, but you can also develop them in other files inside the src directory. What matter to us is that your workflow definitions must be exported to the workflows.ts and your activities must be exported to the activities.ts. They are essential for making the workflow bundle and registering the activities to the Agent Runner at run time.

A workflow is a Typescript function, it contains an optional input, an optional output, and a required function name. The input corresponds to the workflow request, and the output corresponds to the workflow response. Since a workflow may not have any input or output structure, they are optional. However, the function name is required because it corresponds to the workflow type in Temporal (or command line option --type in the commands temporal workflow <sub-command>). We recommand you to write your workflow in the following style:

  • Use camel-case for workflow name (function)
  • Use title-case for the request and the response, where the prefix of the types match the workflow name, so that it's easier to understand which workflow these types belong to

Here is an example for the workflow getRepos and its corresponding types GetReposRequest and GetReposResponse:

// file: src/workflows.ts

export type GetReposRequest = {
    names: string[];
}

export type GetReposResponse = {
    count: number;
    repos: activities.GetRepoResponse[];
}

export async function getRepos(request: GetReposRequest): Promise<GetReposResponse> {
    const responses = await Promise.all(request.names.map((name) => getRepoInfo({name})));

    return {
        count: responses.length,
        repos: responses,
    } as GetReposResponse;
}

Once done, you can compile and start the agent again. Then, you can test the new workflow with the temporal CLI.

Next Steps

Now you have learned the basics of Agent Runner, you can continue to read the following pages to learn more about different advanced topics:

Was this page helpful?