Agent Operations

Manageand operate agents. These endpoints allow you to create, retrieve, update, delete, and interact with agents through chats and background tasks.

Create Agent

post

API Layer: Create a new Agent

查询参数

tenant_idany of可选

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c

string可选

或

null可选

tenant_unit_idany of可选

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589

string可选

或

null可选

请求体

application/json

Request model for creating a workflow. Only includes fields that should be provided by the frontend.

icon_typeany of可选

Source type: 'emoji' or 'url'

string · enum可选可能的值:

或

null可选

iconany of可选

Raw icon value: emoji char, full URL, or gallery key

string可选

或

null可选

icon_backgroundany of可选

Hex background color behind the icon

Default: #FFF

string可选

或

null可选

created_byany of可选

string可选

或

null可选

updated_byany of可选

string可选

或

null可选

created_by_roleany of可选

string可选

或

null可选

updated_by_roleany of可选

string可选

或

null可选

created_timeany of可选

string · date-time可选

或

null可选

updated_timeany of可选

string · date-time可选

或

null可选

modestring · enum必填

Workflow mode, e.g., chat or job

Example: job可能的值:

typestring · enum必填

Agent type (single-agent, multi-agent) - legacy types (flow, instruction, tool) are deprecated

Example: single-agent可能的值:

namestring必填

Workflow name

Example: test_workflow_name

descriptionany of可选

Workflow description

Default: ""Example: test_description

string可选

或

null可选

tagsstring[]可选

List of tags

Default: []Example: test_tag

is_favoriteboolean可选

Indicates if the item is marked as favorite

Default: false

extend_propertiesany of可选

Extend properties

Example: {}

object可选

或

null可选

响应

201

Successful Response

application/json

422

Validation Error

application/json

post

/admin/api/v2/agents

HTTPcURLJavaScriptPython

POST /admin/api/v2/agents HTTP/1.1
Host: api.workfx.ai
Content-Type: application/json
Accept: */*
Content-Length: 260

{
  "description": "A standard chat flow agent for general purposes",
  "icon": "🤖",
  "icon_background": "#EFF1F5",
  "icon_type": "emoji",
  "is_favorite": false,
  "mode": "flow-chat",
  "name": "Standard Chat Flow Agent",
  "tags": [
    "flow",
    "chat",
    "single-agent"
  ],
  "type": "single-agent"
}

{
  "icon_type": "emoji",
  "icon": "text",
  "icon_background": "#FFF",
  "created_by": "text",
  "updated_by": "text",
  "created_by_role": "text",
  "updated_by_role": "text",
  "created_time": "2026-01-30T20:35:55.717Z",
  "updated_time": "2026-01-30T20:35:55.717Z",
  "mode": "job",
  "type": "single-agent",
  "name": "test_workflow_name",
  "description": "test_description",
  "abilities": {
    "file_upload": {
      "enabled": true
    }
  },
  "tags": "test_tag",
  "is_favorite": false,
  "extend_properties": {},
  "id": "22a976a1-4f6d-4357-a167-26684daa60c5",
  "tenant_id": "40d39c4b-9585-4123-8fd4-f1cc23a1184c",
  "tenant_unit_id": "da114de3-d7e6-4161-bc55-0ce85dbee589",
  "status": "ACTIVE",
  "code": "text",
  "definition_id": "text",
  "definition_type": "flow",
  "ab_test_id": "text",
  "ab_test_enabled": false,
  "usage_guide": "text",
  "visibility": {},
  "agent_definition_entity": {},
  "variables": [
    {}
  ],
  "icon_url": "text"
}

List Agents

get

API Layer: Retrieve a list of Agents with pagination and filtering.

查询参数

page_numinteger可选

Current page number

Default: 1

page_sizeinteger可选

Items per page

Default: 20

is_favoriteany of可选

Filter by favorite status

boolean可选

或

null可选

tagsany of可选

Filter by tags

string[]可选

或

null可选

modeany of可选

Filter by mode (flow-chat | flow-job | instruction-chat | multi-agent-flow-chat | multi-agent-flow-job | multi-agent-instruction-chat)

string可选

或

null可选

nameany of可选

Filter by name (fuzzy match)

string可选

或

null可选

orderany of可选

order by: 'recent'(default) or 'oldest'

Default: recent

string可选

或

null可选

exclude_draftany of可选

Exclude draft agents

Default: false

boolean可选

或

null可选

agent_idsany of可选

Filter by agent ids

string[]可选

或

null可选

typeany of可选

Filter by agent type ('single-agent' | 'multi-agent')

string可选

或

null可选

tenant_idany of可选

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c

string可选

或

null可选

tenant_unit_idany of可选

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589

string可选

或

null可选

响应

200

Successful Response

application/json

422

Validation Error

application/json

get

/admin/api/v2/agents

HTTPcURLJavaScriptPython

GET /admin/api/v2/agents HTTP/1.1
Host: api.workfx.ai
Accept: */*

