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

nullOptional

tenant_unit_idany ofOptional

Tenant Unit ID

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

stringOptional

nullOptional

Body

The request body

created_byany ofOptional

stringOptional

nullOptional

updated_byany ofOptional

stringOptional

nullOptional

created_by_roleany ofOptional

stringOptional

nullOptional

updated_by_roleany ofOptional

stringOptional

nullOptional

created_timeany ofOptional

string · date-timeOptional

nullOptional

updated_timeany ofOptional

string · date-timeOptional

nullOptional

llm_configobjectRequired

Configuration for the LLM model_name

structured_promptobject · StructuredPromptRequired

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

nullOptional

featuresany ofOptional

Additional features in JSON format

objectOptional

nullOptional

variablesany ofOptional

Variables in JSON format

object[]Optional

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

put

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": "2025-09-03T18:55:51.541Z",
  "updated_time": "2025-09-03T18:55:51.541Z",
  "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": "2025-09-03T18:55:51.541Z",
  "updated_time": "2025-09-03T18:55:51.541Z",
  "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

nullOptional

tenant_unit_idany ofOptional

Tenant Unit ID

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

stringOptional

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

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": "2025-09-03T18:55:51.541Z",
  "updated_time": "2025-09-03T18:55:51.541Z",
  "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

nullOptional

tenant_unit_idany ofOptional

Tenant Unit ID

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

stringOptional

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

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": "2025-09-03T18:55:51.541Z",
  "updated_time": "2025-09-03T18:55:51.541Z",
  "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

nullOptional

tenant_unit_idany ofOptional

Tenant Unit ID

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

stringOptional

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

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": "2025-09-03T18:55:51.541Z",
      "updated_time": "2025-09-03T18:55:51.541Z",
      "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

nullOptional

tenant_unit_idany ofOptional

Tenant Unit ID

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

stringOptional

nullOptional

Body

queryany ofOptionalDefault: ""

stringOptional

nullOptional

inputsany ofOptional

Input variables

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

objectOptional

nullOptional

streamingbooleanOptionalDefault: false

filesany ofOptionalDefault: []

string[]Optional

nullOptional

response_typeany ofOptionalDefault: wfx

stringOptional

nullOptional

wfx_contextany ofOptionalDefault: {}

objectOptional

nullOptional

conversation_idany ofOptional

stringOptional

nullOptional

Responses

200

Successful Response

application/json

Responsestring

422

Validation Error

application/json

post

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

PreviousAgent Operations NextTools

Last updated 2 months ago

Was this helpful?