SDK Integration

In previous sections, we've seen how the Agent Runner provides an excellent environment for quickly experimenting with Agents in Studio. To seamlessly integrate Vertesia Agents into your business applications and workflows, Vertesia offers a comprehensive REST API and a robust TypeScript SDK.

This section will guide you through interacting with agents using the TypeScript SDK. No complex configuration is required to get started.

Client Initialization

First, you'll need to get an instance of the Vertesia client. Remember to replace apiKey with your actual API key.

import { VertesiaClient } from "@vertesia/client";
import { AgentMessageType } from "@vertesia/common";

const vertesia = new VertesiaClient({
  site: 'api.vertesia.io',
  apikey: '<YOUR_API_KEY>',
});

Initiating Agent Execution

Start an agent run using the store.agents.start() method. This creates a stable AgentRun with its own ID, lifecycle tracking, and artifact storage.

const task = `
Generate three lease agreement documents for commercial office space, each tailored to different specifications:

- A basic, cost-effective option suitable for approximately eight workstations.
- A mid-range option accommodating approximately twenty workstations, three meeting rooms, and two individual phone booths.
- A premium option located on the fortieth floor or above in an office building, designed to accommodate approximately fifty workstations, ten meeting rooms, and ten individual phone booths.

A lease agreement document must have the following metadata properties:
- space size in square feet
- term length
- monthly cost
- deposit amount
- state
- city
- address
- property manager

If a document type named  "Lease Agreement" doesn't already exit, create it with properties listed above

Subsequently, these documents should be organized and stored within a collection named "Office Leases."
`;

const run = await vertesia.store.agents.start({
  interaction: "MultipurposeAgent",
  data: {
    task: task
  },
  interactive: true,
});

console.log(run.id); // stable AgentRun ID

Streaming Agent Messages

You can then stream messages from the agent using the streamMessages function. This function uses the AgentRun ID returned in the previous step.

await vertesia.store.agents.streamMessages(run.id, (item) => {
  const { type, message } = item;
  const date = new Date(item.timestamp);
  console.log(`${date.toLocaleString()} - ${type}:\n${message}\n`);
});

The streamMessages function automatically stops when a message of type AgentMessageType.COMPLETE is received. This signals that the agent's current task is finished.

Sending Signals to the Agent

Finally, to send a message or "signal" to the agent, use the sendSignal function.

await vertesia.store.agents.sendSignal(run.id, "UserInput", {
  message: "create a spreadsheet with the agreement properties and add it to the collection",
});

In the current architecture, agents handle this kind of spreadsheet workflow by orchestrating skills together with the execute_shell and artifact tools, rather than using dedicated spreadsheet-specific built-in tools.

Managing Agent Lifecycle

The Agent Runs API also supports lifecycle operations:

// Retrieve the current state of an agent run
const current = await vertesia.store.agents.retrieve(run.id);
console.log(current.status); // 'running' | 'completed' | 'failed' | 'cancelled'

// Terminate a running agent
await vertesia.store.agents.terminate(run.id, 'No longer needed');

// Restart a completed/failed agent (continues the same conversation)
const restarted = await vertesia.store.agents.restart(run.id);

// Fork into a new agent run (new ID, loads history from source)
const forked = await vertesia.store.agents.fork(run.id);

Further Exploration

Full Agent Runs API reference
A simple agent cli example is available on GitHub