Valta Docs

Agents

What is an agent

A Valta agent is an AI entity with a scoped spending policy, and — for agents actually moving Valta-held money — its own isolated wallet. You create it, assign it a policy, and give it tasks; whether you also fund a wallet for it depends on which mode it runs in (see below).

Key properties:

Isolated wallet, in wallet mode — an agent moving real Valta-held money has its own USDC balance. One agent cannot access another agent's funds. An agent with no funded wallet can still exist and run — see Valta Cap for that case.
Scoped policy — spending rules apply to that agent only. Changing one agent's policy does not affect others.
Independent audit trail — every action the agent takes is logged under its own agentId.

Wallet mode vs. Cap mode

Every agent is in exactly one mode, set on its policy:

Wallet mode (the default) — the agent has a funded Valta wallet; real spend is governed by a Spending Policy and moves through POST /api/v1/spend.
Cap mode — no Valta wallet at all. The agent calls a paid provider (OpenAI, Anthropic, etc.) directly with its own key, and just checks in with Valta first via cap.allow() for a per-run/day/month ceiling. See Valta Cap for the full difference.

Agent status

Status	Description
`active`	Agent is running normally. It can receive tasks and execute financial actions within its policy.
`frozen`	All financial motion is stopped immediately. The agent cannot spend, transfer, or be run until unfrozen.
`inactive`	Agent has been soft-deleted or deactivated. Cannot be run.

Creating an agent

import { ValtaClient } from 'valta-sdk'

const valta = new ValtaClient({ apiKey: process.env.VALTA_API_KEY })

const agent = await valta.agents.create({
  name: 'Procurement Agent',
  description: 'Handles vendor API subscriptions for the engineering team.',
})

console.log(agent.id)     // ag_...
console.log(agent.status) // 'active'

Running an agent

Pass a task and optional context. Valta routes the task through the policy engine before any financial action executes.

const run = await valta.agents.run(agent.id, {
  task: 'Renew the SendGrid subscription for the marketing workspace.',
  context: 'Budget owner: Sarah Chen. Renewal is due today.',
})

console.log(run.status)      // 'completed' | 'failed' | 'waiting_approval'
console.log(run.summary)     // Human-readable summary of what the agent did
console.log(run.durationMs)  // How long the run took in milliseconds

Run status values

Status	Description
`running`	Run is in progress.
`completed`	Run finished successfully. All actions were within policy.
`failed`	Run encountered an error (policy violation, insufficient funds, etc.). Check `run.error`.
`waiting_approval`	A financial action exceeded the approval threshold. Run is paused pending human approval.

Kill switch

Freeze an agent immediately. All transactions stop. No new runs can start.

// Freeze — immediate, no transactions possible
await valta.agents.freeze(agent.id)
// { success: true, agentId: 'ag_...', status: 'frozen' }

// Unfreeze when ready
await valta.agents.unfreeze(agent.id)
// { success: true, agentId: 'ag_...', status: 'active' }

Freeze and unfreeze events are logged to the audit trail with the user ID that triggered them.

Listing agents

const { data, total, page } = await valta.agents.list({
  limit: 20,
  page: 1,
  status: 'active', // optional filter
})

for (const agent of data) {
  console.log(agent.id, agent.name, agent.status)
}

// Fetch the next page
const nextPage = await valta.agents.list({ limit: 20, page: 2 })

An agent cannot change its own policy or read the audit trail directly. Policy changes require a call from your server using your API key.