Agents & runs

veroai.agents manages agent configuration, workspace files, and triggers. veroai.agents.runs inspects and streams execution.

Create

typescript
const agent = await veroai.agents.create({
  displayName:  "Research Planner",
  roleId:       "planner",
  model:        "claude-sonnet-4-20250514",
  systemPrompt: "You coordinate a team of research agents.",
  autoTrigger:  true,
  voiceId:      "nova",
  language:     "en",
});

List, get, update, delete

typescript
const { agents } = await veroai.agents.list({ status: "active" });

const one = await veroai.agents.get(agent.id);

await veroai.agents.update(agent.id, {
  systemPrompt: "Updated system prompt.",
});

await veroai.agents.delete(agent.id);

Workspace files

Each agent has a workspace of markdown files (SOUL.md, IDENTITY.md, AGENTS.md, TOOLS.md, HEARTBEAT.md) that shape its personality and tool surface.

typescript
const { files } = await veroai.agents.listFiles(agent.id);

const { content } = await veroai.agents.getFile(agent.id, "SOUL.md");

await veroai.agents.updateFile(
  agent.id,
  "SOUL.md",
  "## Role\nYou are calm, precise, and honest about uncertainty.",
);

Trigger a run

typescript
const { runId, status } = await veroai.agents.trigger(agent.id, {
  conversationId: "call_8291",
  senderId:       "david-cohen",
  message:        "Explain my denied claim",
});
// status is always "accepted" — the run executes on a FIFO session lane.

Stream run events

veroai.agents.runs.stream(runId) is an async iterator over SSE events. Cancel by aborting a controller.

typescript
const controller = new AbortController();
setTimeout(() => controller.abort(), 30_000); // 30 s cap

for await (const ev of veroai.agents.runs.stream(runId, { signal: controller.signal })) {
  switch (ev.type) {
    case "turn_start": console.error("turn", ev.data.turn); break;
    case "token":      process.stdout.write(String(ev.data.text)); break;
    case "tool_call":  console.error("→", ev.data.name, ev.data.args); break;
    case "tool_result":console.error("←", ev.data.result); break;
    case "message":    console.error("assistant:", ev.data.text); break;
    case "done":       return;
    case "error":      throw new Error(String(ev.data.message));
  }
}

List runs & cancel

typescript
const { runs } = await veroai.agents.runs.list({
  agentId: agent.id,
  status:  "running",
  limit:   20,
});

await veroai.agents.runs.cancel(runs[0].id);

Run statuses

  • queued — accepted, waiting on session lane
  • running — inside the LLM loop
  • idle — waiting on a brain callback
  • completed — terminal success
  • failed — terminal error (see run.error)
  • cancelled — cancelled by caller or max-turn limit