N+1 Blog

scratch: Structured Scratchpads for Coding Agents

Mon, 08 Jun 2026 00:00:00 +0000

TL;DR: scratch organizes the temporary knowledge an agent produces — notes, snippets, command output, intermediate artifacts — into a scratchpad: a folder plus a scratchpad.json manifest, kept out of your source tree. It’s a thin metadata layer over the filesystem, not a database.

Install with bun add -g @nikiforovall/scratchpad

Docs & live demo: nikiforovall.blog/scratchpad/

Why files: the context window is a real limit

One constraint shapes everything else: agents work better when they write things down.

The context window is the agent’s only short-term memory — the running transcript of the task so far is all it can actually “see.” That transcript is finite. Once it fills up, the oldest parts drop off to make room: findings, decisions, the command output from twenty steps ago. There’s no warning; the model just quietly forgets. Long-horizon tasks fail less because the model is incapable and more because the memory it needed is gone.

The fix is almost boring: externalize that memory to the filesystem. Write the plan to a .md file. Write findings to a .md file. Now the agent re-reads exactly what it needs, when it needs it, instead of hoping it’s still in context — and a markdown file is durable, greppable, diffable, and survives a compaction. “Markdown files are all you need” is becoming a real pattern, not a hack.

So agents should write to disk. The open question is what happens to those files next.

The problem: temporary agent knowledge has nowhere to go

Spend a session with a coding agent and watch what it produces. It greps the codebase and finds five relevant files. It writes a quick design note before touching code. It runs the test suite and the failure output is what it reasons about next. It sketches a mermaid diagram to make sense of a flow.

All of that is real, useful work. And almost none of it sticks around.

Agents generate a lot of temporary knowledge per session, and nothing keeps track of it. It ends up scattered across the repo, buried in chat history, or lost when the context window rolls over.

The knowledge is temporary — tied to a session or a task, not to the project forever — but “temporary” shouldn’t mean “lost” or “scattered.”

The solution: a scratchpad is just a folder

A scratchpad is a folder containing a scratchpad.json manifest. The folder path is its identity — there’s no central store, no daemon, no SQLite file hidden away under your config. scratch is a thin metadata layer over the filesystem: it creates pads, registers files with a description and type, and shows you what’s there.

The agent writes files with its normal tools. Then it registers each one:

scratch new "auth-refactor" --dir _scratchpads
# → creates _scratchpads/auth-refactor/ + scratchpad.json

# agent writes _scratchpads/auth-refactor/findings.md with its normal tools, then:
scratch add "auth-refactor" findings.md \
  --desc "where the current token flow breaks" \
  --type note --tag auth,investigation

The --desc is the point: it captures why this file exists, not just that it does. Months later — or two compactions later — that one line is the difference between a useful artifact and a mystery file.

Two things make this pleasant in practice. First, no lock-in: it’s files on disk. Delete the folder and the knowledge is gone; the CLI never authors, copies, or moves your content. Second, a human can actually read it.

The demo: see what the agent gathered

Run scratch ui and you get a read-only, two-pane viewer in a “Lab Notebook” theme that auto-detects light/dark:

Markdown is rendered (with a raw/rendered toggle), code is syntax-highlighted, mermaid diagrams draw, images show inline. It opens a native window by default and falls back to your browser if the native backend isn’t available.

Scratchpads are also shareable. scratch export bundles a whole pad into a single self-contained HTML file — file contents embedded, no server needed — that you can hand to a teammate or link from anywhere. Here’s one exported live:

Try it: a scratchpad, exported →

No digging through transcripts to find what the agent learned. You open the viewer — or the exported file — and browse.

Wiring it into Claude Code

The repo doubles as a Claude Code plugin marketplace. Add it and the agent gets a scratch skill that teaches it when and how to drive the CLI — so it reaches for a scratchpad on its own when a task starts generating keepable knowledge:

/plugin marketplace add NikiforovAll/scratchpad
/plugin install scratchpad@scratchpad

The plugin ships the skill; the scratch CLI itself still comes from the install above:

bun add -g @nikiforovall/scratchpad

From there the agent runs the loop — create, write, register, browse — without you micromanaging it.

Planning with scratchpads

The plugin ships a second skill, planning-with-scratchpad, that puts a real workflow on top of the raw CLI. Its goal: use scratchpads as external memory for complex, multi-session tasks — the kind where a single Plan Mode pass isn’t enough and you need research, decisions, and rationale to survive context limits and session boundaries.

The convention is one pad per task under _plans/, and one concern per file rather than a sprawling 200-line plan.md:

plan.md — the index: goal, phases, status, errors. Kept lean; it’s the map, not the territory.
research-<topic>.md — sources and findings, one file per distinct topic.
decisions.md — options, the choice, and why (the rationale future-you needs).
scratch-<label>.md — disposable working notes and prototypes.

The flow it encourages: research into files first, outline every phase and task in plan.md and get your approval before any code is written, then batch-create the tasks. Because every file is registered with scratch, you open scratch ui and watch the plan take shape in the viewer — the agent’s thinking laid out as browsable files instead of buried in a long transcript. You can read the plan and steer it before it turns into code.

▶ Show the full planning-with-scratchpad SKILL.md (click to expand)

---
name: planning-with-scratchpad
description: Use when user explicitly requests planning with a scratchpad, or asks for persistent tracking of a complex task that the human can browse visually. Backs planning files with the `scratch` CLI so a pad's files are registered and viewable.
disable-model-invocation: true
---

# Planning with Scratchpad

Use persistent markdown files as external memory for complex tasks. Files survive context limits and session boundaries. The files live in a **scratchpad** (a `_plans/` folder + manifest) so the human can browse the plan in the visual viewer.

**Load the `scratch` skill first** — it owns all CLI mechanics (`new`, `add`, `ls`, `show`, `ui`). This skill adds the planning conventions on top.

Use persistent files for planning, `TaskCreate` for tracking execution. Before closing session, use `AskUserQuestion` to confirm findings, decisions, and deliverables are satisfactory.

## Bundled References

Read these when you need deeper guidance on a specific aspect:

- **[reference.md](reference.md)** — Context engineering principles (Manus-inspired). Read when designing how to structure planning files for a long-running or multi-agent task.
- **[examples.md](examples.md)** — Real task examples showing different file combinations. Read when unsure which files to create for a given task shape.

## When to Use

- User explicitly requests planning/tracking with a scratchpad
- Complex multi-session tasks
- Research-heavy work requiring persistent notes
- Tasks where decisions and rationale need to be preserved

## When NOT to Use

- Simple single-session tasks (use Plan Mode instead)
- Quick fixes or small changes
- Tasks with clear requirements needing no research

## Directory Convention

One pad per task, created in `_plans/` with a date-prefixed folder:

```
scratch new "<task-name>" --dir _plans --id "$SESSION_ID"
```

This creates `_plans/YYYY-MM-DD-<slug>/`. Write files into that folder with your normal tools, then **register each** with `scratch add` so it appears in the viewer:

```
_plans/
  2026-01-08-dark-mode-toggle/
    scratchpad.json          # manifest (managed by scratch)
    plan.md
    research-css-strategies.md
    decisions.md
  2026-01-09-api-auth-refactor/
    scratchpad.json
    plan.md
    research-auth-providers.md
    research-token-storage.md
    decision-oauth-vs-saml.md
    decision-session-strategy.md
    references.md
    scratch-migration-steps.md
```

**Naming:** `YYYY-MM-DD-task-name` (kebab-case, concise description) — `scratch new` derives this from the task name + date.

## File Types — One Concern Per File

Each file owns a single concern. Never merge concerns into one file — a 200-line plan.md that also contains research notes, decisions, and scratch work is hard to navigate and easy to lose track of. Split early; you can always cross-reference with relative links. Register each file with the matching `scratch add --type`.

| File                  | Concern                                      | Create when                                                                                                         | `--type`    |
| --------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------- |
| `plan.md`             | Goal, phases, status, errors                 | Always — this is the index                                                                                          | `note`      |
| `research-<topic>.md` | Sources, findings for one topic              | Any research needed. One file per distinct topic — e.g. `research-auth-providers.md`, `research-perf-benchmarks.md` | `reference` |
| `decisions.md`        | ADRs, options, rationale                     | Any non-obvious tradeoff. For large efforts, split per decision: `decision-database-choice.md`                      | `note`      |
| `scratch-<label>.md`  | Drafts, working notes, exploratory code      | Complex reasoning or prototyping. Disposable — can be deleted after use                                             | `snippet`   |
| `<deliverable>.md`    | Final outputs                                | Reports, summaries, documentation                                                                                   | `artifact`  |
| `references.md`       | Links to external resources, docs, prior art | When multiple sources inform the work                                                                               | `reference` |

Always pass `--desc "why this file exists"` — it's the most valuable metadata in the viewer.

### Splitting heuristic

- If a section in any file exceeds ~80 lines, extract it into its own file
- If you're about to add a second `## Research:` or `## Decision:` heading to an existing file, create a new file instead
- `plan.md` should stay lean — it's the map, not the territory. Link to detail files:
  ```markdown
  ## Research
  - [Auth providers](research-auth-providers.md)
  - [Performance](research-perf-benchmarks.md)
  ```

### plan.md Template

```markdown
# Plan: [Brief Description]

## Goal
[One sentence describing the end state]

## Phases
- [ ] Phase 1: [Description]
- [ ] Phase 2: [Description]
- [ ] Phase 3: [Description]

## Status
**Current:** [What's happening now]

## Decisions
- [Decision]: [Rationale]

## Errors Encountered
- [Error]: [Resolution]
```

### research.md Template

```markdown
# Research: [Topic]

## Sources
- [Source]: [Key findings]

## Findings
### [Category]
- [Finding]
```

### decisions.md Template

```markdown
# Decisions: [Task]

## [Decision Title]
**Status:** Decided | Pending
**Options:**
1. [Option A] - [Pros/Cons]
2. [Option B] - [Pros/Cons]

**Choice:** [Selected option]
**Rationale:** [Why]
```

## Task System Integration

Planning files and tasks serve different stages:

| Stage             | Tool                | Purpose                                    |
| ----------------- | ------------------- | ------------------------------------------ |
| **Investigation** | Planning Files      | Research, decisions, rationale, error logs |
| **Execution**     | TaskCreate/TaskList | Decomposed work items with dependencies    |

### Workflow

```
1. scratch new "<task>" --dir _plans --id "$SESSION_ID"   # create the pad + plan.md
2. Research and document in planning files; `scratch add` each one
3. Make decisions, document rationale
4. Outline ALL tasks in plan.md first — present to user for review
5. After user approves, batch-create all tasks via TaskCreate
6. Link tasks back to planning docs
7. scratch ui "<task>" --dir _plans   # backgrounded, for the human
```

### Outline Before Creating Tasks

Do NOT create tasks one by one as you discover them. Instead:

1. Collect all phases and tasks during investigation, write them as a checklist in `plan.md`
2. Present the full outline to the user via `AskUserQuestion` — they need to see the complete picture before committing
3. Only after approval, batch-create **all** tasks in a single pass — both phase-level and work-item tasks

This matters because the user needs to evaluate scope, reorder priorities, and spot gaps — which is impossible when tasks trickle in one at a time.

### Task Hierarchy

Create tasks at two levels:

1. **Phase tasks** — one per phase, owns the high-level goal. Mark complete when all child tasks are done.
2. **Work-item tasks** — concrete implementation steps within a phase.

Example batch after outline approval:
```
TaskCreate: subject: "Phase 1: Research auth providers"
TaskCreate: subject: "Phase 1.1: Compare OAuth2 libraries"
TaskCreate: subject: "Phase 1.2: Evaluate token storage options"
TaskCreate: subject: "Phase 2: Implement auth flow"
TaskCreate: subject: "Phase 2.1: Add OAuth2 login endpoint"
TaskCreate: subject: "Phase 2.2: Add token refresh middleware"
```

Phase tasks give the user a progress overview; work-item tasks track actual execution.

### Linking Tasks to Planning Documents

When batch-creating, reference the pad dir in each task:

```
TaskCreate:
  subject: "Add OAuth2 login endpoint"
  description: |
    Implement /auth/login endpoint.
    References: _plans/2026-01-23-auth-api/plan.md
  metadata:
    planDir: "_plans/2026-01-23-auth-api"
```

Tasks can have dependencies on each other, and all link back to the same pad directory for context.

## Recommended Tools

| Tool                 | When to Use                                                                       |
| -------------------- | --------------------------------------------------------------------------------- |
| **Explore subagent** | Search codebase, find patterns, understand existing structure before planning     |
| **AskUserQuestion**  | Clarify requirements, validate assumptions, confirm decisions before proceeding   |
| **scratch ui**       | Open the pad in the visual viewer (backgrounded) so the human can browse the plan |

Use these proactively during investigation to avoid wrong assumptions and wasted effort.

## Success Criteria

