Umbraco.AI.Agent

Umbraco.AI.Agent

An agent management add-on for Umbraco.AI that provides storage, execution, and management of AI agents with full AG-UI protocol support.

Features

• Agent Management - Store and manage AI agent definitions with instructions and configuration
• Agent Execution - Run agents with real-time SSE streaming via the AG-UI protocol
• Profile Integration - Link agents to Umbraco.AI profiles for model configuration
• Context Injection - Attach context sources to agents for RAG scenarios
• Backoffice UI - Agent management interface integrated into Umbraco
• Management API - RESTful API for agent CRUD operations and execution

Note: For the Copilot chat UI (sidebar, tool execution, HITL approval), install Umbraco.AI.Agent.Copilot alongside this package.

Monorepo Context

This package is part of the Umbraco.AI monorepo. For local development, see the monorepo setup instructions in the root README.

Installation

# Agent only (management + APIs)
dotnet add package Umbraco.AI.Agent

# Agent + Copilot (includes chat UI)
dotnet add package Umbraco.AI.Agent
dotnet add package Umbraco.AI.Agent.Copilot

This meta-package includes all required components. For more control, install individual packages:

Package	Description
Umbraco.AI.Agent.Core	Domain models and service interfaces
Umbraco.AI.Agent.Web	Management API controllers
Umbraco.AI.Agent.Web.StaticAssets	Backoffice UI components
Umbraco.AI.Agent.Persistence	EF Core persistence
Umbraco.AI.Agent.Persistence.SqlServer	SQL Server migrations
Umbraco.AI.Agent.Persistence.Sqlite	SQLite migrations
Umbraco.AI.AGUI	AG-UI protocol SDK

Requirements

• Umbraco CMS 17.0.0+
• Umbraco.AI 1.0.0+
• .NET 10.0

Agent Model

An AIAgent represents a stored agent definition:

Property	Description
Id	Unique identifier (GUID)
Alias	URL-safe unique identifier
Name	Display name
Description	Optional description
ProfileId	Umbraco.AI profile for model configuration
ContextIds	Context sources for RAG injection
Instructions	System instructions defining agent behavior
IsActive	Whether the agent is available for use

Management API

All endpoints are under /umbraco/ai/management/api/v1/agents/:

Method	Endpoint	Description
GET	/	List all agents (paged)
GET	/{idOrAlias}	Get agent by ID or alias
POST	/	Create agent
PUT	/{idOrAlias}	Update agent
DELETE	/{idOrAlias}	Delete agent
POST	/{idOrAlias}/run	Run agent with AG-UI streaming

The {idOrAlias} parameter accepts either a GUID or a string alias.

Running Agents

The /run endpoint accepts an AG-UI RunRequest and returns a Server-Sent Events stream:

POST /umbraco/ai/management/api/v1/agents/my-agent/run
Content-Type: application/json

{
  "threadId": "thread-123",
  "runId": "run-456",
  "messages": [
    { "role": "user", "content": "Hello!" }
  ]
}

Response: text/event-stream with AG-UI events.

Umbraco.AI.AGUI

The Umbraco.AI.AGUI package is a standalone AG-UI protocol SDK that provides:

• Event Types - All AG-UI event models (lifecycle, messages, tools, state)
• SSE Streaming - AGUIEventStreamResult for ASP.NET Core streaming
• Models - AGUIRunRequest, AGUIMessage, AGUITool, etc.

This package can be used independently of the Agent add-on to build custom AG-UI endpoints.

Architecture

Built on the Microsoft Agent Framework (MAF) for agent execution, with a custom AG-UI layer that provides:

• Umbraco authorization integration
• Frontend tool handling with client-side execution
• Custom context item injection

Documentation

• CLAUDE.md - Development guide, architecture, and technical details for this package
• Root CLAUDE.md - Shared coding standards and conventions
• Contributing Guide - How to contribute to the monorepo

License

This project is licensed under the MIT License. See LICENSE.md for details.