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_idstring · nullableOptional

Tenant Id

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

tenant_unit_idstring · nullableOptional

Tenant Unit ID

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

Body

application/json

The request body

created_bystring · nullableOptional

updated_bystring · nullableOptional

created_by_rolestring · nullableOptional

updated_by_rolestring · nullableOptional

created_timestring · date-time · nullableOptional

updated_timestring · date-time · nullableOptional

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_configobject · nullableOptional

Configuration for the product retrieval used

featuresobject · Features · nullableOptional

Additional features in JSON format

variablesobject[] · nullableOptional

Variables in JSON format

Responses

200

Successful Response

application/json

created_bystring · nullableOptional

Identifier of the creator

updated_bystring · nullableOptional

Identifier of the last updater

created_by_rolestring · nullableOptional

updated_by_rolestring · nullableOptional

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_configobject · nullableOptional

Configuration for the product retrieval used

featuresobject · Features · nullableOptional

Additional features in JSON format

variablesobject[] · nullableOptional

Variables in JSON format

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-07-16T07:28:54.618Z",
  "updated_time": "2026-07-16T07:28:54.618Z",
  "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-07-16T07:28:54.618Z",
  "updated_time": "2026-07-16T07:28:54.618Z",
  "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_idstring · nullableOptional

Tenant Id

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

tenant_unit_idstring · nullableOptional

Tenant Unit ID

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

Responses

200

Successful Response

application/json

created_bystring · nullableOptional

Identifier of the creator

updated_bystring · nullableOptional

Identifier of the last updater

created_by_rolestring · nullableOptional

updated_by_rolestring · nullableOptional

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_configobject · nullableOptional

Configuration for the product retrieval used

featuresobject · Features · nullableOptional

Additional features in JSON format

variablesobject[] · nullableOptional

Variables in JSON format

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-07-16T07:28:54.618Z",
  "updated_time": "2026-07-16T07:28:54.618Z",
  "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_idstring · nullableOptional

Tenant Id

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

tenant_unit_idstring · nullableOptional

Tenant Unit ID

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

Responses

200

Successful Response

application/json

created_bystring · nullableOptional

Identifier of the creator

updated_bystring · nullableOptional

Identifier of the last updater

created_by_rolestring · nullableOptional

updated_by_rolestring · nullableOptional

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_configobject · nullableOptional

Configuration for the product retrieval used

featuresobject · Features · nullableOptional

Additional features in JSON format

variablesobject[] · nullableOptional

Variables in JSON format

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-07-16T07:28:54.618Z",
  "updated_time": "2026-07-16T07:28:54.618Z",
  "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_idstring · nullableOptional

Tenant Id

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

tenant_unit_idstring · nullableOptional

Tenant Unit ID

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

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-07-16T07:28:54.618Z",
      "updated_time": "2026-07-16T07:28:54.618Z",
      "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_idstring · nullableOptional

Tenant Id

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

tenant_unit_idstring · nullableOptional

Tenant Unit ID

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

Body

application/json

querystring · nullableOptionalDefault: ""

inputsobject · Inputs · nullableOptional

Input variables

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

streamingbooleanOptionalDefault: false

filesstring[] · nullableOptionalDefault: []

response_typestring · nullableOptionalDefault: wfx

wfx_contextobject · Wfx Context · nullableOptionalDefault: {}

conversation_idstring · nullableOptional

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