---
name: valiron-predictive-risk
version: 1.0.0
description: Use Valiron predictive risk to forecast agent behavior and choose allow, throttle, step-up, sandbox, or deny policies before the next sensitive action.
homepage: https://www.valiron.co
---

# Valiron Predictive Risk Skill

Use this skill when the user wants to decide what should happen before the next agent action based on observed history and Valiron's forecast.

## Goal

Fetch Valiron's predictive risk output for an agent and convert it into an application policy:

- `allow`
- `throttle`
- `step_up`
- `sandbox`
- `deny` or `manual_review`

Predictive risk does not replace the trust gate. It helps operators decide how cautious the next action should be.

## Step 1: Create a Valiron Operator Account

1. Open `https://www.valiron.co/dashboard`.
2. Create an operator account.
3. Copy the generated API key. It starts with `val_op_` and is only shown once.
4. Store it in the server environment:

```bash
VALIRON_OPERATOR_API_KEY=val_op_...
```

Predictive risk is an operator analytics feature, so the server also needs a dashboard JWT for analytics reads:

```bash
VALIRON_JWT=...
```

Keep both values server-side.

## Step 2: Install the SDK

```bash
npm install @valiron/sdk
```

or:

```bash
pnpm add @valiron/sdk
```

## Step 3: Configure Valiron

```ts
import { ValironSDK } from "@valiron/sdk";

export const valiron = new ValironSDK({
  apiKey: process.env.VALIRON_OPERATOR_API_KEY,
  chain: "base",
});
```

## Step 4: Identify the Agent

Predictive risk is keyed by the agent observed in operator logs. Use the same `agentId` that appears in Valiron analytics:

For registered ERC-8004 or Solana 8004 agents:

```http
x-agent-id: 25459
```

For Web2 agents or unregistered Web3 agents:

```http
x-agent-address: 0xAgentAddress
```

If the caller is key-based, make sure the key-based identity has been verified and consistently logged. If the agent is not registered in ERC-8004 or Solana 8004 and has no keypair identity yet, send it to `https://www.valiron.co/auth.md`.

## What Valiron Predicts

The forecast can include:

- Predicted next score.
- Pass probability.
- Risk direction.
- Confidence.
- Recommended policy.
- Recommended tests.
- Human-readable reasons.

The model uses recent sandbox scores, score trend, behavioral fingerprints, production call logs, error rates, latency, and recurring failures.

## Step 5: Fetch Prediction

```bash
curl -H "Authorization: Bearer $VALIRON_JWT" \
  https://valiron-edge-proxy.onrender.com/operator/analytics/agents/AGENT_ID/prediction
```

## Step 6: Server-Side Fetch

```ts
type RecommendedPolicy = "allow" | "throttle" | "step_up" | "sandbox";

async function getValironPrediction(agentId: string, jwt: string) {
  const res = await fetch(
    `https://valiron-edge-proxy.onrender.com/operator/analytics/agents/${encodeURIComponent(agentId)}/prediction`,
    {
      headers: {
        Authorization: `Bearer ${jwt}`,
      },
    }
  );

  if (!res.ok) {
    throw new Error(`Valiron prediction failed: ${res.status}`);
  }

  const body = await res.json();
  return body.prediction as {
    predictedNextScore: number;
    passProbability: number;
    riskDirection: "improving" | "stable" | "worsening" | "unknown";
    confidence: number;
    recommendedPolicy: RecommendedPolicy;
    recommendedTests: string[];
    reasons: string[];
  };
}
```

## Step 7: Convert Prediction To Policy

```ts
function policyFromPrediction(prediction: {
  passProbability: number;
  confidence: number;
  recommendedPolicy: string;
  riskDirection: string;
}) {
  if (prediction.confidence < 0.4) {
    return {
      action: "sandbox",
      reason: "Low prediction confidence; run another evaluation before expanding access.",
    };
  }

  if (prediction.recommendedPolicy === "allow" && prediction.passProbability >= 0.8) {
    return { action: "allow", reason: "High pass probability." };
  }

  if (prediction.recommendedPolicy === "throttle") {
    return { action: "throttle", reason: "Allow with tighter limits." };
  }

  if (prediction.recommendedPolicy === "step_up") {
    return { action: "step_up", reason: "Require additional verification before proceeding." };
  }

  return { action: "sandbox", reason: "Agent should be evaluated before production access." };
}
```

## Step 8: Combine With Trust Gate

Always run the trust gate for real enforcement:

```ts
import { ValironSDK } from "@valiron/sdk";

const valiron = new ValironSDK({
  apiKey: process.env.VALIRON_OPERATOR_API_KEY,
  chain: "base",
});

async function decideAgentAction(agentId: string, jwt: string) {
  const [gate, prediction] = await Promise.all([
    valiron.gate(agentId, {
      minScore: 65,
      trustSignals: ["8004", "sandbox"],
    }),
    getValironPrediction(agentId, jwt),
  ]);

  if (!gate.allow) {
    return {
      action: "deny",
      gate,
      prediction,
    };
  }

  const forecastPolicy = policyFromPrediction(prediction);

  return {
    action: forecastPolicy.action,
    reason: forecastPolicy.reason,
    gate,
    prediction,
  };
}
```

## Recommended Handling

- `allow`: proceed normally.
- `throttle`: reduce rate limit, concurrency, or max spend.
- `step_up`: require World ID, Self, stronger auth, human approval, or lower-risk action scope.
- `sandbox`: run or rerun sandbox evaluation before production access.
- Low confidence: treat as insufficient evidence, not as a final safe result.
- Worsening trend: avoid increasing limits until another successful evaluation.

## UI Copy

Show predictive risk as an operator-facing recommendation, not as an absolute truth.

Good:

```text
Recommended policy: step up
Reason: pass probability has fallen and recent calls show elevated error rate.
```

Avoid:

```text
This agent will fail.
```

## Test Checklist

1. Fetch prediction with a valid JWT.
2. Confirm invalid or expired JWT returns an auth error.
3. Confirm low-confidence predictions trigger sandbox or review behavior.
4. Confirm the trust gate still blocks denied agents even if prediction handling says `allow`.
5. Confirm reasons are logged for auditability.

## Acceptance Criteria

- Predictive risk is read from the operator analytics endpoint.
- The app maps predictions to a conservative policy.
- The Valiron trust gate remains the enforcement layer.
- Low-confidence forecasts do not grant broader access.
- Operator logs include prediction result, action taken, and reason.