AI Agents API - OpenAPI 3.0

Base URL: https://ai-agents.sls.epilot.io
Full API Docs: https://docs.epilot.io/api/ai-agents

Usage

import { epilot } from '@epilot/sdk'

epilot.authorize(() => '<token>')
const { data } = await epilot.aiAgents.createAgent(...)

Tree-shakeable import

import { getClient, authorize } from '@epilot/sdk/ai-agents'

const aiAgentsClient = getClient()
authorize(aiAgentsClient, () => '<token>')
const { data } = await aiAgentsClient.createAgent(...)

Operations

Agents Configuration

createAgent
listAgents
getAgentById
updateAgentById
deleteAgentById

Agent Execution

executeAgent
listExecutions
getExecution
cancelExecution
getExecutionTrace
approveExecution
rejectExecution

Schemas

AgentId
CreateAgentRequest
UpdateAgentRequest
AgentDefinition
ListAgentsResponse
ListExecutionsResponse
ApproveExecutionRequest
RejectExecutionRequest
ExecuteAgentRequest
ExecutionResponse
ExecutionTrace
ExecutionIteration
PendingAction
ExecutionError
ExecutionMetrics
ToolPreview
PreviewActionType
PreviewEntity
PreviewChange
PreviewValue
ToolDefinition
SkillCategory
AgentSource
SkillAvailability
ExecutionContext
ExecutionPattern
ExecutionMode
ExecutionStatus
ParameterType
InputParameterDefinition
InputParametersSchema
ModelConfig
Error

`createAgent`

Create Agent definition

POST /v1/agents

const { data } = await client.createAgent(
  null,
  {
    name: 'Email Reply Generator',
    description: 'string',
    category: 'message',
    icon: 'mail-reply',
    system_prompt: 'string',
    tools: ['entity.search', 'message.draft'],
    model_config: {
      model_id: 'anthropic.claude-3-5-sonnet-20241022-v2:0',
      temperature: 0.7,
      max_tokens: 4096
    },
    max_iterations: 10,
    execution_pattern: 'direct',
    execution_mode: 'automatic',
    output_schema: {},
    input_parameters_schema: {
      type: 'object',
      parameters: [
        {
          name: 'target_schema',
          label: 'Target Schema',
          type: 'entity-schema',
          description: 'Entity type to create'
        },
        {
          name: 'confidence_threshold',
          label: 'Confidence Threshold',
          type: 'number',
          minimum: 0,
          maximum: 1,
          default: 0.8
        },
        /* ... 1 more */
      ],
      required: ['target_schema']
    }
  },
)

Response

{
  "agent_id": "skill:email-categorizer",
  "org_id": "string",
  "name": "string",
  "description": "string",
  "category": "message",
  "icon": "string",
  "source": "system",
  "availability": ["flows", "copilot"],
  "allowed_entity_schemas": ["message"],
  "system_prompt": "string",
  "tools": ["string"],
  "model_config": {
    "model_id": "anthropic.claude-3-5-sonnet-20241022-v2:0",
    "temperature": 0.7,
    "max_tokens": 4096
  },
  "max_iterations": 0,
  "execution_pattern": "direct",
  "execution_mode": "automatic",
  "output_schema": {},
  "input_parameters_schema": {
    "type": "object",
    "parameters": [
      {
        "name": "target_schema",
        "label": "Target Schema",
        "type": "entity-schema",
        "description": "Entity type to create"
      },
      {
        "name": "confidence_threshold",
        "label": "Confidence Threshold",
        "type": "number",
        "minimum": 0,
        "maximum": 1,
        "default": 0.8
      }
    ],
    "required": ["target_schema"]
  },
  "version": 0,
  "created_at": "1970-01-01T00:00:00.000Z",
  "updated_at": "1970-01-01T00:00:00.000Z",
  "created_by": "string"
}

`listAgents`

List all agent configurations

GET /v1/agents

const { data } = await client.listAgents({
  source: 'example',
  availability: 'example',
  entity_schema: 'example',
})

Response

{
  "agents": [
    {
      "agent_id": "skill:email-categorizer",
      "org_id": "string",
      "name": "string",
      "description": "string",
      "category": "message",
      "icon": "string",
      "source": "system",
      "availability": ["flows", "copilot"],
      "allowed_entity_schemas": ["message"],
      "system_prompt": "string",
      "tools": ["string"],
      "model_config": {
        "model_id": "anthropic.claude-3-5-sonnet-20241022-v2:0",
        "temperature": 0.7,
        "max_tokens": 4096
      },
      "max_iterations": 0,
      "execution_pattern": "direct",
      "execution_mode": "automatic",
      "output_schema": {},
      "input_parameters_schema": {
        "type": "object",
        "parameters": [
          {
            "name": "target_schema",
            "label": "Target Schema",
            "type": "entity-schema",
            "description": "Entity type to create"
          },
          {
            "name": "confidence_threshold",
            "label": "Confidence Threshold",
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "default": 0.8
          }
        ],
        "required": ["target_schema"]
      },
      "version": 0,
      "created_at": "1970-01-01T00:00:00.000Z",
      "updated_at": "1970-01-01T00:00:00.000Z",
      "created_by": "string"
    }
  ],
  "next_cursor": "string"
}

