# Agentes

An **Agente** es un sistema de IA que ejecutas, un bot de apoyo, un asistente de codificación, un flujo de trabajo autónomo. Task Guard, Govern y Secure aceptan una identidad de agente para que las tareas, decisiones e incidentes puedan atribuirse al agente adecuado.

> **Good to know**
> **Los agentes registrados son opcionales.** Puedes llamar a cada punto final con solo un texto libre `agent_name`. Registrar un agente le da un establo `agent_id` y informes más ricos — pero nunca es un requisito previo para usar la API.


### Registrado vs. no registrado

La tarea de Task Guard comienza y cada llamada de Govern y Secure acepta dos campos de identidad opcionales:

| Campo | Úsalo cuando... | Ejemplo |
| ------------ | ------------------------------------------------------------------------------------ | ----------------------------- |
| `agent_name` | El agente no está registrado (o solo quieres etiquetar al callador). | `"agent_name": "billing-bot"` |
| `agent_id` | El agente **es** registrado en Maetra y quiere que los puntos de control/incidentes estén atados a ella. | `"agent_id": "agt_5Ab2"` |

Usted puede enviar, ambos, o ninguno. Pasando `agent_id` vincula la actividad con el agente registrado; `agent_name` es una etiqueta legible por humanos. Empieza con `agent_name`, y cambiar a `agent_id` una vez que te registres.

### Cómo Govern resuelve el alcance de la política

Para una evaluación normal de políticas activas, `agent_id` es opcional. Govern todavía evalúa la acción cuando una solicitud de REST o MCP envía sólo `agent_name`.

| Solicitud de identidad | Ámbito de política Maetra evalúa |
| ------------------------------------ | --------------------------------------------------------------------------------------------- |
| `agent_id` coincide con un agente registrado | Políticas para toda la organización, además de políticas asignadas a ese agente registrado. |
| `agent_name` coincide con un nombre de agente registrado | Políticas para toda la organización, además de políticas asignadas a ese agente registrado. |
| Sólo un desconocido `agent_name` es enviado | Políticas para toda la Organización solamente. Las políticas asignadas a agentes registrados específicos no funcionan. |
| No se envía identidad de agente | Políticas para toda la Organización solamente. |

Paso `agent_id` cuando se puede; utilizar `agent_name` cuando un agente no está registrado todavía o cuando un cliente de MCP no tiene una identificación registrada. Si pasas `policy_ids` o `policy_group_ids` en un puesto de control, Maetra evalúa las políticas que seleccionó explícitamente.

#### Cuándo registrarse

* Quieres tableros de control, hallazgos y pistas de auditoría.
* Quieres incluir reglas o políticas a agentes específicos.
* Estás a bordo de un agente para la gobernanza formal.

#### Cuando no necesitas

* Estás integrándote rápidamente o prototipando.
* El callador es un script one-off o una superficie de producto, no un agente rastreado.

### Registrar un agente

Agentes registrados en el panel bajo **Discover → Registro de agentes → Agente de registro**. Sólo un **nombre** es necesario; todo lo demás (propietario, medio ambiente, marco, nivel de autonomía, herramientas) es contexto opcional. A salvo, Maetra asigna el `agent_id` pasa a la API.

### Agentes de lista

`GET /v1/agents` — devuelve a los agentes en su espacio de trabajo, el más nuevo primero, con una proyección pública mínima. Requiere el `discover:agents:read` alcance.

**Parámetros de consulta**

| Param | Descripción |
| -------- | ------------------------------------------------------------------------------------ |
| `status` | Filtro por `pending_review`, `registered`, `under_review`, `governed`, `archived`. |
| `limit` | Agentes de Max para regresar, `1`–`200`. Defaults to `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());
```


#### Respuesta

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

| Campo | Tipo | Descripción |
| --------------------------- | -------------- | ----------------------------------------------------------------------- |
| `id` | cuerda. | La identificación del agente - pasar como `agent_id` a otros puntos finales. |
| `name` | cuerda. | Nombre legible por humanos. |
| `description` | cuerda. \| nulo | Descripción opcional. |
| `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` | cuerda. | Momento ISO 8601. |