Skip to content

Commit de0b0fb

Browse files
KSemenenkoKSemenenko
authored
Merge pull request #85 from managedcode/more-fixes
More fixes
2 parents 174e5d6 + 6b4ac2a commit de0b0fb

File tree

262 files changed

+46259
-1167
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

262 files changed

+46259
-1167
lines changed

‎.codex/skills/dotnet-microsoft-agent-framework/SKILL.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
name: dotnet-microsoft-agent-framework
3+
version: "1.4.0"
4+
category: "AI"
5+
description: "Build .NET AI agents and multi-agent workflows with Microsoft Agent Framework using the right agent type, threads, tools, workflows, hosting protocols, and enterprise guardrails."
6+
compatibility: "Requires preview-era Microsoft Agent Framework packages and a .NET application that truly needs agentic or workflow orchestration."
7+
---
8+
9+
# Microsoft Agent Framework
10+
11+
## Trigger On
12+
13+
- building or reviewing `.NET` code that uses `Microsoft.Agents.*`, `Microsoft.Extensions.AI`, `AIAgent`, `AgentThread`, or Agent Framework hosting packages
14+
- choosing between `ChatClientAgent`, Responses agents, hosted agents, custom agents, workflows, or durable agents
15+
- adding tools, MCP, A2A, OpenAI-compatible hosting, AG-UI, DevUI, background responses, or OpenTelemetry
16+
- migrating from Semantic Kernel agent APIs or aligning AutoGen-style multi-agent patterns to Agent Framework
17+
18+
## Workflow
19+
20+
1. Decide whether the problem should stay deterministic. If plain code or a typed workflow without LLM autonomy is enough, do that instead of adding an agent.
21+
2. Choose the execution shape first: single `AIAgent`, explicit `Workflow`, Azure Functions durable agent, ASP.NET Core hosted agent, AG-UI remote UI, or DevUI local debugging.
22+
3. Choose the agent type and provider intentionally. Prefer the simplest agent that satisfies the threading, tooling, and hosting requirements.
23+
4. Keep agents stateless and keep conversation or long-lived state in `AgentThread`. Treat serialized threads as opaque provider-specific state.
24+
5. Add only the tools and middleware that the scenario needs. Narrow the tool surface, require approval for side effects, and treat MCP, A2A, and third-party services as trust boundaries.
25+
6. For workflows, model executors, edges, request-response ports, checkpoints, shared state, and human-in-the-loop explicitly rather than hiding control flow in prompts.
26+
7. Prefer Responses-based protocols for new remote/OpenAI-compatible integrations unless you specifically need Chat Completions compatibility.
27+
8. Use durable agents only when you truly need Azure Functions serverless hosting, durable thread storage, or deterministic long-running orchestrations.
28+
9. Verify preview status, package maturity, docs recency, and provider-specific limitations before locking a production architecture.
29+
30+
## Architecture
31+
32+
```mermaid
33+
flowchart LR
34+
A["Task"] --> B{"Deterministic code is enough?"}
35+
B -->|Yes| C["Write normal .NET code or a plain workflow"]
36+
B -->|No| D{"One dynamic decision-maker is enough?"}
37+
D -->|Yes| E["Use an `AIAgent` / `ChatClientAgent`"]
38+
D -->|No| F["Use a typed `Workflow`"]
39+
F --> G{"Needs durable Azure hosting or week-long execution?"}
40+
G -->|Yes| H["Use durable agents on Azure Functions"]
41+
G -->|No| I["Use in-process workflows"]
42+
E --> J{"Need a remote protocol or UI?"}
43+
F --> J
44+
J -->|OpenAI-compatible HTTP| K["ASP.NET Core Hosting.OpenAI"]
45+
J -->|Agent-to-agent protocol| L["A2A hosting"]
46+
J -->|Web UI protocol| M["AG-UI"]
47+
J -->|Local debug shell| N["DevUI (dev only)"]
48+
```
49+
50+
## Core Knowledge
51+
52+
- `AIAgent` is the common runtime abstraction. It should stay mostly stateless.
53+
- `AgentThread` holds conversation identity and long-lived interaction state. Treat serialized thread payloads as opaque provider-owned data.
54+
- `AgentResponse` and `AgentResponseUpdate` are not just text containers. They can include tool calls, tool results, structured output, reasoning-like updates, and response metadata.
55+
- `ChatClientAgent` is the safest default when you already have an `IChatClient` and do not need a hosted-agent service.
56+
- `Workflow` is an explicit graph of executors and edges. Use it when the control flow must stay inspectable, typed, resumable, or human-steerable.
57+
- Hosting layers such as OpenAI-compatible HTTP, A2A, and AG-UI are adapters over your in-process agent or workflow. They do not replace the core architecture choice.
58+
- Durable agents are a hosting and persistence decision for Azure Functions. They are not the default answer for ordinary app-level orchestration.
59+
60+
## Decision Cheatsheet
61+
62+
| If you need | Default choice | Why |
63+
|---|---|---|
64+
| One model-backed assistant with normal .NET composition | `ChatClientAgent` or `chatClient.AsAIAgent(...)` | Lowest friction, middleware-friendly, works with `IChatClient` |
65+
| OpenAI-style future-facing APIs, background responses, or richer response state | Responses-based agent | Better fit for new OpenAI-compatible integrations |
66+
| Simple client-managed chat history | Chat Completions agent | Keeps request/response simple |
67+
| Service-hosted agents and service-owned threads/tools | Azure AI Foundry Agent or other hosted agent | Managed runtime is the requirement |
68+
| Typed multi-step orchestration | `Workflow` | Control flow stays explicit and testable |
69+
| Week-long or failure-resilient Azure execution | Durable agent on Azure Functions | Durable Task gives replay and persisted state |
70+
| Agent-to-agent interoperability | A2A hosting or A2A proxy agent | This is protocol-level delegation, not local inference |
71+
| Browser or web UI protocol integration | AG-UI | Designed for remote UI sync and approval flows |
72+
73+
## Common Failure Modes
74+
75+
- Adding an agent where deterministic code or a plain typed workflow would be clearer and cheaper.
76+
- Assuming agent instance fields are the durable source of truth instead of storing real state in `AgentThread`, stores, or workflow state.
77+
- Picking Chat Completions when the scenario really needs Responses features such as background execution or service-backed response chains.
78+
- Treating hosted-agent services and local `IChatClient` agents as if they share the same thread and tool guarantees.
79+
- Hiding orchestration inside prompts instead of modeling executors, edges, requests, checkpoints, and HITL explicitly.
80+
- Exposing too many tools at once, especially side-effecting tools without approvals, middleware checks, or clear trust boundaries.
81+
- Treating DevUI as a production UI surface instead of a development and debugging tool.
82+
83+
## Deliver
84+
85+
- a justified architecture choice: agent vs workflow vs durable orchestration
86+
- the concrete .NET agent type, provider, and package set
87+
- an explicit thread, tool, middleware, and observability strategy
88+
- hosting and protocol decisions for OpenAI-compatible APIs, A2A, AG-UI, or Azure Functions
89+
- migration notes when replacing Semantic Kernel agent APIs or AutoGen-style orchestration
90+
91+
## Validate
92+
93+
- the scenario really needs agentic behavior and is not better served by deterministic code
94+
- the selected agent type matches the provider, thread model, and tool model
95+
- `AgentThread` lifecycle, serialization, and compatibility boundaries are explicit
96+
- tool approval, MCP headers, and third-party trust boundaries are handled safely
97+
- workflows define checkpoints, request-response, shared state, and HITL paths deliberately
98+
- DevUI is treated as a development sample, not a production surface
99+
- docs or packages marked preview are called out, and Python-only docs are not mistaken for guaranteed .NET APIs
100+
101+
When a decision depends on exact wording, long-tail feature coverage, or a less-common integration, check the local official docs snapshot before relying on summaries.
102+
103+
## References
104+
105+
- [official-docs-index.md](references/official-docs-index.md) - Slim local Microsoft Learn snapshot map with direct links to every mirrored page, live-only support pages, and API-reference pointers
106+
- [patterns.md](references/patterns.md) - Architecture routing, agent types, provider and thread model selection, and durable-agent guidance
107+
- [providers.md](references/providers.md) - Provider, SDK, endpoint, package, and Responses-vs-ChatCompletions selection
108+
- [tools.md](references/tools.md) - Function tools, hosted tools, tool approval, agent-as-tool, and service limitations
109+
- [sessions.md](references/sessions.md) - `AgentThread`, chat history storage, reducers, context providers, and thread serialization
110+
- [middleware.md](references/middleware.md) - Agent, function-calling, and `IChatClient` middleware with guardrail patterns
111+
- [workflows.md](references/workflows.md) - Executors, edges, requests and responses, checkpoints, orchestrations, and declarative workflow notes
112+
- [mcp.md](references/mcp.md) - MCP integration, agent-as-MCP, security rules, and MCP-vs-A2A guidance
113+
- [hosting.md](references/hosting.md) - ASP.NET Core hosting, OpenAI-compatible APIs, A2A, AG-UI, Azure Functions, and Purview integration
114+
- [devui.md](references/devui.md) - DevUI capabilities, modes, auth, tracing, and safe usage boundaries
115+
- [migration.md](references/migration.md) - Semantic Kernel and AutoGen migration notes, concept mapping, and breaking-model shifts
116+
- [support.md](references/support.md) - Preview status, official support channels, and recurring troubleshooting checks
117+
- [examples.md](references/examples.md) - Quick-start and tutorial recipe index covering the official docs set