`getAgentById`

Get the agent configuration by ID

GET /v1/agents/{agent_id}

const { data } = await client.getAgentById({
  agent_id: 'example',
})

Response

{
  "agent_id": "skill:email-categorizer",
  "org_id": "string",
  "name": "string",
  "description": "string",
  "category": "message",
  "icon": "string",
  "source": "system",
  "availability": ["flows", "copilot"],
  "allowed_entity_schemas": ["message"],
  "system_prompt": "string",
  "tools": ["string"],
  "model_config": {
    "model_id": "anthropic.claude-3-5-sonnet-20241022-v2:0",
    "temperature": 0.7,
    "max_tokens": 4096
  },
  "max_iterations": 0,
  "execution_pattern": "direct",
  "execution_mode": "automatic",
  "output_schema": {},
  "input_parameters_schema": {
    "type": "object",
    "parameters": [
      {
        "name": "target_schema",
        "label": "Target Schema",
        "type": "entity-schema",
        "description": "Entity type to create"
      },
      {
        "name": "confidence_threshold",
        "label": "Confidence Threshold",
        "type": "number",
        "minimum": 0,
        "maximum": 1,
        "default": 0.8
      }
    ],
    "required": ["target_schema"]
  },
  "version": 0,
  "created_at": "1970-01-01T00:00:00.000Z",
  "updated_at": "1970-01-01T00:00:00.000Z",
  "created_by": "string"
}

`updateAgentById`

Update the agent configuration by ID

PUT /v1/agents/{agent_id}

const { data } = await client.updateAgentById(
  {
    agent_id: 'example',
  },
  {
    name: 'string',
    description: 'string',
    category: 'message',
    icon: 'string',
    system_prompt: 'string',
    tools: ['string'],
    model_config: {
      model_id: 'anthropic.claude-3-5-sonnet-20241022-v2:0',
      temperature: 0.7,
      max_tokens: 4096
    },
    max_iterations: 1,
    execution_pattern: 'direct',
    execution_mode: 'automatic',
    output_schema: {},
    input_parameters_schema: {
      type: 'object',
      parameters: [
        {
          name: 'target_schema',
          label: 'Target Schema',
          type: 'entity-schema',
          description: 'Entity type to create'
        },
        {
          name: 'confidence_threshold',
          label: 'Confidence Threshold',
          type: 'number',
          minimum: 0,
          maximum: 1,
          default: 0.8
        },
        /* ... 1 more */
      ],
      required: ['target_schema']
    }
  },
)

Response

{
  "agent_id": "skill:email-categorizer",
  "org_id": "string",
  "name": "string",
  "description": "string",
  "category": "message",
  "icon": "string",
  "source": "system",
  "availability": ["flows", "copilot"],
  "allowed_entity_schemas": ["message"],
  "system_prompt": "string",
  "tools": ["string"],
  "model_config": {
    "model_id": "anthropic.claude-3-5-sonnet-20241022-v2:0",
    "temperature": 0.7,
    "max_tokens": 4096
  },
  "max_iterations": 0,
  "execution_pattern": "direct",
  "execution_mode": "automatic",
  "output_schema": {},
  "input_parameters_schema": {
    "type": "object",
    "parameters": [
      {
        "name": "target_schema",
        "label": "Target Schema",
        "type": "entity-schema",
        "description": "Entity type to create"
      },
      {
        "name": "confidence_threshold",
        "label": "Confidence Threshold",
        "type": "number",
        "minimum": 0,
        "maximum": 1,
        "default": 0.8
      }
    ],
    "required": ["target_schema"]
  },
  "version": 0,
  "created_at": "1970-01-01T00:00:00.000Z",
  "updated_at": "1970-01-01T00:00:00.000Z",
  "created_by": "string"
}

`deleteAgentById`

Delete the agent configuration by ID

DELETE /v1/agents/{agent_id}

const { data } = await client.deleteAgentById({
  agent_id: 'example',
})

`executeAgent`

Execute an agent

POST /v1/agents/{agent_id}/execute

const { data } = await client.executeAgent(
  {
    agent_id: 'example',
  },
  {
    input: {
      entity_id: 'string',
      entity_schema: 'string',
      workflow_id: 'string',
      workflow_execution_id: 'string',
      task_id: 'string',
      custom_data: {},
      flow_context: [
        {
          entity_id: 'string',
          entity_schema: 'string'
        }
      ]
    },
    parameters: {},
    execution_mode_override: 'automatic',
    execution_context: 'flows',
    callback_url: 'https://example.com/path',
    timeout_ms: 30000
  },
)

Response

