Crear el flujo de trabajo de la API

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

Paso 1: crea el flujo de trabajo de la API de Monster Query

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.

Este paso tiene seis pasos secundarios; asigna entre 10 y 15 minutos para completarlo.

Crear un nuevo proyecto de flujo de trabajo de 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.

Cambia el nombre de la solución y el flujo de trabajo predeterminado. Abre el menú contextual para cada nombre en el explorador de proyectos y selecciona Cambiar nombre:

• Nombre de la solución: Monster Query - 5e SRD
• Nombre del flujo de trabajo: API Query - 5e Monsters

Configurar entradas y salidas

Selecciona Data Manager (icono del portapapeles en la barra izquierda) para acceder a las variables de datos para el flujo de trabajo.

Añade un argumento de entrada al flujo de trabajo:

Nombre	Tipo	Obligatorio	Descripción
searchName	Cadena	Sí	El nombre del monstruo o el nombre parcial que se buscará

Añade un argumento de salida:

Nombre	Tipo	Obligatorio	Descripción
monsterResults	Matriz	Sí	Lista de resultados de Monster

Añadir la solicitud 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. Abre el menú contextual de la actividad y selecciona Cambiar nombre. Nómbralo 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. Establezca la URL en https://api.open5e.com/v2/creatures/.
5. Cambia el nombre de la salida de la actividad a 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:

Clave	Valor
name__icontains	the searchName input argument - see the warning below
document__key	srd-2014
limit	10
fields	key,name,type,size,challenge_rating,alignment

ADVERTENCIA:

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.

Qué hace cada parámetro:

• name__icontains: coincidencia parcial que no distingue entre mayúsculas y minúsculas; dragon devuelve "Dragón rojo adulto", "Dragón azul joven" y otros
• 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: limita los candidatos a 10; suficiente para que el agente razone sin inundar su contexto
• fields: limits the response to only the fields the agent needs; the full v2 creature object is much larger and would waste token budget

ADVERTENCIA:

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.

Referencia de propiedad de solicitud HTTP

La actividad expone los bloques de construcción HTTP estándar. La mayoría de los que configurarás para cada API que llames; algunas las omitirás para API públicas como esta:

• Autenticación: opciones prediseñadas para OAuth 2.0, clave API y autenticación básica. Establezca aquí como "Autenticación manual" porque Open5e no requiere ninguna. Para las API autenticadas, elige la opción adecuada y proporciona las credenciales.
• Encabezados: pares clave/valor enviados con cada solicitud. Usos comunes: Authorization: Bearer <token> para API basadas en token, Accept: application/json para controlar el formato de respuesta y encabezados de versiones de API.
• Cuerpo: se utiliza con solicitudes POST, PUT y PATCH para enviar JSON, datos de formulario o contenido sin procesar. No aplicable a las solicitudes GET, que llevan parámetros en la URL a través de parámetros de consulta.
• 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.

Añadir la respuesta

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. Establece el cuerpo de la respuesta en:

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

$context.outputs contiene todas las salidas con nombre de las actividades de este flujo de trabajo. searchResults es la variable de salida que has cambiado de nombre en la actividad Solicitud HTTP; .content.results navega en el sobre de respuesta en el que Open5e envuelve sus datos, hasta la matriz real de entradas de monstruos. Para obtener más información, consulta la documentación de UiPath sobre el uso de Javascript para acceder a los datos del flujo de trabajo.

Probar el flujo de trabajo

1. Selecciona Depurar en la barra de herramientas.
2. En el panel de entrada, establece searchName como dragon o goblin y ejecuta el flujo de trabajo.
3. Verifique que la respuesta incluya una matriz monsterResults con entradas de monstruos antes de continuar.

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.

Publicar en su fuente

La publicación registra el flujo de trabajo como un proceso implementable en Orchestrator. Esto es lo que lo hace reconocible en la lista de recursos disponibles del Agent Builder: el creador muestra los flujos de trabajo publicados desde tu espacio de trabajo, no los borradores guardados localmente en Studio Web.

1. Selecciona Publicar en la barra de herramientas.
2. En el cuadro de diálogo de publicación, selecciona Para mí publicar en tu fuente de espacio de trabajo personal. Una fuente de espacio de trabajo personal es un repositorio de paquetes privado vinculado a tu espacio de trabajo de Orchestrator; publicar "Para mí" hace que este flujo de trabajo sea visible solo para ti, que es el ámbito correcto para el desarrollo y las pruebas. Consulta Espacios de trabajo personales en los documentos de UiPath para obtener más información.
3. Selecciona Publicar para confirmar.

Nota:

¿El flujo de trabajo no aparece en Recursos disponibles en el paso 3? El flujo de trabajo debe publicarse (no solo guardarse) antes de que sea visible como herramienta. Si no aparece, vuelve aquí y confirma que la publicación se ha completado correctamente y, a continuación, actualiza Agent Builder.

---

Con el flujo de trabajo publicado, está disponible en el Agent Builder como herramienta conectable en la siguiente sección.