Skip to main content
Agents allow you to automate responses to events in your annotation workflows. Configure agents to listen for specific events and trigger callbacks to your external services.

​
List agents

Retrieve a paginated list of agents. 
const agents = await avala.agents.list({
  limit: 50,
  cursor: 'next-cursor'
});

​
Parameters

​
options.limit
number
Maximum number of agents to return per page
​
options.cursor
string
Cursor for pagination

​
Returns

Returns a cursor-paginated list of agent objects.
​
items
Agent[]
Array of agent objects
​
nextCursor
string | null
Cursor for the next page of results
​
previousCursor
string | null
Cursor for the previous page of results
​
hasMore
boolean
Whether more results are available

​
Create an agent

Create a new automation agent. 
const agent = await avala.agents.create({
  name: 'Quality Control Agent',
  description: 'Automatically validates annotations',
  callbackUrl: 'https://api.example.com/webhooks/agent',
  events: ['task.completed', 'annotation.created'],
  project: 'project-uid',
  taskTypes: ['segmentation', 'classification']
});

​
Parameters

​
options.name
string
required
Name of the agent
​
options.description
string
Description of the agent’s purpose
​
options.callbackUrl
string
URL to send event callbacks to
​
options.events
string[]
required
Array of event types the agent should listen for
​
options.project
string
Project UID to scope the agent to
​
options.taskTypes
string[]
Task types the agent should respond to

​
Returns

Returns the created agent object.
​
uid
string
Unique identifier for the agent
​
name
string
Name of the agent
​
description
string | null
Description of the agent
​
events
string[]
Events the agent listens for
​
callbackUrl
string | null
Callback URL for the agent
​
isActive
boolean
Whether the agent is active
​
project
string | null
Project UID the agent is scoped to
​
taskTypes
string[]
Task types the agent responds to
​
createdAt
string | null
ISO 8601 timestamp of when the agent was created
​
updatedAt
string | null
ISO 8601 timestamp of when the agent was last updated

​
Get an agent

Retrieve a specific agent by UID. 
const agent = await avala.agents.get('agent-uid');

​
Parameters

​
uid
string
required
The unique identifier of the agent

​
Returns

Returns the agent object.

​
Update an agent

Update an existing agent. 
const agent = await avala.agents.update('agent-uid', {
  name: 'Updated Agent Name',
  isActive: false,
  events: ['task.completed']
});

​
Parameters

​
uid
string
required
The unique identifier of the agent to update
​
options.name
string
New name for the agent
​
options.description
string
New description for the agent
​
options.callbackUrl
string
New callback URL
​
options.events
string[]
New array of event types
​
options.isActive
boolean
Whether the agent should be active
​
options.project
string
New project UID to scope the agent to
​
options.taskTypes
string[]
New task types the agent should respond to

​
Returns

Returns the updated agent object.

​
Delete an agent

Delete an agent. 
await avala.agents.delete('agent-uid');

​
Parameters

​
uid
string
required
The unique identifier of the agent to delete

​
Returns

Returns void on success.

​
List agent executions

Retrieve execution history for a specific agent. 
const executions = await avala.agents.listExecutions('agent-uid', {
  limit: 50,
  cursor: 'next-cursor'
});

​
Parameters

​
uid
string
required
The unique identifier of the agent
​
options.limit
number
Maximum number of executions to return per page
​
options.cursor
string
Cursor for pagination

​
Returns

Returns a cursor-paginated list of agent execution objects.
​
items
AgentExecution[]
Array of agent execution objects
​
items[].uid
string
Unique identifier for the execution
​
items[].registration
string
Agent registration UID
​
items[].eventType
string
Type of event that triggered the execution
​
items[].task
string | null
Task UID associated with the execution
​
items[].result
string | null
Result of the execution
​
items[].status
string | null
Execution status
​
items[].action
string | null
Action taken by the agent
​
items[].eventPayload
object | null
Payload of the event that triggered the execution
​
items[].responsePayload
object | null
Response payload from the agent
​
items[].errorMessage
string | null
Error message if the execution failed
​
items[].startedAt
string | null
ISO 8601 timestamp of when the execution started
​
items[].completedAt
string | null
ISO 8601 timestamp of when the execution completed
​
items[].createdAt
string | null
ISO 8601 timestamp of when the execution was created
​
items[].updatedAt
string | null
ISO 8601 timestamp of when the execution was last updated

​
Test an agent

Test an agent’s callback URL to verify connectivity. 
const result = await avala.agents.test('agent-uid');

​
Parameters

​
uid
string
required
The unique identifier of the agent to test

​
Returns

​
success
boolean
Whether the test was successful

Build docs developers (and LLMs) love

Get started for freeTalk to us