Agent Instructions

Manage Agent Instructions, which are agents configured directly via conversation prompts. These endpoints allow you to create, retrieve, publish, and execute draft Agent instructions.

Upsert Draft Instruction

put

Upsert the draft version of the instruction

Path parameters

agent_idstringRequired

The UUID of the agent

Query parameters

tenant_idany ofOptional

Tenant Id

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

stringOptional

or

nullOptional

tenant_unit_idany ofOptional

Tenant Unit ID

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

stringOptional

or

nullOptional

Body

application/json

The request body

created_byany ofOptional

stringOptional

or

nullOptional

updated_byany ofOptional

stringOptional

or

nullOptional

created_by_roleany ofOptional

stringOptional

or

nullOptional

updated_by_roleany ofOptional

stringOptional

or

nullOptional

created_timeany ofOptional

string · date-timeOptional

or

nullOptional

updated_timeany ofOptional

string · date-timeOptional

or

nullOptional

llm_configobjectRequired

Configuration for the LLM model_name

structured_promptobject · Structured PromptRequired

Structured prompt in JSON format

text_promptstringRequired

Textual prompt for the agent

agent_modestringRequired

Mode of operation for the agent

product_retrieval_configany ofOptional

Configuration for the product retrieval used

objectOptional

or

nullOptional

featuresany ofOptional

Additional features in JSON format

objectOptional

or

nullOptional

variablesany ofOptional

Variables in JSON format

object[]Optional

or

nullOptional

Responses

200

Successful Response

application/json

created_byany ofOptional

Identifier of the creator

stringOptional

or

nullOptional

updated_byany ofOptional

Identifier of the last updater

stringOptional

or

nullOptional

created_by_roleany ofOptional

stringOptional

or

nullOptional

updated_by_roleany ofOptional

stringOptional

or

nullOptional

created_timestring · date-timeRequired

Timestamp of creation

updated_timestring · date-timeRequired

Timestamp of last update

llm_configobjectRequired

Configuration for the LLM model_name

structured_promptobject · Structured PromptRequired

Structured prompt in JSON format

text_promptstringRequired

Textual prompt for the agent

agent_modestringRequired

Mode of operation for the agent

product_retrieval_configany ofOptional

Configuration for the product retrieval used

objectOptional

or

nullOptional

featuresany ofOptional

Additional features in JSON format

objectOptional

or

nullOptional

variablesany ofOptional

Variables in JSON format

object[]Optional

or

nullOptional

idstringRequired

Unique identifier for the Agent Instruction

tenant_idstringRequired

Tenant identifier

tenant_unit_idstringRequired

Tenant unit identifier

agent_idstringRequired

Associated agent identifier

versionstringRequired

Version timestamp

is_deletedbooleanRequired

Indicates if the item is deleted

422

Validation Error

application/json

put

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

HTTPcURLJavaScriptPython

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

{
  "created_by": "text",
  "updated_by": "text",
  "created_by_role": "text",
  "updated_by_role": "text",
  "created_time": "2026-04-03T08:02:25.145Z",
  "updated_time": "2026-04-03T08:02:25.145Z",
  "llm_config": {},
  "structured_prompt": {},
  "text_prompt": "text",
  "tools_config": [
    {
      "tool": {
        "tool_type": {},
        "vendor_id": "text",
        "resource_id": "text",
        "tool_name": "text",
        "tool_parameters": {}
      },
      "prompt": "text",
      "approval_mode": "text",
      "approval_condition": {},
      "enable": true
    }
  ],
  "agent_mode": "text",
  "dataset_retrieval_config": {
    "datasets": [
      {
        "id": "text",
        "name": "text",
        "enable": true
      }
    ],
    "top_k": 1,
    "retrieval_mode": "text",
    "tool_enabled": false
  },
  "product_retrieval_config": {},
  "features": {},
  "variables": [
    {}
  ]
}

{
  "created_by": "text",
  "updated_by": "text",
  "created_by_role": "text",
  "updated_by_role": "text",
  "created_time": "2026-04-03T08:02:25.145Z",
  "updated_time": "2026-04-03T08:02:25.145Z",
  "llm_config": {},
  "structured_prompt": {},
  "text_prompt": "text",
  "tools_config": [
    {
      "tool": {
        "tool_type": {},
        "vendor_id": "text",
        "resource_id": "text",
        "tool_name": "text",
        "tool_parameters": {}
      },
      "prompt": "text",
      "approval_mode": "text",
      "approval_condition": {},
      "enable": true
    }
  ],
  "agent_mode": "text",
  "dataset_retrieval_config": {
    "datasets": [
      {
        "id": "text",
        "name": "text",
        "enable": true
      }
    ],
    "top_k": 1,
    "retrieval_mode": "text",
    "tool_enabled": false
  },
  "product_retrieval_config": {},
  "features": {},
  "variables": [
    {}
  ],
  "id": "text",
  "tenant_id": "text",
  "tenant_unit_id": "text",
  "agent_id": "text",
  "version": "text",
  "is_deleted": true
}

