# Agenten

An **Agent** ist ein KI-System, das Sie ausführen - ein Support-Bot, ein Programmierassistent, ein autonomer Workflow. Task Guard, Govern und Secure akzeptieren eine Agentenidentität, sodass Aufgaben, Entscheidungen und Vorfälle dem richtigen Agenten zugeschrieben werden können.

> **Good to know**
> **Registrierende Agenten sind optional.** Sie können jeden Endpunkt mit nur einem freien Text anrufen `agent_name`. Die Registrierung eines Agenten gibt Ihnen einen Stall `agent_id` und ein reichhaltigeres Reporting - aber es ist niemals eine Voraussetzung für die Verwendung der API.


### Registriert vs. nicht registriert

Die Task Guard-Aufgabe beginnt und jeder Govern- und Secure-Aufruf akzeptiert zwei optionale Identitätsfelder:

| Feld | Verwenden Sie es, wenn ... | Beispiel |
| ------------ | ------------------------------------------------------------------------------------ | ----------------------------- |
| `agent_name` | Der agent ist nicht registriert (oder sie möchten nur den anrufer kennzeichnen). | `"agent_name": "billing-bot"` |
| `agent_id` | Der Agent **ist** Registriert in Maetra und Sie möchten, dass Checkpoints / Vorfälle daran gebunden sind. | `"agent_id": "agt_5Ab2"` |

Sie können entweder beide oder keines von beiden senden. Passieren `agent_id` Verknüpfung der Aktivität mit dem registrierten Agenten; `agent_name` Es ist ein menschenlesbares Label. Beginnen Sie mit `agent_name`, und wechseln zu `agent_id` Sobald Sie sich registriert haben.

### Wie Govern den politischen Anwendungsbereich auflöst

für die normale Bewertung der Aktivpolitik, `agent_id` ist optional. Govern bewertet die Aktion immer noch, wenn eine REST- oder MCP-Anfrage nur gesendet wird `agent_name`.

| Name des Antrags | Policy Scope bewertet Maetra |
| ------------------------------------ | --------------------------------------------------------------------------------------------- |
| `agent_id` Matches ein registrierter Agent | Organisationsweite Richtlinien sowie Richtlinien, die diesem registrierten Agenten zugewiesen wurden. |
| `agent_name` Übereinstimmung mit einem registrierten Agentennamen | Organisationsweite Richtlinien sowie Richtlinien, die diesem registrierten Agenten zugewiesen wurden. |
| Nur ein Unbekannter `agent_name` wird verschickt | Nur organisationsweite Politik. Richtlinien, die bestimmten registrierten Agenten zugewiesen sind, werden nicht ausgeführt. |
| Keine Agentenidentität wird gesendet | Nur organisationsweite Politik. |

Passierpass `agent_id` Wenn Sie können; verwenden `agent_name` wenn ein Agent noch nicht registriert ist oder wenn ein MCP-Client keine registrierte ID hat. Wenn Sie gehen `policy_ids` oder `policy_group_ids` An einem Checkpoint bewertet Maetra die Richtlinien, die Sie explizit ausgewählt haben.

#### Wann sich registrieren lässt

* Sie möchten Per-Agent-Dashboards, Ergebnisse und Audit-Trails.
* Sie möchten Regeln oder Richtlinien auf bestimmte Agenten ausdehnen.
* Sie bringen einen Agenten in die formale Governance.

#### Wenn du es nicht brauchst

* Sie integrieren schnell oder Prototyping.
* Der Caller ist ein einmaliges Skript oder eine Produktoberfläche, kein Tracked Agent.

### Registrierung eines Agenten

Registrieren Sie Agenten im Dashboard unter **Discover → Agentenregister → Registeragenten**. Nur a **Name** Alles andere (Eigentümer, Umgebung, Framework, Autonomieebene, Werkzeuge) ist optionaler Kontext. Bei Save weist Maetra die `agent_id` Sie gehen zur API über.

### Listenagenten

`GET /v1/agents` Gibt die Agenten in Ihrem Arbeitsbereich zurück, neueste zuerst, mit einer minimalen öffentlichen Projektion. Erfordert die `discover:agents:read` Anwendungsbereich.

**Abfrageparameter**

| Achsschenkel | Beschreibung |
| -------- | ------------------------------------------------------------------------------------ |
| `status` | Filter durch `pending_review`, `registered`, `under_review`, `governed`, oder `archived`. |
| `limit` | Max-Agenten kommen zurück, `1`–`200`. Ausfälle bis `50`. |

#### cURL

```bash
curl "https://api.maetra.io/v1/agents?limit=20" \
  -H "Authorization: Bearer $MAETRA_API_KEY"
```

#### JavaScript

```javascript
const res = await fetch("https://api.maetra.io/v1/agents?limit=20", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAETRA_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`Maetra API ${res.status}`);
const data = await res.json();
console.log(data);
```

#### TypeScript

```typescript
const res = await fetch("https://api.maetra.io/v1/agents?limit=20", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAETRA_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`Maetra API ${res.status}`);
const data = (await res.json());
```

#### Python

```python
import os, requests

res = requests.get(
    "https://api.maetra.io/v1/agents?limit=20",
    headers={"Authorization": f"Bearer {os.environ['MAETRA_API_KEY']}"},
)
res.raise_for_status()
print(res.json())
```

#### Rust

```rust
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let key = std::env::var("MAETRA_API_KEY")?;
    let client = reqwest::Client::new();
    let res = client
        .get("https://api.maetra.io/v1/agents?limit=20")
        .bearer_auth(&key)
        .send()
        .await?;
    let data: serde_json::Value = res.json().await?;
    println!("{data:#}");
    Ok(())
}
```

#### C++

```cpp
#include <curl/curl.h>
#include <cstdlib>
#include <string>

int main() {
    CURL* curl = curl_easy_init();
    std::string auth = "Authorization: Bearer " + std::string(std::getenv("MAETRA_API_KEY"));
    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, auth.c_str());
    curl_easy_setopt(curl, CURLOPT_URL, "https://api.maetra.io/v1/agents?limit=20");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_perform(curl);   // response is written to stdout by default
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}
```

#### Java

```java
import java.net.URI;
import java.net.http.*;

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.maetra.io/v1/agents?limit=20"))
    .header("Authorization", "Bearer " + System.getenv("MAETRA_API_KEY"))
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```


#### Antwort

```json
{
  "agents": [
    {
      "id": "agt_5Ab2",
      "name": "billing-bot",
      "description": "Handles customer refunds.",
      "status": "registered",
      "autonomy_level": "L3",
      "risk_level": "medium",
      "environment": "production",
      "created_at": "2026-07-01T09:12:00.000Z",
      "updated_at": "2026-07-06T22:04:00.000Z"
    }
  ]
}
```

| Feld | Typ | Beschreibung |
| --------------------------- | -------------- | ----------------------------------------------------------------------- |
| `id` | Schnurschnur | ID des Agenten — Pass als `agent_id` zu anderen Endpunkten. |
| `name` | Schnurschnur | Menschenlesbarer Name. |
| `description` | Schnurschnur \| Null | Fakultative Beschreibung. |
| `status` | enum | `pending_review`, `registered`, `under_review`, `governed`, `archived`. |
| `autonomy_level` | enum | `L0`–`L5`. |
| `risk_level` | enum | `low`, `medium`, `high`, `critical`, `unknown`. |
| `environment` | enum | `production`, `staging`, `development`, `unknown`. |
| `created_at` / `updated_at` | Schnurschnur | Zeitstempel nach ISO 8601. |