Prerequisites

Before you begin, confirm that:

• You have the ROLE_AGENT_AUTHOR on the target tenant. For more information about how to get this role, see Assign Agent Builder roles to users.
• At least one user on the tenant must have the ROLE_AGENT_AUTHOR role (PUBLISH permission). Publishing requires an approver with PUBLISH permission.
• The tools you plan to use must be in the tenant-approved tool catalog.

Step 1: Enter agent and prompt information

In this step, define the agent and create its system prompt. You can either enter the information manually or use Agent Blueprint to generate it from your requirements.

Enter agent and prompt information manually

Use this path when you are building a new agent manually from scratch.

1. Open AgentFlow and go to Agent Builder.
2. Select + Build new agent.

   
   
   

3. Under AGENT DETAILS, enter a name, description, and any relevant tags. These values appear in Discover Agents after the agent is published.

   
   
   

   Use the following rules when filling in the agent details fields:

   • Agent name: Letters, numbers, spaces, and _ - ( ) . & ` are allowed.
   • Describe your agent: Maximum 100 characters. The symbols < and > are not allowed.
   • Tags: Letters, numbers, and hyphens only. Separate multiple tags with commas.

   If a field contains an invalid value, an inline error appears below it. Correct the value before continuing.
4. Write the System prompt. The system prompt defines the agent's:
   1. Identity
   2. Objectives
   3. Tool usage rules
   4. Workflow
   5. Guardrails
   6. Output format
   7. Error handling behavior.

   
   
   

   For more information about structuring an effective system prompt, see AgentFlow system prompt guidelines.

5. Select Save & continue.

   After the agent is created, the Agent ID appears in the AGENT DETAILS section. Select the copy icon next to the Agent ID to copy it to your clipboard.

Generate a system prompt using Agent Blueprint

Follow these steps when you want AI to generate a first draft of the system prompt and select the required tools based on your requirements:

1. Open Agentflow and select Agent Builder.
2. Select + Build new agent and select Build new agent from scratch.
3. Select Generate Agent Blueprint.
4. Enter the required details in the following fields:
   • Agent Name: Enter a clear, specific name that describes what the agent does.
   • Short Description: Enter a brief summary of the main purpose of the agent and the benefit it provides to users.
   • Describe your agent: Describe the role of the agents, the tasks the agent must perform, and the type of responses you need.
   • Intended users: Specify the users or roles the agent is intended for
   • Describe use cases: List the main scenarios or business tasks the agent should support.
   • Constraints: Enter any limits or rules the agent must follow, such as read-only access, restricted tools, or response boundaries.
   • Notes: Enter any additional instructions, preferences, or context that helps improve the generated prompt.
5. Select Generate.

   Agent Builder generates a system prompt draft based on the information you entered. On completion, the Generate agent blueprint pop-up appears.

6. Review the generated system prompt and verify the details.
7. Select See assumptions made to review the inputs used to generate the system prompt.
8. Select Next.
9. Review the list of MCP tools selected for the agent.

   Agent Builder automatically selects tools based on your requirements. You can add or remove tools as required.

   Each tool includes a confidence score of High, Medium, or Low.

10. On reviewing all the details of the agent, select Done.

    The Build an agent page appears.

11. Select Save & continue.

    After the agent is created, the Agent ID appears in the AGENT DETAILS section. Select the copy icon next to the Agent ID to copy it to your clipboard.

To continue, see Step 3: Test & publish the agent

Step 2: Tools & capabilities

1. [Optional] Enable Web search.
   Note: Enabling Web search during agent creation is not sufficient. End users must also enable Web search in their own settings before they can use this capability at runtime.
2. Enable server and select each of the tools you want to add. The selected tools form the agent's allowlist — the agent cannot call tools outside this selection.
   Note: If you proceed without selecting any tools, Agent Builder displays a warning before you can submit for review. You can still proceed, but the agent will have no approved actions available at runtime.

   
   
   

3. Select Save & continue.

Step 3: Test & publish the agent

1. Enter a prompt and review the streaming response.
   Note: If a violation is detected in the system prompt, the test run is blocked. Revise the prompt before testing again.
2. Review the run summary after each test. It shows latency, tokens used, and tool calls for that run.
3. Iterate on the prompt and tool selection as needed.

   
   
   

4. Select Submit for review.
5. Confirm the submission.

   A Confirm submit for review dialog appears. Select Submit for review to proceed, or Back to return to the test panel.

   The system automatically scans the system prompt. Two outcomes are possible:

   • If no violations are detected, the agent transitions to Pending review state.
   • If a violation is detected, the request is auto-blocked. You receive a notification with the scan result. Revise the system prompt and submit again when ready.

   If you need to make changes after submitting, you can withdraw the pending request at any time. Withdrawing returns the agent to Draft state and unlocks the editor.

6. If this agent already has a published version, that version remains live in Discover Agents while the new version is under review.

View agent history

After you submit a publish request, you can review the audit logs in Agent Builder to track the history of changes made to an agent. The agent history displays events such as approvals or rejections, along with key details such as who performed the action, when it occurred, and the resulting status.

To view the agent history, perform the following steps:

1. Go to AgentFlow > Agent Builder.
2. Select the required agent.
3. Select See History.

The history panel displays events in chronological order for the selected agent version.

Update a published agent

To update a published agent, create a new draft from the published version. This allows you to make changes while the latest published version is available to users. Your ability to update an agent depends on your assigned roles:

• ROLE_AGENT_AUTHOR: Create a new draft for agents you published.
• ROLE_ADMIN_AGENTS and ROLE_ADMIN_TENANT: Create or edit drafts for all published agents in a tenant.

To update an agent, perform the following steps:

Result

Your agent is updated, and Agent Builder maintains version history across all draft and published versions.

Handling save conflicts

If another user saves changes to the agent after you make your own changes, Agent Builder blocks your next save and displays a conflict error.

Refreshing the page loads the latest version and allows you to continue editing, but it also discards your unsaved changes. To avoid losing your progress, perform the following steps:

1. Select Go back without refreshing.
2. Copy your changes to a separate location.
3. Refresh the page to load the latest version.
4. Reapply your changes and click Save.

Result

The publish request is now in the reviewer queue. For more information about what each state means, see Agent states in Agent Builder.

For more information about what happens next, see Review and act on a publish request.

Validation steps

• Confirm the agent shows Pending review status in Agent Builder.