Valta Docs
Agents SDK
Base path: /agents on https://valta.co/api/v1.
valta.agents.create(params)
Creates a new agent with an isolated wallet.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Display name for the agent. |
description | string | no | Optional notes on what this agent does. |
Returns 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'
console.log(agent.createdAt) // ISO 8601 timestamp
Errors
400 INVALID_REQUEST—nameis missing.403 FORBIDDEN— account has reached the agent limit for its tier.
valta.agents.list(params?)
Returns a paginated list of agents on your account.
Parameters
| Field | Type | Description |
|---|---|---|
page | number | Page number, starting at 1. |
limit | number | Results per page. Maximum 100. |
status | string | Filter by status: active, frozen, or inactive. |
Returns PaginatedResponse<Agent>
const { data, total, page } = await valta.agents.list({
limit: 20,
page: 1,
status: 'active',
})
for (const agent of data) {
console.log(agent.id, agent.name, agent.status)
}
// Next page
const nextPage = await valta.agents.list({ limit: 20, page: 2 })
valta.agents.get(agentId)
Fetches a single agent by ID.
Returns Agent
Throws NOT_FOUND if the agent does not exist or is not owned by your account.
const agent = await valta.agents.get('ag_...')
console.log(agent.name, agent.status)
valta.agents.update(agentId, params)
Updates mutable fields on an agent.
Parameters
| Field | Type | Description |
|---|---|---|
name | string | New display name. |
description | string | Updated description. |
Returns Agent
const updated = await valta.agents.update(agent.id, {
name: 'Procurement Agent v2',
description: 'Extended to handle SaaS renewals and one-off API spend.',
})
valta.agents.delete(agentId)
Deletes an agent. The agent's audit trail is preserved after deletion — entries remain queryable by agentId.
Returns { success: true }
await valta.agents.delete(agent.id)
// { success: true }
valta.agents.run(agentId, params)
Starts a run on the agent. The task is routed through the policy engine before any financial action executes.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
task | string | yes | Natural language description of what the agent should do. |
context | string | no | Additional context passed to the agent (e.g. budget owner, deadline). |
Returns AgentRun
| Field | Type | Description |
|---|---|---|
id | string | Run ID, prefixed run_. |
agentId | string | The agent that ran. |
status | string | running, completed, failed, or waiting_approval. |
summary | string | Human-readable summary of what the agent did. |
error | string | null | Error details if the run failed. |
startedAt | string | ISO 8601 timestamp. |
completedAt | string | null | ISO 8601 timestamp. Null if still running. |
durationMs | number | null | Wall-clock time in milliseconds. |
Throws CREDITS_EXHAUSTED (402), AGENT_FROZEN (403)
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'
console.log(run.summary) // 'Renewed SendGrid Pro plan for $29.00'
console.log(run.durationMs) // 4823
valta.agents.listRuns(agentId, params?)
Returns a paginated list of runs for an agent.
Parameters
| Field | Type | Description |
|---|---|---|
limit | number | Results per page. |
status | string | Filter by run status. |
Returns PaginatedResponse<AgentRun>
const { data } = await valta.agents.listRuns(agent.id, {
limit: 10,
status: 'failed',
})
for (const run of data) {
console.log(run.id, run.error)
}
valta.agents.getRun(agentId, runId)
Fetches a single run by ID.
Returns AgentRun
const run = await valta.agents.getRun(agent.id, 'run_...')
console.log(run.status, run.summary)
valta.agents.freeze(agentId)
Freezes an agent immediately. No transactions are possible while frozen. No new runs can start.
Returns { success: true, agentId: string, status: 'frozen' }
await valta.agents.freeze(agent.id)
// { success: true, agentId: 'ag_...', status: 'frozen' }
valta.agents.unfreeze(agentId)
Restores a frozen agent to active status.
Returns { success: true, agentId: string, status: 'active' }
await valta.agents.unfreeze(agent.id)
// { success: true, agentId: 'ag_...', status: 'active' }