‎.codex/skills/dotnet-microsoft-agent-framework/agents/agent-framework-router/AGENT.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
name: agent-framework-router
3+
description: Microsoft Agent Framework routing agent for agent-vs-workflow decisions, agent types, AgentThread state, tools, workflows, hosting protocols, durable agents, and migration from Semantic Kernel or AutoGen. Use when the repo is already clearly on Microsoft Agent Framework and the remaining ambiguity is inside framework-specific design choices.
4+
tools: Read, Edit, Glob, Grep, Bash
5+
model: inherit
6+
skills:
7+
- dotnet-microsoft-agent-framework
8+
- dotnet-microsoft-extensions-ai
9+
- dotnet-mcp
10+
- dotnet-azure-functions
11+
- dotnet-aspnet-core
12+
- dotnet-semantic-kernel
13+
---
14+
15+
# Microsoft Agent Framework Router
16+
17+
## Role
18+
19+
Act as a narrow Microsoft Agent Framework companion agent for repos that are already clearly on `Microsoft.Agents.*`. Triage the dominant framework concern first, then route into the right skill guidance without drifting back into broad generic `.NET` or generic AI routing.
20+
21+
This is a skill-scoped agent. It lives under `skills/dotnet-microsoft-agent-framework/` because it only makes sense next to framework-specific implementation guidance and the local docs snapshot for Agent Framework.
22+
23+
## Trigger On
24+
25+
- the repo already references `Microsoft.Agents.*`, `AIAgent`, `AgentThread`, `Microsoft.Agents.AI.Workflows`, or Agent Framework hosting packages
26+
- the task is primarily about agent-vs-workflow choice, provider selection, thread/state handling, tools, middleware, hosting, AG-UI, A2A, DevUI, or durable-agent execution
27+
- the ambiguity is inside Microsoft Agent Framework design choices rather than across unrelated `.NET` stacks
28+
29+
## Workflow
30+
31+
1. Confirm the repo is truly using Microsoft Agent Framework and identify the current runtime shape: local `IChatClient` agent, hosted agent service, explicit workflow, ASP.NET Core hosting, or Azure Functions durable hosting.
32+
2. Classify the dominant framework concern:
33+
- architecture choice: deterministic code vs agent vs workflow
34+
- provider and agent type selection
35+
- `AgentThread`, chat history, and state boundaries
36+
- tools, middleware, approvals, and MCP
37+
- workflows, checkpoints, request-response, and HITL
38+
- hosting, protocol adapters, and remote interoperability
39+
- migration from Semantic Kernel or AutoGen
40+
3. Route to `dotnet-microsoft-agent-framework` as the main implementation skill.
41+
4. Pull in adjacent skills only when the problem crosses a clear boundary:
42+
- `dotnet-microsoft-extensions-ai` for `IChatClient` composition and provider abstractions
43+
- `dotnet-mcp` for MCP client/server boundaries and tool exposure
44+
- `dotnet-azure-functions` for durable-agent hosting and Azure Functions runtime concerns
45+
- `dotnet-aspnet-core` for ASP.NET Core hosting integration and HTTP surface design
46+
- `dotnet-semantic-kernel` when the main task is migration, coexistence, or framework replacement
47+
5. End with the validation surface that matters for the chosen concern: thread persistence, tool approval safety, workflow checkpoints, hosting protocol behavior, or migration parity.
48+
49+
## Routing Map
50+
51+
| Signal | Route |
52+
|-------|-------|
53+
| `AIAgent` vs `Workflow`, agent count, orchestration shape | `dotnet-microsoft-agent-framework` |
54+
| `AgentThread`, chat history stores, serialized sessions, reducers, context providers | `dotnet-microsoft-agent-framework` |
55+
| Function tools, tool approvals, agent-as-tool, hosted tools | `dotnet-microsoft-agent-framework` |
56+
| MCP tools, MCP trust boundaries, exposing agents through MCP | `dotnet-microsoft-agent-framework` + `dotnet-mcp` |
57+
| `IChatClient`, provider abstraction, OpenAI vs Azure OpenAI vs local chat clients | `dotnet-microsoft-agent-framework` + `dotnet-microsoft-extensions-ai` |
58+
| Workflows, executors, edges, checkpoints, request-response, HITL | `dotnet-microsoft-agent-framework` |
59+
| ASP.NET Core hosting, OpenAI-compatible HTTP APIs, A2A, AG-UI | `dotnet-microsoft-agent-framework` + `dotnet-aspnet-core` |
60+
| Durable agents, Azure Functions orchestration, replay-safe design | `dotnet-microsoft-agent-framework` + `dotnet-azure-functions` |
61+
| Semantic Kernel migration or coexistence | `dotnet-microsoft-agent-framework` + `dotnet-semantic-kernel` |
62+
63+
## Deliver
64+
65+
- confirmed Microsoft Agent Framework runtime shape
66+
- dominant framework concern classification
67+
- primary skill path and any necessary adjacent skills
68+
- main risk area such as wrong agent type, weak thread model, hidden orchestration, unsafe tool surface, protocol mismatch, or migration drift
69+
- validation checklist aligned to the chosen path
70+
71+
## Boundaries
72+
73+
- Do not act as a broad AI router when the work is no longer Microsoft Agent Framework-centric.
74+
- Do not default to agents when deterministic code or a typed workflow is clearly the better fit.
75+
- Do not assume hosted agents, local `IChatClient` agents, and durable agents share the same thread, tool, or state guarantees.
76+
- Do not replace the detailed implementation guidance that belongs in `skills/dotnet-microsoft-agent-framework/SKILL.md`.

