UiPath Documentation
getting-started
latest
false
Getting started developer guide
  • Overview
    • Overview
  • Getting Started with UiPath Agents
    • Introduction
    • Set up your environment
    • Build the agent
    • Test the agent
  • Getting Started with UiPath Agents using LangGraph
  • Building a Low-Code Agent in Studio Web
  • Adding Tools to Your UiPath Agent

Build the agent

Define the agent contract, write the system prompt, and configure the input and output schemas in agent.json.

With the CLI installed and your UiPath account connected, you are ready to scaffold the agent.

Step 4 - Scaffold the solution and agent​

Low-code agents live inside a solution, the deployable unit the CLI uploads to Studio Web. You create the solution first, then scaffold the agent inside it.

  1. Create a working directory and scaffold the solution:

    mkdir Monster-Selector-Lab
cd Monster-Selector-Lab
uip solution init MonsterSelector
mkdir Monster-Selector-Lab
cd Monster-Selector-Lab
uip solution init MonsterSelector

    This creates a MonsterSelector/ directory containing MonsterSelector.uipx (the solution manifest), plus AGENTS.md and CLAUDE.md briefing files that orient coding agents to the solution structure.

  2. Scaffold the agent project inside the solution directory:

    uip agent init MonsterSelector/MonsterSelector
uip agent init MonsterSelector/MonsterSelector

    uip agent init <path> creates the agent project at the given path and automatically registers it with the solution. It generates agent.json (the system prompt, schemas, and model settings), entry-points.json, an empty evals/ scaffold, and an auto-generated project ID.

  3. Move into the solution directory for the remaining steps:

    cd MonsterSelector
cd MonsterSelector
Note:

Two directories named MonsterSelector. Your lab directory now contains MonsterSelector/ (the solution) which in turn contains another MonsterSelector/ (the agent project). This is normal: the solution and the agent project can share a name. As you work through the next steps, pay attention to which directory you are in. Step 4 ends with you inside the solution directory (Monster-Selector-Lab/MonsterSelector/).

Step 5 - Configure the agent​

Agent configuration is defined by the agent.json and entry-points.json files. You edit these directly to implement the design from the beginning of this lab, replacing the placeholder content the scaffold generated.

Configure agent.json​

To replace the scaffold, open MonsterSelector/agent.json (relative to the solution directory you are in). Replace its entire contents with the following. The one exception is the projectId value on the last line; keep the UUID your scaffold generated rather than using the placeholder shown here.

The JSON below implements the design from What you are building:

  1. Input schema: questDescription (string) and monsters (array), both required.
  2. Output schema: monsterIndex (string).
  3. System prompt: the instruction text in messages[0] (the system role) that tells the model how to reason.
  4. User turn: the message in messages[1] (the user role) that carries questDescription and monsters into the prompt at run time: this is the LLM conversation turn, not a human end user.
{
  "version": "1.1.0",
  "settings": {
    "model": "gpt-4.1-2025-04-14",
    "maxTokens": 16384,
    "temperature": 0,
    "engine": "basic-v2",
    "maxIterations": 25,
    "mode": "standard"
  },
  "inputSchema": {
    "type": "object",
    "properties": {
      "questDescription": {
        "type": "string",
        "description": "Description of the quest"
      },
      "monsters": {
        "type": "array",
        "description": "Candidate monsters from the D&D 5e API"
      }
    },
    "required": ["questDescription", "monsters"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "monsterIndex": {
        "type": "string",
        "description": "The index slug of the chosen monster"
      }
    }
  },
  "metadata": {
    "storageVersion": "50.0.0",
    "isConversational": false,
    "showProjectCreationExperience": false,
    "targetRuntime": "pythonAgent"
  },
  "type": "lowCode",
  "messages": [
    {
      "role": "system",
      "content": "You are an RPG game master helping to select the most thematically appropriate monster for a quest. Given a quest description and a list of candidate monsters (each with a name and an index slug), pick the ONE monster whose lore, environment, or threat level best fits the quest. Return ONLY the index slug of your chosen monster. Do not return the full object or any commentary - just the string slug. If multiple candidates fit, favor the most iconic or thematically resonant choice.",
      "contentTokens": [
        {
          "type": "simpleText",
          "rawString": "You are an RPG game master helping to select the most thematically appropriate monster for a quest. Given a quest description and a list of candidate monsters (each with a name and an index slug), pick the ONE monster whose lore, environment, or threat level best fits the quest. Return ONLY the index slug of your chosen monster. Do not return the full object or any commentary - just the string slug. If multiple candidates fit, favor the most iconic or thematically resonant choice."
        }
      ]
    },
    {
      "role": "user",
      "content": "{{input.questDescription}} {{input.monsters}}",
      "contentTokens": [
        { "type": "variable", "rawString": "input.questDescription" },
        { "type": "simpleText", "rawString": " " },
        { "type": "variable", "rawString": "input.monsters" }
      ]
    }
  ],
  "projectId": "your-scaffold-generated-uuid-here"
}
{
  "version": "1.1.0",
  "settings": {
    "model": "gpt-4.1-2025-04-14",
    "maxTokens": 16384,
    "temperature": 0,
    "engine": "basic-v2",
    "maxIterations": 25,
    "mode": "standard"
  },
  "inputSchema": {
    "type": "object",
    "properties": {
      "questDescription": {
        "type": "string",
        "description": "Description of the quest"
      },
      "monsters": {
        "type": "array",
        "description": "Candidate monsters from the D&D 5e API"
      }
    },
    "required": ["questDescription", "monsters"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "monsterIndex": {
        "type": "string",
        "description": "The index slug of the chosen monster"
      }
    }
  },
  "metadata": {
    "storageVersion": "50.0.0",
    "isConversational": false,
    "showProjectCreationExperience": false,
    "targetRuntime": "pythonAgent"
  },
  "type": "lowCode",
  "messages": [
    {
      "role": "system",
      "content": "You are an RPG game master helping to select the most thematically appropriate monster for a quest. Given a quest description and a list of candidate monsters (each with a name and an index slug), pick the ONE monster whose lore, environment, or threat level best fits the quest. Return ONLY the index slug of your chosen monster. Do not return the full object or any commentary - just the string slug. If multiple candidates fit, favor the most iconic or thematically resonant choice.",
      "contentTokens": [
        {
          "type": "simpleText",
          "rawString": "You are an RPG game master helping to select the most thematically appropriate monster for a quest. Given a quest description and a list of candidate monsters (each with a name and an index slug), pick the ONE monster whose lore, environment, or threat level best fits the quest. Return ONLY the index slug of your chosen monster. Do not return the full object or any commentary - just the string slug. If multiple candidates fit, favor the most iconic or thematically resonant choice."
        }
      ]
    },
    {
      "role": "user",
      "content": "{{input.questDescription}} {{input.monsters}}",
      "contentTokens": [
        { "type": "variable", "rawString": "input.questDescription" },
        { "type": "simpleText", "rawString": " " },
        { "type": "variable", "rawString": "input.monsters" }
      ]
    }
  ],
  "projectId": "your-scaffold-generated-uuid-here"
}
Note:

