Skip to main content
POST https://api.prysm1.com/v1/agent/run · Requires authentication
Where /v1/chat/completions routes one prompt to one model and /v2/orchestrate crosses several models for one robust answer, the agent endpoints execute a goal as a bounded, multi-step trajectory — planning, crossing models, and finishing on their own. Two guarantees set PRYSM agents apart, both enforced server-side and verifiable:
  • A hard cost ceiling. A run with cap $C never spends more than $C — not “+5%”, at most $C. Before each step, AgentGuard bounds the step’s worst-case cost and only runs it if it fits the remaining budget, downshifting intensity (Laser → Halo → Foton) under pressure instead of overspending. Hyper-frontier models are ring-fenced out of flat-tier agents by construction.
  • A tamper-evident trajectory. Every step is hashed into a chain + merkle root — a PrysmProof trajectory. Reorder, drop, or edit any step and verification fails. Anyone can verify a trajectory with POST /v1/agent/verify — no account required.

​
Run an agent

POST /v1/agent/run · Requires authentication

​
Authorization

​
Authorization
string
required
Your secret key as a bearer token: Bearer prysm_sk_...

​
Body

​
goal
string
required
The goal for the agent to accomplish autonomously. (prompt is accepted as an alias.)
​
max_cost_usd
number
The hard spend ceiling for the entire run, in USD. The run can never exceed it. Defaults to 5× the plan’s per-query envelope. A request above your tier’s limit is rejected with 402 before any model runs.
​
max_cost_per_step
number
Optional hard cap for a single step (clamped to ≤ the run cap). Useful to keep a high-fan-out agent from spending most of its budget on one step. AgentGuard binds it when planning each step.
​
max_steps
integer
default:"50"
Maximum number of steps before the run stops gracefully. Hard ceiling: 1000.
​
policy
string
default:"balanced"
The objective dial: efficiency, balanced, or depth. Sets the starting intensity; the guard still downshifts under budget pressure.
​
idempotency_key
string
A retry-safe key. A second /v1/agent/run with the same key (same user) returns the original run without spending again — no double-charge.
​
max_tokens
integer
default:"1024"
Maximum tokens per underlying model call.
​
temperature
number
default:"0.5"
Sampling temperature passed to the underlying models.

​
Response

​
object
string
Always agent.run.
​
run_id
string
Unique run id, e.g. agt_9f8e.... Use it with the other agent endpoints.
​
status
string
complete, budget_exhausted, or max_steps_reached. The run never errors out from budget pressure — it stops gracefully and returns the best partial result.
​
policy
string
The policy the run used.
​
strategy
string
The primary per-step strategy.
​
plan
string[]
The sub-tasks the goal was decomposed into.
​
steps_taken
integer
How many steps executed.
​
cost_consumed_usd
number
Total spend — always ≤ max_cost_usd.
​
max_cost_usd
number
The hard cap that was enforced.
​
remaining_usd
number
Budget left.
​
trajectory_proof
string
The run’s PrysmProof trajectory root, e.g. sha256:a1b2c3d4e5f6....
​
output
string
The consolidated final result.
​
steps
array
The per-step trajectory.
​
alerts
array
Budget-pressure alerts (70% → WARNING/Halo, 90% → CRITICAL/Foton).
​
budget
object
Plan envelope, tier limit, multiplier, and the enforced cap.
​
final_message
string
Set when a run stopped on budget/steps, e.g. “agent stopped after 7 steps (budget_exhausted); 4.98of4.98 of 5.00 spent.”

​
List runs

GET /v1/agent/runs?limit=50 · Requires authentication
Returns your agent runs, newest first (lightweight — no per-step trajectory). limit is capped at 200.
​
object
string
Always list.
​
count
integer
Number of runs returned.
​
data
array
Run summaries (same shape as the run state, plus a truncated goal).

​
Get run state

GET /v1/agent/{run_id} · Requires authentication
Lightweight state for polling — status, cost_consumed_usd, steps_taken, trajectory_proof, output. Returns 404 if the run isn’t yours.

​
Get the full trajectory

