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

Source

Contrôleur de gestion des agents : backend-nestjs/src/agents/agents.controller.ts
Contrôleur MCP : backend-nestjs/src/agents/agent-mcp.controller.ts
Contrôleur de flux MCP : backend-nestjs/src/agents/agent-mcp-stream.controller.ts
DTO : backend-nestjs/src/agents/dto/agent.dto.ts, backend-nestjs/src/agents/dto/agent-stream.dto.ts
Registre des actions : backend-nestjs/src/agents/agent-actions.registry.ts
Garde d'authentification de l'agent : backend-nestjs/src/agents/guards/agent-api-key.guard.ts
Énumération de statut : backend-nestjs/src/entities/agent-profile.entity.ts

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	Source
`GET`	`/api/agents`	Répertoriez les agents utilisateurs actuels.	Aucun	Clé JWT ou utilisateur API	`agents/agents.controller.ts`
`POST`	`/api/agents`	Créez un agent.	Corps : `name,description`	Clé JWT ou utilisateur API	`agents/agents.controller.ts`
`GET`	`/api/agents/catalog`	Obtenez le catalogue d’actions de l’agent ainsi que les ressources de cadrage.	Aucun	Clé JWT ou utilisateur API	`agents/agents.controller.ts`
`GET`	`/api/agents/:id`	Obtenez un agent.	Chemin : `id`	Clé JWT ou utilisateur API	`agents/agents.controller.ts`
`PUT`	`/api/agents/:id`	Mettez à jour le nom, la description ou le statut.	Chemin : `id`, corps : `name,description,status`	Clé JWT ou utilisateur API	`agents/agents.controller.ts`
`DELETE`	`/api/agents/:id`	Désactivez un agent.	Chemin : `id`	Clé JWT ou utilisateur API	`agents/agents.controller.ts`
`PUT`	`/api/agents/:id/permissions`	Remplacez l'ensemble d'autorisations de l'agent.	Chemin : `id`, corps : `permissions[]`	Clé JWT ou utilisateur API	`agents/agents.controller.ts`
`GET`	`/api/agents/:id/keys`	Répertoriez les clés d’un agent.	Chemin : `id`	Clé JWT ou utilisateur API	`agents/agents.controller.ts`
`POST`	`/api/agents/:id/keys`	Créez une clé d'agent.	Chemin : `id`, corps : `label`	Clé JWT ou utilisateur API	`agents/agents.controller.ts`
`DELETE`	`/api/agents/:id/keys/:keyId`	Révoquer une clé d'agent.	Chemin : `id,keyId`	Clé JWT ou utilisateur API	`agents/agents.controller.ts`

MCP Durée d'exécution

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

Demander des formes

Définition de l'agent

CreateAgentDto et UpdateAgentDto dans backend-nestjs/src/agents/dto/agent.dto.ts

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 de registre actuelles de backend-nestjs/src/agents/agent-actions.registry.ts :

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.

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

Source​

Authentification et autorisations​

Référence du point de terminaison​

Gestion des agents​

MCP Durée d'exécution​

Demander des formes​

Définition de l'agent​

Autorisations​

Clés et exécution​

Catalogue et modèle de portée​

Exemples d'appels​

Créer un agent​

Remplacer les autorisations de l'agent​

Appeler le runtime MCP​

Notes de réponse et de comportement​

Meilleures pratiques​