Skip to content

v1.2.0 — Content Audit v2 + agent sanctum + body extraction + search

Latest
Latest

Choose a tag to compare

View all tags
@ashallcross ashallcross released this 22 Apr 14:00
v1.2.0
7868dec

v1.2.0 is the first NuGet release since 1.0.0 and bundles the v1.1 engine upgrades (prompt caching, per-step model profiles, prompt-variable injection, web search, Umbraco.AI Context access) together with the v1.2 feature set (Agent Sanctum pattern, Examine-powered content search, body-extraction + Brand pillar in the Content Audit). The shipped surface is now an engine, not just three example workflows — extensible via a small .NET interface, cache-aware across providers, and configurable per step.

What's new

Tools — new adoptable surface

  • web_search — HTTP-backed web search with provider abstraction. Brave (default) and Tavily adapters ship; custom providers plug in via IWebSearchProvider. API keys live in appsettings.json under AgentRun:WebSearch:Providers:*:ApiKey (or the matching environment variable). Structured error envelopes (not_configured / rate_limited / transport / invalid_argument) never throw into the agent loop.
  • get_ai_context — read-only access to Umbraco.AI Contexts by alias. Use it to thread brand voices, source lists, or any other Umbraco.AI Context resource into workflow prompts without hard-coding content into agent markdown.
  • search_content — Examine-backed keyword search across published Umbraco content. Score-ordered results with optional contentType and parentId filters. Complements the existing list_content / get_content pair when you need to discover by keyword rather than enumerate.

Total shipped tool count is now ten: fetch_url, read_file, write_file, list_files, list_content, get_content, list_content_types, search_content, get_ai_context, web_search. Custom tools plug in through Umbraco's composer system and appear to every workflow that declares them.

Engine — authoring ergonomics

  • Prompt-variable substitution. Agent prompts can include {today}, {instance_id}, {step_index}, {previous_artifacts}, and any workflow-declared config: token. Substitution is deterministic, logged when keys are missing, and happens at prompt-assembly time so dates, IDs, and configuration never hallucinate.
  • Per-step model profiles. Route each step to the Umbraco.AI profile that fits — a Sonnet-class profile for high-volume scanning, Opus-class for the visible report — via a profile: field in the step definition. Resolution order is step → workflow default → site default → auto-detect.
  • Provider-aware prompt caching. Stable-first prompt authoring now gets automatic cache discounts: ~90% on Anthropic (once the cache_control translation lands upstream — see Known Limitations) and automatic caching on OpenAI / Azure OpenAI once prompts cross the provider size threshold. No YAML changes needed; the discount comes from authoring discipline documented in the guide.
  • Agent Sanctum pattern. For agents whose identity matters (archivist voice, evidence-first analyst), split PERSONA.md / CREED.md / CAPABILITIES.md into ship-time sidecar files. The engine auto-loads them into a cache-stable preamble above the per-turn runtime context. Agents without sanctum files behave identically to 1.0.

Umbraco Content Audit — v2 showcase

The shipped umbraco-content-audit workflow has been substantially upgraded:

  • Real body-prose extraction. get_content now returns body_text (capped prose sample) and body_metadata (structural data: headings, links, alt-texts, image count) for every node. The cap is configurable via content_audit_body_max_chars (default 15000). Readability, Accessibility, and Brand pillars now score against real Block List / Block Grid / Rich Text content — prior versions returned "Not applicable" on modern block-composed pages.
  • Optional Brand pillar. Attach an Umbraco.AI "Brand Voice" Context (with toneDescription, targetAudience, styleGuidelines, avoidPatterns), set brand_voice_context: "your-alias" in the workflow's config: block, and the audit runs as a 7-pillar scan with Brand-voice scoring + evidence citations. Leave the config empty and you get the 6-pillar audit — byte-identical to 1.0 output.
  • Hard halt on misconfiguration. If brand_voice_context is set but the alias doesn't exist, the scanner halts with an explicit error and no artifacts are written — it will never silently fall back to a 6-pillar scan, so misconfigurations surface loudly.
  • Richer audit outputs. The final report now surfaces Brand column, Brand-category root-cause clustering, and Brand-aligned actions when the pillar is enabled.

Documentation refresh

Single coherence pass across README.md, docs/workflow-authoring-guide.md, docs/beta-test-plan.md, and umbraco-marketplace.json. The guide gained a top-level Contents TOC, a Conditional Pillars via Config pattern section, refreshed Learning from the Examples walkthroughs, and dedicated sections for every new tool.

Breaking changes

None. Backwards compatibility is a hard v1.2 constraint:

  • All new configuration keys (brand_voice_context, content_audit_body_max_chars, per-step profile:) are optional with sensible defaults.
  • Prompt-variable substitution is off-by-default; prompts without {…} tokens pass through unchanged.
  • Agent Sanctum files are optional; agents without them behave identically to 1.0.
  • The umbraco-content-audit workflow, run without brand_voice_context, produces output byte-identical to 1.0's 6-pillar audit.

Upgrading from 1.0

1.1.0 was tagged internally but never published to NuGet, so 1.0 adopters upgrade directly to 1.2.0 and pick up both the 1.1 and 1.2 feature sets in a single step.

dotnet add package AgentRun.Umbraco --version 1.2.0

A new migration (CopyWorkflowSchemaToDisk) runs on next startup to drop the workflow JSON schema into App_Data/AgentRun.Umbraco/Schemas/ for IDE validation — without this, YAML editors logged "Unable to load schema" on the shipped workflow.yaml files. Workflows already on disk are left untouched; the migration only fills in missing state. Log output on startup confirms the migration ran:

Starting package migration for AgentRun.Umbraco
Execute CopyWorkflowSchemaToDisk
Copied workflow-schema.json to App_Data/AgentRun.Umbraco/Schemas/ for IDE validation

If you've customised any of the shipped workflows under App_Data/AgentRun.Umbraco/workflows/, those files are preserved — the migration's copy step is skip-if-exists. To pick up the v1.2 workflow upgrades (Brand pillar scanner / analyser / reporter, body-extraction-aware prompts, sanctum files), either diff against the in-package sources at the NuGet cache location or delete your modified copies and let the first-run migration re-seed them.

Known limitations

  • Single concurrent instance per workflow.
  • Disk-based persistence only (YAML + JSONL) — no database backend.
  • Interactive mode is the primary UX; autonomous mode is functional but secondary.
  • Anthropic cache_control marker translation through Umbraco.AI is a planned follow-up; caching still works automatically on OpenAI / Azure OpenAI once prompts cross the provider size threshold.
  • Provider compatibility: Anthropic is the most thoroughly exercised provider to date. OpenAI and Azure OpenAI are supported through Umbraco.AI and work in practice; please open an issue if you hit a provider-specific error.

Links

Apache 2.0 licensed. Thanks to everyone who tested the beta and surfaced the rough edges.

Assets 2
Loading