Build Your First Governed Agent

This tutorial builds a CFO Agent that checks wallet balances and reports on spending. You will create the agent, attach a spending policy, run it, read the audit trail, and clean up.

Prerequisites

• valta-sdk installed (npm install valta-sdk)
• VALTA_API_KEY set in your environment

Complete working example

import { ValtaClient } from 'valta-sdk'

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

async function main() {
  // 1. Create the agent
  const agent = await valta.agents.create({
    name: 'CFO Agent',
    description: 'Monitors wallet balances and reports on spending anomalies',
  })
  console.log(`✓ Agent created: ${agent.id}`)

  // 2. Set a spending policy
  await valta.policies.create({
    agentId: agent.id,
    dailyLimit: 100,
    maxPerTransaction: 25,
    requireApprovalAbove: 50,
    blockedCategories: ['gambling', 'adult'],
  })
  console.log('✓ Policy set')

  // 3. Check the wallet
  const wallet = await valta.wallets.get(agent.id)
  console.log(`✓ Wallet: ${wallet.balance} ${wallet.currency}`)

  // 4. Run the agent
  const run = await valta.agents.run(agent.id, {
    task: 'Check the current wallet balance and write a one-sentence summary of the financial position.',
  })

  if (run.status === 'completed') {
    console.log(`✓ Run completed in ${run.durationMs}ms`)
    console.log(`  Output: ${run.summary}`)
  } else if (run.status === 'failed') {
    console.log(`✗ Run failed: ${run.error}`)
  } else if (run.status === 'waiting_approval') {
    console.log('! Approval required before agent can continue')
    // Approve or deny via dashboard or API
  }

  // 5. Read the audit trail
  const { data: entries } = await valta.audit.list({ agentId: agent.id })
  console.log(`✓ Audit trail: ${entries.length} entries`)
  for (const entry of entries.slice(0, 3)) {
    console.log(`  ${new Date(entry.createdAt).toLocaleTimeString()} — ${entry.action}`)
  }

  // 6. Clean up (optional)
  await valta.agents.delete(agent.id)
  console.log('✓ Agent deleted')
}

main().catch(console.error)

What each step does

Step 1 — Create the agent. Valta allocates an isolated USDC wallet and returns an agent ID. The agent is active and ready to receive a policy.

Step 2 — Set a spending policy. The policy is stored in the Valta backend, not in a prompt. The agent cannot spend more than $25 in a single transaction or $100 in a day. Any action above $50 pauses and waits for your explicit approval.

Step 3 — Check the wallet. The wallet starts with a zero balance. You can fund it via the dashboard or the deposits API. The CFO Agent can report on whatever balance is present.

Step 4 — Run the agent. Valta runs the agent, enforces the policy on every attempted action, and returns a result. The status field will be one of completed, failed, or waiting_approval.

Step 5 — Read the audit trail. Every run, tool call, policy check, and blocked action is recorded in the hash-chained audit trail. The entries you see here are the raw evidence of what the agent did.

Step 6 — Clean up. Deleting the agent removes it from your account but does not erase the audit trail. Audit records are retained according to your plan's retention policy.

Expected output

What the audit trail contains

Each entry includes an action string, a timestamp, the agent ID, and a hash linking it to the previous entry. The actions you will see from this tutorial:

• agent.created — wallet allocated
• policy.created — limits attached
• agent.run.started — run initiated
• policy.check.passed — spending check cleared
• agent.run.completed — run finished with output
• agent.deleted — agent removed from account