UiPath Documentation
getting-started
latest
false
Getting started developer guide
  • Introduction
    • Overview
    • Environment set up
  • Getting Started with UiPath Agents
  • Getting Started with UiPath Agents using LangGraph
  • Building a Low-Code Agent in Studio Web
  • Adding Tools to Your UiPath Agent
    • Introduction
    • Build the API workflow
    • Connect to your agent
    • Test end-to-end
    • Evaluate agent trajectory
  • Getting Started with the Flow canvas in UiPath Maestro

Build the API workflow

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

Step 1 - Build the Monster Query API workflow​

An API workflow is a lightweight workflow published as an API endpoint. You build a simple one that wraps the Open5e monster search for the 5e System Reference Document (SRD): it takes a string input, does an HTTP request, and returns an array of monster entries, each a JSON string that the agent parses. Because it lives in the same solution as your agent, the agent builder lists it as a tool your agent can call.

This step has five tasks, plus a property reference for the HTTP Request activity; budget 10–15 minutes to complete it.

Create a new API workflow project​

  1. Open your quest classifier solution in Studio Web: the one from the low-code lab, or AdvGuild.quest-classifier if you deployed the starter.
  2. In the Project Explorer pane, select Add to solution (+ icon) and choose API Workflow under Task automation.
  3. Rename the project to API Query - 5e Monsters and select the Apply check icon. You can also rename the project by opening the context menu in the project explorer and selecting Rename.

Configure inputs and outputs​

  1. Select the Data Manager (clipboard icon along the left rail) to access the data variables for the workflow.

  2. Add one input argument to the workflow:

    NameTypeRequiredDescription
    searchNameStringYesThe monster name or partial name to search for
  3. Add one output argument:

    NameTypeRequiredDescription
    monsterResultsArray[String]YesMonster result list

Add the HTTP request​

  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. Open the activity context menu and select Rename.
  3. Enter HTTP Request - Open5e Monster Query as the name.
  4. 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.
  5. Set URL to https://api.open5e.com/v2/creatures/.
  6. Rename the activity output to searchResults.

Set the query parameters​
  1. Open the Query parameters property. It opens a Dictionary editor with Key and Value columns.

  2. Add the following fields:

    KeyValue
    name__icontainsthe $input.searchName input argument - see the note that follows
    document__keysrd-2024
    limit10
    fieldskey,name,type,size,challenge_rating,alignment
Important:

Use the Expression Editor to enter $input.searchName, instead of entering it as text. After you select Save in the expression editor, the value renders as a chip. Entered as plain text, $input.searchName goes to the API as a literal string and returns zero results while every node stays green.

What each parameter does:

  • name__icontains: case-insensitive partial match; dragon returns "Adult Red Dragon", "Young Blue Dragon", and others
  • document__key: srd-2024: filters to the official 5e SRD (the 2024 edition); without it, results include every publisher in the database, third-party content included
  • limit: 10: caps candidates at 10; enough for the agent to reason over without flooding its context
  • fields: limits the response to only the fields the agent needs; the full v2 creature object is much larger and would waste token budget
Important:

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 call returns creatures from every publisher instead of the SRD. A goblin search returns 5 results with the filter applied and 29 without it.

HTTP Request property reference​

The activity exposes the standard HTTP building blocks. You configure most of them for every API you call, and skip some for public APIs like this one:

  • Authentication: pre-built options for OAuth 2.0, API key, and Basic auth. Set to "Manual authentication" here because Open5e requires none. For authenticated APIs, choose the appropriate option and supply credentials.
  • Headers: key/value pairs sent with every request. Common uses: Authorization: Bearer <your-access-token> for token-based APIs, Accept: application/json to control response format, and API versioning headers.
  • Body: used with POST, PUT, and PATCH requests to send JSON, form data, or raw content. Not applicable for GET requests, which carry parameters in the URL via query parameters.
  • Query parameters: key/value pairs appended to the URL. To reference a workflow argument, use the Expression Editor to enter $input.<name>; after you save the expression, the field displays it as a chip. 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.

Add the response​

  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). The response body becomes the tool output the agent reasons over.

  2. Set the response body to:

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

$context.outputs contains every named output from the activities in this workflow. searchResults is the output variable you renamed on the HTTP Request activity; .content.results navigates into the response envelope that Open5e wraps its data in, down to the array of monster entries. For more information, see the UiPath documentation on using JavaScript to access workflow data.

Test the workflow​

  1. Select Debug from the toolbar.
  2. In the input panel, set searchName to rat and run the workflow.

The response includes a monsterResults array of up to 10 entries. Each entry has:

  • key
  • name
  • alignment
  • challenge_rating
  • Nested type and size objects

Searching rat returns exactly seven results, all with srd-2024_ keys, including:

  • Giant Rat (srd-2024_giant-rat, challenge rating 0.125)
  • Swarm of Rats (srd-2024_swarm-of-rats, challenge rating 0.25)
  • Triceratops (srd-2024_triceratops, challenge rating 5)
  • Two pirates, because name__icontains matches the search text anywhere in the name

Any other count means a parameter is misspelled or not bound to the variable; fix it before you continue.


With the workflow returning results, switch back to the agent in the same solution to connect it as a tool.

Was this page helpful?

Connect

Need help? Support(opens in new window)

Want to learn? UiPath Academy(opens in new window)

Have questions? UiPath Forum(opens in new window)

Stay updated