The rivano.agents resource lets you manage AI agent definitions programmatically — the same agents you define in rivano.yaml and deploy via the CLI.

List agents

import Rivano from '@rivano/sdk';

const rivano = new Rivano({ apiKey: 'rv_...' });

const { data, total } = await rivano.agents.list();

console.log(`${total} agents`);
for (const agent of data) {
  console.log(`${agent.name} — ${agent.environment ?? 'no environment'}`);
}

import requests

response = requests.get(
    'https://api.rivano.ai/api/agents',
    headers={'Authorization': 'Bearer rv_...'},
)
result = response.json()
for agent in result['data']:
    print(agent['name'], agent.get('environment'))

curl https://api.rivano.ai/api/agents \
  -H "Authorization: Bearer rv_..."

Get a single agent

import Rivano from '@rivano/sdk';

const rivano = new Rivano({ apiKey: 'rv_...' });

const agent = await rivano.agents.get('agent_abc123');
console.log(agent.name, agent.modelProvider, agent.modelName);

Create an agent

import Rivano from '@rivano/sdk';

const rivano = new Rivano({ apiKey: 'rv_...' });

const agent = await rivano.agents.create({
  name: 'contract-summarizer',
  description: 'Summarizes legal contracts for review teams',
  modelProvider: 'openai',
  modelName: 'gpt-4o',
  environment: 'production',
});

console.log('Created agent:', agent.id);

import requests

response = requests.post(
    'https://api.rivano.ai/api/agents',
    headers={
        'Authorization': 'Bearer rv_...',
        'Content-Type': 'application/json',
    },
    json={
        'name': 'contract-summarizer',
        'description': 'Summarizes legal contracts for review teams',
        'modelProvider': 'openai',
        'modelName': 'gpt-4o',
        'environment': 'production',
    },
)
agent = response.json()
print('Created agent:', agent['id'])

curl https://api.rivano.ai/api/agents \
  -X POST \
  -H "Authorization: Bearer rv_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "contract-summarizer",
    "description": "Summarizes legal contracts for review teams",
    "modelProvider": "openai",
    "modelName": "gpt-4o",
    "environment": "production"
  }'

Create parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	Unique agent name within the tenant
`description`	`string`	No	Human-readable description
`modelProvider`	`string`	No	Provider key: `openai`, `anthropic`, `google`, etc.
`modelName`	`string`	No	Model identifier, e.g. `gpt-4o`, `claude-3-5-sonnet-20241022`
`environment`	`string`	No	Deployment environment: `production`, `staging`, `development`
`configYaml`	`string`	No	Raw YAML config for advanced agent configuration

Get agent tools

Returns the tools (function definitions) associated with an agent:

import Rivano from '@rivano/sdk';

const rivano = new Rivano({ apiKey: 'rv_...' });

const tools = await rivano.agents.getTools('agent_abc123');
for (const tool of tools) {
  console.log(tool.name, tool.description);
}

Get deployment history

Returns a list of all deployments for an agent, newest first:

import Rivano from '@rivano/sdk';

const rivano = new Rivano({ apiKey: 'rv_...' });

const history = await rivano.agents.getHistory('agent_abc123');
for (const deployment of history) {
  console.log(deployment.version, deployment.deployedAt, deployment.deployedBy);
}

💡

Use the CLI to roll back to a previous version: rivano agents rollback contract-summarizer. The SDK exposes deployment history so you can build rollback automation into your own tooling.

Error handling

Error	When it occurs
`SdkAuthError`	Invalid API key
`SdkForbiddenError`	Key lacks access to this tenant
`SdkNotFoundError`	Agent ID does not exist
`SdkError`	Validation failure (e.g. duplicate name)

import Rivano, { SdkNotFoundError, SdkError } from '@rivano/sdk';

const rivano = new Rivano({ apiKey: 'rv_...' });

try {
  const agent = await rivano.agents.get('agent_does_not_exist');
} catch (error) {
  if (error instanceof SdkNotFoundError) {
    console.error('No agent with that ID');
  } else if (error instanceof SdkError) {
    console.error('Unexpected error:', error.message);
  }
}

CLI Agents — Manage agents from the terminal
CLI Deploy — Deploy agents from rivano.yaml
SDK Traces — Query trace data for a specific agent
Core Concepts — Agents — Mental model

SDK — Agents