VexaAgent · Overview

VexaAgent

VexaAgent is a production agent runtime built on ContextAPI, DataAPI, and Vexa-1. You describe a goal and provide tools — the agent plans, retrieves, composes, and verifies in a single loop.

How an agent runs

Every VexaAgent invocation follows a four-stage loop. The loop continues until the goal is satisfied or the budget is exhausted.

Run an agent

The simplest agent invocation: pass a goal, point at a tenant, and let the runtime decide which tools to call.

const run = await cosavu.agents.run({
  goal: "Draft a refund response for ticket #4821 citing our policy docs.",
  tenant: "my-org",
  maxSteps: 8,
})
 
console.log(run.output)
console.log(`Used ${run.toolCalls.length} tools in ${run.totalMs}ms`)

Custom tools

Define your own tools to give the agent access to your APIs, databases, or systems. Each tool is a typed function the agent can call:

import { defineTool } from "@cosavu/sdk"
 
const getTicket = defineTool({
  name: "get_ticket",
  description: "Fetch a customer support ticket by ID.",
  parameters: {
    ticketId: { type: "string", description: "Support ticket ID" },
  },
  handler: async ({ ticketId }) => {
    const res = await fetch(`https://my-app.com/api/tickets/${ticketId}`)
    return res.json()
  },
})
 
const run = await cosavu.agents.run({
  goal: "Summarise ticket #4821 in two sentences.",
  tools: [getTicket],
})

Streaming

Stream agent events as they happen — useful for surfacing progress to end users:

const stream = await cosavu.agents.stream({
  goal: "Research the latest Cosavu blog posts and summarise.",
  tenant: "my-org",
})
 
for await (const event of stream) {
  switch (event.type) {
    case "plan":      console.log("Plan:", event.steps); break
    case "tool_call": console.log("Calling:", event.tool); break
    case "token":     process.stdout.write(event.delta); break
    case "complete":  console.log("\nDone:", event.output); break
  }
}

Event types

Background mode

For long-running workflows, start an agent and receive a job ID. Poll status or subscribe to a webhook:

const job = await cosavu.agents.runAsync({
  goal: "Generate a competitive analysis report.",
  webhook: "https://my-app.com/cosavu/callback",
})
 
console.log(job.id) // "agt_a1b2c3..."