Planning is complete when:
- [ ] A pad exists under `_plans/` with `plan.md` (clear goal and phases) registered
- [ ] All phases marked complete or explicitly deferred
- [ ] Key decisions documented with rationale
- [ ] Errors encountered are logged with resolutions
- [ ] All files registered with `scratch add` (visible in the viewer)
- [ ] User confirms deliverables via `AskUserQuestion`

## Critical Rules

### Refresh Goals When Context Gets Long

After many tool calls (~20+), re-read `plan.md` before major decisions. This brings goals back into the attention window.

### 1. Store, Don't Stuff
Large outputs go to files, not context. Keep paths in working memory, content in files.

### 2. Log All Errors
Every error goes in plan.md under "Errors Encountered". This builds knowledge and shows recovery.

### 3. Decisions Need Rationale
Don't just record what you decided - record WHY. Future-you needs this context.

### 4. Update Status Immediately
Mark phases complete as soon as they're done. Don't batch status updates.

## Anti-Patterns

| Don't                                            | Do Instead                                               |
| ------------------------------------------------ | -------------------------------------------------------- |
| Create files in project root                     | Use a pad under `_plans/YYYY-MM-DD-name/`                |
| Write files but forget to register them          | `scratch add` each file so it shows in the viewer        |
| State goals once and forget                      | Re-read plan.md when context is long                     |
| Hide errors and retry silently                   | Log errors with resolution                               |
| Stuff everything in context                      | Store large content in files                             |
| Start executing immediately                      | Create plan.md first for complex tasks                   |
| Put research + decisions + notes in one big file | One file per concern — split by topic                    |
| Let plan.md grow past ~80 lines                  | Extract sections into dedicated files, link from plan.md |

Also works on pi

If you’re on the pi coding agent, the @nikiforovall/pi-scratchpad package ships the same skills plus /scratch ui | export | stop commands for the viewer:

pi install npm:@nikiforovall/pi-scratchpad

Same idea, same CLI underneath — give your agent’s working memory somewhere to land.

Summary

scratch turns the throwaway-but-useful output of an agent session into durable, inspectable, shareable knowledge: a folder, a manifest, and a viewer. It’s deliberately small — the agent does the writing, the filesystem does the storing, and scratch just keeps track.

Reference

pi-otel: OpenTelemetry Tracing for the Pi Coding Agent

Sat, 16 May 2026 00:00:00 +0000

TL;DR: pi-otel is an OpenTelemetry extension for the pi coding agent. It emits one trace tree per user prompt — interaction, turns, LLM requests, and tool calls — over OTLP. The default target is a local .NET Aspire dashboard. Any OTLP-compatible backend (Grafana LGTM, Jaeger, Honeycomb) works too. Install with pi install npm:pi-otel, start with /otel start.

Docs: nikiforovall.blog/pi-otel/

Why telemetry for a coding agent?

Pi is deliberately minimal. That minimalism is a feature — but it means there’s no built-in timeline view of what the agent actually did. You can read the session log, but a log is not a trace. You can count tokens from the session info modal, but a histogram is not a counter.

Honestly, the first reason to install it is just curiosity. Watching a span tree populate in real time — seeing exactly which tool ran, how long it took, what the model returned — is a different kind of understanding than reading a session log after the fact. If you’ve ever wondered what pi is actually doing under the hood, a trace will show you in a way that no amount of log-reading will.

If you’re running pi in a CI pipeline or as part of a larger workflow, “it worked or it didn’t” is not enough. You want to know which tool call ate 40 seconds, why a particular prompt costs twice as much as others, and whether errors cluster around a specific model or tool. That’s what spans give you.

What it emits

One trace tree per user prompt:

pi.interaction                      ← root span (one per turn)
└── pi.turn                         ← one per agent turn
    ├── pi.llm_request              ← the LLM call
    └── pi.tool.<name>              ← one per tool execution

Every span carries GenAI semantic convention attributes — gen_ai.system, gen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, finish reason, tool call IDs, and gen_ai.conversation.id to correlate spans across a session.

The session is intentionally not a span. A pi session can run for hours; long-running root spans are an OTel anti-pattern. Instead, session identity travels as attributes on every span.

Quickstart

pi install npm:pi-otel

Then inside pi:

/otel start

That’s it. pi-otel auto-detects an OTLP backend in this order: Aspire CLI → Docker → Podman. It spawns a local .NET Aspire dashboard and opens it at http://localhost:18888.

Backend install options:

Aspire CLI — irm https://aspire.dev/install.ps1 | iex (Windows) or curl -sSL https://aspire.dev/install.sh | bash
Docker or Podman — any recent version

What you see in Aspire

The Traces tab shows one root span per user prompt. Expand to see the full turn → LLM request → tool call nesting. Click any span for the attribute panel: model, token counts, finish reason, tool input/output.

The Metrics tab (enabled with "signals": { "metrics": true }) shows histograms for LLM request latency, token usage (input/output/cache), and tool execution time.

The Structured Logs tab (enabled with "signals": { "logs": true }) surfaces lifecycle events — pi.session.start, pi.session.end, pi.tool.error — plus the filtered OTel SDK diag bridge output.

Any OTLP backend

Aspire is the default because it requires zero configuration. But pi-otel is built on open standards — the OTLP exporter works with anything.

Grafana LGTM

The samples/lgtm/ directory ships a docker-compose.yml that spins up the otel-lgtm image (Tempo + Mimir + Loki in one container):

cd samples/lgtm
docker compose up -d

Then inside pi:

/otel connect http://localhost:4317

Traces land in Tempo, metrics in Mimir/Prometheus, logs in Loki — all pre-wired to Grafana.

Other backends

For Honeycomb, Grafana Cloud, Jaeger, or any other OTLP receiver, point the endpoint and add auth headers:

// .pi/settings.json
{
  "otel": {
    "endpoint": "https://api.honeycomb.io",
    "headers": { "x-honeycomb-team": "YOUR_API_KEY" }
  }
}

Or via env vars:

OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
OTEL_EXPORTER_OTLP_HEADERS=x-honeycomb-team=YOUR_API_KEY

Configuration reference

// .pi/settings.json or ~/.pi/agent/settings.json
{
  "otel": {
    "enabled": true,
    "endpoint": "http://localhost:4317",
    "protocol": "grpc",
    "serviceName": "pi",
    "captureContent": "metadata_only",
    "sampleRatio": 1.0,
    "signals": { "traces": true, "metrics": false, "logs": false }
  }
}

Key	Default	Description
`enabled`	`true`	Master switch
`endpoint`	`http://localhost:4317`	OTLP receiver URL
`protocol`	`grpc`	`grpc`, `http/protobuf`, or `http/json`
`captureContent`	`metadata_only`	Content capture mode
`sampleRatio`	`1.0`	Head sampling ratio (0.0–1.0)
`signals.traces`	`true`	Emit trace spans
`signals.metrics`	`false`	Emit token/cost/latency histograms
`signals.logs`	`false`	Emit lifecycle log records + diag bridge

Standard OTEL_* env vars override settings. PI_OTEL_DISABLED=1 makes the extension a complete no-op.

Content capture

By default (captureContent: "metadata_only") spans carry token counts, model names, finish reasons, and tool call IDs — but not prompt or response text. Three modes:

Mode	What lands on spans
`metadata_only`	Token counts, model, finish reason, tool IDs
`no_tool_content`	+ LLM message content; no tool input/output
`full`	Everything, including tool input/output (capped at 60 KB per attribute)

{ "otel": { "captureContent": "full" } }

Extensibility — logs from your own pi package

Since pi-otel registers a global OTel LoggerProvider at startup, any code in the same process can emit log records into the same stream. Two ways to do it:

OTel API directly — add @opentelemetry/api-logs as a dependency, call the global provider. The call is a no-op if pi-otel isn’t loaded.

import { logs, SeverityNumber } from "@opentelemetry/api-logs";

logs.getLogger("my-package", "1.0.0").emit({
  severityNumber: SeverityNumber.DEBUG,
  body: "cache hit",
  attributes: { "tool.name": "bash" },
});

pi-otel:log event bus — no import needed. From any pi extension, emit on pi’s shared event bus.

pi.events.emit("pi-otel:log", {
  eventName: "my-package.cache-hit",
  severity: "debug",
  body: "cache hit",
  attributes: { "tool.name": "bash" },
});

Both land in Aspire Structured Logs alongside pi-otel’s own session and error events. The OTel API approach uses your own instrumentation scope; the event bus emits under pi-otel.

The diagnostic bridge