‎.codex/skills/dotnet-microsoft-agent-framework/references/devui.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# DevUI
2+
3+
## What DevUI Actually Is
4+
5+
DevUI is a sample app for development-time testing of agents and workflows.
6+
7+
It gives you:
8+
9+
- a local web UI
10+
- an OpenAI-compatible local API surface
11+
- trace viewing
12+
- directory discovery for sample entities
13+
- a quick way to exercise inputs without building your real frontend
14+
15+
It is not a production hosting surface.
16+
17+
## `.NET` Caveat
18+
19+
The current docs are explicit that `.NET` DevUI documentation is still limited and mostly "coming soon", while Python has the richer published guidance.
20+
21+
So for `.NET` work:
22+
23+
- treat DevUI docs as conceptual guidance
24+
- do not invent `.NET` APIs that the docs do not actually publish
25+
- do not anchor production architecture on DevUI behavior
26+
27+
## Good Uses
28+
29+
- smoke-testing prompts and tools locally
30+
- checking whether a workflow input shape is usable
31+
- tracing runs during early development
32+
- trying sample entities before you wire real hosting
33+
34+
## Bad Uses
35+
36+
- production chat surfaces
37+
- public internet endpoints
38+
- security boundaries
39+
- long-lived integration contracts
40+
41+
## DevUI Versus Real Hosting
42+
43+
| Need | Use DevUI? | Real Answer |
44+
| --- | --- | --- |
45+
| Local debugging | Yes | DevUI is good here |
46+
| Human-facing production UI | No | AG-UI or your own app |
47+
| OpenAI-compatible production endpoint | No | Hosting.OpenAI |
48+
| Agent-to-agent interoperability | No | A2A |
49+
| Secure public service boundary | No | ASP.NET Core hosting with your own auth and policies |
50+
51+
## Safe Usage Rules
52+
53+
- Keep it on localhost by default.
54+
- If you expose it to a network, add auth and still treat it as non-production.
55+
- Be careful with side-effecting tools even in local demos.
56+
- Do not mistake "it works in DevUI" for "the production contract is done".
57+
58+
## Source Pages
59+
60+
- `references/official-docs/user-guide/devui/index.md`
61+
- `references/official-docs/user-guide/devui/security.md`
62+
- `references/official-docs/user-guide/devui/tracing.md`
63+
- `references/official-docs/user-guide/devui/directory-discovery.md`

0 commit comments

Comments
 (0)