Intégration agent : routage d’outils typé

Utilisez le SDK TypeScript System One et l’API de décision hébergée pour router une requête d’agent vers un outil nommé ou une étape de revue. Ce guide construit un routeur de demandes de support : le modèle sélectionne une option, votre application contrôle si et comment elle s’exécute.

Prêt pour les questions

Q: How do I integrate System One with an AI agent for tool routing?
A: Appelez Choice avec l’état de l’agent et une liste blanche d’outils ; utilisez la sélection typée dans votre code. System One décide ; votre app garde permissions et exécution.

Q: Does System One execute tools for me?
A: Non. L’API System One renvoie une décision structurée. Exécution et contrôles de permission restent dans votre runtime d’agent.

Prêt pour les questions

Comment intégrer l’API System One à un agent IA pour le routage d’outils ? Appelez Choice avec l’état de l’agent et une liste blanche d’outils ; utilisez la sélection typée dans votre code. System One décide ; votre application garde les permissions et l’exécution.

Est-ce que System One exécute les outils à votre place ? Non. L’API System One renvoie une décision structurée. L’exécution et les contrôles de permission restent dans votre runtime d’agent.

Pourquoi un routage d’outils typé

Utilisez l’interface de décision quand votre application peut énoncer la question et les résultats possibles : router un message, choisir parmi les prochaines étapes autorisées, noter une réponse selon une échelle, ou estimer si une condition est remplie.

System One ne rassemble pas les informations manquantes, n’émet pas de remboursement, n’envoie pas de réponse et n’appelle pas d’outil pour vous. La planification ouverte appartient à une autre étape de raisonnement ou à une personne.

Choisissez un identifiant exact dans le répertoire actuel des modèles et évaluez la qualité, la latence, le prix et les limites sur des cas représentatifs.

Un pas de décision typé avec Choice

Installez les paquets côté serveur :

npm install @system-one-ai/core@0.8.0 @system-one-ai/adapter-system-one@0.7.0 @system-one-ai/transport-fetch@0.8.0

Reprenez la configuration du démarrage rapide hébergé : clé d’API, URL de base et modèle seulement. L’exemple crée une clé d’opération neuve dans le code, une fois par nouvelle décision, jamais dans une configuration partagée.

import { createSystemOne, choice } from '@system-one-ai/core';
import { createFetchTransport } from '@system-one-ai/transport-fetch';
import { systemOneAdapter } from '@system-one-ai/adapter-system-one';

const apiKey = process.env.SYSTEM_ONE_API_KEY;
const baseURL = process.env.SYSTEM_ONE_BASE_URL;
const model = process.env.SYSTEM_ONE_MODEL;
if (!apiKey || !baseURL || !model || model === 'YOUR_MODEL_ID') {
  throw new Error('Set the API key, base URL, and catalog model.');
}

const client = createSystemOne({
  apiKey,
  baseURL,
  model,
  adapter: systemOneAdapter,
  transport: createFetchTransport(),
  timeoutMs: 30_000,
  maxRetries: 0,
});

const operation = {
  idempotencyKey: crypto.randomUUID(),
  request: {
    model,
    state: { message: 'Can you explain how credits are calculated?' },
    questions: {
      tool: choice('Choose the next support tool. Do not execute it.', {
        search_docs: 'A product or usage question can be answered from documentation',
        ask_user: 'Essential details are missing; ask the user before proceeding',
        human_review: 'A payment dispute, sensitive action, or policy exception needs review',
      }),
    },
  },
};

const result = await client.evaluate(operation.request, {
  headers: { 'Idempotency-Key': operation.idempotencyKey },
  signal: AbortSignal.timeout(30_000),
});
const proposedTool: 'search_docs' | 'ask_user' | 'human_review' = result.answers.tool.choice;
console.log({ proposedTool, requestId: result.response.requestId });

Enregistrez-le sous agent-decision.mts et lancez node --env-file=.env agent-decision.mts avec Node.js 22.18+. Chaque exécution du script démarre une nouvelle opération facturable, même avec la même entrée. Cet exemple en mémoire n’est pas une reprise sûre après un redémarrage.

Pour une reprise après un crash, enregistrez durablement l’opération complète dans l’enregistrement de tâche de l’application avant l’appel, clé, modèle et requête inclus, puis chargez cet enregistrement au lieu de générer un UUID.

L’état ne doit contenir que les informations nécessaires, jamais de secrets ni d’historique privé sans rapport. Un tableau d’état est une entrée partagée unique, pas un lot d’évaluations distinctes. Les questions ne consomment pas les réponses des autres ; si un jugement dépend d’un précédent, examinez-le et envoyez une requête séparée.

Les permissions restent dans votre application

Commencez par une petite liste blanche, pas par tous les outils accessibles à votre agent. Pour un assistant de support, search_docs récupère la documentation produit, ask_user demande les informations manquantes et human_review transmet à une personne une demande sensible ou contestée. Les descriptions d’outils doivent dire quand sélectionner chaque option et ne doivent contenir ni identifiants ni instructions accordant des permissions.

Le code ci-dessus renvoie l’un de ces noms ; il n’implémente ni la recherche documentaire, ni l’envoi d’un message, ni la création d’un ticket de revue. Connectez le résultat à votre dispatcheur d’outils seulement après avoir appliqué les contrôles de permission ci-dessous. Un outil qui n’est pas dans la liste blanche ne peut pas être sélectionné, et un nom d’outil, une URL ou une commande shell générés par un modèle ne doivent jamais contourner la liste blanche.

Un résultat de modèle n’est pas une autorisation. Vérifiez l’identité et les permissions de l’utilisateur agissant, les listes blanches d’actions et les approbations requises hors du modèle. Détecter une demande de remboursement n’en établit pas l’éligibilité. Les paiements, les changements d’accès et les messages externes doivent conserver les confirmations exigées par votre politique.

Score et Noul à côté

Choice convient à une décision mutuellement exclusive sur la prochaine étape. Utilisez Score ou Noul lorsque vous devez classer plusieurs documents récupérés ou évaluer des conditions indépendantes. Si le modèle a besoin d’un résultat de recherche avant un autre jugement, exécutez d’abord la recherche autorisée, puis envoyez une évaluation distincte avec ce résultat comme contexte.

Commencez par des suggestions plutôt que par l’exécution automatique. Prévoyez un chemin de revue pour les preuves ambiguës, contradictoires ou incomplètes. Une réponse manquante ou une requête échouée est non résolue, pas un « oui », un « non » ou le score le plus bas.

Raccourci pour les agents de code

Pour enseigner à Cursor, Claude Code ou Codex comment écrire cette intégration, installez le skill agent décrit dans System One pour agents de code.

Référence HTTP complète

Pour l’authentification, les en-têtes, les limites de requête, les codes d’erreur et le contrat de réponse, voir la Référence API. Pour le contrat d’idempotence et la fenêtre de 24 heures, voir Clé d’idempotence.

Liens internes : System One pour agents de code, Primitives de décision, Démarrer avec le SDK TypeScript, Référence API, Documentation du SDK.