Get Draft Instruction

get

Get the draft version of the instruction

Path parameters

agent_idstringRequired

The UUID of the agent

Query parameters

tenant_idany ofOptional

Tenant Id

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

stringOptional

or

nullOptional

tenant_unit_idany ofOptional

Tenant Unit ID

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

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

created_byany ofOptional

Identifier of the creator

stringOptional

or

nullOptional

updated_byany ofOptional

Identifier of the last updater

stringOptional

or

nullOptional

created_by_roleany ofOptional

stringOptional

or

nullOptional

updated_by_roleany ofOptional

stringOptional

or

nullOptional

created_timestring · date-timeRequired

Timestamp of creation

updated_timestring · date-timeRequired

Timestamp of last update

llm_configobjectRequired

Configuration for the LLM model_name

structured_promptobject · Structured PromptRequired

Structured prompt in JSON format

text_promptstringRequired

Textual prompt for the agent

agent_modestringRequired

Mode of operation for the agent

product_retrieval_configany ofOptional

Configuration for the product retrieval used

objectOptional

or

nullOptional

featuresany ofOptional

Additional features in JSON format

objectOptional

or

nullOptional

variablesany ofOptional

Variables in JSON format

object[]Optional

or

nullOptional

idstringRequired

Unique identifier for the Agent Instruction

tenant_idstringRequired

Tenant identifier

tenant_unit_idstringRequired

Tenant unit identifier

agent_idstringRequired

Associated agent identifier

versionstringRequired

Version timestamp

is_deletedbooleanRequired

Indicates if the item is deleted

422

Validation Error

application/json

get

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

HTTPcURLJavaScriptPython

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

{
  "created_by": "text",
  "updated_by": "text",
  "created_by_role": "text",
  "updated_by_role": "text",
  "created_time": "2026-04-03T08:02:25.145Z",
  "updated_time": "2026-04-03T08:02:25.145Z",
  "llm_config": {},
  "structured_prompt": {},
  "text_prompt": "text",
  "tools_config": [
    {
      "tool": {
        "tool_type": {},
        "vendor_id": "text",
        "resource_id": "text",
        "tool_name": "text",
        "tool_parameters": {}
      },
      "prompt": "text",
      "approval_mode": "text",
      "approval_condition": {},
      "enable": true
    }
  ],
  "agent_mode": "text",
  "dataset_retrieval_config": {
    "datasets": [
      {
        "id": "text",
        "name": "text",
        "enable": true
      }
    ],
    "top_k": 1,
    "retrieval_mode": "text",
    "tool_enabled": false
  },
  "product_retrieval_config": {},
  "features": {},
  "variables": [
    {}
  ],
  "id": "text",
  "tenant_id": "text",
  "tenant_unit_id": "text",
  "agent_id": "text",
  "version": "text",
  "is_deleted": true
}

Publish Draft Instruction

post

Get the draft version of the instruction

Path parameters

agent_idstringRequired

The UUID of the agent

Query parameters

tenant_idany ofOptional

Tenant Id

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

stringOptional

or

nullOptional

tenant_unit_idany ofOptional

Tenant Unit ID

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

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

created_byany ofOptional

Identifier of the creator

stringOptional

or

nullOptional

updated_byany ofOptional

Identifier of the last updater

stringOptional

or

nullOptional

created_by_roleany ofOptional

stringOptional

or

nullOptional

updated_by_roleany ofOptional

stringOptional

or

nullOptional

created_timestring · date-timeRequired

Timestamp of creation

updated_timestring · date-timeRequired

Timestamp of last update

llm_configobjectRequired

Configuration for the LLM model_name

structured_promptobject · Structured PromptRequired

Structured prompt in JSON format

text_promptstringRequired

Textual prompt for the agent

agent_modestringRequired

Mode of operation for the agent

product_retrieval_configany ofOptional

Configuration for the product retrieval used

objectOptional

or

nullOptional

featuresany ofOptional

Additional features in JSON format

objectOptional

or

nullOptional

variablesany ofOptional

Variables in JSON format

object[]Optional

or

nullOptional

idstringRequired

Unique identifier for the Agent Instruction

