v3

latestOpenAPI 3.0.02026-08-081996601.2 MB

Instructions

Test instruction

Tests an instruction template with supplied context and available tools. The endpoint evaluates Velocity expressions such as $tools, ${session.metadata.field}, or ${agent.metadata.field}, and returns the fully rendered template output. Use this operation to validate formatting, logic, or metadata-dependent behavior before you deploy instructions to agents.

post/v2/instructions/{instruction_id}/test

Path parameters

instruction_idstring required

The unique identifier for an instruction.

Example:ins_customer_support_init

The unique identifier of the instruction to test.

Query parameters

versioninteger

Example:1

The specific version of the instruction to test. If not specified, the platform uses the latest version.

Headers

Request-Timeoutinteger

The platform makes a best effort to complete the request in the specified seconds, or it times out.

Request-Timeout-Millisinteger

The platform makes a best effort to complete the request in the specified milliseconds, or it times out.

Request body

contextobject

Context data to use when rendering the instruction template. The platform merges this data into $session.metadata for template access.

Example: If you provide {"currentDate": "2024-01-15"}, you can access it in the template as $session.metadata.currentDate.

Example request

{
  "context": {
    "currentDate": "2024-01-15",
    "companyName": "Acme Corp"
  },
  "tools": []
}

Response

The rendered result of the instruction test.

rendered_instructionstring required

The instruction template rendered with the provided context.

Example response

{
  "rendered_instruction": "You are a helpful customer support agent for Acme Corp. Today's date is 2024-01-15. You have access to the following tools: Web Search, Email Sender"
}