Agents

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"])

curl https://api.prysm1.com/v1/agent/run \
  -H "Authorization: Bearer $PRYSM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Research the top 3 AI gateways, compare pricing, and draft a one-page brief.",
    "max_cost_usd": 1.00,
    "policy": "balanced"
  }'

curl https://api.prysm1.com/v1/agent/verify \
  -H "Content-Type: application/json" \
  -d '{ "run_id": "agt_...", "trajectory_proof": "sha256:...", "policy": "balanced",
        "strategy": "ensemble_moa", "output": "...", "steps": [ /* full-hash step records */ ] }'

{
  "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 }
}

{
  "error": "budget_exceeds_tier_limit",
  "message": "budget_exceeds_tier_limit: requested $50.00 exceeds tier limit $5.00 (plan envelope $1.00 x 5). Reduce max_cost_usd or upgrade plan.",
  "tier_limit_usd": 5.0,
  "plan_envelope_usd": 1.0,
  "requested_max_cost_usd": 50.0
}

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

string

required

Your secret key as a bearer token: Bearer prysm_sk_...

Body

string

required

The goal for the agent to accomplish autonomously. (prompt is accepted as an alias.)

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.

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.

integer

default:"50"

Maximum number of steps before the run stops gracefully. Hard ceiling: 1000.

string

default:"balanced"

The objective dial: efficiency, balanced, or depth. Sets the starting intensity; the guard still downshifts under budget pressure.

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.

integer

default:"1024"

Maximum tokens per underlying model call.

number

default:"0.5"

Sampling temperature passed to the underlying models.

Response

string

Always agent.run.

string

Unique run id, e.g. agt_9f8e.... Use it with the other agent endpoints.

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.

string

The policy the run used.

string

The primary per-step strategy.

string[]

The sub-tasks the goal was decomposed into.

integer

How many steps executed.

number

Total spend — always ≤ max_cost_usd.

number

The hard cap that was enforced.

number

Budget left.

string

The run’s PrysmProof trajectory root, e.g. sha256:a1b2c3d4e5f6....

string

The consolidated final result.

array

The per-step trajectory.

Show steps[]

integer

Step index (chain order).

string

subtask or finalize.

string

The model that ran the step.

string

Laser, Halo, or Foton — the rung AgentGuard chose under budget pressure.

string

The step’s orchestration shape.

number

The step’s cost.

number

Confidence in the step, 0–1.

string

sha256: of the step input (privacy-preserving — never the raw text).

string

sha256: of the step output.

string

The chained per-step proof.

array

Budget-pressure alerts (70% → WARNING/Halo, 90% → CRITICAL/Foton).

object

Plan envelope, tier limit, multiplier, and the enforced cap.

string

Set when a run stopped on budget/steps, e.g. “agent stopped after 7 steps (budget_exhausted);

4.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.

string

Always list.

integer

Number of runs returned.

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.

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.

array

Every step with its hashes, cost, intensity, and per-step proof (full 64-hex when ?full=true).

object

Deterministic-replay result: { "valid": true, "recomputed_proof": "sha256:...", "n_steps": N, "mismatched_steps": [] }.

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.

string

required

The run id the proof was computed over.

string

required

The claimed sha256:... root to check.

array

required

The step records (index, model, input_hash, output_hash, cost_usd, confidence, timestamp).

string

default:"balanced"

The run’s policy.

string

default:"single"

The run’s primary strategy.

string

The raw final output (we hash it). Or supply output_hash directly.

string[]

Optional claimed per-step proofs — when supplied, a tamper is localized in mismatched_steps.

boolean

Whether the trajectory verifies.

string

The proof recomputed from the supplied data.

integer[]

Indices of steps whose proof didn’t match (empty when valid).

Errors

Status	`error`	Meaning
`400`	`no_goal`	`goal` (or `prompt`) was empty.
`401`	—	Missing or invalid API key.
`402`	`budget_exceeds_tier_limit`	`max_cost_usd` exceeds your tier’s ceiling (5× the plan envelope).
`404`	`run_not_found`	No such run, or it isn’t yours.
`413`	`request_too_large`	Request body exceeds the server limit (default 2 MiB).
`502`	`agent_error`	The runner raised unexpectedly.
`503`	`no_provider_available`	No 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"])

curl https://api.prysm1.com/v1/agent/run \
  -H "Authorization: Bearer $PRYSM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Research the top 3 AI gateways, compare pricing, and draft a one-page brief.",
    "max_cost_usd": 1.00,
    "policy": "balanced"
  }'

curl https://api.prysm1.com/v1/agent/verify \
  -H "Content-Type: application/json" \
  -d '{ "run_id": "agt_...", "trajectory_proof": "sha256:...", "policy": "balanced",
        "strategy": "ensemble_moa", "output": "...", "steps": [ /* full-hash step records */ ] }'

{
  "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 }
}

{
  "error": "budget_exceeds_tier_limit",
  "message": "budget_exceeds_tier_limit: requested $50.00 exceeds tier limit $5.00 (plan envelope $1.00 x 5). Reduce max_cost_usd or upgrade plan.",
  "tier_limit_usd": 5.0,
  "plan_envelope_usd": 1.0,
  "requested_max_cost_usd": 50.0
}

Code Skills

Overview

Endpoints

Agentic Control Plane

Agentic Control Plane

Run an agent

Authorization

Body

Response

List runs

Get run state

Get the full trajectory

Cancel a run

Verify a trajectory

Errors

​Run an agent

​Authorization

​Body

​Response

​List runs

​Get run state

​Get the full trajectory

​Cancel a run

​Verify a trajectory

​Errors

Run an agent

Authorization

Body

Response

List runs

Get run state

Get the full trajectory

Cancel a run

Verify a trajectory

Errors