Crie o agente

Defina o contrato do agente, escreva o prompt do sistema e configure os esquemas de entrada e saída no agent.json.

Com a CLI instalada e sua conta da UiPath conectada, você está pronto para estruturar o agente.

Etapa 4 - Estruturar a solução e o agente

Agentes de pouco código residem dentro de uma solução, a unidade implantável que a CLI carrega para o Studio Web. Você cria a solução primeiro e, em seguida, estrutura o agente dentro dela.

1. Crie um diretório de trabalho e estruture a solução:

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

   Isso cria um diretório MonsterSelector/ contendo MonsterSelector.uipx (o manifesto da solução), além de arquivos de resumo AGENTS.md e CLAUDE.md que orientam agentes de codificação para a estrutura da solução.

2. Estruture o projeto do agente dentro do diretório da solução:

   uip agent init MonsterSelector/MonsterSelector
   

   uip agent init <path> o projeto do agente no caminho fornecido e o registra automaticamente na solução. Ele gera agent.json (a solicitação do sistema, esquemas e configurações do modelo), entry-points.json, um framework evals/ vazio e um ID do projeto gerado automaticamente.

3. Mova para o diretório da solução para as etapas restantes:

   cd MonsterSelector
   

Observação:

Dois diretórios chamados SeletorDeMonstro. Seu diretório de laboratório agora contém MonsterSelector/ (a solução) que, por sua vez, contém outro MonsterSelector/ (o projeto do agente). Isso é normal: a solução e o projeto do agente podem compartilhar um nome. Ao trabalhar nas próximas etapas, preste atenção em qual diretório você está. A etapa 4 termina com você dentro do diretório da solução (Monster-Selector-Lab/MonsterSelector/).

---

Etapa 5 - Configurar o agente

A configuração do agente é definida pelos arquivos agent.json e entry-points.json . Você os edita diretamente para implementar o design do início deste laboratório, substituindo o conteúdo do espaço reservado que o suporte gerou.

Configurar o agent.json

Para substituir o framework, abra MonsterSelector/agent.json (em relação ao diretório da solução em que você está). Substitua todo o seu conteúdo pelo seguinte. A única exceção é o valor projectId na última linha; mantenha o UUID que seu framework gerou em vez de usar o espaço reservado mostrado aqui.

O JSON abaixo implementa o design do que você está construindo:

1. Esquema de entrada: questDescription (string) e monsters (array), ambos obrigatórios.
2. Esquema de saída: monsterIndex string).
3. Prompt do sistema: o texto da instrução em messages[0] (a função system ) que informa ao modelo como raciocinar.
4. Turno do usuário: a mensagem em messages[1] (a função user ) que carrega questDescription e monsters no prompt no tempo de execução: essa é a vez de conversa do LLM, não um usuário final humano.

{
  "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"
}

Observação:

temperature: 0 reduz a variação de saída, mas não torna o modelo totalmente determinístico. Mesmo em 0, o modelo pode ocasionalmente retornar diferentes saídas válidas entre as execuções. Para esse agente, qualquer escolha de alvo deDas está correta; a reprodutibilidade exata da string não é o objetivo.

Configurar entry-points.json

Agora MonsterSelector/entry-points.json e substitua todo o seu conteúdo pelo seguinte. Mais uma vez, mantenha o valor uniqueId que seu robô gerou em vez de usar o espaço reservado.

O JSON abaixo define um agent ponto de entrada, que você chama nas etapas abaixo. Uma solução pode expor vários pontos de entrada (por exemplo, uma variante simples e uma variante de entrada estendida do mesmo agente), mas é tudo o que precisamos aqui.

{
  "$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"
          }
        }
      }
    }
  ]
}

Compreensão do agent.json e do entry-points.json

• agent.json a definição do agente: as configurações do modelo, o prompt do sistema e os esquemas de entrada e saída.
• entry-points.json expõe esses esquemas para o runtime da solução.
• Importante: os blocos inputSchema e outputSchema devem ser idênticos em ambos os arquivos. Uma incompatibilidade faz com que a validação falhe.

Adaptação ao seu caso de uso. Para criar um agente diferente, substitua as strings content em messages[0] por sua solicitação do sistema e atualize os blocos properties em inputSchema e outputSchema para corresponder aos campos aos quais sua solicitação se refere. Espelhe essas mesmas alterações em entry-points.json. O settings, metadata, type e a estrutura da mensagem permanecem as mesmas.

---

Etapa 6 - Validar o agente

No diretório da solução, valide o agente:

uip agent validate MonsterSelector

Você deve ver "Status": "Valid" com "StorageVersion": "50.0.0" e um resumo "Validated" mostrando agent: true. A validação também gera os arquivos .agent-builder/ usados pelo Studio Web; você não precisa tocar neles.

Se a validação falhar, confirme se inputSchema e outputSchema são idênticos em agent.json e entry-points.json, e se cada referência de variável em messages[1].content usa o prefixo input. (por exemplo, {{input.questDescription}}).

---

Com o agente validado localmente, você está pronto para carregá-lo no Studio Web e executar um teste ao vivo na próxima seção.