Create and run your first agent

This tutorial walks you through the complete builder workflow in FlowAI: creating an agent project, configuring an agent, validating its tools, and running your first session. When you’re done, you’ll have a working agent that you can build on and govern.

Before you begin

An active FlowAI subscription. Contact your Customer Service Manager (CSM) to subscribe.
Itential Gateway 5.5 and Gateway Manager 1.2 or later deployed in your environment. Gateway handles all tool execution at runtime. Contact your Platform admin to confirm. For more information, see System requirements.
At least one provider profile configured in Model Registry with an enabled model. If no profiles are configured, contact your LLM admin. For more information, see Model Registry.
Access to at least one tool your agent can invoke, such as a workflow, adapter API, or Gateway service. You can create and save an agent without tools, but it won’t be able to do anything useful.

Step 1: Create a project

Every agent must belong to a project. Projects group related agents and control who can view, edit, and run them.

In the Platform sidebar, go to Design and click Agent Projects.

Click Create Project.

Enter a Project Name. Optionally, enter a Description.

Click Create. The project is saved and you’re assigned the Owner role automatically.

You can add team members to the project now or after your agent is ready. For more information, see Manage agent projects.

Step 2: Build your agent

In your project, click Create Agent.

Enter a Name. The name must be unique within the project. It appears in the agent list, in Operations Manager automations, and when the agent is exposed as a tool to other agents.

Enter a Prompt. Write in plain text to define the agent’s role, behavior, and constraints.

A well-written prompt tells the agent what it is, what it should do, and what it should not do. For example:

You are a diagnostic assistant for network operations. When given a device
name or IP address, check its connectivity status using the available tools
and summarize your findings. Do not attempt to make configuration changes.

If your prompt references dynamic values, define them as input variables using {{ variableName }} syntax. For more information, see Input variables.

Select Tools. Choose the workflows, adapter APIs, Gateway services, or other agents this agent can invoke. The agent is constrained to only the tools you select here.

For guidance on tool types, visibility rules, and how to browse and select tools, see Tools.

Select a Profile, then select a Model. If no profiles appear, contact your LLM admin.

(Optional) To let people outside your project run this agent, add user groups to Groups. Project Owners and Editors already have run access.

Click Save.

Step 3: Validate your tools

Before an agent can run, every tool you’ve selected must be validated. This confirms the tool reference is reachable and the agent is permitted to use it.

Open the agent details page.

Click Validate for each tool in the list. You must have access to the tool to validate it.

The gate passes when all tools are validated. It’s a one-time action per tool. It doesn’t reset when you update the prompt, swap the model, or remove and re-add the same tool.

If a tool shows as inaccessible, ask a user who has access to that tool to validate it from this page. They don’t need a project role to validate. For more information, see Agent readiness.

Step 4: Run your agent

On the agent details page, click Save and Run.

If your agent has required input variables, provide values for each one in the dialog that appears.

When the session starts, a new browser tab opens to the session detail in Agent Sessions. If the tab opens but shows a loading state, the session is still initializing.

If no tab opens, an error message appears explaining why. Common causes:

Cause	What to do
Agent hasn’t passed the ready gate	Return to Step 3 and validate all tools.
No gateway cluster configured	Contact your admin to configure a gateway cluster in Admin Essentials.
Input data doesn’t match the agent’s input schema	Check that the values you entered match the types defined in the schema.

Step 5: Monitor the session in Agent Sessions

When a session starts, a new tab opens to the session detail in Agent Sessions. Here’s what you’ll find.

Session detail layout

Section	What it shows
Metadata bar	Status, who triggered the session, tools called so far, elapsed time, start and end timestamps. Elapsed time updates live while the session is running.
Agent Instructions	The prompt the agent received before it started. Long prompts are truncated; click Expand to see the full text.
Thoughts and Decisions feed	The full execution trace in chronological order: reasoning, tool calls, and the final response. Latest entry is at the bottom. Auto-scrolls during live sessions.

Read the feed

Each feed entry is collapsed by default. Click Expand on any entry to see its full content. Three filter tabs let you focus on what matters:

Tab	Shows
All	Everything in chronological order.
Agent Reasoning & Response	Only the agent’s thinking and its final response.
Tool Called	Only tool invocations and their results.

Reasoning entries show which tools the agent decided to call as tags next to the entry header. Expand to read the agent’s full reasoning text, including why it chose those tools.

Tool call entries update as the tool executes. Each entry starts in-progress, then resolves to succeeded, failed, or canceled. If a tool call launched a child agent session or a workflow job, the entry includes a link to that child execution.

Agent Response is the last entry in the feed when the session completes.

Handle manual tasks

If the agent invokes a workflow that includes a manual task, the session pauses at that step. The manual task appears in Work Center for an operator to complete. When the task is done, the session resumes automatically. For more information, see Use Work Center.

Intervene in a running session

If you need to stop the agent mid-run, use the Pause or Cancel actions from the session list or session detail.

Pause stops the agent from starting new tool calls. Any in-flight calls finish normally. A paused session can be resumed or permanently canceled.
Cancel is permanent. The agent stops dispatching new tool calls immediately. In-flight calls finish on their own. A canceled session can’t be resumed.

Both actions show a confirmation dialog before taking effect.

For more information, see Monitor agent sessions.

Step 6: Set up triggers in Operations Manager

Save and Run is convenient for testing, but it requires you to open the agent every time. Triggers let operators run the agent on a schedule, via API, from an event, or manually through a dedicated interface, without opening Agent Projects.

Create an automation

In the Platform sidebar, go to Operations and click Operations Manager.

Click Create Automation.

Select Agent as the automation type.

Select your agent from the Agent dropdown. Only agents you have permission to access are shown. You must be an Owner or Editor on the agent’s project, or have been granted operator access on the individual agent.

Add user groups under Access. Users with read access can execute enabled triggers. Users with write access can also update the automation configuration and its triggers.

Click Create.

Add a trigger

After creating the automation, add one or more triggers to define when and how the agent runs.

Open the automation and click Add Trigger.

Select a trigger type: Manual, Schedule, API, or Event.

(Optional) Attach a form to the trigger. The form selection list shows only forms whose field keys are compatible with the agent’s input schema. An attached form is shown to users when they execute a manual trigger or configure a schedule. Each trigger on the same automation can have a different form.

Save the trigger.

When a manual trigger fires, a new browser tab opens to the session detail in Agent Sessions. For schedule, API, and event triggers, sessions appear in Agent Sessions automatically after they start.

For more information, see Create agents in Operations Manager.

What’s next

Create and configure agents

Explore input variables, tool selection, decorators, and agent readiness in depth.

Manage agent projects

Add team members, export projects across environments, and manage access control.