# Agents

Une **agent** est un système d'IA que vous exécutez — un robot de support, un assistant de codage, un workflow autonome. Task Guard, Govern et Secure acceptent l'identité d'un agent afin que les tâches, les décisions et les incidents puissent être attribués au bon agent.

> **Good to know**
> **L'enregistrement des agents est facultatif.** Vous pouvez appeler chaque terminal avec juste un texte libre `agent_name`C'est vrai. Enregistrer un agent vous donne une écurie `agent_id` et des rapports plus riches — mais ce n'est jamais une condition préalable pour utiliser l'API.


### Inscrits par rapport aux non inscrits

La tâche Task Guard commence et chaque appel Govern et Secure accepte deux champs d'identité optionnels :

| Champ | Utilisez-le quand... | Exemple |
| ------------ | ------------------------------------------------------------------------------------ | ----------------------------- |
| `agent_name` | L'agent n'est pas enregistré (ou vous voulez juste l'étiqueter). | `"agent_name": "billing-bot"` |
| `agent_id` | L'agent **est** enregistré à Maetra et vous voulez des points de contrôle / incidents liés à elle. | `"agent_id": "agt_5Ab2"` |

Vous pouvez envoyer soit les deux, soit l'un ou l'autre. Passage `agent_id` relie l'activité à l'agent enregistré; `agent_name` est une étiquette lisible par l'homme. Commencez par `agent_name`, et passer à `agent_id` une fois que vous vous inscrivez.

### Comment Govern résout la portée de la politique

Pour l'évaluation normale des politiques actives, `agent_id` est facultatif. Govern évalue toujours l'action quand une demande REST ou MCP envoie seulement `agent_name`.

| Demande d'identité | Portée de la politique Maetra évalue |
| ------------------------------------ | --------------------------------------------------------------------------------------------- |
| `agent_id` correspond à un agent enregistré | Politiques à l'échelle de l'organisation, plus les politiques attribuées à cet agent enregistré. |
| `agent_name` correspond à un nom d'agent enregistré | Politiques à l'échelle de l'organisation, plus les politiques attribuées à cet agent enregistré. |
| Seulement un inconnu `agent_name` est envoyé | Politiques à l ' échelle de l ' Organisation seulement. Les politiques attribuées à certains agents enregistrés ne sont pas appliquées. |
| Aucune identité d'agent n'est envoyée | Politiques à l ' échelle de l ' Organisation seulement. |

Passons `agent_id` quand vous pouvez; utiliser `agent_name` lorsqu'un agent n'est pas encore inscrit ou lorsqu'un client MCP n'a pas d'identité enregistrée. Si vous passez `policy_ids` ou `policy_group_ids` sur un point de contrôle, Maetra évalue les politiques que vous avez explicitement sélectionnées.

#### Quand s'inscrire

* Vous voulez des tableaux de bord, des constatations et des pistes d'audit par agent.
* Vous voulez étendre les règles ou les politiques à des agents spécifiques.
* Vous êtes à bord d'un agent pour la gouvernance formelle.

#### Quand vous n'avez pas besoin de

* Tu t'intègres rapidement ou tu fais du prototypage.
* L'appelant est un script unique ou une surface de produit, et non un agent traqué.

### Enregistrement d'un agent

Agents d'enregistrement dans le tableau de bord **Discover → Registre des agents → Agent d'enregistrement**C'est vrai. Seulement un **nom** Tout le reste (propriétaire, environnement, cadre, niveau d'autonomie, outils) est un contexte facultatif. En cours de sauvegarde, Maetra assigne la `agent_id` vous passez à l'API.

### Liste des agents

`GET /v1/agents` — retourne les agents dans votre espace de travail, le plus récent d'abord, avec une projection publique minimale. Nécessite le `discover:agents:read` champ d'application.

**Paramètres de requête**

| Param | Désignation des marchandises |
| -------- | ------------------------------------------------------------------------------------ |
| `status` | Filtrer par `pending_review`, `registered`, `under_review`, `governed`ou `archived`. |
| `limit` | Max agents de retour, `1`–`200`C'est vrai. Par défaut à `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());
```


#### Réponse

```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"
    }
  ]
}
```

| Champ | Type | Désignation des marchandises |
| --------------------------- | -------------- | ----------------------------------------------------------------------- |
| `id` | chaîne de caractères | L'identité de l'agent — passez comme `agent_id` à d'autres paramètres. |
| `name` | chaîne de caractères | Nom lisible par l'homme. |
| `description` | chaîne de caractères \| null | Description facultative. |
| `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` | chaîne de caractères | Horodatages ISO 8601. |