Prerequisites

Before you begin, confirm that:

• You must have the ROLE_AGENT_AUTHOR on the target tenant.
• 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.

Create a draft agent

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

1. Open AgentFlow and go to Agent Builder.
2. Select Create agent.
3. Enter a name, description, and any relevant tags. These values appear in Discover Agents after the agent is published.
4. Save the agent. Agent Builder creates it in Draft state.

Update a published agent

Use this path when you want to revise an agent that is already published. An Agent Author (for their own agents) or an Agent Admin can initiate this. The published version remains live and available to users throughout the editing and review process.

Version history is maintained across all draft and published versions of the agent.

Write the system prompt

1. In the agent editor, open the prompt authoring area.
2. Enter the agent's system prompt. The system prompt defines the agent's:
   • Identity
   • Objectives
   • Tool usage rules
   • Workflow
   • Guardrails
   • Output format
   • Error handling behavior.
   Note: For more information about structuring an effective system prompt, see AgentFlow system prompt guidelines.
3. Save your changes.

Select tools

1. In the agent editor, open the tool selection area.
2. Search or scroll to find the tools you want this agent to use. Only tools in the tenant-approved catalog are available.
3. Select each tool 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.
4. Save your changes.

Test the draft agent

1. Open the test panel in the agent editor.
2. 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.
3. Review the run summary after each test. It shows latency, tokens used, and tool calls for that run.
4. Iterate on the prompt and tool selection as needed. Save your changes and retest.

Submit for review

1. When the agent is ready, select the publish action in the agent editor.
2. Optionally add version notes. Version notes are visible to the reviewer.
3. Confirm the submission.

   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.
   Note: 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.
4. If this agent already has a published version, that version remains live in Discover Agents while the new version is under review.

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.