temperature: 0. reduces output variance but does not make the model fully deterministic. Even at 0, the model can occasionally return different valid outputs across runs. For this agent, any defensible monster pick is correct; exact string reproducibility is not the goal.

Configure entry-points.json​

Now open MonsterSelector/entry-points.json and replace its entire contents with the following. Again, keep the uniqueId value your scaffold generated rather than using the placeholder.

The JSON below defines a single agent entry point, which you call in the steps below. A solution can expose multiple entry points (for example, a simple variant and an extended-input variant of the same agent), but one is all we need here.

{
  "$schema": "https://cloud.uipath.com/draft/2024-12/entry-point",
  "$id": "entry-points.json",
  "entryPoints": [
    {
      "filePath": "/content/agent.json",
      "uniqueId": "your-scaffold-generated-uuid-here",
      "type": "agent",
      "input": {
        "type": "object",
        "properties": {
          "questDescription": {
            "type": "string",
            "description": "Description of the quest"
          },
          "monsters": {
            "type": "array",
            "description": "Candidate monsters from the D&D 5e API"
          }
        },
        "required": ["questDescription", "monsters"]
      },
      "output": {
        "type": "object",
        "properties": {
          "monsterIndex": {
            "type": "string",
            "description": "The index slug of the chosen monster"
          }
        }
      }
    }
  ]
}
{
  "$schema": "https://cloud.uipath.com/draft/2024-12/entry-point",
  "$id": "entry-points.json",
  "entryPoints": [
    {
      "filePath": "/content/agent.json",
      "uniqueId": "your-scaffold-generated-uuid-here",
      "type": "agent",
      "input": {
        "type": "object",
        "properties": {
          "questDescription": {
            "type": "string",
            "description": "Description of the quest"
          },
          "monsters": {
            "type": "array",
            "description": "Candidate monsters from the D&D 5e API"
          }
        },
        "required": ["questDescription", "monsters"]
      },
      "output": {
        "type": "object",
        "properties": {
          "monsterIndex": {
            "type": "string",
            "description": "The index slug of the chosen monster"
          }
        }
      }
    }
  ]
}

Understanding agent.json and entry-points.json​

  • agent.json is the agent definition: the model settings, the system prompt, and the input and output schemas.
  • entry-points.json exposes those schemas to the solution runtime.
  • Important: The inputSchema and outputSchema blocks must be identical in both files. A mismatch causes validation to fail.

Adapting to your use case. To build a different agent, replace the content strings in messages[0] with your system prompt and update the properties blocks in inputSchema and outputSchema to match the fields your prompt refers to. Mirror those same changes in entry-points.json. The settings, metadata, type, and message structure stay the same.

Step 6 - Validate the agent​

From the solution directory, validate the agent:

uip agent validate MonsterSelector
uip agent validate MonsterSelector

You should see "Status": "Valid" with "StorageVersion": "50.0.0" and a "Validated" summary showing agent: true. Validation also generates the .agent-builder/ files used by Studio Web; you do not need to touch these.

If validation fails, confirm that inputSchema and outputSchema are identical in both agent.json and entry-points.json, and that every variable reference in messages[1].content uses the input. prefix (for example, {{input.questDescription}}).

With the agent validated locally, you are ready to upload it to Studio Web and run a live test in the next section.

Was this page helpful?

Connect

Need help? Support

Want to learn? UiPath Academy

Have questions? UiPath Forum

Stay updated