Agents represent named AI workloads registered in your tenant. The Agents API lets you register agents, query their configuration, inspect the tools they have used, and review their deployment history.

GET /api/agents

List all agents for the current tenant

Parameters:

Param	Type	Description
`limit`	number	Max results (default 50, max 500)
`offset`	number	Pagination offset
`environment`	string	Filter by environment (e.g. `production`)

Response (200):

{
  "data": [
    {
      "id": "agent_abc123",
      "name": "customer-support",
      "description": "Handles tier-1 support tickets",
      "modelProvider": "openai",
      "modelName": "gpt-4o",
      "environment": "production",
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-03-20T14:32:00Z"
    }
  ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

import Rivano from '@rivano/sdk';
const rivano = new Rivano({ apiKey: process.env.RIVANO_API_KEY! });

const agents = await rivano.agents.list({ environment: 'production' });
console.log(agents.total, 'agents');

curl "https://api.rivano.ai/api/agents?environment=production" \
  -H "Authorization: Bearer rv_api_..."

GET /api/agents/:id

Get a single agent by ID

Response (200):

{
  "data": {
    "id": "agent_abc123",
    "name": "customer-support",
    "description": "Handles tier-1 support tickets",
    "modelProvider": "openai",
    "modelName": "gpt-4o",
    "environment": "production",
    "configYaml": "agents:\n  - name: customer-support\n    ...",
    "createdAt": "2026-01-15T10:00:00Z",
    "updatedAt": "2026-03-20T14:32:00Z"
  }
}

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

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

POST /api/agents

Request body:

{
  "name": "invoice-processor",
  "description": "Extracts line items from invoice PDFs",
  "modelProvider": "anthropic",
  "modelName": "claude-opus-4-5",
  "environment": "production",
  "configYaml": "agents:\n  - name: invoice-processor\n    ..."
}

Field	Required	Description
`name`	Yes	Unique name within the tenant
`modelProvider`	No	LLM provider identifier
`modelName`	No	Model name
`environment`	No	Environment tag
`description`	No	Human-readable description
`configYaml`	No	Full `rivano.yaml` config for this agent

Response (201):

{
  "data": {
    "id": "agent_xyz789",
    "name": "invoice-processor",
    "modelProvider": "anthropic",
    "modelName": "claude-opus-4-5",
    "environment": "production",
    "createdAt": "2026-04-04T09:15:00Z",
    "updatedAt": "2026-04-04T09:15:00Z"
  }
}

const agent = await rivano.agents.create({
  name: 'invoice-processor',
  modelProvider: 'anthropic',
  modelName: 'claude-opus-4-5',
  environment: 'production',
});
console.log('Created:', agent.data.id);

curl -X POST https://api.rivano.ai/api/agents \
  -H "Authorization: Bearer rv_api_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "invoice-processor",
    "modelProvider": "anthropic",
    "modelName": "claude-opus-4-5",
    "environment": "production"
  }'

GET /api/agents/:id/tools

List tools observed for an agent

Returns every tool the agent has invoked through the proxy, with call counts and last invocation time.

Parameters:

Param	Type	Description
`limit`	number	Max results (default 50)
`offset`	number	Pagination offset

Response (200):

{
  "data": [
    {
      "id": "tool_abc123",
      "agentId": "agent_abc123",
      "toolName": "search_knowledge_base",
      "callCount": 1847,
      "lastCalledAt": "2026-04-04T08:55:00Z"
    },
    {
      "id": "tool_def456",
      "agentId": "agent_abc123",
      "toolName": "create_ticket",
      "callCount": 342,
      "lastCalledAt": "2026-04-03T22:10:00Z"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

const tools = await rivano.agents.listTools('agent_abc123');
for (const tool of tools.data) {
  console.log(`${tool.toolName}: ${tool.callCount} calls`);
}

curl https://api.rivano.ai/api/agents/agent_abc123/tools \
  -H "Authorization: Bearer rv_api_..."

GET /api/agents/:id/history

Get deployment history for an agent

Returns the full version history of the agent’s configuration, most recent first.

Parameters:

Param	Type	Description
`limit`	number	Max results (default 20)
`offset`	number	Pagination offset

Response (200):

{
  "data": [
    {
      "id": "deploy_abc123",
      "agentId": "agent_abc123",
      "configYaml": "agents:\n  - name: customer-support\n    modelName: gpt-4o\n    ...",
      "deployedBy": "user_xyz789",
      "deployedAt": "2026-03-20T14:32:00Z"
    },
    {
      "id": "deploy_def456",
      "agentId": "agent_abc123",
      "configYaml": "agents:\n  - name: customer-support\n    modelName: gpt-4-turbo\n    ...",
      "deployedBy": "user_xyz789",
      "deployedAt": "2026-02-10T09:00:00Z"
    }
  ],
  "total": 5,
  "limit": 20,
  "offset": 0
}

const history = await rivano.agents.getHistory('agent_abc123');
console.log(`${history.total} deployments`);

curl https://api.rivano.ai/api/agents/agent_abc123/history \
  -H "Authorization: Bearer rv_api_..."

Policies API — Attach policies to agents
Traces API — Query traces for a specific agent
SDK Agents — Typed SDK wrapper
CLI Agents — Manage agents from the terminal

Agents API

Related