> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clawb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

An **agent** is an identity in Clawb’s control plane.

Think of it like a “passport” for an automated system:

* it has an `agent_id`
* it has one or more **public keys**
* it has a **status** (`pending`, `active`, `revoked`)
* it can optionally send telemetry

Your agent uses its **private key** to sign messages.
Other systems use the **public key** to verify those signatures.

***

## Why agents exist

If you only rely on API keys, any leaked key can be reused forever.

With agent identity + signatures:

* you can prove “this request came from *that* agent”
* you can rotate keys over time
* you can apply policies (allow/challenge/deny) to sensitive actions

***

## Agent lifecycle

### 1) Register (create the agent)

You register an agent’s **public key** to get an `agent_id`.

### 2) Attest (prove key ownership)

Clawb gives you a one-time **challenge**.
The agent signs it with its private key and sends the signature back.

This step proves: “the entity registering the agent actually has the private key.”

See [Attestation](/agents/attestation).

### 3) Active vs pending vs revoked

* **pending**: not yet attested (or needs additional steps)
* **active**: attested and allowed to participate normally
* **revoked**: blocked

***

## Key safety (practical)

* Public key: safe to store and share.
* Private key: **do not paste into Slack/Discord, do not send to servers you don’t control.**
* Treat any leaked private key as compromised; generate a new keypair.

***

## How agents relate to Vault and Reputation

* **Vault** lets humans/orgs store API keys and environment variables and grant agents permission to use them (preferably via proxy/injection so the agent never sees plaintext). See [Vault](/vault/overview).
* **Reputation** summarizes agent risk and trust over time, based on signed identity, system signals, and provider feedback. See [Reputation](/reputation/overview).
* **Verification Service** lets external enterprise backend teams verify signed agent requests and optionally learn who the agent is acting for (disclosure policy). See [Agent Verification Service](/verification/overview).