Agents API

Agents are AI-powered execution units that can be used in workflow steps. The platform provides both core agents (available to all companies) and the ability to create custom agents.

Core Agents

Four universal core agents are available to all companies:

ID	Name	Type	Description
`agent_extraction`	Universal Extraction Agent	`extraction`	Extract structured data from documents with confidence scoring
`agent_content`	Content Generation Agent	`content`	Generate professional emails, messages, and notifications
`agent_transform`	Data Transformation Agent	`transform`	Transform data between formats and schemas
`agent_decision`	Decision & Routing Agent	`decision`	Make business decisions and route based on criteria

Agent Scopes

Scope	Description
`global`	Available to all companies (core agents)
`company`	Restricted to the creating company

List Agents

Retrieve all agents available to your company, including core agents and custom agents.

GET /api/v1/agents

Query Parameters

Parameter	Type	Default	Description
`type`	string	-	Filter by type: `extraction`, `content`, `transform`, `decision`, `code`, `classification`, `custom`
`status`	string	-	Filter by status: `active`, `deprecated`
`search`	string	-	Search by agent name
`includeBuiltIn`	boolean	true	Include core agents in results
`limit`	number	50	Number of results (1-100)
`cursor`	string	-	Cursor for pagination

Example

curl -X GET "http://localhost:3000/api/v1/agents?type=extraction" \
  -H "x-api-key: YOUR_API_KEY"

Create Agent

Create a new custom agent for your company.

POST /api/v1/agents

Request Body

Field	Type	Required	Description
`name`	string	Yes	Agent display name
`description`	string	No	Agent description
`type`	string	Yes	Agent type (see below)
`provider`	string	No	AI provider: `openai` (default), `anthropic`
`model`	string	No	Model ID (defaults to `gpt-4o`)
`systemPrompt`	string	Yes	System prompt defining agent behavior
`outputSchema`	object	No	JSON Schema for structured output
`temperature`	number	No	Temperature (0.0-2.0), defaults to 0.7
`maxTokens`	number	No	Max tokens in response, defaults to 4096

Agent Types

Type	Description
`extraction`	Extract structured data from documents/text
`content`	Generate text content (emails, messages, etc.)
`transform`	Transform data between formats
`decision`	Make decisions and classify items
`code`	Generate or analyze code
`classification`	Classify inputs into categories
`custom`	Custom agent with user-defined behavior

Supported Models

Provider	Models
OpenAI	`gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`, `gpt-4`, `gpt-3.5-turbo`, `o1`, `o3-mini`
Anthropic	`claude-3-5-sonnet-latest`, `claude-3-5-haiku-latest`, `claude-3-opus-latest`

Get Agent

Retrieve details of a specific agent, including core agents.

GET /api/v1/agents/:id

Path Parameters

Parameter	Type	Description
`id`	string	Agent ID or core agent ID (e.g., `agent_extraction`)

Update Agent

Update a custom agent. Each update increments the version number.

PUT /api/v1/agents/:id

Only company-owned agents can be updated. Core agents and agents from other companies cannot be modified.

Delete Agent

Soft delete an agent. The agent is marked as deprecated and will no longer appear in listings.

DELETE /api/v1/agents/:id

Core agents cannot be deleted. Only company-owned agents can be removed.

Test Agent

Test an agent with sample input to verify configuration and output.

POST /api/v1/agents/:id/test

Request Body

Field	Type	Required	Description
`input`	object	Yes	Input variables for the agent
`userMessage`	string	No	Optional user message override

Core agents cannot be directly tested via API. Create a workflow with an agent step to test built-in agents.

Execute Agent

Execute an agent standalone (outside of a workflow context).

POST /api/v1/agents/:id/execute

Request Body

Field	Type	Required	Description
`input`	object	Yes	Input variables for the agent
`userMessage`	string	No	User message for the agent
`workflowRunId`	string	No	Optional workflow run ID for tracking
`overrides`	object	No	Runtime parameter overrides

Overrides

Field	Type	Description
`temperature`	number	Override temperature for this execution
`maxTokens`	number	Override max tokens
`model`	string	Override model for this execution

List Agent Executions

Retrieve execution history for an agent.

GET /api/v1/agents/:id/executions

Query Parameters

Parameter	Type	Default	Description
`limit`	number	50	Number of results (1-100)
`cursor`	string	-	Cursor for pagination

Core Agent Input Variables

Universal Extraction Agent (`agent_extraction`)

Variable	Type	Description
`document`	string	Document content to extract from
`schema`	object	JSON Schema defining fields to extract
`fields`	array	List of field definitions (alternative to schema)
`documentType`	string	Document type hint (invoice, receipt, contract)
`customInstructions`	string	Additional extraction instructions

Content Generation Agent (`agent_content`)

Variable	Type	Description
`contentType`	string	email, message, summary, notification
`tone`	string	professional, friendly, formal, casual, urgent
`format`	string	text, html, markdown
`recipient`	string	Who the content is for
`subject`	string	Subject or topic
`context`	string	Background context
`keyPoints`	array	Key points to include
`customInstructions`	string	Additional instructions

Data Transformation Agent (`agent_transform`)

Variable	Type	Description
`data`	any	Data to transform
`sourceSchema`	object	Schema of input data
`targetSchema`	object	Desired output schema
`mappingRules`	array	Field mapping rules
`defaultValues`	object	Default values for missing fields
`customInstructions`	string	Additional instructions

Decision & Routing Agent (`agent_decision`)

Variable	Type	Description
`data`	any	Data to evaluate
`decisionType`	string	approval_routing, classification, priority
`options`	array	Available decision options
`criteria`	array	Evaluation criteria
`thresholds`	object	Threshold values
`context`	string	Additional context
`customInstructions`	string	Additional instructions

Error Responses

Agent Not Found (404)

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Agent not found"
  }
}

Cannot Modify Built-in Agent (400)

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Cannot modify built-in agents"
  }
}

Duplicate Name (400)

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "An agent with the name \"Invoice Extractor\" already exists"
  }
}

Agents API

On this page