navigate_workspace · Documentation Subagent

En bref

Propriété	Valeur
Titre	Afficher une page dans Subagent
Outil MCP	`navigate_workspace`, sur `https://api.subagent.fr/mcp`
Appelé par	l’assistant et la vue
Appel HTTP	`POST https://api.subagent.fr/v1/navigate_workspace`
Accès	toute clé
État de l’espace	vérifié ou non
Effet	lecture seule
Vue dans l’assistant	non

Ce que fait l’outil

Le serveur décrit l’outil ainsi à l’agent qui se branche :

Pilote l’établi déjà ouvert, sans créer de carte. Reprenez l’instance_id du contexte de cette conversation. page=audiences, contacts ou campagnes ; performances avec arguments.campaign_id pour une campagne sélectionnée. Une navigation demandée peut attendre la fin d’une saisie : ne prétendez pas qu’elle est déjà affichée. Aucun envoi.

Paramètres

navigate_workspace accepte ces paramètres. Un paramètre inconnu est refusé avec le code invalid_argument.

Paramètre	Type	Obligatoire	Description
`page`	texte	oui	Rubrique à afficher. jour par défaut. performances avec `campaign_id` montre les résultats de cette campagne. Valeurs : `jour`, `valider`, `fils`, `campagnes`, `audiences`, `contacts`, `boites`, `domaines`, `blocages`, `espace`, `performances`.
`arguments`	objet	non	Arguments de lecture de la page : query pour chercher un contact, email pour sa fiche, `campaign_id`, `audience_id`, `thread_id` ou `message_id` pour ouvrir un détail. Aucun envoi.
`instance_id`	texte	oui	Identifiant de l’établi actif, fourni par son contexte. Ne jamais en inventer ni reprendre celui d’une autre conversation.

Résultat

L’outil rend un texte lisible en français et un objet structuré (structuredContent). En HTTP, la réponse est cet objet.

Champ	Type	Contenu
`_navigation`	objet	Reçu de navigation : `instance_id`, sequence et route. Ce reçu ne contient pas le résultat de lecture et ne confirme pas son affichage.
`closed`	booléen	Instance libérée.
`instance_id`	texte	Instance de cet établi.
`sequence`	entier	Numéro de séquence de cette instance ; sert à ignorer les commandes anciennes. Présent selon la forme du résultat.
`status`	texte	pending ou superseded : navigation demandée, pas confirmation de son affichage.
`unchanged`	booléen	Aucune nouvelle page à appliquer.

Exemple d’appel

Les valeurs sont fictives.

HTTP

curl -X POST https://api.subagent.fr/v1/navigate_workspace \
  -H "Authorization: Bearer $SUBAGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "instance_id": "7e4b6dc2-3a91-4d85-8cf0-1e692b4c3a70",
  "page": "contacts",
  "arguments": {
    "query": "Alice"
  }
}'

MCP · tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "navigate_workspace",
    "arguments": {
      "instance_id": "7e4b6dc2-3a91-4d85-8cf0-1e692b4c3a70",
      "page": "contacts",
      "arguments": {
        "query": "Alice"
      }
    }
  }
}

Refus possibles

Code	HTTP	Ce qui s’est passé	Que faire
`workspace_expired`	404	L’instance de l’établi a expiré, a été fermée, ou n’est pas accessible avec cette connexion.	Rouvrir avec `open_workspace`, puis reprendre le nouvel `instance_id` fourni par cette conversation.
`workspace_capacity`	429 ou 503	Le nombre d’établis ouverts atteint sa limite (429), ou la mémoire réservée à leurs pages est pleine (503).	Réutiliser l’instance de cette conversation, fermer les vues inutilisées et réessayer dans un instant.
`access_changed`	409	Les droits de la connexion ont changé pendant une lecture ou la synchronisation de l’établi.	Rouvrir l’établi avec l’accès actuel ; le contexte de l’ancien accès ne vaut plus.

S’y ajoutent les refus communs à tous les outils (unauthorized, forbidden, invalid_argument, rate_limited, internal) : voir Erreurs.

`navigate_workspace`