{
  "page_num": 1,
  "page_size": 1,
  "total_count": 1,
  "total_pages": 1,
  "has_next_page": true,
  "data": [
    {
      "icon_type": "emoji",
      "icon": "text",
      "icon_background": "#FFF",
      "created_by": "text",
      "updated_by": "text",
      "created_by_role": "text",
      "updated_by_role": "text",
      "created_time": "2026-01-30T20:35:55.717Z",
      "updated_time": "2026-01-30T20:35:55.717Z",
      "mode": "job",
      "type": "single-agent",
      "name": "test_workflow_name",
      "description": "test_description",
      "abilities": {
        "file_upload": {
          "enabled": true
        }
      },
      "tags": "test_tag",
      "is_favorite": false,
      "extend_properties": {},
      "id": "22a976a1-4f6d-4357-a167-26684daa60c5",
      "tenant_id": "40d39c4b-9585-4123-8fd4-f1cc23a1184c",
      "tenant_unit_id": "da114de3-d7e6-4161-bc55-0ce85dbee589",
      "status": "ACTIVE",
      "code": "text",
      "definition_id": "text",
      "definition_type": "flow",
      "ab_test_id": "text",
      "ab_test_enabled": false,
      "usage_guide": "text",
      "visibility": {},
      "agent_definition_entity": {},
      "variables": [
        {}
      ],
      "icon_url": "text"
    }
  ]
}

Get Agent

get

API Layer: Retrieve a Agent by ID

路径参数

agent_idstring必填

查询参数

tenant_idany of可选

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c

string可选

或

null可选

tenant_unit_idany of可选

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589

string可选

或

null可选

响应

200

Successful Response

application/json

422

Validation Error

application/json

get

/admin/api/v2/agents/{agent_id}

HTTPcURLJavaScriptPython

GET /admin/api/v2/agents/{agent_id} HTTP/1.1
Host: api.workfx.ai
Accept: */*

{
  "icon_type": "emoji",
  "icon": "text",
  "icon_background": "#FFF",
  "created_by": "text",
  "updated_by": "text",
  "created_by_role": "text",
  "updated_by_role": "text",
  "created_time": "2026-01-30T20:35:55.717Z",
  "updated_time": "2026-01-30T20:35:55.717Z",
  "mode": "job",
  "type": "single-agent",
  "name": "test_workflow_name",
  "description": "test_description",
  "abilities": {
    "file_upload": {
      "enabled": true
    }
  },
  "tags": "test_tag",
  "is_favorite": false,
  "extend_properties": {},
  "id": "22a976a1-4f6d-4357-a167-26684daa60c5",
  "tenant_id": "40d39c4b-9585-4123-8fd4-f1cc23a1184c",
  "tenant_unit_id": "da114de3-d7e6-4161-bc55-0ce85dbee589",
  "status": "ACTIVE",
  "code": "text",
  "definition_id": "text",
  "definition_type": "flow",
  "ab_test_id": "text",
  "ab_test_enabled": false,
  "usage_guide": "text",
  "visibility": {},
  "agent_definition_entity": {},
  "variables": [
    {}
  ],
  "icon_url": "text"
}

Get Agent By Code

get

API Layer: Retrieve a Agent by code

路径参数

agent_codestring必填

响应

200

Successful Response

application/json

422

Validation Error

application/json

get

/admin/api/v2/agents/code/{agent_code}

HTTPcURLJavaScriptPython

GET /admin/api/v2/agents/code/{agent_code} HTTP/1.1
Host: api.workfx.ai
Accept: */*

