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

# Agents

> First-class Entities die Karten, Tokens, Transaktionen und eine Policy besitzen.

Ein Agent ist eine Stripe-shaped Resource: er besitzt Karten, Tokens, Transaktionen und genau eine Policy zur Zeit. Agents sind für AI-Use typisiert — sie tragen einen `purpose`, optionales `framework` (`openai-assistants`, `anthropic-sdk`, `langgraph`, `crewai`) und optionale Capabilities damit Dashboard und Audit-Trail beschreiben können wofür sie da sind.

## Das Agent-Modell

| Feld                   | Beschreibung                                           |
| ---------------------- | ------------------------------------------------------ |
| `id`                   | `ag_*`                                                 |
| `name`                 | Display-Name                                           |
| `policyId`             | Genau eine Policy, mutable aber immer present          |
| `profile.purpose`      | **Required.** Freitext — beschreibt was der Agent tut. |
| `profile.framework`    | Optional — z.B. `langgraph`                            |
| `profile.capabilities` | Optionales `string[]` — was der Agent kann             |
| `profile.description`  | Optional längere Beschreibung                          |
| `profile.department`   | Optionales Cost-Center-Tag                             |
| `profile.ownerContact` | Optionaler Eskalations-Kontakt                         |
| `status`               | `active` · `suspended` · `archived`                    |

## Minimal-Create

Der Dashboard-Create-Drawer (und der dokumentierte Happy-Path) ist `name + purpose + policyId`. Andere Profile-Felder sind optional, hinter einem „Advanced"-Toggle versteckt.

<CodeGroup>
  ```bash curl theme={}
  curl -X POST https://api.getovra.com/agents \
    -H "Authorization: Bearer $OVRA_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    -d '{
      "name": "procurement-bot",
      "policyId": "po_default_...",
      "profile": { "purpose": "Bürobedarf unter EUR 100 kaufen" }
    }'
  ```

  ```ts SDK theme={}
  const agent = await ovra.agents.create({
    name: "procurement-bot",
    policyId: "po_default_...",
    profile: { purpose: "Bürobedarf unter EUR 100 kaufen" },
  });
  ```

  ```text MCP theme={}
  ovra_agent { action: "provision", name: "procurement-bot", policyId: "po_default_...", profile: { purpose: "..." } }
  ```
</CodeGroup>

## Lebenszyklus

| Endpoint                                | Zweck                                         |
| --------------------------------------- | --------------------------------------------- |
| `POST /agents`                          | Erstellen (idempotent)                        |
| `GET /agents/:id`                       | Lesen                                         |
| `PATCH /agents/:id`                     | Update name / profile / status                |
| `DELETE /agents/:id`                    | Archivieren (kaskadiert über Karten + Tokens) |
| `POST /agents/:id/freeze` / `/unfreeze` | Pausieren / Resumieren                        |
| `POST /agents/:id/tokens`               | Agent-scoped Token (`at_*`) ausstellen        |

## Agent-Tokens

Agents können eigene scoped Tokens (`at_*`) halten. Ein Token ist an einen Agent gebunden, trägt typisierte Permissions und kann optional einen Spend-Cap haben (via [Delegation](/de/concepts/delegations)).

```bash theme={}
curl -X POST https://api.getovra.com/agents/ag_.../tokens \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "production-runtime",
    "scopes": ["intents.write", "checkout.write"],
    "expiresInDays": 90
  }'
```

`at_*`-Tokens in deiner Runtime statt deinen org-level `sk_*`-Key teilen. Cross-Agent-Reads mit `at_*`-Token returnen `403 E_AGENT_ISOLATION` — Strict Isolation ist eine der [Sacred Invariants](/de/introduction#sacred-invariants).

## Signing-Keys (Phase-8-Prep)

Pro Agent wird async ein Ed25519-Keypair provisioniert. Die Public-JWK wird exposed an:

```http theme={}
GET /.well-known/agent-jwks/{agent_id}
```

Das ist Wiring für **Visa Trusted Agent Protocol** (RFC-9421 HTTP Message Signatures). Kein Outbound-Signing aktiv in v1.2 — Code landet sobald der erste TAP-aware Merchant es verlangt.

## Webhooks

* `agent.created`
* `agent.frozen`
* `agent.unfrozen`

## Plan-Tier-Limits

| Plan       | Agents     |
| ---------- | ---------- |
| Free       | 1          |
| Starter    | 5          |
| Business   | 10         |
| Enterprise | Unbegrenzt |

## Surfaces

| Surface   | Capability                      |
| --------- | ------------------------------- |
| REST      | `/agents`, `/agents/:id/tokens` |
| SDK       | `ovra.agents.*`                 |
| MCP       | `ovra_agent` (admin-side)       |
| Dashboard | `/dashboard/agents`             |

## Weiter

<CardGroup cols={2}>
  <Card title="Karten" icon="rectangle" href="/de/concepts/cards">
    Karten an einen Agent binden.
  </Card>

  <Card title="Policies" icon="shield-check" href="/de/concepts/policies">
    Definieren was ein Agent ausgeben darf.
  </Card>

  <Card title="Intents" icon="file-signature" href="/de/concepts/intents">
    Die Approval-Primitive mit der jede Belastung beginnt.
  </Card>

  <Card title="Bezahlung" icon="credit-card" href="/de/concepts/pay">
    Wie ein Agent tatsächlich zahlt.
  </Card>
</CardGroup>