Agent Runs

The Agent Runs API is the canonical way to start and manage conversation agents. Each agent run gets a stable identity (MongoDB document) with its own ID, lifecycle tracking, artifact storage, and Elasticsearch indexing.

For non-conversation asynchronous interaction execution (webhooks, batch processing), continue using the /execute/async endpoint.

Base path: /api/v1/agents

Create Agent Run

Creates a new agent run and starts a conversation workflow.

Endpoint: /agents

Method: POST

Requirements: User must have workflow:run permission.

Headers

Input Parameters

Example Request

{
  "interaction": "MyAgent",
  "data": {
    "task": "Analyze the Q4 report"
  },
  "environment": "<ENVIRONMENT_ID>",
  "model": "<MODEL_ID>",
  "interactive": true,
  "tags": ["analysis"]
}

Example Response

{
  "id": "6801a3f2e4b0d1234abcdef0",
  "account": "...",
  "project": "...",
  "interaction": "MyAgent",
  "data": { "task": "Analyze the Q4 report" },
  "environment": "default",
  "model": "claude-sonnet-4-6",
  "interactive": true,
  "status": "running",
  "started_at": "2025-04-17T10:30:00.000Z",
  "started_by": "user:abc123",
  "tags": ["analysis"],
  "visibility": "project",
  "created_at": "2025-04-17T10:30:00.000Z",
  "updated_at": "2025-04-17T10:30:00.000Z"
}

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "interaction": "MyAgent",
    "data": { "task": "Analyze the Q4 report" },
    "environment": "<ENVIRONMENT_ID>",
    "model": "<MODEL_ID>",
    "interactive": true
  }'

Retrieve Agent Run

Get an agent run by its stable ID.

Endpoint: /agents/:agentRunId

Method: GET

Requirements: User must have workflow:run permission. Private runs are only visible to the owner or superadmin.

Code Example

const run = await client.store.agents.retrieve('6801a3f2e4b0d1234abcdef0');
console.log(run.status); // 'running' | 'completed' | 'failed' | 'cancelled'

List Agent Runs

List agent runs with optional filters.

Endpoint: /agents

Method: GET

Query Parameters

Code Example

const runs = await client.store.agents.list({
  status: 'running',
  limit: 10,
});

Terminate Agent Run

Cancel a running agent.

Endpoint: /agents/:agentRunId

Method: DELETE

Code Example

await client.store.agents.terminate('6801a3f2e4b0d1234abcdef0', 'No longer needed');

Restart Agent Run

Restart a completed, failed, or cancelled agent run. This continues the same AgentRun — a new workflow is started that loads the conversation history from where it left off.

Endpoint: /agents/:agentRunId/restart

Method: POST

Code Example

const run = await client.store.agents.restart('6801a3f2e4b0d1234abcdef0');
// Same run.id, status back to 'running'

Fork Agent Run

Fork a conversation into a new agent run. The new run loads conversation history from the source but has its own identity, stream, and artifacts.

Endpoint: /agents/:agentRunId/fork

Method: POST

Code Example

const forked = await client.store.agents.fork('6801a3f2e4b0d1234abcdef0');
console.log(forked.id); // new AgentRun ID

Send Signal

Send a signal to a running agent. Common signals: UserInput, Stop, FileUploaded.

Endpoint: /agents/:agentRunId/signal/:signalName

Method: POST

Code Example

await client.store.agents.sendSignal('6801a3f2e4b0d1234abcdef0', 'UserInput', {
  message: 'Please also include a summary',
});

Query Agent State

Query a running agent's state. Common queries: ActiveWorkstreams, AgentPlan, AvailableTools.

Endpoint: /agents/:agentRunId/query/:queryName

Method: GET

Code Example

const workstreams = await client.store.agents.getActiveWorkstreams('6801a3f2e4b0d1234abcdef0');

Stream Messages

Stream real-time messages from an agent run via SSE. The SDK handles historical message fetch followed by SSE connection automatically.

Endpoint: /agents/:agentRunId/stream

Method: GET (SSE)

Code Example

await client.store.agents.streamMessages(
  '6801a3f2e4b0d1234abcdef0',
  (message) => {
    console.log(`[${message.type}] ${message.message}`);
  },
);

Retrieve Messages

Get stored messages for an agent run.

Endpoint: /agents/:agentRunId/updates

Method: GET

Code Example

const messages = await client.store.agents.retrieveMessages('6801a3f2e4b0d1234abcdef0');

Artifacts

Agent runs have dedicated artifact storage for files produced during execution.

List Artifacts

Endpoint: /agents/:agentRunId/artifacts Method: GET

Get Artifact

Endpoint: /agents/:agentRunId/artifacts/:path Method: GET Use ?url=1 to get a signed download URL instead of streaming content.

Upload Artifact

Endpoint: /agents/:agentRunId/artifacts/:path Method: PUT

Code Examples

// List artifacts
const files = await client.store.agents.listArtifacts(run.id);

// Get download URL
const { url } = await client.store.agents.getArtifactUrl(run.id, 'report.pdf', 'inline');

// Upload
await client.store.agents.uploadArtifact(run.id, 'data.csv', csvBlob, 'text/csv');

// Download
const stream = await client.store.agents.downloadArtifact(run.id, 'report.pdf');

AgentRun Object

The AgentRun object returned by all endpoints: