> ## Documentation Index
> Fetch the complete documentation index at: https://hs-df36fa00.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Track Provider and Agent Trust, Health, and Reputation

> Query reputation scores, blocklist status, and health metrics for providers and agents on Watt ServiceNet to monitor your network.

ServiceNet tracks two separate signals for every provider and agent: **trust** (reputation score and blocklist status) and **health** (online status, latency, and success/failure rates). You can query both at any time to monitor your service network, identify degraded participants, and react before blocked or failing agents disrupt your workflows.

## Trust records

Trust records carry a `reputation_score` and a `blocked` flag for each provider and agent. The gateway checks both before forwarding any invocation — a blocked provider or agent is rejected immediately with HTTP 403.

### Agent trust

```bash theme={null}
curl http://127.0.0.1:8042/v1/trust/agents
```

Returns `{ "items": [...] }` where each entry is an `AgentTrustRecord`:

```json theme={null}
{
  "items": [
    {
      "agent_id": "stripe-agent",
      "reputation_score": 0.95,
      "blocked": false,
      "block_reason": null,
      "updated_at": "2025-01-15T12:00:00Z"
    }
  ]
}
```

### Provider trust

```bash theme={null}
curl http://127.0.0.1:8042/v1/trust/providers
```

Returns the same structure with a `provider_id` field instead of `agent_id`:

```json theme={null}
{
  "items": [
    {
      "provider_id": "acme-labs",
      "reputation_score": 1.0,
      "blocked": false,
      "block_reason": null,
      "updated_at": "2025-01-15T12:00:00Z"
    }
  ]
}
```

### Trust record fields

<ResponseField name="agent_id / provider_id" type="string">
  The unique identifier of the agent or provider this trust record belongs to.
</ResponseField>

<ResponseField name="reputation_score" type="float">
  A score between `0.0` and `1.0` representing accumulated reputation. Higher is better. The score is updated automatically as invocations succeed or fail.
</ResponseField>

<ResponseField name="blocked" type="boolean">
  Whether this entity is currently on the blocklist. Blocked entities are rejected at invocation with HTTP 403 before any A2A call is made.
</ResponseField>

<ResponseField name="block_reason" type="string | null">
  The human-readable reason provided when the entity was blocked, if any.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of the last trust record update.
</ResponseField>

### Blocking and unblocking

Use the admin endpoints to block or unblock providers and agents. Blocking takes effect immediately for all subsequent invocations.

```bash theme={null}
# Block an agent
curl -X POST http://127.0.0.1:8042/v1/admin/agents/stripe-agent/block \
  -H 'content-type: application/json' \
  -d '{ "reason": "policy violation under review" }'

# Unblock an agent
curl -X POST http://127.0.0.1:8042/v1/admin/agents/stripe-agent/unblock

# Block a provider
curl -X POST http://127.0.0.1:8042/v1/admin/providers/acme-labs/block \
  -H 'content-type: application/json' \
  -d '{ "reason": "manual review" }'

# Unblock a provider
curl -X POST http://127.0.0.1:8042/v1/admin/providers/acme-labs/unblock
```

<Note>
  Blocking a provider blocks all invocations to every agent under that provider — the gateway checks provider trust before agent trust. If you only want to restrict a single agent, block the agent directly and leave the provider unblocked.
</Note>

## Health records

Health records reflect real invocation outcomes — there is no separate health probe. Every time an agent or provider participates in an invocation (success or failure), ServiceNet updates the corresponding health record automatically.

### Agent health

```bash theme={null}
curl http://127.0.0.1:8042/v1/health/agents
```

Returns `{ "items": [...] }` where each entry is an `AgentHealthRecord`:

```json theme={null}
{
  "items": [
    {
      "agent_id": "stripe-agent",
      "provider_id": "acme-labs",
      "status": "online",
      "last_seen_at": "2025-01-15T12:34:56Z",
      "last_latency_ms": 142,
      "success_count": 831,
      "failure_count": 4,
      "success_rate": 0.995,
      "updated_at": "2025-01-15T12:34:56Z"
    }
  ]
}
```

### Provider health

```bash theme={null}
curl http://127.0.0.1:8042/v1/health/providers
```

Same structure, scoped to the provider level rather than a specific agent.

### Health record fields

<ResponseField name="agent_id / provider_id" type="string">
  The entity this health record belongs to. Agent records also include `provider_id` to indicate which provider hosts the agent.
</ResponseField>

<ResponseField name="status" type="string">
  The current health status. See the [status meanings](#health-status-meanings) table below.
</ResponseField>

<ResponseField name="last_seen_at" type="string | null">
  ISO 8601 timestamp of the most recent invocation attempt (successful or not). `null` if no invocations have been recorded yet.
</ResponseField>

<ResponseField name="last_latency_ms" type="integer | null">
  Round-trip latency in milliseconds for the most recent invocation. `null` if not yet measured.
</ResponseField>

<ResponseField name="success_count" type="integer">
  Cumulative count of successful invocations.
</ResponseField>

<ResponseField name="failure_count" type="integer">
  Cumulative count of failed invocations.
</ResponseField>

<ResponseField name="success_rate" type="float">
  Rolling success rate between `0.0` and `1.0`. Calculated from `success_count / (success_count + failure_count)`.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of the last health record write.
</ResponseField>

## Health status meanings

| Status     | Meaning                                                                                    |
| ---------- | ------------------------------------------------------------------------------------------ |
| `unknown`  | No invocations have been recorded yet. The entity is registered but has never been called. |
| `online`   | The entity has recent successful invocations and no elevated failure rate.                 |
| `degraded` | The entity is reachable but has an elevated failure rate. Callers should monitor closely.  |
| `offline`  | All recent invocations have failed. The entity is likely unreachable.                      |

<CardGroup cols={2}>
  <Card title="online" icon="circle-check">
    Normal operation. Recent invocations succeeded within expected latency bounds.
  </Card>

  <Card title="degraded" icon="triangle-exclamation">
    Elevated failure rate detected. The agent or provider is responding but not reliably.
  </Card>

  <Card title="offline" icon="circle-xmark">
    All recent invocations failed. Check the provider's endpoint configuration and network reachability.
  </Card>

  <Card title="unknown" icon="circle-question">
    No invocation history exists yet. Status will update automatically on first call.
  </Card>
</CardGroup>

<Tip>
  Health records update on every invocation — both sync (`/invoke`) and async (`/invoke-async`). You do not need to configure any separate health checks. Query `/v1/health/agents` after running a batch of invocations to see results immediately.
</Tip>