{
  "execution_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "agent_id": "skill:email-categorizer",
  "agent_source": "system",
  "agent_name": "string",
  "execution_context": "flows",
  "org_id": "string",
  "status": "pending",
  "input": {},
  "parameters": {},
  "result": {
    "response": "string",
    "structured_output": {}
  },
  "error": {
    "code": "TIMEOUT",
    "message": "string",
    "details": {}
  },
  "pending_action": {
    "tool": "string",
    "input": {},
    "description": "string",
    "preview": {
      "action": {
        "type": "move",
        "verb": "Move Thread"
      },
      "source": {
        "type": "inbox",
        "id": "string",
        "name": "Support Inbox",
        "schema": "string",
        "icon": "string",
        "url": "string"
      },
      "target": {
        "type": "inbox",
        "id": "string",
        "name": "Support Inbox",
        "schema": "string",
        "icon": "string",
        "url": "string"
      },
      "changes": [
        {
          "field": "string",
          "label": "string",
          "from": {
            "type": "text",
            "value": {},
            "values": ["string"],
            "id": "string",
            "name": "string",
            "schema": "string",
            "color": "success"
          },
          "to": {
            "type": "text",
            "value": {},
            "values": ["string"],
            "id": "string",
            "name": "string",
            "schema": "string",
            "color": "success"
          }
        }
      ],
      "metadata": {},
      "summary": "This email discusses solar panel installation and should be handled by the Service team."
    }
  },
  "metrics": {
    "total_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0,
    "total_cost_usd": 0,
    "duration_ms": 0,
    "iteration_count": 0
  },
  "started_at": "1970-01-01T00:00:00.000Z",
  "completed_at": "1970-01-01T00:00:00.000Z"
}

`listExecutions`

List executions

GET /v1/executions

const { data } = await client.listExecutions({
  agent_id: 'example',
  status: 'example',
  limit: 1,
})

Response

