Table of Contents

Creating Your First Agent

A short, step-by-step guide to creating a working agent in the Management Portal.

Overview

You will create a simple agent that uses the generic agent workflow, one main model, and a system prompt. Optional steps show how to add a tool and adjust the chat experience. For every option in the editor, see Create a New Agent.

Prerequisites

  • The Agents Contributor role on the instance. Without it, the Create Agent button is not shown.
  • At least one AI model of type completion (under Agents > Models).
  • The generic agent workflow (GenericAgentWorkflow) and the FoundationaLLM agent plugins package installed in your instance.

Step 1: Open the Agent Editor

  1. In the sidebar, select Agents > Agents.
  2. Select Create Agent at the top right.

The editor opens on the Basic Settings tab. Create Agent and Cancel are at the top right on every tab.

Step 2: Select the Workflow

  1. Open the Workflow tab.
  2. Under "What workflow should the agent use?", select GenericAgentWorkflow.
  3. Check the defaults that appear:
Field Expected value
Workflow name Agent-Workflow
Workflow package name foundationallm_agent_plugins
Workflow class name A workflow class from the package, for example FoundationaLLMFunctionCallingWorkflow
Workflow host LangChain
  1. If you use FoundationaLLMFunctionCallingWorkflow, add a router prompt:
    1. Next to Additional workflow resources, select the add icon.
    2. Set Resource Type to Prompt.
    3. Type Router in the search box, then select Platform-Agent-Workflow-Router (or another Agent Workflow prompt).
    4. Enter router_prompt as the Resource Role.
    5. Select Save.

Select the workflow before you change Max rounds on Basic Settings; selecting a workflow on a new agent resets the workflow properties.

Step 3: Enter the Basic Settings

  1. Open the Basic Settings tab.
  2. Fill in the fields:
Field Example Notes
Agent Display Name Help Desk Assistant What users see.
Agent name help-desk-assistant Letters, numbers, dashes, and underscores. Wait for ✔️. Cannot be changed later.
Description Answers common IT help desk questions. Optional.
Main model Your completion model Required.
What is the main workflow prompt? See below Required.

Example main workflow prompt:

You are a helpful assistant named Help Desk Assistant that answers IT help desk questions.
Provide concise, accurate answers. If you don't know something, say so clearly.

Step 4: Adjust Agent Behavior (Optional)

On the Agent Configuration tab, select a card to edit it and select Done when finished.

  • Conversation History: set Enabled to Yes so the agent remembers earlier messages. Max Messages defaults to 5.
  • Shielding: add pre-completion or post-completion shielding plugins to screen prompts and responses.
  • Enter a cost center or an expiration date if your organization needs them.

Step 5: Add a Tool (Optional)

  1. Open the Tools tab and select Add Tool.
  2. In the Tool Library, find Code (in the FoundationaLLM family), select Select, and then select Add to Agent.
  3. In Edit Agent Tool, set the Main Model resource reference to a completion model. Keep the default prompts.
  4. Select Save changes.

See Tools for the other tools in the library.

Step 6: Set the Chat Experience (Optional)

On the Portal Experience tab:

  1. Write a Welcome message.
  2. Open Conversation Starters, select Add Starter, and enter a Title and Content. Select Done.
  3. Review the toggles. Message tokens, rating, viewing prompts, and content artifacts are Yes by default; file upload and the operation identifier are No.

Step 7: Create the Agent

  1. Select Create Agent.
  2. If a required field is missing, the editor switches to the tab with the problem and shows a message under the field.
  3. When the agent is saved, the message "Agent "help-desk-assistant" was successfully created!" appears and you return to the Agents page.

Testing Your Agent

  1. Open the User Portal.
  2. Select your new agent.
  3. Send a test message and confirm the response.
  4. If you added the Code tool, ask a question that needs a calculation.

To let other users find the agent, open it again from the Agents page and use Access Control on the Security tab.

Troubleshooting

The Create Agent button is missing

You need the Agents Contributor role on the instance. Ask an administrator to assign it.

The agent name shows ❌

Hover over the icon to see the reason. Choose a different name if it is already taken.

The main model is not listed

Only AI models of type completion are listed. Check the model under Agents > Models.

The agent returns an error about the router prompt

The FoundationaLLMFunctionCallingWorkflow class needs a workflow resource with the router_prompt role. Add one on the Workflow tab, as described in Step 2.

The agent does not appear in the User Portal

  • Confirm the agent was created on the Agents page.
  • Check that the user has access to the agent.
  • Check that the agent hasn't expired.

Next Steps