---
title: "SDK Integration"
source: "https://docs.vertesiahq.com/agent-runner/sdk"
markdown: "https://docs.vertesiahq.com/llms/agent-runner/sdk.md"
---

# 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](/quickstart#vertesia-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.

```js
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.

```js
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.

```js
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.

```js
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:

```js
// 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](/api/agents)
- A simple agent cli example is available on [GitHub](https://github.com/vertesia/examples/tree/main/agent-cli)