{
  "executions": [
    {
      "execution_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "agent_id": "skill:email-categorizer",
      "agent_source": "system",
      "agent_name": "string",
      "execution_context": "flows",
      "org_id": "string",
      "status": "pending",
      "input": {},
      "parameters": {},
      "result": {
        "response": "string",
        "structured_output": {}
      },
      "error": {
        "code": "TIMEOUT",
        "message": "string",
        "details": {}
      },
      "pending_action": {
        "tool": "string",
        "input": {},
        "description": "string",
        "preview": {
          "action": {
            "type": "move",
            "verb": "Move Thread"
          },
          "source": {
            "type": "inbox",
            "id": "string",
            "name": "Support Inbox",
            "schema": "string",
            "icon": "string",
            "url": "string"
          },
          "target": {
            "type": "inbox",
            "id": "string",
            "name": "Support Inbox",
            "schema": "string",
            "icon": "string",
            "url": "string"
          },
          "changes": [
            {
              "field": "string",
              "label": "string",
              "from": {
                "type": "text",
                "value": {},
                "values": ["string"],
                "id": "string",
                "name": "string",
                "schema": "string",
                "color": "success"
              },
              "to": {
                "type": "text",
                "value": {},
                "values": ["string"],
                "id": "string",
                "name": "string",
                "schema": "string",
                "color": "success"
              }
            }
          ],
          "metadata": {},
          "summary": "This email discusses solar panel installation and should be handled by the Service team."
        }
      },
      "metrics": {
        "total_tokens": 0,
        "input_tokens": 0,
        "output_tokens": 0,
        "total_cost_usd": 0,
        "duration_ms": 0,
        "iteration_count": 0
      },
      "started_at": "1970-01-01T00:00:00.000Z",
      "completed_at": "1970-01-01T00:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

`getExecution`

Get execution by ID

GET /v1/executions/{execution_id}

const { data } = await client.getExecution({
  execution_id: 'example',
})

Response

{
  "execution_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "agent_id": "skill:email-categorizer",
  "agent_source": "system",
  "agent_name": "string",
  "execution_context": "flows",
  "org_id": "string",
  "status": "pending",
  "input": {},
  "parameters": {},
  "result": {
    "response": "string",
    "structured_output": {}
  },
  "error": {
    "code": "TIMEOUT",
    "message": "string",
    "details": {}
  },
  "pending_action": {
    "tool": "string",
    "input": {},
    "description": "string",
    "preview": {
      "action": {
        "type": "move",
        "verb": "Move Thread"
      },
      "source": {
        "type": "inbox",
        "id": "string",
        "name": "Support Inbox",
        "schema": "string",
        "icon": "string",
        "url": "string"
      },
      "target": {
        "type": "inbox",
        "id": "string",
        "name": "Support Inbox",
        "schema": "string",
        "icon": "string",
        "url": "string"
      },
      "changes": [
        {
          "field": "string",
          "label": "string",
          "from": {
            "type": "text",
            "value": {},
            "values": ["string"],
            "id": "string",
            "name": "string",
            "schema": "string",
            "color": "success"
          },
          "to": {
            "type": "text",
            "value": {},
            "values": ["string"],
            "id": "string",
            "name": "string",
            "schema": "string",
            "color": "success"
          }
        }
      ],
      "metadata": {},
      "summary": "This email discusses solar panel installation and should be handled by the Service team."
    }
  },
  "metrics": {
    "total_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0,
    "total_cost_usd": 0,
    "duration_ms": 0,
    "iteration_count": 0
  },
  "started_at": "1970-01-01T00:00:00.000Z",
  "completed_at": "1970-01-01T00:00:00.000Z"
}

`cancelExecution`

Cancel execution

DELETE /v1/executions/{execution_id}

const { data } = await client.cancelExecution({
  execution_id: 'example',
})

Response

{
  "execution_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "agent_id": "skill:email-categorizer",
  "agent_source": "system",
  "agent_name": "string",
  "execution_context": "flows",
  "org_id": "string",
  "status": "pending",
  "input": {},
  "parameters": {},
  "result": {
    "response": "string",
    "structured_output": {}
  },
  "error": {
    "code": "TIMEOUT",
    "message": "string",
    "details": {}
  },
  "pending_action": {
    "tool": "string",
    "input": {},
    "description": "string",
    "preview": {
      "action": {
        "type": "move",
        "verb": "Move Thread"
      },
      "source": {
        "type": "inbox",
        "id": "string",
        "name": "Support Inbox",
        "schema": "string",
        "icon": "string",
        "url": "string"
      },
      "target": {
        "type": "inbox",
        "id": "string",
        "name": "Support Inbox",
        "schema": "string",
        "icon": "string",
        "url": "string"
      },
      "changes": [
        {
          "field": "string",
          "label": "string",
          "from": {
            "type": "text",
            "value": {},
            "values": ["string"],
            "id": "string",
            "name": "string",
            "schema": "string",
            "color": "success"
          },
          "to": {
            "type": "text",
            "value": {},
            "values": ["string"],
            "id": "string",
            "name": "string",
            "schema": "string",
            "color": "success"
          }
        }
      ],
      "metadata": {},
      "summary": "This email discusses solar panel installation and should be handled by the Service team."
    }
  },
  "metrics": {
    "total_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0,
    "total_cost_usd": 0,
    "duration_ms": 0,
    "iteration_count": 0
  },
  "started_at": "1970-01-01T00:00:00.000Z",
  "completed_at": "1970-01-01T00:00:00.000Z"
}

`getExecutionTrace`

Get execution trace/iterations

GET /v1/executions/{execution_id}/trace

const { data } = await client.getExecutionTrace({
  execution_id: 'example',
})

Response

{
  "execution_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "iterations": [
    {
      "iteration_index": 0,
      "thought": "string",
      "action": {
        "tool": "string",
        "input": {}
      },
      "observation": {},
      "timestamp": "1970-01-01T00:00:00.000Z",
      "tokens_used": 0,
      "latency_ms": 0
    }
  ],
  "total_iterations": 0
}

`approveExecution`

Approve pending action

POST /v1/executions/{execution_id}/approve

const { data } = await client.approveExecution(
  {
    execution_id: 'example',
  },
  {
    reason: 'string'
  },
)

Response

{
  "execution_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "agent_id": "skill:email-categorizer",
  "agent_source": "system",
  "agent_name": "string",
  "execution_context": "flows",
  "org_id": "string",
  "status": "pending",
  "input": {},
  "parameters": {},
  "result": {
    "response": "string",
    "structured_output": {}
  },
  "error": {
    "code": "TIMEOUT",
    "message": "string",
    "details": {}
  },
  "pending_action": {
    "tool": "string",
    "input": {},
    "description": "string",
    "preview": {
      "action": {
        "type": "move",
        "verb": "Move Thread"
      },
      "source": {
        "type": "inbox",
        "id": "string",
        "name": "Support Inbox",
        "schema": "string",
        "icon": "string",
        "url": "string"
      },
      "target": {
        "type": "inbox",
        "id": "string",
        "name": "Support Inbox",
        "schema": "string",
        "icon": "string",
        "url": "string"
      },
      "changes": [
        {
          "field": "string",
          "label": "string",
          "from": {
            "type": "text",
            "value": {},
            "values": ["string"],
            "id": "string",
            "name": "string",
            "schema": "string",
            "color": "success"
          },
          "to": {
            "type": "text",
            "value": {},
            "values": ["string"],
            "id": "string",
            "name": "string",
            "schema": "string",
            "color": "success"
          }
        }
      ],
      "metadata": {},
      "summary": "This email discusses solar panel installation and should be handled by the Service team."
    }
  },
  "metrics": {
    "total_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0,
    "total_cost_usd": 0,
    "duration_ms": 0,
    "iteration_count": 0
  },
  "started_at": "1970-01-01T00:00:00.000Z",
  "completed_at": "1970-01-01T00:00:00.000Z"
}

`rejectExecution`

Reject pending action

POST /v1/executions/{execution_id}/reject

const { data } = await client.rejectExecution(
  {
    execution_id: 'example',
  },
  {
    reason: 'string'
  },
)

Response

{
  "execution_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "agent_id": "skill:email-categorizer",
  "agent_source": "system",
  "agent_name": "string",
  "execution_context": "flows",
  "org_id": "string",
  "status": "pending",
  "input": {},
  "parameters": {},
  "result": {
    "response": "string",
    "structured_output": {}
  },
  "error": {
    "code": "TIMEOUT",
    "message": "string",
    "details": {}
  },
  "pending_action": {
    "tool": "string",
    "input": {},
    "description": "string",
    "preview": {
      "action": {
        "type": "move",
        "verb": "Move Thread"
      },
      "source": {
        "type": "inbox",
        "id": "string",
        "name": "Support Inbox",
        "schema": "string",
        "icon": "string",
        "url": "string"
      },
      "target": {
        "type": "inbox",
        "id": "string",
        "name": "Support Inbox",
        "schema": "string",
        "icon": "string",
        "url": "string"
      },
      "changes": [
        {
          "field": "string",
          "label": "string",
          "from": {
            "type": "text",
            "value": {},
            "values": ["string"],
            "id": "string",
            "name": "string",
            "schema": "string",
            "color": "success"
          },
          "to": {
            "type": "text",
            "value": {},
            "values": ["string"],
            "id": "string",
            "name": "string",
            "schema": "string",
            "color": "success"
          }
        }
      ],
      "metadata": {},
      "summary": "This email discusses solar panel installation and should be handled by the Service team."
    }
  },
  "metrics": {
    "total_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0,
    "total_cost_usd": 0,
    "duration_ms": 0,
    "iteration_count": 0
  },
  "started_at": "1970-01-01T00:00:00.000Z",
  "completed_at": "1970-01-01T00:00:00.000Z"
}

Schemas

`AgentId`

Agent identifier. Can be either:

System skill ID (prefixed): "skill:email-categorizer", "skill:email-labeler"
Custom agent UUID: "0336a235-9417-4dd8-894c-fe81285bba75"

type AgentId = string

`CreateAgentRequest`

type CreateAgentRequest = {
  name: string
  description?: string
  category?: "message" | "entity" | "document" | "classification" | "custom"
  icon?: string
  system_prompt: string
  tools?: string[]
  model_config?: {
    model_id?: string
    temperature?: number
    max_tokens?: number
  }
  max_iterations?: number
  execution_pattern: "direct" | "react"
  execution_mode?: "automatic" | "approval" | "draft"
  output_schema?: object
  input_parameters_schema?: {
    type: "object"
    parameters: Array<{
      name: { ... }
      label: { ... }
      type: { ... }
      description?: { ... }
      default?: { ... }
      multi?: { ... }
      dependsOn?: { ... }
      visibleWhen?: { ... }
      enum?: { ... }
      minimum?: { ... }
      maximum?: { ... }
      step?: { ... }
      minLength?: { ... }
      maxLength?: { ... }
      schemaFilter?: { ... }
      attributeTypeFilter?: { ... }
    }>
    required?: string[]
  }
}

`UpdateAgentRequest`

type UpdateAgentRequest = {
  name?: string
  description?: string
  category?: "message" | "entity" | "document" | "classification" | "custom"
  icon?: string
  system_prompt?: string
  tools?: string[]
  model_config?: {
    model_id?: string
    temperature?: number
    max_tokens?: number
  }
  max_iterations?: number
  execution_pattern?: "direct" | "react"
  execution_mode?: "automatic" | "approval" | "draft"
  output_schema?: object
  input_parameters_schema?: {
    type: "object"
    parameters: Array<{
      name: { ... }
      label: { ... }
      type: { ... }
      description?: { ... }
      default?: { ... }
      multi?: { ... }
      dependsOn?: { ... }
      visibleWhen?: { ... }
      enum?: { ... }
      minimum?: { ... }
      maximum?: { ... }
      step?: { ... }
      minLength?: { ... }
      maxLength?: { ... }
      schemaFilter?: { ... }
      attributeTypeFilter?: { ... }
    }>
    required?: string[]
  }
}

`AgentDefinition`

type AgentDefinition = {
  agent_id?: string
  org_id?: string
  name?: string
  description?: string
  category?: "message" | "entity" | "document" | "classification" | "custom"
  icon?: string
  source?: "system" | "custom"
  availability?: "flows" | "copilot" | "all"[]
  allowed_entity_schemas?: string[]
  system_prompt?: string
  tools?: string[]
  model_config?: {
    model_id?: string
    temperature?: number
    max_tokens?: number
  }
  max_iterations?: number
  execution_pattern?: "direct" | "react"
  execution_mode?: "automatic" | "approval" | "draft"
  output_schema?: object
  input_parameters_schema?: {
    type: "object"
    parameters: Array<{
      name: { ... }
      label: { ... }
      type: { ... }
      description?: { ... }
      default?: { ... }
      multi?: { ... }
      dependsOn?: { ... }
      visibleWhen?: { ... }
      enum?: { ... }
      minimum?: { ... }
      maximum?: { ... }
      step?: { ... }
      minLength?: { ... }
      maxLength?: { ... }
      schemaFilter?: { ... }
      attributeTypeFilter?: { ... }
    }>
    required?: string[]
  }
  version?: number
  created_at?: string // date-time
  updated_at?: string // date-time
  created_by?: string
}

`ListAgentsResponse`

type ListAgentsResponse = {
  agents?: Array<{
    agent_id?: string
    org_id?: string
    name?: string
    description?: string
    category?: "message" | "entity" | "document" | "classification" | "custom"
    icon?: string
    source?: "system" | "custom"
    availability?: "flows" | "copilot" | "all"[]
    allowed_entity_schemas?: string[]
    system_prompt?: string
    tools?: string[]
    model_config?: {
      model_id?: { ... }
      temperature?: { ... }
      max_tokens?: { ... }
    }
    max_iterations?: number
    execution_pattern?: "direct" | "react"
    execution_mode?: "automatic" | "approval" | "draft"
    output_schema?: object
    input_parameters_schema?: {
      type: { ... }
      parameters: { ... }
      required?: { ... }
    }
    version?: number
    created_at?: string // date-time
    updated_at?: string // date-time
    created_by?: string
  }>
  next_cursor?: string
}

`ListExecutionsResponse`

type ListExecutionsResponse = {
  executions?: Array<{
    execution_id?: string // uuid
    agent_id?: string
    agent_source?: "system" | "custom"
    agent_name?: string
    execution_context?: "flows" | "copilot" | "api"
    org_id?: string
    status?: "pending" | "running" | "waiting_approval" | "completed" | "failed" | "cancelled"
    input?: object
    parameters?: object
    result?: {
      response?: { ... }
      structured_output?: { ... }
    }
    error?: {
      code?: { ... }
      message?: { ... }
      details?: { ... }
    }
    pending_action?: {
      tool?: { ... }
      input?: { ... }
      description?: { ... }
      preview?: { ... }
    }
    metrics?: {
      total_tokens?: { ... }
      input_tokens?: { ... }
      output_tokens?: { ... }
      total_cost_usd?: { ... }
      duration_ms?: { ... }
      iteration_count?: { ... }
    }
    started_at?: string // date-time
    completed_at?: string // date-time
  }>
  next_cursor?: string
}

`ApproveExecutionRequest`

type ApproveExecutionRequest = {
  reason?: string
}

`RejectExecutionRequest`

type RejectExecutionRequest = {
  reason: string
}

`ExecuteAgentRequest`

type ExecuteAgentRequest = {
  input?: {
    entity_id?: string
    entity_schema?: string
    workflow_id?: string
    workflow_execution_id?: string
    task_id?: string
    custom_data?: Record<string, unknown>
    flow_context?: Array<{
      entity_id: { ... }
      entity_schema: { ... }
    }>
  }
  parameters?: Record<string, unknown>
  execution_mode_override?: "automatic" | "approval" | "draft"
  execution_context?: "flows" | "copilot" | "api"
  callback_url?: string // uri
  timeout_ms?: number
}

`ExecutionResponse`

type ExecutionResponse = {
  execution_id?: string // uuid
  agent_id?: string
  agent_source?: "system" | "custom"
  agent_name?: string
  execution_context?: "flows" | "copilot" | "api"
  org_id?: string
  status?: "pending" | "running" | "waiting_approval" | "completed" | "failed" | "cancelled"
  input?: object
  parameters?: object
  result?: {
    response?: string
    structured_output?: object
  }
  error?: {
    code?: "TIMEOUT" | "MAX_ITERATIONS_EXCEEDED" | "TOOL_EXECUTION_FAILED" | "LLM_ERROR" | "INVALID_OUTPUT" | "REJECTED" | "INTERNAL_ERROR"
    message?: string
    details?: object
  }
  pending_action?: {
    tool?: string
    input?: object
    description?: string
    preview?: {
      action?: { ... }
      source?: { ... }
      target?: { ... }
      changes?: { ... }
      metadata?: { ... }
      summary?: { ... }
    }
  }
  metrics?: {
    total_tokens?: number
    input_tokens?: number
    output_tokens?: number
    total_cost_usd?: number
    duration_ms?: number
    iteration_count?: number
  }
  started_at?: string // date-time
  completed_at?: string // date-time
}

`ExecutionTrace`

type ExecutionTrace = {
  execution_id?: string // uuid
  iterations?: Array<{
    iteration_index?: number
    thought?: string
    action?: {
      tool?: { ... }
      input?: { ... }
    }
    observation?: object
    timestamp?: string // date-time
    tokens_used?: number
    latency_ms?: number
  }>
  total_iterations?: number
}

`ExecutionIteration`

type ExecutionIteration = {
  iteration_index?: number
  thought?: string
  action?: {
    tool?: string
    input?: object
  }
  observation?: object
  timestamp?: string // date-time
  tokens_used?: number
  latency_ms?: number
}

`PendingAction`

Action waiting for approval (when status=waiting_approval)

type PendingAction = {
  tool?: string
  input?: object
  description?: string
  preview?: {
    action?: {
      type: { ... }
      verb: { ... }
    }
    source?: {
      type?: { ... }
      id?: { ... }
      name?: { ... }
      schema?: { ... }
      icon?: { ... }
      url?: { ... }
    }
    target?: {
      type?: { ... }
      id?: { ... }
      name?: { ... }
      schema?: { ... }
      icon?: { ... }
      url?: { ... }
    }
    changes?: Array<{
      field?: { ... }
      label?: { ... }
      from?: { ... }
      to?: { ... }
    }>
    metadata?: Record<string, {
      type: { ... }
      value?: { ... }
      values?: { ... }
      id?: { ... }
      name?: { ... }
      schema?: { ... }
      color?: { ... }
    }>
    summary?: string
  }
}

`ExecutionError`

type ExecutionError = {
  code?: "TIMEOUT" | "MAX_ITERATIONS_EXCEEDED" | "TOOL_EXECUTION_FAILED" | "LLM_ERROR" | "INVALID_OUTPUT" | "REJECTED" | "INTERNAL_ERROR"
  message?: string
  details?: object
}

`ExecutionMetrics`

type ExecutionMetrics = {
  total_tokens?: number
  input_tokens?: number
  output_tokens?: number
  total_cost_usd?: number
  duration_ms?: number
  iteration_count?: number
}

`ToolPreview`

Structured preview data for approval UI. Provides a generic format that any tool can populate.

type ToolPreview = {
  action?: {
    type: "move" | "create" | "update" | "delete" | "apply" | "send" | "link" | "unlink"
    verb: string
  }
  source?: {
    type?: string
    id?: string
    name?: string
    schema?: string
    icon?: string
    url?: string
  }
  target?: {
    type?: string
    id?: string
    name?: string
    schema?: string
    icon?: string
    url?: string
  }
  changes?: Array<{
    field?: string
    label?: string
    from?: {
      type: { ... }
      value?: { ... }
      values?: { ... }
      id?: { ... }
      name?: { ... }
      schema?: { ... }
      color?: { ... }
    }
    to?: {
      type: { ... }
      value?: { ... }
      values?: { ... }
      id?: { ... }
      name?: { ... }
      schema?: { ... }
      color?: { ... }
    }
  }>
  metadata?: Record<string, {
    type: "text" | "number" | "boolean" | "list" | "entity" | "badge"
    value?: unknown
    values?: string[]
    id?: string
    name?: string
    schema?: string
    color?: "success" | "warning" | "error" | "info"
  }>
  summary?: string
}

`PreviewActionType`

Type of action being previewed

type PreviewActionType = "move" | "create" | "update" | "delete" | "apply" | "send" | "link" | "unlink"

`PreviewEntity`

Entity reference for preview display

type PreviewEntity = {
  type?: string
  id?: string
  name?: string
  schema?: string
  icon?: string
  url?: string
}

`PreviewChange`

A single field change in the preview

type PreviewChange = {
  field?: string
  label?: string
  from?: {
    type: "text" | "number" | "boolean" | "list" | "entity" | "badge"
    value?: unknown
    values?: string[]
    id?: string
    name?: string
    schema?: string
    color?: "success" | "warning" | "error" | "info"
  }
  to?: {
    type: "text" | "number" | "boolean" | "list" | "entity" | "badge"
    value?: unknown
    values?: string[]
    id?: string
    name?: string
    schema?: string
    color?: "success" | "warning" | "error" | "info"
  }
}

`PreviewValue`

Typed value for preview display

type PreviewValue = {
  type: "text" | "number" | "boolean" | "list" | "entity" | "badge"
  value?: unknown
  values?: string[]
  id?: string
  name?: string
  schema?: string
  color?: "success" | "warning" | "error" | "info"
}

`ToolDefinition`

type ToolDefinition = {
  tool_id?: string
  name?: string
  description?: string
  category?: "entity" | "email" | "taxonomy" | "rag" | "workflow"
  parameters?: object
  returns?: object
  requires_approval?: boolean
  enabled?: boolean
}

`SkillCategory`

type SkillCategory = "message" | "entity" | "document" | "classification" | "custom"

`AgentSource`

system: Pre-built by epilot (system skills)
custom: Created by organization

type AgentSource = "system" | "custom"

`SkillAvailability`

Where the skill/agent is available:

flows: Available in workflow automations
copilot: Available as a sub-agent in copilot
all: Available everywhere

type SkillAvailability = "flows" | "copilot" | "all"

`ExecutionContext`

Where the execution was triggered from:

flows: Triggered from workflow automation
copilot: Triggered from copilot assistant
api: Direct API call

type ExecutionContext = "flows" | "copilot" | "api"

`ExecutionPattern`

direct: Single LLM call, no tools
react: Multi-step reasoning with tool use

type ExecutionPattern = "direct" | "react"

`ExecutionMode`

automatic: Execute without human intervention
approval: Pause for human approval before tool execution
draft: Execute but mark output as draft for review

type ExecutionMode = "automatic" | "approval" | "draft"

`ExecutionStatus`

type ExecutionStatus = "pending" | "running" | "waiting_approval" | "completed" | "failed" | "cancelled"

`ParameterType`

Base types:

text: Text input field
textarea: Multi-line text input field
number: Numeric input field
boolean: Toggle switch
select: Dropdown selection (requires enum array)

Custom types (domain-specific):

entity-schema: Entity schema selector (fetches from Entity API)
entity-attribute

type ParameterType = "text" | "textarea" | "number" | "boolean" | "select" | "entity-schema" | "entity-attribute" | "entity-id" | "taxonomy" | "taxonomy-classification" | "shared-inbox" | "label"

`InputParameterDefinition`

type InputParameterDefinition = {
  name: string
  label: string
  type: "text" | "textarea" | "number" | "boolean" | "select" | "entity-schema" | "entity-attribute" | "entity-id" | "taxonomy" | "taxonomy-classification" | "shared-inbox" | "label"
  description?: string
  default?: unknown
  multi?: boolean
  dependsOn?: string
  visibleWhen?: Record<string, unknown[]>
  enum?: string[]
  minimum?: number
  maximum?: number
  step?: number
  minLength?: number
  maxLength?: number
  schemaFilter?: string[]
  attributeTypeFilter?: string[]
}

`InputParametersSchema`

type InputParametersSchema = {
  type: "object"
  parameters: Array<{
    name: string
    label: string
    type: "text" | "textarea" | "number" | "boolean" | "select" | "entity-schema" | "entity-attribute" | "entity-id" | "taxonomy" | "taxonomy-classification" | "shared-inbox" | "label"
    description?: string
    default?: unknown
    multi?: boolean
    dependsOn?: string
    visibleWhen?: Record<string, unknown[]>
    enum?: string[]
    minimum?: number
    maximum?: number
    step?: number
    minLength?: number
    maxLength?: number
    schemaFilter?: string[]
    attributeTypeFilter?: string[]
  }>
  required?: string[]
}

`ModelConfig`

type ModelConfig = {
  model_id?: string
  temperature?: number
  max_tokens?: number
}

`Error`

type Error = {
  error?: string
  message?: string
  details?: object
}

AI Agents API - OpenAPI 3.0

Usage​

Tree-shakeable import​

Operations​

createAgent​

listAgents​

getAgentById​

updateAgentById​

deleteAgentById​

executeAgent​

listExecutions​

getExecution​

cancelExecution​

getExecutionTrace​

approveExecution​

rejectExecution​

Schemas​

AgentId​

CreateAgentRequest​

UpdateAgentRequest​

AgentDefinition​

ListAgentsResponse​

ListExecutionsResponse​

ApproveExecutionRequest​

RejectExecutionRequest​

ExecuteAgentRequest​

ExecutionResponse​

ExecutionTrace​

ExecutionIteration​

PendingAction​

ExecutionError​

ExecutionMetrics​

ToolPreview​

PreviewActionType​

PreviewEntity​

PreviewChange​

PreviewValue​

ToolDefinition​

SkillCategory​

AgentSource​

SkillAvailability​

ExecutionContext​

ExecutionPattern​

ExecutionMode​

ExecutionStatus​

ParameterType​

InputParameterDefinition​

InputParametersSchema​

ModelConfig​

Error​

Usage

Tree-shakeable import

Operations

`createAgent`

`listAgents`

`getAgentById`

`updateAgentById`

`deleteAgentById`

`executeAgent`

`listExecutions`

`getExecution`

`cancelExecution`

`getExecutionTrace`

`approveExecution`

`rejectExecution`

Schemas

`AgentId`

`CreateAgentRequest`

`UpdateAgentRequest`

`AgentDefinition`

`ListAgentsResponse`

`ListExecutionsResponse`

`ApproveExecutionRequest`

`RejectExecutionRequest`

`ExecuteAgentRequest`

`ExecutionResponse`

`ExecutionTrace`

`ExecutionIteration`

`PendingAction`

`ExecutionError`

`ExecutionMetrics`

`ToolPreview`

`PreviewActionType`

`PreviewEntity`

`PreviewChange`

`PreviewValue`

`ToolDefinition`

`SkillCategory`

`AgentSource`

`SkillAvailability`

`ExecutionContext`

`ExecutionPattern`

`ExecutionMode`

`ExecutionStatus`

`ParameterType`

`InputParameterDefinition`

`InputParametersSchema`

`ModelConfig`

`Error`