{
  "icon_type": "emoji",
  "icon": "text",
  "icon_background": "#FFF",
  "created_by": "text",
  "updated_by": "text",
  "created_by_role": "text",
  "updated_by_role": "text",
  "created_time": "2026-01-30T20:35:55.717Z",
  "updated_time": "2026-01-30T20:35:55.717Z",
  "mode": "job",
  "type": "single-agent",
  "name": "test_workflow_name",
  "description": "test_description",
  "abilities": {
    "file_upload": {
      "enabled": true
    }
  },
  "tags": "test_tag",
  "is_favorite": false,
  "extend_properties": {},
  "id": "22a976a1-4f6d-4357-a167-26684daa60c5",
  "tenant_id": "40d39c4b-9585-4123-8fd4-f1cc23a1184c",
  "tenant_unit_id": "da114de3-d7e6-4161-bc55-0ce85dbee589",
  "status": "ACTIVE",
  "code": "text",
  "definition_id": "text",
  "definition_type": "flow",
  "ab_test_id": "text",
  "ab_test_enabled": false,
  "usage_guide": "text",
  "visibility": {},
  "agent_definition_entity": {},
  "variables": [
    {}
  ],
  "icon_url": "text"
}

Update Agent

put

API Layer: Update an existing Agent

路径参数

agent_idstring必填

查询参数

tenant_idany of可选

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c

string可选

或

null可选

tenant_unit_idany of可选

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589

string可选

或

null可选

请求体

application/json

icon_typeany of可选

Type of icon used

Example: emoji

string可选

或

null可选

iconany of可选

Icon representation

Example: 🤖

string可选

或

null可选

icon_backgroundany of可选

Background color of the icon

Example: #EFF1F5

string可选

或

null可选

nameany of可选

Workflow name

Example: test_workflow_name

string可选

或

null可选

descriptionany of可选

Workflow description

Example: test_description

string可选

或

null可选

tagsany of可选

List of tags

Example: test_tag

string[]可选

或

null可选

is_favoriteany of可选

Indicates if the item is marked as favorite

boolean可选

或

null可选

statusany of可选

Workflow status

Example: ACTIVE

string可选

或

null可选

ab_test_idany of可选

AB test config ID

string · uuid可选

或

null可选

ab_test_enabledany of可选

Indicates if AB testing is enabled

boolean可选

或

null可选

extend_propertiesany of可选

Extend properties

Example: {}

object可选

或

null可选

usage_guideany of可选

Usage guide

string可选

或

null可选

响应

200

Successful Response

application/json

422

Validation Error

application/json

put

/admin/api/v2/agents/{agent_id}

HTTPcURLJavaScriptPython

PUT /admin/api/v2/agents/{agent_id} HTTP/1.1
Host: api.workfx.ai
Content-Type: application/json
Accept: */*
Content-Length: 300

{
  "icon_type": "emoji",
  "icon": "🤖",
  "icon_background": "#EFF1F5",
  "name": "test_workflow_name",
  "description": "test_description",
  "tags": "test_tag",
  "is_favorite": false,
  "status": "ACTIVE",
  "ab_test_id": "123e4567-e89b-12d3-a456-426614174000",
  "ab_test_enabled": false,
  "extend_properties": {},
  "usage_guide": "text"
}

{
  "icon_type": "emoji",
  "icon": "text",
  "icon_background": "#FFF",
  "created_by": "text",
  "updated_by": "text",
  "created_by_role": "text",
  "updated_by_role": "text",
  "created_time": "2026-01-30T20:35:55.717Z",
  "updated_time": "2026-01-30T20:35:55.717Z",
  "mode": "job",
  "type": "single-agent",
  "name": "test_workflow_name",
  "description": "test_description",
  "abilities": {
    "file_upload": {
      "enabled": true
    }
  },
  "tags": "test_tag",
  "is_favorite": false,
  "extend_properties": {},
  "id": "22a976a1-4f6d-4357-a167-26684daa60c5",
  "tenant_id": "40d39c4b-9585-4123-8fd4-f1cc23a1184c",
  "tenant_unit_id": "da114de3-d7e6-4161-bc55-0ce85dbee589",
  "status": "ACTIVE",
  "code": "text",
  "definition_id": "text",
  "definition_type": "flow",
  "ab_test_id": "text",
  "ab_test_enabled": false,
  "usage_guide": "text",
  "visibility": {},
  "agent_definition_entity": {},
  "variables": [
    {}
  ],
  "icon_url": "text"
}

Delete Agent

delete

API Layer: Delete a Agent by ID

路径参数

agent_idstring必填

查询参数

tenant_idany of可选

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c

string可选

或

null可选

tenant_unit_idany of可选

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589

string可选

或

null可选

响应

204

Successful Response

application/json

422

Validation Error

application/json

delete

/admin/api/v2/agents/{agent_id}

HTTPcURLJavaScriptPython

DELETE /admin/api/v2/agents/{agent_id} HTTP/1.1
Host: api.workfx.ai
Accept: */*

