Dry-run the composed request of an Agent version

POST /v1/agents/{agent_id}/versions/{version}/render

Composes the request the Agent version sends for one model request, in the order of agent-runtime.md section 3.2: the platform base it tracks or pins, the Organization layer it receives, its Agent layer (its template or its inline instructions), then the synthetic directive and context entries of the body, and answers every section with its token estimate, the stable prefix, the names of missing values and the lint cross-checks of its publish (1.55.0). It writes nothing: no Call, Audit or Usage event.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the prompts:read scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/agents/agt_.../versions/1/render" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

const response = await fetch(`${process.env.VOCAL_API}/v1/agents/agt_.../versions/1/render`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());

import os
import uuid

import requests

response = requests.post(
    f"{os.environ['VOCAL_API']}/v1/agents/agt_.../versions/1/render",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={},
)
print(response.status_code, response.text)

Parameters

Request body

Content type application/json, required: AgentPromptRenderRequest.

Responses

Fields of the 200 answer

The shape is PromptRenderResult.