# AI Agents API - OpenAPI 3.0

TypeScript SDK client for the epilot AI Agents API - OpenAPI 3.0: usage with @epilot/sdk, all operations and schemas.

- **Base URL:** `https://ai-agents.sls.epilot.io`
- **Full API Docs:** [https://docs.epilot.io/api/ai-agents](https://docs.epilot.io/api/ai-agents)

## Usage

```ts
import { epilot } from '@epilot/sdk'

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

### Tree-shakeable import

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

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

## Operations

**Agents Configuration**
- [`createAgent`](#createagent)
- [`listAgents`](#listagents)
- [`getAgentById`](#getagentbyid)
- [`updateAgentById`](#updateagentbyid)
- [`deleteAgentById`](#deleteagentbyid)

**Agent Execution**
- [`executeAgent`](#executeagent)
- [`listExecutions`](#listexecutions)
- [`getExecution`](#getexecution)
- [`cancelExecution`](#cancelexecution)
- [`getExecutionTrace`](#getexecutiontrace)
- [`approveExecution`](#approveexecution)
- [`rejectExecution`](#rejectexecution)

**Schemas**
- [`AgentId`](#agentid)
- [`CreateAgentRequest`](#createagentrequest)
- [`UpdateAgentRequest`](#updateagentrequest)
- [`AgentDefinition`](#agentdefinition)
- [`ListAgentsResponse`](#listagentsresponse)
- [`ListExecutionsResponse`](#listexecutionsresponse)
- [`ApproveExecutionRequest`](#approveexecutionrequest)
- [`RejectExecutionRequest`](#rejectexecutionrequest)
- [`ExecuteAgentRequest`](#executeagentrequest)
- [`ExecutionResponse`](#executionresponse)
- [`ExecutionTrace`](#executiontrace)
- [`ExecutionIteration`](#executioniteration)
- [`PendingAction`](#pendingaction)
- [`ExecutionError`](#executionerror)
- [`ExecutionMetrics`](#executionmetrics)
- [`ToolPreview`](#toolpreview)
- [`PreviewActionType`](#previewactiontype)
- [`PreviewEntity`](#previewentity)
- [`PreviewChange`](#previewchange)
- [`PreviewValue`](#previewvalue)
- [`ToolDefinition`](#tooldefinition)
- [`SkillCategory`](#skillcategory)
- [`AgentSource`](#agentsource)
- [`SkillAvailability`](#skillavailability)
- [`ExecutionContext`](#executioncontext)
- [`ExecutionPattern`](#executionpattern)
- [`ExecutionMode`](#executionmode)
- [`ExecutionStatus`](#executionstatus)
- [`ParameterType`](#parametertype)
- [`InputParameterDefinition`](#inputparameterdefinition)
- [`InputParametersSchema`](#inputparametersschema)
- [`ModelConfig`](#modelconfig)
- [`Error`](#error)

### `createAgent`

Create Agent definition

`POST /v1/agents`

```ts
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']
    }
  },
)
```

<details>
<summary>Response</summary>

```json
{
  "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"
}
```

</details>

---

### `listAgents`

List all agent configurations

`GET /v1/agents`

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

<details>
<summary>Response</summary>

```json
{
  "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"
}
```

</details>

---

### `getAgentById`

Get the agent configuration by ID

`GET /v1/agents/{agent_id}`

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

<details>
<summary>Response</summary>

```json
{
  "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"
}
```

</details>

---

### `updateAgentById`

Update the agent configuration by ID

`PUT /v1/agents/{agent_id}`

```ts
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']
    }
  },
)
```

<details>
<summary>Response</summary>

```json
{
  "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"
}
```

</details>

---

### `deleteAgentById`

Delete the agent configuration by ID

`DELETE /v1/agents/{agent_id}`

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

---

### `executeAgent`

Execute an agent

`POST /v1/agents/{agent_id}/execute`

```ts
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
  },
)
```

<details>
<summary>Response</summary>

```json
{
  "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"
}
```

</details>

---

### `listExecutions`

List executions

`GET /v1/executions`

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

<details>
<summary>Response</summary>

```json
{
  "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"
}
```

</details>

---

### `getExecution`

Get execution by ID

`GET /v1/executions/{execution_id}`

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

<details>
<summary>Response</summary>

```json
{
  "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"
}
```

</details>

---

### `cancelExecution`

Cancel execution

`DELETE /v1/executions/{execution_id}`

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

<details>
<summary>Response</summary>

```json
{
  "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"
}
```

</details>

---

### `getExecutionTrace`

Get execution trace/iterations

`GET /v1/executions/{execution_id}/trace`

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

<details>
<summary>Response</summary>

```json
{
  "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
}
```

</details>

---

### `approveExecution`

Approve pending action

`POST /v1/executions/{execution_id}/approve`

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

<details>
<summary>Response</summary>

```json
{
  "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"
}
```

</details>

---

### `rejectExecution`

Reject pending action

`POST /v1/executions/{execution_id}/reject`

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

<details>
<summary>Response</summary>

```json
{
  "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"
}
```

</details>

---

## 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"

```ts
type AgentId = string
```

### `CreateAgentRequest`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
type ApproveExecutionRequest = {
  reason?: string
}
```

### `RejectExecutionRequest`

```ts
type RejectExecutionRequest = {
  reason: string
}
```

### `ExecuteAgentRequest`

```ts
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`

```ts
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`

```ts
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`

```ts
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)

```ts
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`

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

### `ExecutionMetrics`

```ts
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.

```ts
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

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

### `PreviewEntity`

Entity reference for preview display

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

### `PreviewChange`

A single field change in the preview

```ts
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

```ts
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`

```ts
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`

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

### `AgentSource`

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

```ts
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

```ts
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

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

### `ExecutionPattern`

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

```ts
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

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

### `ExecutionStatus`

```ts
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

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

### `InputParameterDefinition`

```ts
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`

```ts
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`

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

### `Error`

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