Agent API

Agents AI et MCP

Créer des agents, définir leurs autorisations, émettre des clés d'agent et appeler le runtime MCP

PrimeCal expose une surface dédiée à la gestion des agents sous /api/agents et un un runtime MCP séparé sous /api/mcp. Les routes de gestion utilisent l'authentification de l'utilisateur ; le Le runtime utilise uniquement les clés d'agent.

JWT pour la gestionClé d'agent pour MCPAutorisations étenduesExécution à distance

Authentification et autorisations

Surface	Modèle d'authentification	Remarques
/api/agents/*	Clé JWT ou utilisateur API	L'utilisateur actuel gère ses propres agents
/api/mcp/*	Clé d'agent uniquement	Les jetons Bearer sont explicitement rejetés

En-têtes de clé d'agent acceptés :

• x-agent-key
• x-agent-token
• Authorization: Agent <token>

Référence du point de terminaison

Gestion des agents

Méthode	Chemin	Objectif	Demande ou requête	Authentification
GET	/api/agents	Répertoriez les agents utilisateurs actuels.	Aucun	Clé JWT ou utilisateur API
POST	/api/agents	Créez un agent.	Corps : name,description	Clé JWT ou utilisateur API
GET	/api/agents/catalog	Obtenez le catalogue d’actions de l’agent ainsi que les ressources de cadrage.	Aucun	Clé JWT ou utilisateur API
GET	/api/agents/:id	Obtenez un agent.	Chemin : id	Clé JWT ou utilisateur API
PUT	/api/agents/:id	Mettez à jour le nom, la description ou le statut.	Chemin : id, corps : name,description,status	Clé JWT ou utilisateur API
DELETE	/api/agents/:id	Désactivez un agent.	Chemin : id	Clé JWT ou utilisateur API
PUT	/api/agents/:id/permissions	Remplacez l'ensemble d'autorisations de l'agent.	Chemin : id, corps : permissions[]	Clé JWT ou utilisateur API
GET	/api/agents/:id/keys	Répertoriez les clés d’un agent.	Chemin : id	Clé JWT ou utilisateur API
POST	/api/agents/:id/keys	Créez une clé d'agent.	Chemin : id, corps : label	Clé JWT ou utilisateur API
DELETE	/api/agents/:id/keys/:keyId	Révoquer une clé d'agent.	Chemin : id,keyId	Clé JWT ou utilisateur API

MCP Durée d'exécution

Méthode	Chemin	Objectif	Demande ou requête	Authentification
GET	/api/mcp/metadata	Renvoyez les métadonnées de l’agent et du propriétaire pour la clé émise.	Aucun	Clé d'agent
GET	/api/mcp/actions	Répertorie les actions autorisées pour l'agent authentifié.	Aucun	Clé d'agent
POST	/api/mcp/execute	Exécutez une action d’agent.	Corps : action,parameters	Clé d'agent
ALL	/api/mcp/stream	Transport de streaming HTTP pour les clients MCP.	Corps : payload	Clé d'agent

Demander des formes

Définition de l'agent

CreateAgentDto et UpdateAgentDto

• name : requis à la création, maximum 80 caractères
• description : facultatif, maximum 255 caractères
• status : énumération de mise à jour uniquement active|disabled

Autorisations

UpdateAgentPermissionsDto

• permissions : tableau requis
• permissions[].actionKey : valeur d'énumération d'action requise du registre
• permissions[].scope : objet facultatif

Clés d'action actuelles :

• calendar.list
• calendar.events.read
• calendar.events.create
• calendar.events.update
• calendar.events.delete
• automation.rules.list
• automation.rules.trigger
• user.profile.read
• tasks.list
• tasks.create
• tasks.update
• tasks.delete
• task-labels.list
• task-labels.create
• task-labels.update
• task-labels.delete

Clés et exécution

• CreateAgentKeyDto.label : obligatoire, maximum 80 caractères
• ExecuteAgentActionDto.action : clé d'action requise
• ExecuteAgentActionDto.parameters : objet facultatif
• AgentStreamPayloadDto.payload : wrapper de requête utilisé par /api/mcp/stream

Catalogue et modèle de portée

GET /api/agents/catalog renvoie :

• actions : le catalogue d'actions
• resources.calendars : agendas de l'utilisateur actuel pour les autorisations au niveau du calendrier
• resources.automationRules : règles d'automatisation de l'utilisateur actuel pour les autorisations au niveau de l'automatisation

Cela fait de l’itinéraire du catalogue la source de vérité pour les éditeurs d’autorisations.

Exemples d'appels

Créer un agent

curl -X POST "$PRIMECAL_API/api/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Family Planner",
    "description": "Reads family calendars and creates tasks"
  }'

Remplacer les autorisations de l'agent

curl -X PUT "$PRIMECAL_API/api/agents/9/permissions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": [
      { "actionKey": "calendar.list" },
      {
        "actionKey": "calendar.events.create",
        "scope": { "calendarIds": [5, 7] }
      },
      { "actionKey": "tasks.create" }
    ]
  }'

Appeler le runtime MCP

curl "$PRIMECAL_API/api/mcp/metadata" \
  -H "Authorization: Agent $AGENT_KEY"

curl -X POST "$PRIMECAL_API/api/mcp/execute" \
  -H "Authorization: Agent $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "calendar.events.create",
    "parameters": {
      "calendarId": 5,
      "title": "Parent-teacher meeting",
      "startDate": "2026-04-02",
      "startTime": "16:00"
    }
  }'

Notes de réponse et de comportement

• La réponse du catalogue est enrichie des calendriers réels de l'utilisateur et des règles d'automatisation.
• DELETE /api/agents/:id désactive l'agent et renvoie { success: true }.
• POST /api/agents/:id/keys renvoie une clé en texte brut uniquement au moment de la création.
• GET /api/mcp/metadata renvoie les blocs agent, owner et protocol.

Meilleures pratiques

• Gardez la portée des agents étroite. Accordez uniquement les actions et les étendues de ressources dont l’agent a réellement besoin.
• Traitez les clés d'agent comme des secrets. Ils sont distincts des JWT utilisateur et ne doivent jamais être intégrés dans le code du navigateur.
• Utilisez GET /api/agents/catalog avant de générer un éditeur d'autorisations afin de ne pas vous éloigner du registre d'action en direct.
• Préférez /api/mcp/metadata comme premier test de fumée lors du câblage d'un client MCP externe.
• Désactivez les agents lorsqu'ils ne sont plus nécessaires au lieu de laisser les clés actives en place.