Build with
PV agents.

PV lets you hand complex, long-running work to autonomous AI agents. You describe the goal, choose what the agent is allowed to touch, and PV runs it on distributed infrastructure, streaming progress back to you and recording every action it takes.

This guide covers the core concepts and walks you through your first task. For every endpoint and field, see the API Reference.

API access is included in the PV Platform plan. Contact salesto set up your workspace; you'll receive an API key and the base URL for your account.

Store both as environment variables. The examples in these docs assume:

export PV_API_URL="<your base URL>"
export PV_API_KEY="<your API key>"

Keep your key secret. Never commit it to source control or expose it in client-side code.

• Agent: a reusable worker with instructions, a model, and a set of permissions. Create it once and give it many tasks.
• Task:a single job you assign to an agent, such as “reconcile last week’s invoices”. Tasks run asynchronously and move through queued, running, and finally succeeded, failed, or cancelled.
• Permissions: the integrations, data, and actions an agent may use. Agents can never act outside them.
• Events: a live stream of what an agent is doing while a task runs: its steps, tool calls, and output.
• Audit log: a permanent record of every action, for review and compliance.

1. Create an agent. Give it a name, instructions, and the permissions it needs.

curl "$PV_API_URL/agents" \
  -H "Authorization: Bearer $PV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "invoice-reconciler",
    "instructions": "Match incoming invoices to purchase orders and flag mismatches.",
    "model": "auto",
    "permissions": ["integrations:accounting:read", "files:write"]
  }'

2. Run a task. Send the agent a goal. The response includes the task ID.

curl "$PV_API_URL/tasks" \
  -H "Authorization: Bearer $PV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_123",
    "input": "Reconcile all invoices received last week."
  }'

3. Get the result. Poll the task, or stream its events as they happen (see Streaming results).

curl "$PV_API_URL/tasks/tsk_456" \
  -H "Authorization: Bearer $PV_API_KEY"

Any HTTP client works. Here is the same flow with fetch in TypeScript:

const api = process.env.PV_API_URL!;
const headers = {
  Authorization: `Bearer ${process.env.PV_API_KEY}`,
  "Content-Type": "application/json",
};

const task = await fetch(`${api}/tasks`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    agent_id: "agt_123",
    input: "Reconcile all invoices received last week.",
  }),
}).then((res) => res.json());

console.log(task.id, task.status); // "tsk_456", "queued"

Watch an agent work in real time by subscribing to a task's event stream. Events are sent as server-sent events until the task finishes.

curl -N "$PV_API_URL/tasks/tsk_456/events" \
  -H "Authorization: Bearer $PV_API_KEY"

event: step
data: {"type":"step","message":"Fetching invoices from accounting"}

event: completed
data: {"type":"completed","status":"succeeded"}

PV routes work across leading model providers, including OpenAI ChatGPT, Anthropic Claude, Mistral, and Llama. Set model to auto to let PV choose the best model for each step, or name a specific model to pin it.

Custom routing rules are available on request.

Agents follow the principle of least privilege: grant only the permissions a job needs. Each agent runs in its own isolated sandbox, and every action is written to the audit log.

Read more on our Security page.

Stuck on something? Check the API Reference, see the current system status, or contact our team.