Prompt Preview

The prompt preview API lets you render a role's prompts with sample context data, so you can verify template variable substitution and see the final prompt structure before an agent executes.

Preview Endpoint

POST /api/v1/agent-roles/:id/preview

This endpoint renders the role's system prompt, task template, and output template with the provided context, returning the rendered result.

Request Format

{
  "task_type": "ticket_task",
  "context": {
    "global": {
      "timestamp": "2025-01-15T10:30:00Z",
      "run_id": "run-abc-123"
    },
    "project": {
      "id": "project-uuid",
      "name": "My Project",
      "description": "A web application"
    },
    "ticket": {
      "id": "ticket-uuid",
      "title": "Add user authentication",
      "description": "Implement OAuth2 login flow",
      "acceptance_criteria": "Users can sign in with Google",
      "tags": "auth, security",
      "source": "user",
      "status": "in_progress",
      "priority": "high",
      "type": "feature",
      "slug": "add-user-auth",
      "complexity": "medium"
    },
    "pipeline": {
      "name": "Default",
      "step": "implement"
    },
    "role_local": {
      "name": "developer",
      "description": "Writes and maintains code"
    }
  }
}

Fields

Field	Type	Required	Description
`task_type`	string	Yes	Which template to render: `ticket_task`, `chat_task`, or `gate_eval`
`context`	object	No	Sample values for template variable substitution

Context Object

The context object has five optional sections, each containing key-value pairs that map to template variables:

Section	Maps to Variables
`global`	`{{ global.timestamp }}`, `{{ global.run_id }}`
`project`	`{{ project.id }}`, `{{ project.name }}`, `{{ project.description }}`
`ticket`	`{{ ticket.id }}`, `{{ ticket.title }}`, `{{ ticket.description }}`, etc.
`pipeline`	`{{ pipeline.name }}`, `{{ pipeline.step }}`
`role_local`	`{{ role_local.name }}`, `{{ role_local.description }}`

Values should be provided as strings or JSON values. String values are used directly; other JSON types are serialized to their string representation.

Response Format

{
  "system_prompt": "You are a senior software developer...",
  "task_instructions": "Implement the following ticket:\n\nTitle: Add user authentication\n...",
  "output_instructions": "Task complete. Summarize what was done.",
  "full_prompt": "<prompt>\n<system>...</system>\n<context>...</context>\n<instructions>...</instructions>\n<output>...</output>\n</prompt>"
}

Response Fields

Field	Description
`system_prompt`	The rendered system prompt with variables substituted
`task_instructions`	The rendered task template (e.g., `ticket_task`) with variables substituted
`output_instructions`	The rendered output template (`agent_done`) with variables substituted
`full_prompt`	The complete prompt assembled into XML structure with all sections

The full_prompt field shows the final XML-wrapped structure:

<prompt>
  <system>rendered system prompt</system>
  <context>rendered context sections</context>
  <instructions>rendered task instructions</instructions>
  <output>rendered output instructions</output>
</prompt>

Usage Examples

Preview a Ticket Task

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "ticket_task",
    "context": {
      "ticket": {
        "title": "Fix login timeout",
        "description": "Users are getting logged out after 5 minutes",
        "priority": "critical",
        "type": "bug"
      },
      "project": {
        "name": "Web App"
      }
    }
  }' \
  https://your-instance.com/api/v1/agent-roles/:id/preview

Preview a Chat Task

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "chat_task",
    "context": {
      "project": {
        "name": "My Project"
      }
    }
  }' \
  https://your-instance.com/api/v1/agent-roles/:id/preview

Note that for chat previews, the {{ chat.message }} variable will not be substituted since it is populated at runtime from the actual user message.

Preview a Gate Evaluation

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "gate_eval",
    "context": {
      "ticket": {
        "title": "Add pagination",
        "acceptance_criteria": "List endpoints return paginated results"
      }
    }
  }' \
  https://your-instance.com/api/v1/agent-roles/:id/preview

Error Handling

Status	Cause
`404 Not Found`	Role ID does not exist
`422 Validation Error`	Invalid `task_type` (must be `ticket_task`, `chat_task`, or `gate_eval`)

Limitations

The preview endpoint provides a simplified rendering compared to the full worker execution:

Context blocks ({{ context.roles }}, {{ context.documents }}, etc.) are not populated. These require live platform data that is only available during actual execution.
Memory ({{ context.memory }}) is not retrieved. Memory lookup requires the memory store and a real task context.
Git variables ({{ git.branch }}, {{ git.work_dir }}) are not populated. These are set up by the execution environment.
Agent variables ({{ agent.name }}, {{ agent.model }}) are not populated. These come from the agent assignment at runtime.

The preview is best used for verifying that your template structure is correct, your variable references are properly formatted, and the overall prompt flow reads well with sample data.

Prompt Preview

On this page