Créer le workflow d’API

Build a Monster Query API Workflow that calls the 5e SRD and returns structured monster data.

Étape 1 - Créer le workflow de l'API Test Manager

An API Workflow is a lightweight workflow published as an API endpoint. You build one that wraps the Open5e 5e SRD monster search: one input, one HTTP request, one output. Once published, it appears in the agent builder as a tool your agent can call.

Cette étape comporte six sous-étapes; Prévoyez 10 à 15 minutes pour la réaliser.

Créer un nouveau projet de workflow d’API

Select Create New from your Cloud Workspace. In the Start building dialog, choose API Workflow under Task automation.

Selecting the type creates the project immediately, with no name prompt, so you rename it in the next step.

Renommez la solution et le workflow par défaut. Ouvrez le menu contextuel de chaque nom dans l'explorateur de projet et sélectionnez Renommer:

• Nom de la solution: Monster Query - 5e SRD
• Nom du workflow: API Query - 5e Monsters

Configurer les entrées et les sorties

Sélectionnez le gestionnaire de données (icône dans le presse-papiers le long de la barre de gauche) pour accéder aux variables de données du workflow.

Ajoutez un argument d'entrée au workflow:

Nom	Saisie de texte	Requis	Description
searchName	Chaîne de caractères (string)	Oui (Yes)	Le nom du moniteur ou le nom partiel à rechercher

Ajoutez un argument de sortie:

Nom	Saisie de texte	Requis	Description
monsterResults	Tableau	Oui (Yes)	Liste des résultats Extras

Ajouter la requête HTTP

1. In the workflow canvas, select + between activities to open the activity menu. Select HTTP. The activity appears on the canvas as HTTP Request.
2. Ouvrez le menu contextuel de l'activité et sélectionnez Rename (Renommer). Nommez-le HTTP Request - Open5e Monster Query.
3. In the Properties pane, confirm Authentication is Manual authentication and Method is GET. Both are the defaults on a new activity, so there is normally nothing to change.
4. Définissez l'URL sur https://api.open5e.com/v2/creatures/.
5. Renommez la sortie de l'activité searchResults.

Set the Query parameters property:

Open the Query parameters property, which opens a Dictionary editor with Key and Value columns, and add the following fields:

Clé (Key)	Valeur (Value)
name__icontains	the searchName input argument - see the warning below
document__key	srd-2014
limit	10
fields	key,name,type,size,challenge_rating,alignment

Avertissement :

name__icontains takes the searchName variable, and you must pick it from the variable picker rather than typing it. In the value field, start by typing @ to open the picker and select searchName - not using the picker will send the input as a literal string, and the API will return HTTP 200 with no results. The field then renders the value as a chip, and the stored value is $input.searchName.

Ce que chaque paramètre fait:

• name__icontains: correspondance partielle insensible à la casse; dragon renvoie « Attribuer un mot de passe rouge», « Forcer le bleu», et d'autres
• document__key: srd-2014: filters to the official 5e SRD; without it, results include every publisher in the database, third-party content included
• limit: 10: limite les candidats à 10; suffisamment pour que l'agent raisonne sans inonder son contexte
• fields: limits the response to only the fields the agent needs; the full v2 creature object is much larger and would waste token budget

Avertissement :

Open5e ignores query parameters it does not recognize, and returns HTTP 200 anyway. Misspell document__key, or use the v1 spelling document__slug, and the filter is silently dropped: the call succeeds, the run is green, and the agent receives creatures from every publisher instead of the SRD. A goblin search returns 2 results with the filter applied and 29 without it, so check that the result count looks like a handful rather than a catalogue.

Référence de la propriété de la requête HTTP

L'activité expose les blocs de construction HTTP standard. La plupart des éléments que vous configurerez pour chaque API que vous appellerez; certaines que vous ignorerez pour les API publiques comme celle-ci:

• Authentification: options prédéfinies pour OAuth 2.0, Clé API et Authentification de base. Définissez sur « Authentification manuelle » ici, car Open5e n’en nécessite aucune. Pour les API authentifiées, choisissez l'option appropriée et fournissez les informations d'identification.
• En-têtes: paires clé/valeur envoyées avec chaque requête. Utilisations courantes: Authorization: Bearer <token> pour les API basées sur des jetons, Accept: application/json pour contrôler le format de la réponse et les en-têtes de contrôle de version des API.
• Corps: utilisé avec les requêtes POST, PUT et PATCH pour envoyer du JSON, des données de formulaire ou du contenu brut. Non applicable pour les requêtes GET, qui comportent des paramètres dans l'URL via des paramètres de requête.
• Query parameters: key/value pairs appended to the URL. To reference a workflow argument, enter @ to open the variable picker and select the argument - the field stores $input.<name> and displays it as a chip. @ is the picker's trigger character, not a reference syntax you can type out. See configuring activities for more on variables and expressions in Studio Web.
• Output (renamed to searchResults): receives the full HTTP response including status code, headers, and body. Renaming from the default keeps the Response expression readable.

Ajouter la réponse

1. In the workflow canvas, select + after the HTTP Request and select Response.

   The Response activity defines what the API Workflow returns to its caller (in this case, what the agent's tool receives when it invokes the workflow). Whatever you put in the response body here becomes the tool output the agent reasons over.

2. Définissez le corps de la réponse sur:

   {
     "monsterResults": $context.outputs.searchResults.content.results
   }
   

$context.outputs contient chaque sortie nommée des activités de ce workflow. searchResults est la variable de sortie que vous avez renommée sur l’activité Requête HTTP; .content.results navigue dans l'enveloppe de réponse dans laquelle Open5e encapsule ses données, jusqu'au tableau réel des entrées Extras. Pour plus d'informations, consultez la documentation UiPath sur l'utilisation de JavaScript pour accéder aux données de workflow.

Tester le workflow

1. Sélectionnez Debug dans la barre d'outils.
2. Dans le panneau de saisie, définissez searchName sur dragon ou goblin et exécutez le workflow.
3. Vérifiez que la réponse inclut un tableau monsterResults avec des entrées Extra avant de continuer.

A successful response contains up to 10 entries, each with key, name, alignment, and challenge_rating, plus nested type and size objects. Searching goblin returns Goblin and Hobgoblin. If you see an empty array, try a different search term; not every creature name has an exact match in the SRD.

Publier dans votre flux

La publication enregistre le workflow en tant que processus déployable dans Orchestrator. C’est ce qui le rend détectable dans la liste des ressources disponibles de l'Agent Builder: le générateur fait apparaître les workflows publiés de votre espace de travail, et non les brouillons enregistrés localement dans Studio Web.

1. Sélectionnez Publier dans la barre d'outils.
2. Dans la boîte de dialogue de publication, sélectionnez Pour moi afin de publier sur votre flux d'espace de travail personnel. Un flux d'espace de travail personnel est un référentiel de package privé lié à votre espace de travail Orchestrator; la publication de « Pour moi » rend ce workflow visible uniquement par vous, ce qui constitue l’étendue appropriée pour le développement et les tests. Pour de plus amples informations, consultez la section Espaces de travail personnels dans la documentation UiPath.
3. Sélectionnez Publier pour confirmer.

Remarque :

Workflow n’apparaissant pas dans Ressources disponibles à l’étape 3? Le workflow doit être publié (pas seulement enregistré) avant d'être visible en tant qu'outil. S’il ne s’affiche pas, revenez ici et confirmez que la publication est terminée, puis actualisez Agent Builder.

---

Une fois le workflow publié, il est disponible dans l'Agent Builder en tant qu'outil connectable dans la section suivante.