When signals.logs is enabled, pi-otel forwards the @opentelemetry/* SDK’s own internal diag messages to the same OTLP endpoint under the @opentelemetry/diag instrumentation scope.

Getting started

pi install npm:pi-otel

Then in pi:

/otel start         # spawn local Aspire dashboard

Full documentation: nikiforovall.blog/pi-otel/

Summary

Pi’s minimalism is a strength. pi-otel adds one thing: a timeline view of what the agent actually did, in a format that integrates with your existing observability stack. One trace tree per turn, three signals, any OTLP backend.

🙌 I hope you found it helpful. If you have any questions, please feel free to reach out. If you’d like to support my work, a star on GitHub would be greatly appreciated! 🙏

References

pi-kanban: A Workspace for the Pi Coding Agent

Sat, 09 May 2026 00:00:00 +0000

TL;DR: pi-kanban is a read-only observability dashboard for the pi coding agent. It watches ~/.pi/agent/sessions and renders sessions, todos, messages, and subagents in real time. Install with pi install npm:pi-kanban, then run /kanban start.

Source code: github.com/NikiforovAll/pi-kanban

Why agent observability matters

Working with a coding agent is not the same as writing code yourself. The agent makes decisions, calls tools, spawns subagents, and produces artifacts faster than you can read. Without a way to see what’s happening, you end up babysitting a terminal or trusting the output blindly.

A proper observability surface changes a few things:

Reduced cognitive load. You glance, not read. Status, progress, and what the agent is doing right now are visible without scrolling logs.
Better alignment. Plan, todos, and messages sit side by side, so course-correction is cheap. You catch drift early instead of after the fact.
A workspace, not a viewer. Pinned sessions, pinned messages, linked docs, markdown previews. The work lives in the dashboard, not just a window into it.

That last one is the part I care about most. pi-kanban is read-only against pi’s session state, but the workspace around it is not.

What it looks like

Three panes:

Left — sessions grouped by project, with progress, age, and pin state.
Center — kanban board (Pending / In Progress / Completed) for the selected session.
Right — Session Log: messages, tool calls, subagent activity.

A bottom strip shows recent subagent runs across all sessions.

Feature coverage

Sessions and projects

pi-kanban reads ~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<id>.jsonl and groups sessions by working directory. No daemon, no database — just file watching.

Pinning sessions

Long-running work doesn’t fit one session. Pinning lifts a session out of the auto-sort so it stays at the top. It’s how you keep the thing you’re actually working on in front of you while exploratory sessions come and go.

/kanban pin <session-id>
/kanban sticky-pin <session-id>

Pinning messages and linking documents

Inside a session, you can pin individual messages. Useful for the assistant message that contains the answer, or the user message that defined the task. Linked documents and the scratchpad let you attach context that isn’t part of the conversation but should travel with it.

This is what turns the dashboard into a workspace. The things you care about stay anchored even as the session log scrolls past them.

Subagents

When pi-subagents spawns a child session, pi-kanban nests it under the parent.

Session info

The info modal shows model, token usage, cache hit rate, cost, duration, and paths. The things you check before deciding whether a session is worth resuming.

Storage manager

Lists sessions, scratchpads, and linked docs with size accounting. Used to clean orphaned docs and unlink stale references.

Follow last message

Pop the latest assistant message into a floating window.

Themes

Four built-in themes (pi-light, pi-dark, kanban-default, kanban-dark-default) and user-defined themes via ~/.pi/agent/kanban/settings.json.

Slash commands

Command	What it does
`/kanban start`	Start the local server (port 3460) in the background
`/kanban stop`	Stop the running server
`/kanban open`	Open the dashboard in the default browser
`/kanban app`	Open in a standalone PWA window (if installed)
`/kanban pin <id>`	Pin a session to the top of the sidebar
`/kanban sticky-pin <id>`	Pin and keep across restarts
`/kanban preview <path>`	Render a markdown file in the dashboard preview pane
`/kanban link <id>`	Links files to a session

Getting started

pi install npm:pi-kanban
# inside pi:
/kanban start
/kanban open

Here is a live demo of pi-kanban running on synthetic data:

Conclusion

If you use pi and want a dashboard that turns sessions into a workspace, give pi-kanban a try. Questions and feedback welcome on GitHub.

🙌 I hope you found it helpful. If you have any questions, please feel free to reach out. If you’d like to support my work, a star on GitHub would be greatly appreciated! 🙏

References

Hangfire as an MCP Operations Pane for AI Agents

Sat, 02 May 2026 00:00:00 +0000

TL;DR

Nall.Hangfire.Mcp is an in-process library. It exposes your Hangfire jobs at /mcp as MCP tools, and ships a built-in maintenance toolset and a few prompts on the side. Call AddHangfireMcp() and MapHangfireMcp("/mcp") inside the same ASP.NET Core host that already runs Hangfire, and the schemas, descriptions, auth hook, and maintenance tools come with it.

📖 Documentation: https://nikiforovall.github.io/hangfire-mcp-dotnet/

Package	Version	Source	Description
`Nall.Hangfire.Mcp`		hangfire-mcp-dotnet	In-process MCP server for Hangfire jobs and queue maintenance.
`Nall.Hangfire.Mcp.Generator`		hangfire-mcp-dotnet	Roslyn source generator for compile-time job discovery.

1. Why an Operations Pane

Hangfire’s dashboard is a fine UI for humans. It’s a poor surface for agents. Two specific things are missing.

1️⃣ The first is parameterized job invocation. The dashboard is built around retrying and inspecting jobs that already exist. It doesn’t give you a clean way to say “run a job for me with parameters” from chat or a copilot.

2️⃣ The second is operational workflows. “Show me the current backlog.” “List failures from the last hour grouped by exception type.” “Requeue the timeouts, but only the ones older than five minutes.” Most teams end up writing these as one-off scripts.

MCP is a good fit for both. It standardizes how a client discovers tools, inspects schemas, and invokes them. Nall.Hangfire.Mcp puts two kinds of tools on /mcp: job tools, one Run_<jobId> per discovered Hangfire job; and maintenance tools (statistics, queue listing, get/delete/requeue with dryRun), plus three orchestration prompts (hangfire_health_check, hangfire_triage_failures, hangfire_discover).

💡 That mix is what I’m calling an Operations Pane. Hangfire is the system of record. MCP is the discovery and invocation channel. The operator on the other end is whatever you want it to be: Claude, Copilot, MCP Inspector, your own client.

flowchart LR agent["AI Agent"] -->|MCP| mcp[/"/mcp endpoint"/] mcp --> dispatch{Tool kind?} dispatch -->|Run_jobId| sched[HangfireDynamicScheduler] dispatch -->|hangfire_*| maint[MaintenanceDispatcher] sched --> client[IBackgroundJobClient] maint --> storage[(Hangfire JobStorage)] client --> storage storage --> worker[Hangfire Server
executes job]

Aspire bonus 🎁

Aspire 13.x knows about MCP, so the AppHost wiring is short. .WithMcpServer("/mcp") declares an MCP endpoint on a project resource, and AddMcpInspector(...) from CommunityToolkit.Aspire.Hosting.McpInspector deploys the official MCP Inspector as a companion service pointed at your server.

var web = builder.AddProject<Projects.Web>("server").WithMcpServer("/mcp");

builder.AddMcpInspector("inspector").WithMcpServer(web);

Two lines of AppHost code, and the Inspector boots up alongside your app pointed at /mcp. External clients (Claude Desktop, VS Code Copilot, an SDK) get the same endpoint without any tool authoring on your side.

2. Getting started

dotnet add package Nall.Hangfire.Mcp

The minimal wire-up on top of an existing Hangfire host is two lines:

builder.Services.AddHangfireMcp();
app.MapHangfireMcp("/mcp");

Every recurring job in Hangfire’s storage now shows up as a Run_<jobId> MCP tool, and the hangfire_* maintenance tools and prompts are wired up. To pick up one-shot enqueue sites too, opt into the source generator with o.Sources = JobDiscoverySources.All.

2.1 How a job gets discovered

There are two discovery sources, controlled by HangfireMcpOptions.Sources. RecurringStorage (the default) reads RecurringJobDto.Job entries from JobStorage at startup. StaticManifest runs at compile time: a Roslyn source generator walks AddOrUpdate / Enqueue / Schedule call sites and emits a manifest the runtime consumes — that’s how one-shot enqueues that never live in recurring storage end up in the catalog.

Both feed a single JobCatalog, deduped by (DeclaringType, MethodInfo). Schemas are generated once per method and respect both C# defaults and nullable annotations.

flowchart LR subgraph compile [Compile time] src[AddOrUpdate / Enqueue /
Schedule call sites] -->|Roslyn| gen[Source generator] gen --> manifest[Static manifest] end subgraph runtime [Runtime] rec[(JobStorage
recurring)] --> catalog manifest --> catalog[JobCatalog] catalog -->|reflection| schema[JSON Schema
per method] schema --> tools["MCP tools
Run_jobId"] end

2.2 Decorating jobs with `[Description]`

Tool selection in agents lives or dies by description quality. Generic auto-generated descriptions and an agent will pick the wrong tool or fill arguments badly. Nall.Hangfire.Mcp honors the standard System.ComponentModel.DescriptionAttribute at both the method and parameter level — no custom attribute types.

public interface IReportJob
{
    [Description("Generate the annual financial report and persist it.")]
    Task GenerateAsync(
        [Description("Calendar year of the report (e.g. 2026).")] int year,
        [Description("Output format. Supported: pdf, html, csv.")] string format = "pdf",
        [Description("Optional cutoff timestamp.")] DateTimeOffset? since = null);
}

The method [Description] becomes the tool’s description. Each parameter [Description] becomes the JSON Schema description for that property. format is optional because of the C# default; since is optional because of the nullable annotation. Only year ends up in required.

3. Demo: MCP Inspector

End-to-end, with the Aspire AppHost running, the loop is: list the tools on /mcp, fill in parameters in MCP Inspector, hit Run Tool, and see the same enqueue land in the Hangfire dashboard.

1. Invoking with parameters — JSON Schema rendered as a form.

2. Result in the Inspector — Hangfire job ID and state.

3. Same job in the Hangfire dashboard — exact args, real queue.

The point: the agent didn’t need to know anything about Hangfire. It saw a tool, filled in the schema, and the queue did its usual thing.

4. Authentication and authorization

The library is auth-agnostic on purpose. MapHangfireMcp("/mcp") returns IEndpointConventionBuilder, so you layer ASP.NET Core auth on top with .RequireAuthorization(...) like any other endpoint.

The full picture for a tool call looks like this:

sequenceDiagram autonumber participant Agent as AI Agent participant MCP as /mcp participant Auth as ASP.NET Core auth participant Pipe as JobInvocationPipeline participant HF as Hangfire Agent->>MCP: CallTool (no token) MCP-->>Agent: 401 + WWW-Authenticate (RFC 9728) Agent->>Agent: discover OAuth metadata, obtain JWT Agent->>MCP: CallTool (Bearer JWT) MCP->>Auth: validate token, RequireAuthorization Auth->>Pipe: invoke tool Pipe->>Pipe: evaluate [Authorize] on job alt allowed Pipe->>HF: Enqueue job HF-->>Agent: tool result else denied Pipe-->>Agent: MCP error (Forbidden) end

Authentication

The sample uses Keycloak as the OAuth 2.0 / OIDC authorization server, JWT bearer for token validation, and the MCP-spec McpAuthenticationHandler to emit RFC 9728 challenges. That last bit matters: it lets MCP clients self-discover the protected-resource metadata at /.well-known/oauth-protected-resource/mcp, which is how you avoid hardcoding auth server URLs into clients.

app.MapHangfireMcp("/mcp")
    .RequireAuthorization(p => p
        .RequireAuthenticatedUser()
        .AddAuthenticationSchemes(McpAuthenticationDefaults.AuthenticationScheme));

The full setup (Keycloak realm import, JWT + AddMcp(...) resource metadata, the container-vs-host issuer URL caveat that bit me twice) is in the repo at docs/authentication.md. Other ASP.NET Core schemes work the same way: Entra ID, Auth0, custom JWT — nothing about the library cares which one you pick.

Per-job authorization

Endpoint auth is necessary but not enough. Once a client is past the /mcp gate it can list every tool, and you usually want different jobs guarded by different policies. So Nall.Hangfire.Mcp honors the standard [Authorize] attribute on job methods — opt in with AddJobAuthorization(), then decorate:

[Authorize(Policy = "jobs:run")]
Task GenerateAsync(int year, string format = "pdf", DateTimeOffset? since = null);

Under the hood, AddJobAuthorization() registers an AuthorizeAttributeFilter into the job invocation pipeline. When a tool call hits HangfireMcpHandlers, the pipeline collects [Authorize] attributes from the method and its declaring type, evaluates them against the current ClaimsPrincipal via IAuthorizationService, and short-circuits to an MCP error if any check fails. No Hangfire shim, no custom attribute. It’s the same [Authorize] you’d put on a controller action.

That keeps the threat model boring, which is what you want. The /mcp endpoint is gated by RequireAuthorization(). Per-job access is gated by ordinary ASP.NET Core policies. Catalog visibility and execution rights are separate concerns: an agent that lacks the right claims still sees jobs in the catalog it can’t run, and the call returns Forbidden when it tries.

Summary

Nall.Hangfire.Mcp collapses the “expose Hangfire to an MCP client” problem into a couple of lines of host code. Discovery comes from two sources (recurring storage at runtime, a Roslyn source generator at compile time). Schemas come from method signatures, with [Description] doing the heavy lifting. Auth and authorization reuse the standard ASP.NET Core stack: RequireAuthorization() on the endpoint, [Authorize(Policy = ...)] on the job.

Inside an Aspire AppHost, .WithMcpServer plus AddMcpInspector is most of the integration work. What you end up with is what I keep calling an Operations Pane: one surface where agents can run jobs and operate the queue, and where the security model is the same one you already use for the rest of the app.

Reference

User-Managed Access (UMA) 2.0 Resource Sharing with Keycloak and .NET

Wed, 15 Apr 2026 00:00:00 +0000

TL;DR

UMA 2.0 lets resource owners control access to their stuff. Think Google Drive sharing, but wired into your authorization server.
Keycloak.AuthServices now supports the challenge-response flow (automatic ticket-for-RPT exchange) and async approval (request, wait for owner, get in).
A Blazor Server + Minimal API sample shows the full flow. UmaTokenHandler handles the UMA dance behind the scenes.
IKeycloakProtectionClient covers the permission ticket lifecycle: create, list, approve, deny.

Source code: https://github.com/NikiforovAll/keycloak-authorization-services-dotnet/tree/main/samples/UmaResourceSharing

What is UMA?

Most authorization systems work the same way: the resource server decides who gets access based on roles, claims, or policies that an admin defined. But what if the resource owner, not the admin, should make that call?

User-Managed Access (UMA) is an OAuth 2.0 extension that flips this. Alice can grant or revoke access to her resources for bob, without an admin involved, and without needing to be online when bob asks.

You’ve seen this pattern before:

Sharing a Google Doc with specific people
Granting a colleague access to a private GitHub repo
Approving a permission request in a cloud console

What makes UMA different from regular OAuth is the asynchronous approval step. Bob requests access, alice reviews it later, and only then does bob get in.

Key concepts

Concept	Description
Resource Owner	The user who owns the protected resource
Requesting Party	A user who wants access to someone else's resource
Permission Ticket	A one-time challenge token representing an access request
RPT (Requesting Party Token)	An access token enriched with specific resource permissions
Protection API	Keycloak API for managing resources, permissions, and tickets

Demo

Here’s what this looks like in the Blazor sample.

alice (resource owner), instant access

Alice owns shared-document, so authorization succeeds right away:

bob requests access, alice approves

Bob has no permission. He submits a request, alice approves it, then bob retries and gets in:

bob (no permission), access denied

Without approval, bob gets a clear “Access Denied”:

How the UMA flow works

Two flows, working together.

Challenge-response (instant access)

When a user already has permission, the client handles the exchange automatically:

sequenceDiagram participant User as User (Browser) participant Client as Client App participant RS as Resource Server participant KC as Keycloak User->>Client: Access protected resource Client->>RS: GET /resource (Bearer token) RS->>KC: Evaluate permissions KC-->>RS: 403 (no permission yet) RS->>KC: Create permission ticket KC-->>RS: ticket="abc123..." RS-->>Client: 401 WWW-Authenticate: UMA ticket="abc123..." Client->>KC: Exchange ticket for RPT KC-->>Client: RPT (with permissions) Client->>RS: GET /resource (Bearer RPT) RS-->>Client: 200 OK — resource content

UmaTokenHandler handles steps 6-9. Your code just makes HTTP calls as usual.

Async approval (request, approve, access)

When a user has no permission, they submit a request. The resource owner reviews it later:

sequenceDiagram participant Bob as Bob participant App as Application participant KC as Keycloak participant Alice as Alice (Owner) Bob->>App: Request access to resource App->>KC: Create permission ticket (granted=false) KC-->>App: 201 Created App-->>Bob: "Request submitted" Note over Alice: Alice logs in later Alice->>App: View pending requests App->>KC: GET permission tickets (granted=false) KC-->>App: Pending tickets list Alice->>App: Approve bob's request App->>KC: Update ticket (granted=true) Note over Bob: Bob retries Bob->>App: Access resource App->>KC: Evaluate permissions KC-->>App: Permitted App-->>Bob: Resource content

Architecture

Two projects: a Blazor Server client talks to a Minimal API resource server. Keycloak sits in the middle, handling authorization decisions and permission tickets.

Resource server

The resource server protects endpoints with RequireProtectedResource() and returns WWW-Authenticate: UMA challenges on authorization failure via AddUmaPermissionTicketChallenge():

services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddKeycloakWebApi(configuration, options =>
    {
        options.Audience = "uma-resource-server";
        options.RequireHttpsMetadata = false;
    });

// Authorization + UMA challenge handler
services.AddAuthorization()
    .AddKeycloakAuthorization()
    .AddUmaPermissionTicketChallenge();

services.AddAuthorizationServer(configuration)
    .AddStandardResilienceHandler();

// Protection API for ticket management
services.AddKeycloakProtectionHttpClient(configuration)
    .AddClientCredentialsTokenHandler(tokenClientName);

// Protected endpoints
app.MapGet("/documents/{name}", (string name) =>
        new DocumentResponse(name, $"Content of {name}"))
    .RequireProtectedResource("shared-document", "read");

app.MapGet("/documents/{name}/details", (string name) =>
        new DocumentResponse(name, $"Detailed content of {name}"))
    .RequireProtectedResource("shared-document", "write");

It also exposes permission ticket management endpoints:

// Bob submits an access request
app.MapPost("/permissions/request", async (...) =>
{
    // ...
    var ticket = new PermissionTicket
    {
        Resource = resourceId, Requester = userId,
        ScopeName = "read", Granted = false,
    };
    await protectionClient.CreatePermissionTicketWithResponseAsync(realm, ticket);
}).RequireAuthorization();

// Alice lists pending requests
app.MapGet("/permissions/pending", async (...) =>
{
    return await protectionClient.GetPermissionTicketsAsync(realm,
        new GetPermissionTicketsRequestParameters { Granted = false, ReturnNames = true });
}).RequireAuthorization();

// Alice approves
app.MapPut("/permissions/{id}/approve", async (...) =>
{
    await protectionClient.UpdatePermissionTicketAsync(realm,
        new PermissionTicket { Id = id, Granted = true });
}).RequireAuthorization();

Client app (Blazor Server)

The Blazor client registers UmaTokenHandler from Keycloak.AuthServices.Authorization.Uma. It’s a DelegatingHandler that intercepts 401+UMA responses and handles the ticket exchange:

// UMA ticket exchange client
services.AddKeycloakUmaTicketExchangeHttpClient(configuration);

// HTTP client with UMA handling
services.AddHttpClient("ResourceServer", (sp, client) =>
    {
        var config = sp.GetRequiredService<IConfiguration>();
        var baseUrl = config["services:resource-server:http:0"];
        client.BaseAddress = new Uri(baseUrl);
    })
    .AddUmaTokenHandler();

What UmaTokenHandler does:

Attaches the user’s access token to outgoing requests
On 401 with WWW-Authenticate: UMA, extracts the permission ticket
Exchanges the ticket for an RPT at Keycloak’s token endpoint
Retries the original request with the RPT

From the Blazor component side, none of this is visible. You just make HTTP calls:

var response = await Http.GetAsync($"/documents/{documentName}");
if (response.IsSuccessStatusCode)
{
    var document = await response.Content.ReadFromJsonAsync<Document>();
}

Keycloak setup

UMA needs a few things configured in Keycloak:

A confidential client with Authorization Services enabled (the resource server)
A resource with ownerManagedAccess: true and scopes like read, write
An owner policy that grants the resource owner access
An OIDC client for user login, with an audience mapper pointing to the resource server

The sample ships with pre-configured Keycloak realm exports, so you can just run it:

dotnet run --project samples/UmaResourceSharing/AppHost

Aspire opens the dashboard automatically with Keycloak, the resource server, and the Blazor app.

Summary

Role-based access control doesn’t cover the case where users share resources with each other. UMA does.

With Keycloak.AuthServices you get UmaTokenHandler for the challenge-response dance, AddUmaPermissionTicketChallenge() for resource servers, and IKeycloakProtectionClient for managing permission tickets. The sample runs with a single dotnet run via Aspire.

References

Join us on Discord:

Claude Code Hub: Kanban, Marketplace, Cost, and Memory in One Place

Wed, 08 Apr 2026 00:00:00 +0000

Too many tabs

I built a bunch of small tools around Claude Code over the past few months. A Kanban board for watching agent work. A marketplace for managing plugins. A cost dashboard. A memory explorer. Each one is its own npx command and its own browser tab, and at some point I got tired of juggling four terminals and four tabs every time I sat down to work.

So I wrote a hub that runs them all behind one command.

npx claude-code-hub --open

One process spawns four servers, opens a browser, done. The tools live in iframes and you switch between them with keyboard shortcuts. No visible chrome, no tabs.

What’s inside

Kanban

A real-time task board for Claude Code sessions. It shows tasks, agents, and subagent teams as Claude works. State comes from JSONL files written by lightweight hooks (more on that below).

Marketplace

Browse and install Claude Code plugins across local, user, and project scopes. Basically an app store for skills and MCP servers.

Cost

Token usage and cost breakdowns. Drill from totals down to projects, then to individual sessions. I check this more often than I’d like to admit.

Memory

Shows all memory sources that feed into Claude Code: CLAUDE.md files, rules, auto memory, import chains. Really helpful when Claude does something unexpected and you want to figure out which instruction is responsible.

How it actually works

The hub server spawns each sub-app as a child process on its own port. If a port is busy, the tool picks a random free one. The hub reads stdout to detect the actual port each tool landed on, then serves a shell page that embeds them as iframes.

Switching is keyboard-only:

Shortcut	Action
`Alt+1`	Kanban
`Alt+2`	Marketplace
`Alt+3`	Cost
`Alt+4`	Memory
`Ctrl+Alt+Arrow`	Next / previous tool

Tools can also deep-link to each other via postMessage. Click a session in Cost and it can jump you straight to that session’s Kanban board.

You can install it as a PWA for a standalone window with no browser UI. That’s the way I use it, honestly. It feels like its own app.

The whole thing is vanilla JS and Express. No bundler, no build step, works on Node 18+.

Setup

1. Install hooks (once)

For the full Kanban experience, you need to install hooks that log agent activity:

npx claude-code-kanban --install

These are small shell scripts that append to JSONL files. Negligible overhead. Without them you still get the task board, just no live agent indicators.

2. Launch

npx claude-code-hub --open

3. Use Claude Code normally

The hub updates live. Switch tools with the keyboard while Claude works.

Standalone mode

Each tool also works on its own if you only want one:

npx claude-code-kanban          # task board
npx claude-code-marketplace     # plugin manager
npx claude-code-cost            # cost dashboard
npx claude-code-memory-explorer # memory explorer

Claude Code doesn’t need to be running either. You can browse past sessions and costs anytime; live updates just appear when Claude starts.

What's new in Keycloak.AuthServices v2.9.0

Fri, 27 Mar 2026 00:00:00 +0000

What’s new

Keycloak.AuthServices just got a round of updates. Keycloak itself has changed a lot between versions 24 and 26 – lightweight access tokens, organizations, RFC 8414 metadata – and the .NET library needed to catch up.

This post walks through the three biggest additions.

Package	Version	Description
`Keycloak.AuthServices.Authentication`		Authentication for API and Web Apps
`Keycloak.AuthServices.Authorization`		Authorization Services + Authorization Server integration
`Keycloak.AuthServices.Authorization.TokenIntrospection`		Token introspection for lightweight access tokens
`Keycloak.AuthServices.Sdk`		Admin API and Protection API
`Keycloak.AuthServices.Sdk.Kiota`		Admin API based on OpenAPI (Kiota-generated)

Organization authorization

Keycloak 24 introduced organizations as a first-class concept – and for multi-tenant applications, this changes things.

Before organizations, multi-tenancy in Keycloak usually meant one realm per tenant (operational headache) or custom attributes and groups hacked together to represent “who belongs where”. Organizations give you a built-in abstraction: users belong to organizations, organizations have their own identity providers, and membership shows up directly in the token.

For a SaaS app, this means you can stop reinventing tenant isolation. Keycloak manages the “which user belongs to which tenant” question, and the token carries that answer. Your API just needs to enforce it.

The library picks that up and gives you authorization policies that work with it.

Keycloak produces two claim formats depending on the Organization Membership Mapper configuration – a simple string array or a rich JSON map with IDs and attributes. Both are handled transparently.

To include organization membership in tokens, request the organization:* scope. The plain organization scope alone does not include the claim.

Require any organization membership

The simplest check – the user must belong to at least one organization:

app.MapGet("/orgs", () => "You belong to an org")
    .RequireOrganizationMembership();

Require a specific organization

app.MapGet("/acme/settings", () => "Acme settings")
    .RequireOrganizationMembership("acme-corp");

Resolve the organization from route or header

Sometimes the organization comes from the request itself. The library ships with built-in resolvers for routes, headers, and query parameters:

app.MapGet("/orgs/{orgId}/projects", (string orgId) => $"Projects for {orgId}")
    .RequireOrganizationMembership("{orgId}");

app.MapGet("/tenant/projects", () => "Tenant projects")
    .RequireOrganizationMembership<RouteHandlerBuilder, HeaderParameterResolver>("{X-Organization}");

Policy-based approach

If you prefer named policies:

services.AddKeycloakAuthorization()
    .AddAuthorizationBuilder()
    .AddPolicy("AcmeOnly", policy =>
        policy.RequireOrganizationMembership("acme-corp")
              .RequireRealmRoles("user"));

Imperative authorization

For more dynamic scenarios:

var result = await authorizationService.AuthorizeAsync(
    user, null, new OrganizationRequirement(orgId));

The OrganizationRequirementHandler reads the organization claim, parses the JSON structure Keycloak emits, and checks membership. You can configure which claim type to look at if your setup uses a non-default claim name.

Token introspection for lightweight access tokens

This one bit me in production. Keycloak 24+ supports lightweight access tokens – valid signed JWTs, but intentionally stripped of business claims like resource_access, realm_access, and preferred_username. The idea is to keep tokens small.

The problem: role-based authorization silently fails. KeycloakRolesClaimsTransformation looks for resource_access, finds nothing, maps no roles. Every role check returns 403. No errors, no warnings. Just 403s.

The fix is token introspection. You send the token back to Keycloak’s introspection endpoint and get the full claim set.

Installation

Token introspection ships as a separate package:

dotnet add package Keycloak.AuthServices.Authorization.TokenIntrospection

Enabling introspection

services.AddKeycloakWebApiAuthentication(configuration);

services.AddKeycloakAuthorization(options =>
{
    options.EnableRolesMapping = RolesClaimTransformationSource.All;
});

services.AddKeycloakTokenIntrospection(configuration);

That’s it. The AddKeycloakTokenIntrospection call registers a claims transformation that:

Checks if expected claims (resource_access, realm_access) are already present
If missing, calls the introspection endpoint with client credentials
Merges the the full claim set into the ClaimsPrincipal
Caches results per token to avoid redundant calls

The existing role mapping transformation runs after introspection, so everything works transparently.

Configuration

Via appsettings.json:

{
  "Keycloak": {
    "realm": "my-realm",
    "auth-server-url": "https://keycloak.example.com/",
    "resource": "my-api",
    "credentials": {
      "secret": "my-client-secret"
    }
  }
}

The introspection client reuses KeycloakInstallationOptions, so if you already have Keycloak configured, you likely don’t need to add anything.

Cache duration defaults to 60 seconds and is configurable:

services.AddKeycloakTokenIntrospection(options =>
{
    configuration.BindKeycloakOptions(options);
    options.CacheDuration = TimeSpan.FromSeconds(120);
});

When to use this

You need this if:

Your Keycloak admin enabled lightweight access tokens
You’re using KC 26+ admin clients (they use lightweight tokens by default)
You see unexplained 403s after upgrading Keycloak

The alternative is configuring Keycloak protocol mappers with the “Add to lightweight access token” flag, which avoids the introspection round-trip entirely. Pick your trade-off.

RFC 8414 metadata discovery

Since Keycloak 26.4, the RFC 8414 metadata endpoint is available at /.well-known/oauth-authorization-server, alongside the traditional OIDC discovery at /.well-known/openid-configuration.

Why does this matter? If you’re building a pure OAuth 2.0 resource server – no ID tokens, no OIDC – then OIDC discovery is technically the wrong endpoint. More practically, Keycloak 26.4 added MCP (Model Context Protocol) authorization server support, which uses RFC 8414 discovery.

Using RFC 8414 metadata

services.AddKeycloakWebApiAuthentication(options =>
{
    configuration.BindKeycloakOptions(options);
    options.MetadataAddress = KeycloakConstants.OAuthAuthorizationServerMetadataPath;
});

The MetadataAddress property overrides the default OIDC discovery path. The constant OAuthAuthorizationServerMetadataPath resolves to ".well-known/oauth-authorization-server".

If you don’t set it, nothing changes – the library defaults to OIDC discovery as before.

When to use this

Machine-to-machine flows (client credentials, no ID tokens)
OAuth 2.0-only clients that expect RFC 8414 metadata
MCP authorization server scenarios with Keycloak 26.4+
Protocol correctness for pure resource servers

Also in this release

A few more things that shipped in this release:

Extensible policy builder – IProtectedResourcePolicyBuilder lets you customize how protected resource policies are constructed
Pluggable parameter resolution – custom IParameterResolver implementations for resolving resource names from routes, headers, query strings, or your own sources
Configurable organization claim type – if your Keycloak setup uses a non-standard claim name for organization data
Kiota SDK updated to Keycloak 26.5.6 OpenAPI spec

Full changelog: GitHub Releases

Documentation: nikiforovall.github.io/keycloak-authorization-services-dotnet

AI skills for Claude Code

This release also ships a Claude Code plugin with two AI skills that help you work with Keycloak directly from your terminal.

keycloak-auth-services

An implementation guide that knows the library’s API surface – authentication setup, authorization patterns, resource protection, Admin SDK, Protection API, and configuration options. Ask it how to set up JWT Bearer auth or configure protected resources and it’ll give you working code using the current API.

keycloak-administration

A Keycloak server administration guide covering realm management, client configuration, authentication flows, RBAC, user federation, security hardening, and troubleshooting. Useful when you need to configure the Keycloak side of things – setting up clients, mappers, organizations, or debugging token issues.

Join us on Discord:

Microsoft Agent Framework — Azure AI Foundry

Tue, 24 Mar 2026 00:00:00 +0000

TL;DR

This is Part 3 of the Microsoft Agent Framework series. Part 1 built agents locally with tools, sessions, and memory. Part 2 wired them into workflow graphs, MCP servers, and AG-UI frontends. This post moves everything to Azure AI Foundry — same AIAgent / RunAsync() API, but now the agents live server-side with managed lifecycle, hosted tools (code interpreter, web search, file search), declarative workflows, and built-in evaluations.

Source code: https://github.com/NikiforovAll/maf-getting-started

Introduction - Why Foundry?

Parts 1 and 2 ran everything in-process. Your app created agents, held their state in memory, and managed tool execution locally. That works for development, but production asks harder questions: where do agents live between requests? Who manages the Python sandbox for code execution? Where does the vector store run?

Azure AI Foundry answers these by moving agent lifecycle, tool execution, and data storage to the cloud. The programming model stays the same – you still call RunAsync() on an AIAgent. The difference is what happens behind the call.

	MAF (local)	Azure AI Foundry
Agent lifecycle	In-process only	Server-side (named + versioned)
Tools	Client-side `AIFunction`	Client-side + hosted (Code, Search, Web)
Memory	`InMemoryChatHistoryProvider`	Managed conversations
RAG	Build your own	Hosted vector stores + `HostedFileSearchTool`
Evaluation	N/A	Built-in quality + safety evaluators

To switch, you swap one package and one client:

#:package Microsoft.Agents.AI.AzureAI@1.0.0-rc4
#:package Azure.AI.Projects@2.0.0-beta.1

// Before: AzureOpenAIClient → GetChatClient → AsAIAgent
// After:
AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());

Everything else – RunAsync(), RunStreamingAsync(), tools, sessions – stays the same.

First Foundry agent

CreateAIAgentAsync creates a Foundry-side agent. Foundry stores it with a name and a version number. Each call with the same name bumps the version; GetAIAgentAsync retrieves the latest.

AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());

// Foundry-side agent -- named, versioned, persisted in Foundry
AIAgent agent = await aiProjectClient.CreateAIAgentAsync(
    name: "FoundryBasicsAgent",
    model: deploymentName,
    instructions: "You are a friendly assistant. Keep your answers brief.");

// Non-streaming
Console.WriteLine(await agent.RunAsync("Tell me a fun fact about Azure."));

// Streaming
await foreach (var update in agent.RunStreamingAsync("Tell me a fun fact about .NET."))
{
    Console.Write(update);
}

// Cleanup
await aiProjectClient.Agents.DeleteAgentAsync(agent.Name);

Agent definitions are immutable after creation. To change instructions or tools, create a new version:

AIAgent v1 = await aiProjectClient.CreateAIAgentAsync(
    name: "MyAgent", model: "gpt-4o-mini",
    instructions: "You are helpful.");

AIAgent v2 = await aiProjectClient.CreateAIAgentAsync(
    name: "MyAgent", model: "gpt-4o-mini",
    instructions: "You are extremely helpful and concise.");

// Returns v2
AIAgent latest = await aiProjectClient.GetAIAgentAsync(name: "MyAgent");

Observability - OpenTelemetry + Foundry traces

With Foundry agents, traces show up in two places:

	OTEL (client-side)	Server-side (Foundry)
What	Agent spans, chat calls, duration	Token counts, cost, response IDs
Where	Aspire Dashboard / any OTLP backend	Foundry Portal -> Traces tab
How	`.UseOpenTelemetry()` + OTLP exporter	Automatic -- built into Foundry

The same Trace ID links both sides. You see the agent execution flow in Aspire, then jump to Foundry Portal for token counts and cost.

// OTEL setup -- exports to Aspire dashboard
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("FoundryBasicsDemo"))
    .AddSource("FoundryBasicsDemo")
    .AddSource("*Microsoft.Agents.AI")
    .AddOtlpExporter()
    .Build();

// Wrap agent with telemetry
AIAgent agent = (await aiProjectClient.CreateAIAgentAsync(
    name: "FoundryBasicsAgent", model: deploymentName,
    instructions: "You are a friendly assistant."))
    .AsBuilder()
    .UseOpenTelemetry(sourceName: "FoundryBasicsDemo")
    .Build();

// Parent span groups related calls
using var activitySource = new ActivitySource("FoundryBasicsDemo");
using var activity = activitySource.StartActivity("foundry-basics-demo");

Console.WriteLine($"Trace ID: {activity?.TraceId}");

await agent.RunAsync("Tell me a fun fact about Azure.");
await agent.RunStreamingAsync("Tell me a fun fact about .NET.");

Print the Trace ID, then search for it in Foundry Portal to see the server-side view with token counts and cost breakdown.

Persistent sessions

In Part 1, conversation history lived in memory and died with the process. Foundry gives you server-side conversations that persist across sessions. Store only the conversation.Id in your database – Foundry keeps the full thread.

using Azure.AI.Projects.OpenAI;

// Create a server-side conversation
ProjectConversationsClient conversationsClient = aiProjectClient
    .GetProjectOpenAIClient()
    .GetProjectConversationsClient();
ProjectConversation conversation = await conversationsClient.CreateProjectConversationAsync();

// Session 1: establish context
AgentSession session1 = await agent.CreateSessionAsync(conversation.Id);
Console.WriteLine(await agent.RunAsync("My name is Alex.", session1));

// Session 2: new session, same conversation -- agent remembers
AgentSession session2 = await agent.CreateSessionAsync(conversation.Id);
Console.WriteLine(await agent.RunAsync("What's my name?", session2));
// -> "Your name is Alex."

sequenceDiagram participant S1 as Session 1 participant F as Foundry Conversation participant S2 as Session 2 S1->>F: "My name is Alex" F-->>S1: "Nice to meet you, Alex!" Note over F: conversation.Id stored S2->>F: "What's my name?" F-->>S2: "Your name is Alex."

The conversation is visible in the Foundry Portal too, so you can inspect the full message history without writing a single line of debugging code.

Function tools

Same pattern as Part 1 – define C# methods with [Description], register them via AIFunctionFactory.Create(). The difference: Foundry stores the tool JSON schemas server-side. The client still provides the actual implementations.

[Description("Get the current time in a given timezone.")]
static string GetTime([Description("The timezone (e.g., UTC, CET)")] string timezone) =>
    $"The current time in {timezone} is {DateTime.UtcNow:HH:mm} UTC.";

AITool[] tools = [AIFunctionFactory.Create(GetTime)];

// Server stores tool schemas, client provides implementations
AIAgent agent = await aiProjectClient.CreateAIAgentAsync(
    name: "TimeAgent", model: deploymentName,
    instructions: "You are a helpful assistant with time tool.",
    tools: tools);

Console.WriteLine(await agent.RunAsync("What's the time in Kyiv?"));

// Retrieve existing agent -- must pass tools so MAF can invoke them
AIAgent existing = await aiProjectClient.GetAIAgentAsync(name: "TimeAgent", tools: tools);
Console.WriteLine(await existing.RunAsync("What time is it in UTC?"));

When you retrieve an agent with GetAIAgentAsync, the server already knows the tool schemas. But it can’t invoke your C# methods – you have to pass the tools array so MAF can wire up the calls.

Hosted tools - Code Interpreter and Web Search

So far, all tools ran in your process. Hosted tools flip that – they run server-side in Foundry’s infrastructure. No local dependencies, no sandbox to manage.

	Client tools (Parts 1-2)	Hosted tools (Foundry)
Execution	Your process	Foundry cloud sandbox
Setup	Define + implement	One-liner -- Foundry provides the runtime
Examples	`AIFunctionFactory.Create(...)`	`HostedCodeInterpreterTool`, `HostedWebSearchTool`, `HostedFileSearchTool`
Use case	Custom business logic	Python execution, web search, file search

Code Interpreter

HostedCodeInterpreterTool gives the agent a Python sandbox. It writes code, Foundry runs it, and you get back the results.

AIAgent agent = await aiProjectClient.CreateAIAgentAsync(
    model: deploymentName,
    name: "MathTutor",
    instructions: "You are a math tutor. Write and run Python code to solve problems.",
    tools: [new HostedCodeInterpreterTool() { Inputs = [] }]);

AgentResponse response = await agent.RunAsync(
    "Solve x^3 - 6x^2 + 11x - 6 = 0. Show the roots.");

The response contains a mix of content types. Walk through them to see the full execution flow – thinking, code, output, answer:

foreach (var content in response.Messages.SelectMany(m => m.Contents))
{
    switch (content)
    {
        case TextContent text:
            Console.WriteLine($"Text: {text.Text}");
            break;

        case CodeInterpreterToolCallContent toolCall:
            var codeInput = toolCall.Inputs?.OfType<DataContent>().FirstOrDefault();
            if (codeInput?.HasTopLevelMediaType("text") ?? false)
            {
                string code = Encoding.UTF8.GetString(codeInput.Data.ToArray());
                Console.WriteLine($"Python: {code}");
            }
            break;

        case CodeInterpreterToolResultContent toolResult:
            foreach (var output in toolResult.Outputs ?? [])
            {
                if (output is TextContent tc)
                    Console.WriteLine($"Output: {tc.Text}");
            }
            break;
    }
}

Web Search

HostedWebSearchTool lets the agent search the web autonomously and return answers with annotated URL citations.

AIAgent agent = await aiProjectClient.CreateAIAgentAsync(
    name: "WebSearchAgent",
    model: deploymentName,
    instructions: "Search the web to answer questions accurately. Cite your sources.",
    tools: [new HostedWebSearchTool()]);

AgentResponse response = await agent.RunAsync("What are the latest features in .NET 10?");
Console.WriteLine(response.Text);

// Extract URL citations
foreach (var annotation in response.Messages
    .SelectMany(m => m.Contents)
    .SelectMany(c => c.Annotations ?? []))
{
    if (annotation.RawRepresentation is UriCitationMessageAnnotation urlCitation)
    {
        Console.WriteLine($"  - {urlCitation.Title}: {urlCitation.Uri}");
    }
}

RAG via Foundry

Building RAG usually means picking an embedding model, setting up a vector database, writing a chunking pipeline, and wiring it all together. Foundry collapses that into a few API calls:

Step	API	What happens
1. Upload file	`filesClient.UploadFile()`	File stored in Foundry
2. Create vector store	`vectorStoresClient.CreateVectorStoreAsync()`	Auto-chunked + embedded
3. Create agent	`CreateAIAgentAsync(tools: [HostedFileSearchTool])`	Agent grounded on your data
4. Ask questions	`agent.RunAsync()`	Grounded answers with citations
5. Cleanup	Delete agent, vector store, file	No orphan resources

var projectOpenAIClient = aiProjectClient.GetProjectOpenAIClient();
var filesClient = projectOpenAIClient.GetProjectFilesClient();
var vectorStoresClient = projectOpenAIClient.GetProjectVectorStoresClient();

// Upload knowledge base
OpenAIFile uploaded = filesClient.UploadFile(tempFile, FileUploadPurpose.Assistants);

// Create vector store -- auto-chunks and embeds
var vectorStore = await vectorStoresClient.CreateVectorStoreAsync(
    options: new() { FileIds = { uploaded.Id }, Name = "contoso-products" });
string vectorStoreId = vectorStore.Value.Id;

// Create agent with file search grounded on the vector store
AIAgent agent = await aiProjectClient.CreateAIAgentAsync(
    model: deploymentName,
    name: "RAGAgent",
    instructions: "Answer questions using the product catalog. Cite the source.",
    tools: [new HostedFileSearchTool()
    {
        Inputs = [new HostedVectorStoreContent(vectorStoreId)]
    }]);

// Multi-turn Q&A
var session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("What's the cheapest product?", session));
Console.WriteLine(await agent.RunAsync("Which product supports CI/CD?", session));

flowchart LR A[Upload File] --> B[Create Vector Store] B --> C[Auto-chunk + Embed] C --> D[Create Agent + HostedFileSearchTool] D --> E[RunAsync - Grounded Q&A]

Foundry workflows

Part 2 built workflows in-process with WorkflowBuilder and AddEdge(). Foundry workflows take a different approach – you declare the agent graph in YAML, register it server-side, and Foundry orchestrates the execution.

Here’s a workflow where a storyteller writes a story and a critic reviews it:

kind: Workflow
trigger:
  kind: OnConversationStart
  id: story_critic_workflow
  actions:
    - kind: InvokeAzureAgent
      id: storyteller_step
      conversationId: =System.ConversationId
      agent:
        name: StorytellerAgent
    - kind: InvokeAzureAgent
      id: critic_step
      conversationId: =System.ConversationId
      agent:
        name: CriticAgent

First create the agents, then register and run the workflow:

// Create the agents that the workflow will orchestrate
await aiProjectClient.CreateAIAgentAsync(
    name: "StorytellerAgent", model: deploymentName,
    instructions: "You are a creative storyteller. Write a short story based on the user's prompt.");

await aiProjectClient.CreateAIAgentAsync(
    name: "CriticAgent", model: deploymentName,
    instructions: "You are a literary critic. Review the story and provide constructive feedback.");

// Register workflow via raw JSON (the SDK wraps the YAML in a JSON envelope)
string escapedYaml = JsonEncodedText.Encode(workflowYaml).ToString();
string requestJson = $$"""
    {
        "definition": { "kind": "workflow", "workflow": "" },
        "description": "Storyteller writes a story, Critic reviews it."
    }
    """;

await aiProjectClient.Agents.CreateAgentVersionAsync(
    "StoryCriticWorkflow",
    BinaryContent.Create(BinaryData.FromString(requestJson)),
    foundryFeatures: null, options: null);

// Run with streaming
ChatClientAgent workflowAgent = await aiProjectClient.GetAIAgentAsync(
    name: "StoryCriticWorkflow");
AgentSession session = await workflowAgent.CreateSessionAsync();

ChatClientAgentRunOptions runOptions = new(
    new ChatOptions { ConversationId = conversation.Id });

await foreach (var update in workflowAgent.RunStreamingAsync(
    "Write a story about a robot who discovers music.", session, runOptions))
{
    Console.Write(update.Text);
}

Same RunStreamingAsync API as always. Foundry handles the orchestration – each agent produces a separate message in the stream.

flowchart LR U[User Prompt] --> W[Foundry Workflow] W --> S[StorytellerAgent] S --> C[CriticAgent] C --> R[Streamed Response]

Evaluations

Before shipping an agent to production, you want to know: are its answers grounded in the context you provided? Are they relevant? Coherent? Safe? Foundry’s evaluation library runs all of these in a single pass.

Dimension	Evaluator	What it measures
Groundedness	`GroundednessEvaluator`	Are answers grounded in provided context?
Relevance	`RelevanceEvaluator`	Does the answer address the question?
Coherence	`CoherenceEvaluator`	Is the response well-structured and logical?
Safety	`ContentHarmEvaluator`	Violence, self-harm, sexual, hate content

Quality evaluators (groundedness, relevance, coherence) use an LLM as a judge. The safety evaluator uses Azure AI Foundry’s content safety service – a separate endpoint, not an LLM call.

// Evaluator LLM (the judge)
IChatClient chatClient = new AzureOpenAIClient(new Uri(openAiEndpoint), credential)
    .GetChatClient(evaluatorDeployment)
    .AsIChatClient();

// Safety evaluator needs the Foundry content safety endpoint
ContentSafetyServiceConfiguration safetyConfig = new(
    credential: credential, endpoint: new Uri(endpoint));
ChatConfiguration chatConfiguration = safetyConfig.ToChatConfiguration(
    originalChatConfiguration: new ChatConfiguration(chatClient));

// Compose all evaluators
CompositeEvaluator evaluator = new([
    new GroundednessEvaluator(),
    new RelevanceEvaluator(),
    new CoherenceEvaluator(),
    new ContentHarmEvaluator(),
]);

// Run evaluation
List<ChatMessage> messages = [new(ChatRole.User, question)];
ChatResponse chatResponse = new(new ChatMessage(ChatRole.Assistant, agentResponse.Text));

EvaluationResult result = await evaluator.EvaluateAsync(
    messages, chatResponse, chatConfiguration,
    additionalContext: [new GroundednessEvaluatorContext(context)]);

// Read scores
foreach (var metric in result.Metrics.Values)
{
    if (metric is NumericMetric n)
        Console.WriteLine($"{n.Name}: {n.Value:F1}/5 ({n.Interpretation?.Rating})");
    else if (metric is BooleanMetric b)
        Console.WriteLine($"{b.Name}: {b.Value} ({b.Interpretation?.Rating})");
}

Quality metrics score 0-5. Safety metrics are boolean (pass/fail). Run these in CI or as a gate before deployment – you’ll catch regressions in answer quality and safety issues before users do.

Key takeaways

AIProjectClient.CreateAIAgentAsync() – same AIAgent API, server-managed lifecycle with name + version semantics
.UseOpenTelemetry() + Aspire – client spans correlated with Foundry server traces via shared Trace ID
ProjectConversation – server-side persistent conversations, store only the ID
HostedCodeInterpreterTool / HostedWebSearchTool / HostedFileSearchTool – hosted tools that run in Foundry, zero infrastructure on your side
File upload + vector store + HostedFileSearchTool – RAG without managing an embedding pipeline or vector database
Declarative YAML workflows – server-side multi-agent orchestration, same RunStreamingAsync API
CompositeEvaluator – quality + safety scoring in a single pass before production

Presentation

References

Microsoft Agent Framework — Workflows, MCP, A2A & AG-UI

Sat, 07 Mar 2026 00:00:00 +0000

TL;DR

This is Part 2 of the Microsoft Agent Framework series. Part 1 covered the basics — creating agents, tools, multi-turn conversations, and memory. This post goes further: orchestrating agents into workflow graphs, exposing them as MCP servers, enabling agent-to-agent communication via A2A, and streaming to frontends with AG-UI. All samples run as single-file C# scripts with dotnet run.

Source code: https://github.com/NikiforovAll/maf-getting-started

Introduction — From agents to systems

Part 1 built individual agents with tools, sessions, and memory. But real systems need more: pipelines that chain agents together, protocols that expose agents to external clients, and standards that let agents discover each other.

MAF addresses this with three integration protocols:

Protocol	Who talks	Transport	Use case
MCP Server	Client → Your Agent	stdio / HTTP	Expose agents as tools
MCP Client	Your Agent → Remote Tools	stdio / HTTP	Consume external tools
A2A	Agent → Agent	HTTP + JSON-RPC	Multi-agent orchestration
AG-UI	User → Agent	HTTP POST + SSE	Serve end users

MCP gives agents tools (both ways), A2A lets agents talk to agents, AG-UI connects agents to end users.

Workflows — Orchestrating agents as graphs

Workflows in MAF are directed graphs — nodes are executors (functions or agents), edges define data flow. Three patterns cover most use cases:

Pattern	Use Case	API
Function Workflow	Pure data transformations, no LLM	`BindAsExecutor()` + `WorkflowBuilder`
Agent Workflow	LLM-powered multi-agent pipelines	`AgentWorkflowBuilder.BuildSequential()`
Composed Workflow	Mix functions + agents in one graph	`WorkflowBuilder` + `AddEdge()`

The building blocks:

Building Block	API	Description
Executor	`Func<T,R>.BindAsExecutor()`	A node in the workflow graph
Edge	`builder.AddEdge(A, B)`	Connects two executors (A → B)
Output	`builder.WithOutputFrom(B)`	Designates the final output node
Run	`InProcessExecution.RunAsync()`	Executes the workflow
StreamingRun	`InProcessExecution.RunStreamingAsync()`	Executes with streaming events
Events	`ExecutorCompletedEvent`, `AgentResponseUpdateEvent`	Emitted per completed node

Function workflow

Bind plain C# functions as workflow executors — no LLM involved, pure data transformations:

#:package Microsoft.Agents.AI.Workflows@1.0.0-rc2

using Microsoft.Agents.AI.Workflows;

Func<string, string> uppercaseFunc = s => s.ToUpperInvariant();
var uppercase = uppercaseFunc.BindAsExecutor("UppercaseExecutor");

Func<string, string> reverseFunc = s => string.Concat(s.Reverse());
var reverse = reverseFunc.BindAsExecutor("ReverseTextExecutor");

WorkflowBuilder builder = new(uppercase);
builder.AddEdge(uppercase, reverse).WithOutputFrom(reverse);
var workflow = builder.Build();

await using Run run = await InProcessExecution.RunAsync(workflow, "Hello, World!");
foreach (WorkflowEvent evt in run.NewEvents)
{
    if (evt is ExecutorCompletedEvent executorComplete)
    {
        Console.WriteLine($"{executorComplete.ExecutorId}: {executorComplete.Data}");
    }
}

graph LR Input["Hello, World!"] --> U[UppercaseExecutor] U --> R[ReverseTextExecutor] R --> Output["!DLROW ,OLLEH"]

Step	Executor	Output
Input	—	`"Hello, World!"`
1	UppercaseExecutor	`"HELLO, WORLD!"`
2	ReverseTextExecutor	`"!DLROW ,OLLEH"`

BindAsExecutor() wraps any Func<TInput, TOutput> into a workflow node. The TOutput of one node must match the TInput of the next — the type system enforces the contract.

Agent workflow

For LLM-powered pipelines, AgentWorkflowBuilder.BuildSequential() chains agents together:

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME");

var chatClient = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsIChatClient();

AIAgent writer = chatClient.AsAIAgent(
    instructions: "You write short creative stories in 2-3 sentences.", name: "Writer"
);

AIAgent critic = chatClient.AsAIAgent(
    instructions: "You review stories and give brief constructive feedback in 1-2 sentences.", name: "Critic"
);

var agentWorkflow = AgentWorkflowBuilder.BuildSequential("story-pipeline", [writer, critic]);

List<ChatMessage> input = [new(ChatRole.User, "Write a story about a robot learning to paint.")];

await using StreamingRun agentRun = await InProcessExecution.RunStreamingAsync(agentWorkflow,input);
await agentRun.TrySendMessageAsync(new TurnToken(emitEvents: true));

string lastExecutorId = string.Empty;
await foreach (WorkflowEvent evt in agentRun.WatchStreamAsync())
{
    if (evt is AgentResponseUpdateEvent e)
    {
        if (e.ExecutorId != lastExecutorId)
        {
            lastExecutorId = e.ExecutorId;
            Console.WriteLine();
            Console.WriteLine($"[{e.ExecutorId}]:");
        }

        Console.Write(e.Update.Text);
    }
    else if (evt is WorkflowOutputEvent output)
    {
        Console.WriteLine();
    }
}

graph LR U[User Prompt] --> W[Writer] W -->|story| C[Critic] C -->|feedback| O[Output]

[Writer]:
A small robot named Pixel discovered an abandoned art studio and began
mixing colors with its mechanical fingers...

[Critic]:
The story has a charming premise. Consider adding sensory details about
how the robot perceives color differently from humans...

Agent workflows use StreamingRun + AgentResponseUpdateEvent — not Run/NewEvents like function workflows. The TrySendMessageAsync(new TurnToken(emitEvents: true)) call kicks off the pipeline and enables event streaming.

Composed workflow

Real pipelines mix deterministic and intelligent steps. Consider PII redaction:

Step	What	Why not just one?
Regex (function)	Mask emails — fast, 100% reliable	LLMs hallucinate, regex doesn't
LLM (agent)	Rewrite text naturally	Regex can't rephrase prose
Regex (function)	Validate no PII leaked	Trust but verify — deterministic check

WorkflowBuilder lets you compose both in a single directed graph. First, define the three executors:

var client = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential());

// Step 1: Function executor — mask emails with regex
Func<string, string> maskEmails = text =>
    Regex.Replace(text, @"[\w.-]+@[\w.-]+\.\w+", "[EMAIL_REDACTED]");
var maskExecutor = maskEmails.BindAsExecutor("MaskEmails");

// Step 2: Agent executor — wrap LLM agent call as a function executor
AIAgent rewriter = client
    .GetChatClient(deploymentName)
    .AsAIAgent(
        instructions: "You receive text with [EMAIL_REDACTED] placeholders. "
            + "Rewrite the text to sound natural while keeping all redactions intact. "
            + "Do not invent or restore any redacted information. "
            + "Return only the rewritten text.",
        name: "Rewriter"
    );
Func<string, ValueTask<string>> rewriteFunc = async text =>
{
    var response = await rewriter.RunAsync(text);
    return response.ToString();
};
var rewriteExecutor = rewriteFunc.BindAsExecutor("Rewriter");

// Step 3: Function executor — validate no emails leaked
Func<string, string> validate = text =>
{
    var leaks = Regex.Matches(text, @"[\w.-]+@[\w.-]+\.\w+");
    return leaks.Count > 0
        ? $"VALIDATION FAILED - {leaks.Count} email(s) leaked"
        : $"CLEAN - no emails detected\n\n{text}";
};
var validateExecutor = validate.BindAsExecutor("ValidateNoLeaks");

Sync Func<T,R> is auto-wrapped to ValueTask by the framework, while async Func<T, ValueTask<R>> is used for agent calls that involve I/O. Both produce the same Executor — the graph doesn’t care.

Then wire the graph and execute:

// Build graph: mask → rewrite → validate
WorkflowBuilder builder = new(maskExecutor);
builder.AddEdge(maskExecutor, rewriteExecutor);
builder.AddEdge(rewriteExecutor, validateExecutor);
builder.WithOutputFrom(validateExecutor);
var workflow = builder.Build();

var input = """
    Hi team, please contact Alice at alice.smith@example.com for the Q3 report.
    Bob (bob.jones@corp.net) will handle the deployment.
    CC: support@acme.io for any issues.
    """;

await using Run run = await InProcessExecution.RunAsync(workflow, input);

foreach (WorkflowEvent evt in run.NewEvents)
{
    if (evt is ExecutorCompletedEvent executorComplete)
    {
        Console.WriteLine($"[{executorComplete.ExecutorId}]:");
        Console.WriteLine(executorComplete.Data);
        Console.WriteLine();
    }
}

graph LR I[Input text with emails] --> M[MaskEmails
Func — regex] M --> R[Rewriter
AIAgent — LLM] R --> V[ValidateNoLeaks
Func — regex] V --> O[Output]

[MaskEmails]:
Hi team, please contact Alice at [EMAIL_REDACTED] for the Q3 report.
Bob ([EMAIL_REDACTED]) will handle the deployment.
CC: [EMAIL_REDACTED] for any issues.

[Rewriter]:
Hi team, please reach out to Alice at [EMAIL_REDACTED] regarding the Q3 report.
Bob ([EMAIL_REDACTED]) will be managing the deployment.
For any issues, CC [EMAIL_REDACTED].

[ValidateNoLeaks]:
CLEAN - no emails detected

MCP Integration — Agents as servers and clients

Model Context Protocol is an open standard for connecting AI models to external tools and data. The integration is two-sided:

Direction	Pattern	API
Agent as MCP Server	Expose your agents as tools for external MCP clients (Claude Code, VS Code, etc.)	`.AsAIFunction()` → `McpServerTool.Create()`
Agent as MCP Client	Your agent discovers and calls tools from remote MCP servers	`McpClient.CreateAsync()` → `ListToolsAsync()`

MCP Server

Two calls turn any agent into an MCP tool: .AsAIFunction() then McpServerTool.Create():

var client = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential());

AIAgent joker = client
    .GetChatClient(deploymentName)
    .AsAIAgent(
        instructions: "You are good at telling jokes.",
        name: "Joker",
        description: "An agent that tells jokes on any topic."
    );

AIAgent weatherAgent = client
    .GetChatClient(deploymentName)
    .AsAIAgent(
        instructions: "You are a helpful weather assistant.",
        name: "WeatherAgent",
        description: "An agent that answers weather questions.",
        tools: [AIFunctionFactory.Create(GetWeather)]
    );

var jokerTool = McpServerTool.Create(joker.AsAIFunction());
var weatherTool = McpServerTool.Create(weatherAgent.AsAIFunction());

var builder = Host.CreateEmptyApplicationBuilder(settings: null);
builder.Services.AddMcpServer().WithStdioServerTransport().WithTools([jokerTool, weatherTool]);

await builder.Build().RunAsync();

[Description("Get the weather for a given location.")]
static string GetWeather([Description("The location to get the weather for.")] string location) =>
    $"The weather in {location} is cloudy with a high of 15°C.";

sequenceDiagram participant C as MCP Client
(Claude Code) participant S as MCP Server
(stdio) participant W as WeatherAgent participant T as GetWeather C->>S: call WeatherAgent tool S->>W: RunAsync(input) W->>T: GetWeather("Amsterdam") T-->>W: "cloudy, 15°C" W-->>S: response S-->>C: result

Drop a .mcp.json in your repo root and Claude Code / VS Code picks it up automatically:

{
  "mcpServers": {
    "maf-agents": {
      "command": "dotnet",
      "args": ["run", "src/06-agent-as-mcp.cs"],
      "env": {
        "AZURE_OPENAI_ENDPOINT": "https://your-resource.cognitiveservices.azure.com/",
        "AZURE_OPENAI_DEPLOYMENT_NAME": "gpt-4o-mini"
      }
    }
  }
}

dotnet run starts the MCP server as a child process. Communication happens over stdio — no ports, no networking.

MCP Client

Agents can also consume MCP tools. Here’s an agent that uses Microsoft Learn’s public MCP server:

var client = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential());

Console.WriteLine("Connecting to Microsoft Learn MCP...");
await using var mcpClient = await McpClient.CreateAsync(
    new HttpClientTransport(
        new()
        {
            Endpoint = new Uri("https://learn.microsoft.com/api/mcp"),
            Name = "Microsoft Learn MCP",
            TransportMode = HttpTransportMode.StreamableHttp,
        }
    ),
    loggerFactory: loggerFactory
);

Console.WriteLine("Listing tools...");
IList<McpClientTool> mcpTools = await mcpClient.ListToolsAsync();
Console.WriteLine($"Discovered {mcpTools.Count} tools:");
foreach (var tool in mcpTools)
    Console.WriteLine($"  - {tool.Name}");

AIAgent agent = client
    .GetChatClient(deploymentName)
    .AsIChatClient()
    .AsBuilder()
    .UseLogging(loggerFactory)
    .Build()
    .AsAIAgent(
        instructions: "You answer questions using Microsoft Learn documentation tools.",
        name: "DocsAgent",
        loggerFactory: loggerFactory,
        tools: [.. mcpTools.Cast<AITool>()]
    );

Console.WriteLine("Running agent...");
Console.WriteLine(await agent.RunAsync("What is Microsoft Agent Framework?"));

HttpClientTransport connects to remote MCP servers (Streamable HTTP), while StdioClientTransport works for local servers. The same ListToolsAsync() API discovers tools in both cases. Discovered McpClientTool instances are cast to AITool and passed directly as agent tools.

A2A — Agent-to-agent communication

Agent-to-Agent Protocol is an open standard for agents to discover and communicate with each other over HTTP.

	MCP	A2A
Who talks	Client → Tool	Agent → Agent
Transport	stdio / HTTP	HTTP + JSON-RPC
Discovery	Config file	`/.well-known/agent-card.json`
Use case	Extend agent capabilities	Multi-agent orchestration

A2A Server

Every A2A agent publishes an AgentCard that clients fetch for discovery:

var client = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential());

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient().AddLogging();
builder.Services.ConfigureHttpJsonOptions(o =>
{
    o.SerializerOptions.TypeInfoResolverChain.Add(
        A2AJsonUtilities.DefaultOptions.TypeInfoResolver!
    );
    o.SerializerOptions.TypeInfoResolverChain.Add(
        A2AJsonUtilities.DefaultOptions.TypeInfoResolver!
    );
});

var app = builder.Build();

AIAgent agent = client
    .GetChatClient(deploymentName)
    .AsIChatClient()
    .AsAIAgent(
        instructions: "You are a helpful assistant.",
        name: "A2AAssistant",
        tools: [AIFunctionFactory.Create(GetWeather)]
    );

AgentCard agentCard = new()
{
    Name = "A2AAssistant",
    Description = "A helpful assistant exposed via A2A protocol.",
    Version = "1.0.0",
    DefaultInputModes = ["text"],
    DefaultOutputModes = ["text"],
    Capabilities = new() { Streaming = false },
    Skills =
    [
        new()
        {
            Id = "general",
            Name = "General Assistant",
            Description = "Answers general questions and checks weather.",
        },
    ],
};

app.MapA2A(
    agent,
    path: "/",
    agentCard: agentCard,
    taskManager => app.MapWellKnownAgentCard(taskManager, "/")
);

await app.RunAsync();

[Description("Get the weather for a given location.")]
static string GetWeather([Description("The location to get the weather for.")] string location) =>
    $"The weather in {location} is cloudy with a high of 15°C.";

MapA2A() exposes the agent over HTTP, and MapWellKnownAgentCard() serves the card at /.well-known/agent-card.json. Clients discover the agent by fetching the card — no config files, no registry needed.

A2A Client

var host = args.Length > 0 ? args[0] : "http://localhost:5000";

A2ACardResolver resolver = new(new Uri(host));

AIAgent agent = await resolver.GetAIAgentAsync();

Console.WriteLine(await agent.RunAsync("What is the weather in Amsterdam?"));

4 lines to discover a remote agent and call it. A2ACardResolver fetches the agent card, constructs an AIAgent proxy, and you use the same RunAsync() interface as local agents.

AG-UI — Exposing agents to web UIs

Agent User Interface Protocol connects agents to frontend UIs via HTTP POST + Server-Sent Events:

	MCP	A2A	AG-UI
Who talks	Client → Tool	Agent → Agent	User → Agent
Transport	stdio / HTTP	HTTP + JSON-RPC	HTTP POST + SSE
Discovery	Config file	Agent card	URL
Use case	Extend capabilities	Multi-agent orchestration	Serve end users

The client sends one HTTP POST, the server streams back typed SSE events:

Phase	What happens	SSE Events
Start	Server begins processing	`RUN_STARTED`
Text response	Tokens stream to UI in real-time	`TEXT_MESSAGE_START` → `TEXT_MESSAGE_CONTENT`* → `TEXT_MESSAGE_END`
Tool call	Agent invokes a function	`TOOL_CALL_START` → `TOOL_CALL_ARGS` → `TOOL_CALL_END`
State update	Shared state syncs to client	`STATE_SNAPSHOT` or `STATE_DELTA`
Finish	Run completes	`RUN_FINISHED`

AG-UI Server

var client = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential());

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient().AddLogging();
builder.Services.AddCors(o =>
    o.AddDefaultPolicy(p => p.AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader())
);
builder.Services.AddAGUI();

WebApplication app = builder.Build();
app.UseCors();

AIAgent agent = client
    .GetChatClient(deploymentName)
    .AsIChatClient()
    .AsAIAgent(
        instructions: "You are a helpful assistant.",
        name: "AGUIAssistant",
        description: "A helpful assistant that can answer questions and check weather.",
        tools: [AIFunctionFactory.Create(GetWeather)]
    );

app.MapAGUI("/", agent);

await app.RunAsync();

[Description("Get the weather for a given location.")]
static string GetWeather([Description("The location to get the weather for.")] string location) =>
    $"The weather in {location} is cloudy with a high of 15°C.";

AddAGUI() registers the AG-UI JSON serialization, MapAGUI("/", agent) exposes the agent as an HTTP+SSE endpoint. Two calls from agent to web-ready endpoint.

AG-UI Client

using HttpClient httpClient = new() { Timeout = TimeSpan.FromSeconds(60) };
AGUIChatClient chatClient = new(httpClient, "http://localhost:5000");

AIAgent agent = chatClient.AsAIAgent(name: "agui-client");

await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(
    [new ChatMessage(ChatRole.User, "What's the weather in Amsterdam?")]))
{
    foreach (AIContent content in update.Contents)
        if (content is TextContent text)
            Console.Write(text.Text);
}

AGUIChatClient wraps HttpClient and speaks the AG-UI protocol. From there it’s the familiar AsAIAgent() + RunStreamingAsync() pattern. The full interactive client adds a Spectre.Console chat loop with session management. For richer frontend experiences, check out CopilotKit or AG-UI Dojo.

Key takeaways

BindAsExecutor() — turn any Func<T,R> into a workflow node
AgentWorkflowBuilder.BuildSequential() — chain agents into pipelines with one call
WorkflowBuilder + AddEdge() — compose function and agent executors in a single graph
McpServerTool.Create(agent.AsAIFunction()) — expose agents as MCP tools in two lines
MapA2A() + AgentCard — agents discover and call each other over HTTP
AddAGUI() + MapAGUI() — expose agents to web UIs via HTTP+SSE in two lines

Presentation

References

Microsoft Agent Framework — Foundations

Mon, 02 Mar 2026 00:00:00 +0000

TL;DR

Microsoft Agent Framework (MAF) merges Semantic Kernel and AutoGen into a single, production-ready agent runtime built on Microsoft.Extensions.AI. This post walks through five progressive samples — creating your first agent, adding tools, composing agents, multi-turn conversations, and persistent memory — all running as single-file C# scripts with dotnet run.

Source code: https://github.com/NikiforovAll/maf-getting-started

Introduction — What is MAF?

.NET had two AI agent frameworks from Microsoft: Semantic Kernel for enterprise orchestration and AutoGen for multi-agent research. Two ecosystems, overlapping goals, confusion about which to pick. MAF unifies them into one framework.

Before	After
Semantic Kernel — enterprise AI orchestration	Built on Microsoft.Extensions.AI abstractions
AutoGen — multi-agent research framework	Microsoft.Agents.AI — unified agent runtime
Two ecosystems, overlapping goals	Single API for single & multi-agent scenarios

1️⃣ The architecture is layered:

Layer	Components
Your Application	AIAgent, Tools, Sessions, Workflows
Microsoft.Agents.AI	Unified agent runtime
Microsoft.Extensions.AI	`IChatClient`, `AIFunction`
Providers	Azure OpenAI, OpenAI, Ollama, ...

2️⃣ The core concepts:

Concept	Type	Purpose
AIAgent	`IAIAgent`	Core agent abstraction
Tools	`AIFunction`	Functions the agent can call
Session	`AgentSession`	Conversation state & history
Run	`RunAsync` / `RunStreamingAsync`	Execute agent with input
Workflow	`WorkflowBuilder`	Multi-agent orchestration

Your first agent

All samples use .NET 10’s run-file feature — single .cs files with #:package directives, no .csproj needed:

export AZURE_OPENAI_ENDPOINT="https://your-resource.cognitiveservices.azure.com/"
export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"

dotnet run src/01-hello-agent.cs

Here’s the full agent — 38 lines from zero to running:

#:package Microsoft.Agents.AI.OpenAI@1.0.0-rc2
#:package Azure.AI.OpenAI@2.8.0-beta.1
#:package Azure.Identity@1.18.0

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI.Chat;

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME");

AIAgent agent = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(
        new ChatClientAgentOptions
        {
            Name = "HelloAgent",
            ChatOptions = new ChatOptions
            {
                Instructions = "You are a friendly assistant. Keep your answers brief.",
                Temperature = 0.9f,
            },
        }
    );

// Non-streaming
Console.WriteLine(await agent.RunAsync("Tell me a one-sentence fun fact."));

// Streaming — process tokens as they arrive
await foreach (var update in agent.RunStreamingAsync("Tell me a one-sentence fun fact."))
{
    Console.WriteLine(update);
}

The pipeline is straightforward:

Step	Call	Role
1	`new AzureOpenAIClient(...)`	Azure OpenAI provider
2	`.GetChatClient("gpt-4o-mini")`	`ChatClient` via `IChatClient`
3	`.AsAIAgent(options)`	`AIAgent` from MAF
4	`.RunAsync("prompt")`	Execute and get response

AsAIAgent() is the key extension method. It turns any IChatClient into a full agent. Because it’s built on IChatClient, you can swap the provider (Azure OpenAI, OpenAI, Ollama) without touching agent code.

Tools — Giving agents the ability to act

Function tools

Define a plain C# method with [Description] attributes and register it via AIFunctionFactory.Create():

[Description("Get the weather for a given location.")]
static string GetWeather(
    [Description("The location to get the weather for.")] string location) =>
    $"The weather in {location} is cloudy with a high of 15°C.";

AIAgent weatherAgent = client
    .GetChatClient(deploymentName)
    .AsAIAgent(
        instructions: "You are a helpful weather assistant.",
        name: "WeatherAgent",
        description: "An agent that answers weather questions.",
        tools: [AIFunctionFactory.Create(GetWeather)]
    );

Console.WriteLine(await weatherAgent.RunAsync("What is the weather like in Amsterdam?"));

How tool calling works:

User sends: “What’s the weather in Amsterdam?”
LLM decides to call GetWeather("Amsterdam")
MAF invokes the C# method automatically
Result is fed back to the LLM
LLM generates the final answer using the tool result

The [Description] attributes are sent to the LLM as the tool schema — write clear, specific descriptions because that’s all the model sees when deciding which tool to call.

sequenceDiagram participant U as User participant A as WeatherAgent participant T as GetWeather U->>A: "Weather in Amsterdam?" A->>T: GetWeather("Amsterdam") T-->>A: "cloudy, 15°C" A-->>U: final answer

Agent-as-tool

Any agent can become a tool for another agent via .AsAIFunction():

AIAgent orchestrator = client
    .GetChatClient(deploymentName)
    .AsAIAgent(
        instructions: "You are a helpful assistant. Use the weather agent when asked about weather.",
        tools: [weatherAgent.AsAIFunction()]
    );

Console.WriteLine(await orchestrator.RunAsync("What's the weather in Amsterdam and Paris?"));

The orchestrator delegates to WeatherAgent when it encounters weather questions. The weather agent, in turn, calls its own GetWeather tool for each location.

sequenceDiagram participant U as User participant O as Orchestrator participant W as WeatherAgent participant T as GetWeather U->>O: "Weather in Amsterdam and Paris?" O->>W: AsAIFunction() W->>T: GetWeather("Amsterdam") T-->>W: "cloudy, 15°C" W->>T: GetWeather("Paris") T-->>W: "cloudy, 15°C" W-->>O: combined result O-->>U: final answer

Each agent has its own LLM call — be mindful of latency and cost when nesting agents.

Multi-turn conversations

Without a session, each RunAsync call is stateless — the agent has no memory of prior turns. AgentSession holds the conversation thread:

AIAgent agent = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(
        instructions: """You are a friendly assistant. Keep your answers brief.
            And always remember the information the user shares with you
            during the conversation.
            """,
        name: "ConversationAgent"
    );

AgentSession session = await agent.CreateSessionAsync();

// Turn 1 — introduce context
Console.WriteLine(await agent.RunAsync("My name is Alice and I love hiking.", session));

// Turn 2 — agent remembers from session history
Console.WriteLine(await agent.RunAsync("What do you remember about me?", session));

// Turn 3 — agent uses accumulated context
Console.WriteLine(await agent.RunAsync("Suggest a hiking destination for me.", session));

Under the hood, the session accumulates the full conversation and sends it with each LLM call:

Turn	Input	ChatHistory contents
created	—	`[]` (empty)
1	"My name is Alice..."	`[system, user₁, assistant₁]`
2	"What do you remember?"	`[system, user₁, assistant₁, user₂, assistant₂]`
3	"Suggest a destination"	`[system, user₁, assistant₁, user₂, assistant₂, user₃, assistant₃]`

The default provider is InMemoryChatHistoryProvider — zero config, but lost on process restart.

Memory and persistence

In-memory and serialization

The default InMemoryChatHistoryProvider works for single-process scenarios. For persistence across restarts, MAF provides serialization:

AgentSession session = await agent.CreateSessionAsync();

await agent.RunAsync("My name is Alice", session);

// Serialize session to JSON
var serialized = await agent.SerializeSessionAsync(session);
Console.WriteLine($"Session serialized ({serialized.GetRawText().Length} bytes)");

// Store anywhere — database, file, Redis, blob storage

// Restore session from serialized data
var restoredSession = await agent.DeserializeSessionAsync(serialized);

// Agent remembers everything from the original session
await agent.RunAsync("Do you still remember my name?", restoredSession);
// → "Yes, your name is Alice!"

SerializeSessionAsync / DeserializeSessionAsync give you portable session state. Export to JSON, store it however you want, restore later.

Custom ChatHistoryProvider

For more control, implement ChatHistoryProvider directly. Here’s a simple file-backed provider:

sealed class FileChatHistoryProvider(string filePath) : ChatHistoryProvider
{
    protected override ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(
        InvokingContext context, CancellationToken cancellationToken = default)
    {
        if (!File.Exists(filePath))
            return new(Enumerable.Empty<ChatMessage>());

        var json = File.ReadAllText(filePath);
        var messages = JsonSerializer.Deserialize(json, ChatHistoryJsonContext.Default.ListChatMessage) ?? [];
        return new(messages.AsEnumerable());
    }

    protected override ValueTask StoreChatHistoryAsync(InvokedContext context, CancellationToken cancellationToken = default)
    {
        List<ChatMessage> existing = [];
        if (File.Exists(filePath))
        {
            var json = File.ReadAllText(filePath);
            existing = JsonSerializer.Deserialize(json, ChatHistoryJsonContext.Default.ListChatMessage) ?? [];
        }

        existing.AddRange(context.RequestMessages);
        existing.AddRange(context.ResponseMessages ?? []);

        File.WriteAllText(path: filePath, JsonSerializer.Serialize(existing, ChatHistoryJsonContext.Default.ListChatMessage));
        return default;
    }
}

Wire it up via ChatClientAgentOptions:

AIAgent agent = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(new ChatClientAgentOptions
    {
        Name = "PersistentAgent",
        ChatOptions = new ChatOptions
        {
            Instructions = "You are a friendly assistant. Keep your answers brief.",
        },
        ChatHistoryProvider = new FileChatHistoryProvider(filePath),
    });

This survives process restarts — create a new agent with the same file, and it picks up where it left off. The limitation: all sessions share the same file. Concurrent sessions will clobber each other’s history.

Session-aware ChatHistoryProvider

For per-session isolation, use ProviderSessionState<TState>. Each session gets its own file identified by a unique session ID:

sealed class FileChatHistoryProvider : ChatHistoryProvider
{
    private readonly string _directory;
    private readonly ProviderSessionState<SessionState> _sessionState;

    public FileChatHistoryProvider(string directory, string? existingSessionId = null)
    {
        _directory = directory;
        _sessionState = new ProviderSessionState<SessionState>(
            _ => new SessionState(existingSessionId ?? Guid.NewGuid().ToString("N")[..8]),
            nameof(FileChatHistoryProvider));
    }

    public string GetSessionId(AgentSession? session) =>
        _sessionState.GetOrInitializeState(session).SessionId;

    protected override ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(
        InvokingContext context, CancellationToken cancellationToken = default)
    {
        var state = _sessionState.GetOrInitializeState(context.Session);
        var path = Path.Combine(_directory, $"{state.SessionId}.json");
        // ... read from session-specific file
    }

    // ... StoreChatHistoryAsync implementation similar to before, but using session-specific file

    sealed class SessionState(string sessionId)
    {
        public string SessionId { get; } = sessionId;
    }
}

To restore a session after restart, extract the session ID and pass it to a new provider:

var sessionId = historyProvider.GetSessionId(session);
var restoredProvider = new FileChatHistoryProvider(historyDir, sessionId);

AIAgent agent2 = client.GetChatClient(deploymentName)
    .AsAIAgent(new ChatClientAgentOptions
    {
        ChatHistoryProvider = restoredProvider,
    });

AgentSession session2 = await agent2.CreateSessionAsync();
await agent2.RunAsync("Do you remember my name?", session2); // → "Alice"

Key takeaways

AsAIAgent() — one extension method turns any IChatClient into a full agent
[Description] + AIFunctionFactory.Create() — plain C# methods become LLM-callable tools
.AsAIFunction() — any agent can become a tool for another agent
AgentSession — pass to RunAsync to maintain multi-turn conversation history
ChatHistoryProvider — the extension point for production persistence

What’s next

Part 2 covers Workflows, MCP, and AG-UI — orchestrating multi-agent pipelines, exposing agents as MCP servers, and streaming to frontends via the AG-UI protocol.

N+1 Blog

scratch: Structured Scratchpads for Coding Agents

Why files: the context window is a real limit

The problem: temporary agent knowledge has nowhere to go

The solution: a scratchpad is just a folder

The demo: see what the agent gathered

Wiring it into Claude Code

Planning with scratchpads

Also works on pi

Summary

Reference

pi-otel: OpenTelemetry Tracing for the Pi Coding Agent

Why telemetry for a coding agent?

What it emits

Quickstart

What you see in Aspire

Any OTLP backend

Grafana LGTM

Other backends

Configuration reference

Content capture

Extensibility — logs from your own pi package

The diagnostic bridge

Getting started

Summary

References

pi-kanban: A Workspace for the Pi Coding Agent

Why agent observability matters

What it looks like

Feature coverage

Sessions and projects

Pinning sessions

Pinning messages and linking documents

Subagents

Session info

Storage manager

Follow last message

Themes

Slash commands

Getting started

Conclusion

References

Hangfire as an MCP Operations Pane for AI Agents

TL;DR

1. Why an Operations Pane

Aspire bonus 🎁

2. Getting started

2.1 How a job gets discovered

2.2 Decorating jobs with [Description]

3. Demo: MCP Inspector

4. Authentication and authorization

Authentication

Per-job authorization

Summary

Reference

User-Managed Access (UMA) 2.0 Resource Sharing with Keycloak and .NET

TL;DR

What is UMA?

Key concepts

Demo

alice (resource owner), instant access

bob requests access, alice approves

bob (no permission), access denied

How the UMA flow works

Challenge-response (instant access)

Async approval (request, approve, access)

Architecture

Resource server

Client app (Blazor Server)

Keycloak setup

Summary

References

Claude Code Hub: Kanban, Marketplace, Cost, and Memory in One Place

Too many tabs

What’s inside

Kanban

Marketplace

Cost

Memory

How it actually works

2.2 Decorating jobs with `[Description]`