tenant_idstringRequired

Tenant identifier

tenant_unit_idstringRequired

Tenant unit identifier

agent_idstringRequired

Associated agent identifier

versionstringRequired

Version timestamp

is_deletedbooleanRequired

Indicates if the item is deleted

422

Validation Error

application/json

post

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

HTTPcURLJavaScriptPython

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

{
  "created_by": "text",
  "updated_by": "text",
  "created_by_role": "text",
  "updated_by_role": "text",
  "created_time": "2026-04-03T08:02:25.145Z",
  "updated_time": "2026-04-03T08:02:25.145Z",
  "llm_config": {},
  "structured_prompt": {},
  "text_prompt": "text",
  "tools_config": [
    {
      "tool": {
        "tool_type": {},
        "vendor_id": "text",
        "resource_id": "text",
        "tool_name": "text",
        "tool_parameters": {}
      },
      "prompt": "text",
      "approval_mode": "text",
      "approval_condition": {},
      "enable": true
    }
  ],
  "agent_mode": "text",
  "dataset_retrieval_config": {
    "datasets": [
      {
        "id": "text",
        "name": "text",
        "enable": true
      }
    ],
    "top_k": 1,
    "retrieval_mode": "text",
    "tool_enabled": false
  },
  "product_retrieval_config": {},
  "features": {},
  "variables": [
    {}
  ],
  "id": "text",
  "tenant_id": "text",
  "tenant_unit_id": "text",
  "agent_id": "text",
  "version": "text",
  "is_deleted": true
}

List Agent Instructions

get

Path parameters

agent_idstringRequired

The UUID of the agent

Query parameters

pageintegerOptional

The page number

Default: 1

page_sizeintegerOptional

The number of items per page

Default: 10

tenant_idany ofOptional

Tenant Id

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

stringOptional

or

nullOptional

tenant_unit_idany ofOptional

Tenant Unit ID

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

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

page_numintegerRequired

Current page number

page_sizeintegerRequired

Number of items per page

total_countintegerRequired

Total number of items

total_pagesintegerRequired

Total number of pages

has_next_pagebooleanRequired

Whether there is a next page

422

Validation Error

application/json

get

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

HTTPcURLJavaScriptPython

GET /admin/api/v2/agents/{agent_id}/instructions 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": [
    {
      "created_by": "text",
      "updated_by": "text",
      "created_by_role": "text",
      "updated_by_role": "text",
      "created_time": "2026-04-03T08:02:25.145Z",
      "updated_time": "2026-04-03T08:02:25.145Z",
      "llm_config": {},
      "structured_prompt": {},
      "text_prompt": "text",
      "tools_config": [
        {
          "tool": {
            "tool_type": {},
            "vendor_id": "text",
            "resource_id": "text",
            "tool_name": "text",
            "tool_parameters": {}
          },
          "prompt": "text",
          "approval_mode": "text",
          "approval_condition": {},
          "enable": true
        }
      ],
      "agent_mode": "text",
      "dataset_retrieval_config": {
        "datasets": [
          {
            "id": "text",
            "name": "text",
            "enable": true
          }
        ],
        "top_k": 1,
        "retrieval_mode": "text",
        "tool_enabled": false
      },
      "product_retrieval_config": {},
      "features": {},
      "variables": [
        {}
      ],
      "id": "text",
      "tenant_id": "text",
      "tenant_unit_id": "text",
      "agent_id": "text",
      "version": "text",
      "is_deleted": true
    }
  ]
}

Run Specific Instruction

post

Run a specific instruction by ID

Path parameters

agent_idstring · uuidRequiredExample: e06f8e4f-fb57-450d-a8f1-661c7d655769

Query parameters

tenant_idany ofOptional

Tenant Id

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

stringOptional

or

nullOptional

tenant_unit_idany ofOptional

Tenant Unit ID

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

stringOptional

or

nullOptional

Body

application/json

queryany ofOptionalDefault: ""

stringOptional

or

nullOptional

inputsany ofOptional

Input variables

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

objectOptional

or

nullOptional

streamingbooleanOptionalDefault: false

filesany ofOptionalDefault: []

string[]Optional

or

nullOptional

response_typeany ofOptionalDefault: wfx

stringOptional

or

nullOptional

wfx_contextany ofOptionalDefault: {}

objectOptional

or

nullOptional

conversation_idany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

stringOptional

422

Validation Error

application/json

post

/admin/api/v2/agents/{agent_id}/instructions/draft/runs

HTTPcURLJavaScriptPython

POST /admin/api/v2/agents/{agent_id}/instructions/draft/runs 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