> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/itential-cloud/flowai/quickstart/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Create and run your first agent > Walk through the complete builder workflow in FlowAI. Create a project, configure an agent, pass the agent ready gate, and run your first session. 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.1.1 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](/itential-platform/flowai/overview#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](/itential-platform/flowai/model-registry). * One or more permission groups with FlowAI roles assigned. Ask your admin to create a group and assign roles in [Cloud Hub](/itential-cloud/cloud-hub/administration/manage-users-groups#assign-roles-to-a-group) . This tutorial uses Agent Projects, Model Registry, and Agent Sessions, so make sure your roles cover all three. For the full list, see [FlowAI roles](/itential-cloud/cloud-hub/administration/roles-permissions#flowai-roles) . * 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](/itential-platform/flowai/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](/itential-platform/flowai/agent-projects/agent-builder#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](/itential-platform/flowai/agent-projects/agent-builder#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](/itential-platform/flowai/agent-projects#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](/itential-platform/flowai/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](/itential-platform/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](/itential-platform/flowai/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](/itential-platform/operations-manager/agents). --- ## What's next #### [Create and configure agents](/itential-platform/flowai/agent-projects/agent-builder) Explore input variables, tool selection, decorators, and agent readiness in depth. #### [Manage agent projects](/itential-platform/flowai/agent-projects) Add team members, export projects across environments, and manage access control. > Walk through the complete builder workflow in FlowAI. Create a project, configure an agent, pass the agent ready gate, and run your first session.