Umbraco.AI.Agent 18.0.0

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:

Requirements

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

Agent Model

An AIAgent represents a stored agent definition:

Management API

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

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.