Create a Custom Agent
A specialized custom agent on the Agent Canvas with its own instructions, tools, and skills. Custom agents handle focused tasks like health reporting, alert triage, or notification delivery. Learn more → Custom agents. Time: ~5 minutes.
Prerequisites
- An agent created in the Azure SRE Agent portal
- At least one connector configured (if you want the custom agent to use external tools)
- Optionally, create a skill first if you want to attach a custom skill
Create a custom agent
1. Open the Agent Canvas
Navigate to your agent → Builder → Agent Canvas.
2. Click Create → Custom Agent
Click the Create dropdown in the toolbar and select Custom Agent. The creation dialog opens with two tabs at the top: Form and YAML.
3. Enter name and instructions
Fill in the required fields:
| Field | Example value |
|---|---|
| Custom agent name (required) | health-check-reporter |
| Instructions (required) | "You are a health check reporter. Check Azure resource health for container apps in the production resource group. Summarize healthy, warning, and critical counts. Send the summary via email." |
Click Refine with AI above the instructions field to let the agent improve your instructions automatically. Click View AI suggestions to see recommendations for improving instructions, tools, and skills.
4. Select skills (optional)
The Skills section controls which skills this custom agent can use.
By default, the agent inherits all global skills. Selecting specific skills here overrides the defaults.
- Click Choose skills to open the skills picker.
- Select built-in skills (e.g., troubleshooting procedures) or custom skills you created via Create a Skill.
- Leave empty to allow all global skills.
- Learn more → Skills concept
5. Select tools (optional)
The Tools section controls which tools this custom agent can access.
By default, the agent inherits all global tools. Selecting specific tools here overrides the defaults.
- Click Choose tools to open the tools picker panel.
- Browse or search for tools — they're organized by category (e.g., Kusto tools, notification tools).
- Check the tools you want this custom agent to use.
- To create custom tools first, see Create a Kusto Tool or Create a Python Tool.
- Learn more → Tools concept
Before assigning tools, test them individually in the Test playground to make sure they return the data you expect.
6. Configure hooks (optional)
The Hooks section lets you add safety and governance controls to your custom agent.
- Click Manage Hooks to open the hooks panel.
- Add hooks that run before actions (prompt hooks) or after tool use (command hooks).
- See Agent Hooks for setup steps or Create and Manage Hooks in UI for the full walkthrough.
- Learn more → Agent Hooks capability
7. Click Create
Checkpoint: Your custom agent appears as a node on the Agent Canvas with any connected tools displayed.
Test it
After creating your custom agent, test it to verify it behaves as expected.
Test from the dialog
In the create/edit dialog, click the test icon in the top-right corner to open the Test live agent panel. Type a prompt and see how the agent responds with its current instructions and tools.
Test in the playground
- On the Agent Canvas toolbar, select the Test playground view toggle.
- The split-screen layout shows your agent's configuration on the left and a live chat on the right.
- Select your custom agent, type a test prompt, and verify it behaves as expected.
- Iterate — edit instructions or swap tools, then test again until the output matches your expectations.
For full details, see Agent Playground or Test Tool in Playground.
Edit a custom agent
On the Agent Canvas, click the custom agent node to select it, then click Edit (or double-click the node). The edit dialog opens with all current values pre-populated.
| What to change | Field to update |
|---|---|
| What it does | Instructions |
| Which skills it uses | Skills → Choose skills |
| Which tools it uses | Tools → Choose tools |
| Safety controls | Hooks → Manage Hooks |
Click Save when done.
YAML editing
Click the YAML tab at the top of the dialog to view or edit the configuration as YAML. Changes in YAML mode sync back to the form view. This is useful for copying configurations or managing config as code.
What you learned
- Custom agents are specialized workers you create on the Agent Canvas with their own instructions, skills, tools, and hooks
- The agent inherits all global skills and tools by default — selecting specific ones overrides the defaults
- Skills can be built-in or custom (created via the skill editor with SKILL.md instructions)
- Hooks add safety controls that run before actions or after tool use
- The Test playground and in-dialog test panel let you verify behavior before deploying
- YAML editing lets you manage configurations as code
Related
| Resource | What you'll learn |
|---|---|
| Custom Agents → | How custom agents delegate and specialize work |
| Agent Playground → | Test and iterate on your agent configuration |
| Skills → | How skills work and when the agent activates them |
| Tools → | How tools give agents access to external services |
| Agent Hooks → | Safety and governance controls for agent actions |
| Create a Skill → | Build a custom skill your agent can use |
| Create a Kusto Tool → | Create a custom Kusto query tool |
| Create a Python Tool → | Create a custom Python tool |
| Create a Scheduled Task → | Link a recurring task to your custom agent |
| Test Tool in Playground → | Debug individual tools before assigning them |