GET /v1/agent/{run_id}/trajectory · Requires authentication
The full step-by-step audit log plus a server-side re-verification of the stored proof.
​
full
boolean
default:"false"
When true, returns the full 64-hex per-step hashes and step proofs (instead of the truncated display form) plus a ready-to-POST verify_request bundle — pipe it straight into POST /v1/agent/verify to independently re-confirm the run without trusting this server. This closes the external-verification loop end-to-end.
​
steps
array
Every step with its hashes, cost, intensity, and per-step proof (full 64-hex when ?full=true).
​
verification
object
Deterministic-replay result: { "valid": true, "recomputed_proof": "sha256:...", "n_steps": N, "mismatched_steps": [] }.
​
verify_request
object
Present only with ?full=true: a self-contained bundle (run_id, trajectory_proof, policy, strategy, output_hash, steps, step_proofs) that POSTs directly to /v1/agent/verify and returns valid: true.

​
Cancel a run

POST /v1/agent/{run_id}/cancel · Requires authentication
V1 runs execute synchronously, so by the time a cancel arrives the run is already terminal — the endpoint returns its final state and partial result (idempotent), rather than pretending to interrupt it.

​
Verify a trajectory

POST /v1/agent/verify · Public — no authentication
Independently verify a self-contained trajectory bundle by deterministic replay: recompute each step proof, the chain of custody, the merkle root, and the trajectory root, then check it matches the claimed trajectory_proof. Lets an external auditor confirm a PRYSM agent’s trajectory without trusting (or even reaching) PRYSM’s servers. Verification needs the full (64-hex) per-step hashes. Capped at 2,000 steps.
​
run_id
string
required
The run id the proof was computed over.
​
trajectory_proof
string
required
The claimed sha256:... root to check.
​
steps
array
required
The step records (index, model, input_hash, output_hash, cost_usd, confidence, timestamp).
​
policy
string
default:"balanced"
The run’s policy.
​
strategy
string
default:"single"
The run’s primary strategy.
​
output
string
The raw final output (we hash it). Or supply output_hash directly.
​
step_proofs
string[]
Optional claimed per-step proofs — when supplied, a tamper is localized in mismatched_steps.
​
valid
boolean
Whether the trajectory verifies.
​
recomputed_proof
string
The proof recomputed from the supplied data.
​
mismatched_steps
integer[]
Indices of steps whose proof didn’t match (empty when valid).

​
Errors

StatuserrorMeaning
400no_goalgoal (or prompt) was empty.
401—Missing or invalid API key.
402budget_exceeds_tier_limitmax_cost_usd exceeds your tier’s ceiling (5× the plan envelope).
404run_not_foundNo such run, or it isn’t yours.
413request_too_largeRequest body exceeds the server limit (default 2 MiB).
502agent_errorThe runner raised unexpectedly.
503no_provider_availableNo provider API keys are configured on the server.
from prysm import Prysm

client = Prysm()
run = client.agent(
    "Research the top 3 AI gateways, compare pricing, and draft a one-page brief.",
    max_cost_usd=1.00,
)
print(run["status"], run["cost_consumed_usd"], "/", run["max_cost_usd"])
print(run["trajectory_proof"])

{
  "object": "agent.run",
  "run_id": "agt_9f8e7d6c5b4a39281706f5e4",
  "status": "complete",
  "policy": "balanced",
  "strategy": "ensemble_moa",
  "plan": [
    "Research the top 3 AI gateways",
    "Compare their pricing",
    "Draft a one-page brief"
  ],
  "steps_taken": 4,
  "cost_consumed_usd": 0.0184,
  "max_cost_usd": 1.0,
  "remaining_usd": 0.9816,
  "trajectory_proof": "sha256:a1b2c3d4e5f60718",
  "output": "One-page brief: across the three gateways, the trade-offs cluster around...",
  "steps": [
    {
      "index": 0,
      "role": "subtask",
      "model": "claude-sonnet-4.5",
      "intensity": "Laser",
      "strategy": "ensemble_moa",
      "cost_usd": 0.0061,
      "confidence": 0.86,
      "input_hash": "sha256:7c1f...",
      "output_hash": "sha256:9b2a...",
      "step_proof": "sha256:1d4e..."
    }
  ],
  "alerts": [],
  "budget": { "plan": "pro", "plan_envelope_usd": 1.0, "tier_limit_usd": 5.0, "max_cost_usd": 1.0, "multiplier": 5 }
}