{}

Invoke Agent Chat

post

API Layer: Invoke a Agent

路径参数

agent_idstring必填

查询参数

tenant_idany of可选

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c

string可选

或

null可选

tenant_unit_idany of可选

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589

string可选

或

null可选

请求体

application/json

queryany of可选Default: ""

string可选

或

null可选

inputsany of可选

Input variables

Example: {"var1":"1","var2":2}

object可选

或

null可选

streamingboolean可选Default: false

filesany of可选Default: []

string[]可选

或

null可选

response_typeany of可选Default: wfx

string可选

或

null可选

wfx_contextany of可选Default: {}

object可选

或

null可选

conversation_idany of可选

string可选

或

null可选

响应

200

Successful Response

application/json

响应string

422

Validation Error

application/json

post

/admin/api/v2/agents/{agent_id}/chat

HTTPcURLJavaScriptPython

POST /admin/api/v2/agents/{agent_id}/chat HTTP/1.1
Host: api.workfx.ai
Content-Type: application/json
Accept: */*
Content-Length: 142

{
  "query": "",
  "inputs": {
    "var1": "1",
    "var2": 2
  },
  "streaming": false,
  "files": [
    "text"
  ],
  "response_type": "wfx",
  "wfx_context": {},
  "conversation_id": "text"
}

text

Resume Invoke Agent Chat

post

API Layer: Resume Invoke a Agent

路径参数

agent_idstring必填

查询参数

tenant_idany of可选

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c

string可选

或

null可选

tenant_unit_idany of可选

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589

string可选

或

null可选

请求体

application/json

queryany of可选Default: ""

string可选

或

null可选

inputsany of可选

Input variables

Example: {"var1":"1","var2":2}

object可选

或

null可选

streamingboolean可选Default: false

filesany of可选Default: []

string[]可选

或

null可选

response_typeany of可选Default: wfx

string可选

或

null可选

wfx_contextany of可选Default: {}

object可选

或

null可选

conversation_idany of可选

string可选

或

null可选

interrupt_inputsobject · InterruptInputs必填

is_interruptedboolean必填

flow_run_idstring必填

响应

200

Successful Response

application/json

响应string

422

Validation Error

application/json

post

/admin/api/v2/agents/{agent_id}/chat/resume

HTTPcURLJavaScriptPython

POST /admin/api/v2/agents/{agent_id}/chat/resume HTTP/1.1
Host: api.workfx.ai
Content-Type: application/json
Accept: */*
Content-Length: 207

{
  "query": "",
  "inputs": {
    "var1": "1",
    "var2": 2
  },
  "streaming": false,
  "files": [
    "text"
  ],
  "response_type": "wfx",
  "wfx_context": {},
  "conversation_id": "text",
  "interrupt_inputs": {},
  "is_interrupted": true,
  "flow_run_id": "text"
}

text

Invoke Agent Job

post

API Layer: Invoke a Agent

路径参数

agent_idstring必填

查询参数

tenant_idany of可选

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c

string可选

或

null可选

tenant_unit_idany of可选

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589

string可选

或

null可选

请求体

application/json

queryany of可选Default: ""

string可选

或

null可选

inputsany of可选

Input variables

Example: {"var1":"1","var2":2}

object可选

或

null可选

streamingboolean可选Default: false

filesany of可选Default: []

string[]可选

或

null可选

response_typeany of可选Default: wfx

string可选

或

null可选

wfx_contextany of可选Default: {}

object可选

或

null可选

conversation_idany of可选

string可选

或

null可选

响应

200

Successful Response

application/json

响应string

422

Validation Error

application/json

post

/admin/api/v2/agents/{agent_id}/job

HTTPcURLJavaScriptPython

POST /admin/api/v2/agents/{agent_id}/job HTTP/1.1
Host: api.workfx.ai
Content-Type: application/json
Accept: */*
Content-Length: 142

{
  "query": "",
  "inputs": {
    "var1": "1",
    "var2": 2
  },
  "streaming": false,
  "files": [
    "text"
  ],
  "response_type": "wfx",
  "wfx_context": {},
  "conversation_id": "text"
}

text