Crie o fluxo de trabalho da API

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

Etapa 1 - Construir o fluxo de trabalho da API do Monstruário 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.

Essa etapa possui seis subetapas; Consulte o orçamento de 10 a 15 minutos para concluí-lo.

Crie um novo projeto de fluxo de trabalho 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.

Renomeie a solução e o fluxo de trabalho padrão. Abra o menu de contexto para cada nome no explorador de projetos e selecione Renomear:

• Nome da solução: Monster Query - 5e SRD
• Nome do fluxo de trabalho: API Query - 5e Monsters

Configurar entradas e saídas

Selecione o Data Manager (ícone da área de transferência ao longo do trilho esquerdo) para acessar as variáveis de dados para o fluxo de trabalho.

Adicione um argumento de entrada ao fluxo de trabalho:

Name	Tipo	Required	Description
searchName	String	Sim	O nome ou nome parcial do compatíveis a ser pesquisado

Adicione um argumento de saída:

Name	Tipo	Required	Description
monsterResults	Matriz	Sim	Lista de resultados mostrados

Adicionar a solicitação 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. Abra o menu de contexto da atividade e selecione Renomear. Nomeie-o 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. Defina URL como https://api.open5e.com/v2/creatures/.
5. Renomeie a saída da atividade para 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:

Chave	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

AVISO:

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.

O que cada parâmetro faz:

• name__icontains: correspondência parcial sem diferenciação entre maiúsculas e minúsculas; dragon retorna "Adult Red Robot", "Young Blue Robot" e outros
• 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 os candidatos em 10; o suficiente para o agente raciocinar sem confundir seu 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

AVISO:

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.

Referência da propriedade da solicitação HTTP

A atividade expõe os blocos de construção HTTP padrão. O máximo que você configurará para cada API que chamar; algumas você ignorará para APIs públicas como esta:

• Autenticação: opções pré-criadas para OAuth 2.0, chave de API e autenticação básica. Defina como "Autenticação manual" aqui porque o Open5e não exige nenhuma. Para APIs autenticadas, escolha a opção apropriada e forneça as credenciais.
• Cabeçalhos: pares de chave/valor enviados com cada solicitação. Usos comuns: para APIs baseadas em token, Authorization: Bearer <token> para controlar Accept: application/json formato de resposta e cabeçalhos de versionamento de API.
• Corpo: usado com solicitações POST, PUT e PATCH para enviar JSON, dados do formulário ou conteúdo bruto. Não aplicável a solicitações GET, que carregam parâmetros no URL por meio 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.

Adicionar a resposta

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. Defina o corpo da resposta como:

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

$context.outputs contém todas as saídas nomeadas das atividades nesse fluxo de trabalho. searchResults é a variável de saída que você renomeou na atividade HTTP Request; .content.results navega pelo envelope de resposta no qual o Open5e envolve seus dados, até a matriz real de entradas entrada "mostradas". Para obter mais informações, consulte a documentação da UiPath sobre o uso do Javascript para acessar dados do fluxo de trabalho.

Teste o fluxo de trabalho

1. Selecione Debug na barra de ferramentas.
2. No painel de entrada, defina searchName como dragon ou goblin e execute o fluxo de trabalho.
3. Verifique se a resposta inclui uma matriz monsterResults com entradas detalhadas 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 em seu feed

A publicação registra o fluxo de trabalho como um processo implantável no Orchestrator. É isso que o torna detectável na lista de recursos disponíveis do Agent Builder: o construtor revela fluxos de trabalho publicados a partir do seu espaço de trabalho, não rascunhos salvos localmente no Studio Web.

1. Selecione Publicar na barra de ferramentas.
2. Na caixa de diálogo de publicação, selecione Para eu publicar no feed do seu espaço de trabalho pessoal. Um feed de espaço de trabalho pessoal é um repositório de pacotes privado vinculado ao seu espaço de trabalho do Orchestrator; publicar "Para mim" torna esse fluxo de trabalho visível apenas para você, que é o escopo correto para desenvolvimento e testes. Consulte Espaços de trabalho pessoais nos documentos da UiPath para obter detalhes.
3. Selecione Publicar para confirmar.

Observação:

O fluxo de trabalho não aparece em Recursos disponíveis na etapa 3? O fluxo de trabalho deve ser publicado (não apenas salvo) antes de ficar visível como uma ferramenta. Se ele não aparecer, retorne aqui e confirme se a publicação foi concluída com sucesso e, em seguida, atualize o Agent Builder.

---

Com o fluxo de trabalho publicado, ele fica disponível no Agent Builder como uma ferramenta conectável na próxima seção.