Docs

Valta Docs

Agents

What is an agent

A Valta agent is an AI entity with its own isolated wallet and spending policy. You create it, assign it a policy, fund its wallet, and give it tasks.

Key properties:

  • Isolated wallet — each agent has its own USDC balance. One agent cannot access another agent's funds.
  • 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.

Agent status

StatusDescription
activeAgent is running normally. It can receive tasks and execute financial actions within its policy.
frozenAll financial motion is stopped immediately. The agent cannot spend, transfer, or be run until unfrozen.
inactiveAgent has been soft-deleted or deactivated. Cannot be run.

Creating an agent

ts
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.

ts
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

StatusDescription
runningRun is in progress.
completedRun finished successfully. All actions were within policy.
failedRun encountered an error (policy violation, insufficient funds, etc.). Check run.error.
waiting_approvalA 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.

ts
// 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

ts
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.

Next steps