Agent Execution Queue#

This template shows the current authenticated API path end to end: create an agent, queue an execution request, and poll the resulting job envelope until it completes.

What Problem It Solves#

Use this template when you need to answer four basic integration questions quickly:

Can I authenticate against vex-api as it exists today?
What JSON do I send to create an agent?
What comes back when I queue an execution?
What does the completed job envelope look like when I poll it?

Uses#

Prerequisites#

A running vex-api instance
The public base URL for that instance
The VEX_JWT_SECRET used by that instance
Node.js 18+ or any other way to sign an HS256 JWT

Auth is required

POST /api/v1/agents, POST /api/v1/agents/{id}/execute, and GET /api/v1/jobs/{id} all require a bearer JWT. There is no token-mint endpoint today, so evaluators need to sign a token locally from the same VEX_JWT_SECRET.

Step 1: Confirm the Service Is Up#

Bash

curl -sS https://your-service.up.railway.app/health

Expected response shape:

JSON

{
  "status": "healthy",
  "version": "0.1.7",
  "timestamp": "2026-04-04T10:15:32Z"
}

Step 2: Mint an Integration JWT#

Download the zero-dependency helper script:

mint-integration-jwt.mjs

Run it with the same secret configured on the service:

Bash

export VEX_JWT_SECRET="replace-with-your-32-char-secret"
export VEX_SUB="provnai-evaluator"
export VEX_ROLE="user"
node ./mint-integration-jwt.mjs

Expected output:

TEXT

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Save that value as TOKEN in your shell for the next steps.

Step 3: Create an Agent#

Download the request body:

create-agent-request.json

Exact request body:

JSON

{
  "name": "Integration Evaluator",
  "role": "You are a concise evaluator for a PROVNAI integration.",
  "max_depth": 3,
  "spawn_shadow": false
}

Request:

Bash

curl -sS https://your-service.up.railway.app/api/v1/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data @create-agent-request.json

Expected response shape:

JSON

{
  "id": "2d8a5f57-9e84-4510-aa0f-7fef6154d145",
  "name": "Integration Evaluator",
  "role": "You are a concise evaluator for a PROVNAI integration.",
  "generation": 0,
  "fitness": 1.0,
  "created_at": "2026-04-04T10:20:14Z"
}

Artifact produced:

A persisted agent record with a stable UUID

Step 4: Queue an Execution#

Download the request body:

execute-agent-request.json

Exact request body:

JSON

{
  "prompt": "Summarize the current health of this deployment in one sentence.",
  "enable_adversarial": false,
  "max_debate_rounds": 3
}

Request:

Bash

curl -sS https://your-service.up.railway.app/api/v1/agents/2d8a5f57-9e84-4510-aa0f-7fef6154d145/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data @execute-agent-request.json

Expected response shape:

JSON

{
  "agent_id": "2d8a5f57-9e84-4510-aa0f-7fef6154d145",
  "response": "Job queued: 8b9d5f68-8d5d-4971-bf12-44257f0d7fc0",
  "verified": false,
  "confidence": 1.0,
  "context_hash": "pending",
  "latency_ms": 14
}

Artifact produced:

A queued execution job

How to inspect it:

Extract the UUID from the response string and use it as the job ID in the next step

Step 5: Poll the Job#

Request:

Bash

curl -sS https://your-service.up.railway.app/api/v1/jobs/8b9d5f68-8d5d-4971-bf12-44257f0d7fc0 \
  -H "Authorization: Bearer $TOKEN"

Expected response shape:

JSON

{
  "job_id": "8b9d5f68-8d5d-4971-bf12-44257f0d7fc0",
  "status": "completed",
  "result": {
    "job_id": "8b9d5f68-8d5d-4971-bf12-44257f0d7fc0",
    "agent_id": "2d8a5f57-9e84-4510-aa0f-7fef6154d145",
    "prompt": "Summarize the current health of this deployment in one sentence.",
    "response": "The deployment is healthy and responding normally.",
    "tokens_used": 42,
    "completed_at": "2026-04-04T10:20:19Z",
    "success": true,
    "error": null
  },
  "error": null,
  "queued_at": "2026-04-04T10:20:14Z",
  "attempts": 1
}

Artifact produced:

A completed AgentJobResult object inside the result field

How to verify or inspect the result:

Check status first. A successful run should move from pending or running to completed.
Inspect result.success, result.response, result.tokens_used, and result.completed_at.
If the run fails, inspect error and result.error.

Current Limitations#

The JWT bootstrap is external. There is no built-in token issuance endpoint for integrators.
The execution acknowledgement embeds the job ID inside response instead of returning job_id as a top-level field.
The queue acknowledgement returns verified: false and context_hash: "pending" because it is a submission response, not a final proof receipt.
max_depth above 10 is rejected at agent creation time.