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.

Bon à savoir L'enregistrement des agents est facultatif. Vous pouvez appeler chaque terminal avec juste un texte libre agent_nameC'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 :

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.

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'enregistrementC'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

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

Réponse

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