AIStoreHub Package Vault: Ag Ui
Package Slug: ag-ui
Archetype: agent
Upstream Repository: https://github.com/ag-ui-protocol/ag-ui
Workspace Files & Specifications (69 files)
- .claude-plugin/marketplace.json (768 bytes)
{ "$schema": "https://json.schemastore.org/claude-code-marketplace.json", "name": "ag-ui", "owner": { "name": "AG-UI" }, "description": "Plugins for working with the AG-UI protocol SDKs.", "version": "0.1.0", "metadata": { "description": "Plugins for working with the AG-UI protocol SDKs.", "version": "0.1.0" }, "plugins": [ { "name": "ag-ui-dotnet", "source": "./sdks/dotnet/plugins/ag-ui-dotnet", "description": "Skills for building apps with the AG-UI .NET SDK: streaming chat (stateless vs hosted agents), server tools, client tools, human-in-the-loop (approvals & interrupts), shared state, multimodal messages, reasoning traces, protobuf transport, and troubleshooting.", "version": "0.1.0" } ] } - .claude/settings.json (307 bytes)
{ "permissions": { "allow": [ "Bash(npx nx show projects)", "Bash(pnpm nx run dojo:check-types)", "Bash(pnpm nx show projects)", "Bash(pnpm nx run demo-viewer:check-types)", "Bash(pnpm nx show project demo-viewer)", "Bash(pnpm nx run demo-viewer:lint)" ] } } - AGENTS.md (1386 bytes)
<!-- nx configuration start--> <!-- Leave the start & end comments to automatically receive updates. --> # General Guidelines for working with Nx - For requests to add A2UI rendering to AG-UI applications or to scaffold an AG-UI + A2UI quickstart, use `skills/ag-ui-a2ui-integration/SKILL.md`. - When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through `nx` (i.e. `nx run`, `nx run-many`, `nx affected`) instead of using the underlying tooling directly - You have access to the Nx MCP server and its tools, use them to help the user - When answering questions about the repository, use the `nx_workspace` tool first to gain an understanding of the workspace architecture where applicable. - When working in individual projects, use the `nx_project_details` mcp tool to analyze and understand the specific project structure and dependencies - For questions around nx configuration, best practices or if you're unsure, use the `nx_docs` tool to get relevant, up-to-date docs. Always use this instead of assuming things about nx configuration - If the user needs help with an Nx configuration or project graph error, use the `nx_workspace` tool to get any errors - For Nx plugin best practices, check `node_modules/@nx/<plugin>/PLUGIN.md`. Not all plugins have this file - proceed without it if unavailable. <!-- nx configuration end-->
- aistorehub.json (451 bytes)
{ "name": "Ag Ui", "slug": "ag-ui", "version": "1.0.0", "type": "agent", "description": "AG-UI: the Agent-User Interaction Protocol. Bring Agents into Frontend Applications.", "owner": "community", "repository": "catalog", "github_repo_url": "https://github.com/ag-ui-protocol/ag-ui", "tags": [ "trending", "typescript", "ag-ui-protocol", "github", "open-source" ], "imported_at": "2026-11-21T23:56:32.281Z" } - apps/dojo/src/mastra/agents/a2ui-fixed.ts (5554 bytes)
import { Agent } from "@mastra/core/agent"; import { createTool } from "@mastra/core/tools"; import { z } from "zod"; /** * Fixed-schema A2UI agent for Mastra (the direct-tool A2UI mode — the sibling of * the generate_a2ui/subagent path). The component layout is authored in code * (FLIGHT_SCHEMA / HOTEL_SCHEMA); the model only supplies the DATA. Each backend * tool returns a complete `a2ui_operations` envelope which the * `@ag-ui/a2ui-middleware` detects in the tool result and paints — no subagent, * no recovery, no auto-injection. Mirrors the LangGraph/Strands fixed-schema * demos; renders against the dojo fixedSchemaCatalog (fixed_catalog.json: * Row / FlightCard / HotelCard / StarRating). * * Return shape: the tool returns the envelope as an OBJECT (not a JSON string) so * the Mastra bridge single-encodes it onto the wire and the middleware intercepts * it (a bare string would be double-encoded and slip through as a plain result). */ const FIXED_CATALOG_ID = "https://a2ui.org/demos/dojo/fixed_catalog.json"; const A2UI_OPERATIONS_KEY = "a2ui_operations"; const FLIGHT_SURFACE_ID = "flight-search-results"; const FLIGHT_SCHEMA: Array<Record<string, unknown>> = [ { id: "root", component: "Row", children: { componentId: "flight-card", path: "/flights" }, gap: 16, }, { id: "flight-card", component: "FlightCard", airline: { path: "airline" }, airlineLogo: { path: "airlineLogo" }, flightNumber: { path: "flightNumber" }, origin: { path: "origin" }, destination: { path: "destination" }, date: { path: "date" }, departureTime: { path: "departureTime" }, arrivalTime: { path: "arrivalTime" }, duration: { path: "duration" }, status: { path: "status" }, price: { path: "price" }, action: { event: { name: "book_flight", context: { flightNumber: { path: "flightNumber" }, origin: { path: "origin" }, destination: { path: "destination" }, price: { path: "price" }, }, }, }, }, ]; const HOTEL_SURFACE_ID = "hotel-search-results"; const HOTEL_SCHEMA: Array<Record<string, unknown>> = [ { id: "root", component: "Row", children: { componentId: "hotel-card", path: "/hotels" }, gap: 16, }, { id: "hotel-card", component: "HotelCard", name: { path: "name" }, location: { path: "location" }, rating: { path: "rating" }, pricePerNight: { path: "price" }, action: { event: { name: "book_hotel", context: { hotelName: { path: "name" }, price: { path: "price" }, }, }, }, }, ]; function renderOperations( surfaceId: string, schema: Array<Record<string, unknown>>, data: Record<string, unknown>, ): { a2ui_operations: Array<Record<string, unknown>> } { return { [A2UI_OPERATIONS_KEY]: [ { version: "v0.9", createSurface: { surfaceId, catalogId: FIXED_CATALOG_ID }, }, { version: "v0.9", updateComponents: { surfaceId, components: schema } }, { version: "v0.9", updateDataModel: { surfaceId, path: "/", value: data }, }, ], }; } const searchFlightsTool = createTool({ id: "search_flights", description: "Search for flights and display the results as rich cards. Each flight must " + "have: id, airline (e.g. 'United Airlines'), airlineLogo (Google favicon API " + "like 'https://www.google.com/s2/favicons?domain=united.com&sz=128'), " + "flightNumber, origin, destination, date (e.g. 'Tue, Mar 18'), departureTime, " + "arrivalTime, duration (e.g. '4h 25m'), status ('On Time' or 'Delayed'), and " + "price (e.g. '$289'). Generate 3-5 realistic results.", inputSchema: z.object({ flights: z .array(z.record(z.string(), z.unknown())) .describe("Array of flight result objects."), }), execute: async ({ flights }) => renderOperations(FLIGHT_SURFACE_ID, FLIGHT_SCHEMA, { flights }), }); const searchHotelsTool = createTool({ id: "search_hotels", description: "Search for hotels and display the results as rich cards with star ratings. " + "Each hotel must have: id, name (e.g. 'The Plaza'), location " + "(e.g. 'Midtown Manhattan, NYC'), rating (float 0-5, e.g. 4.5), and price " + "(per night, e.g. '$350'). Generate 3-4 realistic results.", inputSchema: z.object({ hotels: z .array(z.record(z.string(), z.unknown())) .describe("Array of hotel result objects."), }), execute: async ({ hotels }) => renderOperations(HOTEL_SURFACE_ID, HOTEL_SCHEMA, { hotels }), }); export const a2uiFixedSchemaAgent = new Agent({ id: "a2ui_fixed_schema", name: "a2ui_fixed_schema", instructions: `You are a helpful travel assistant that can search for flights and hotels. When the user asks about flights, use the search_flights tool. When the user asks about hotels, use the search_hotels tool. IMPORTANT: After calling a tool, do NOT repeat or summarize the data in your text response. The tool renders a rich UI automatically. Just say something brief like "Here are your results". For flights, each needs: id, airline, airlineLogo (Google favicon API), flightNumber, origin, destination, date, departureTime, arrivalTime, duration, status, and price. For hotels, each needs: id, name, location, rating (float 0-5), and price (per night). Generate 3-5 realistic results.`, model: "openai/gpt-4.1", tools: { search_flights: searchFlightsTool, search_hotels: searchHotelsTool }, }); - apps/dojo/src/mastra/agents/a2ui.ts (4324 bytes)
import { Agent } from "@mastra/core/agent"; import type { A2UIAttemptRecord, A2UIInjectConfig } from "@ag-ui/mastra"; // Provider-string model, resolved by Mastra's model router (respects // OPENAI_BASE_URL, so it targets aimock in e2e and a real key in dev). Matches // the other dojo Mastra agents; the render subagent inside the auto-injected // generate_a2ui tool resolves it the same way, so the package never couples to // an @ai-sdk provider version. const A2UI_MODEL = "openai/gpt-4.1"; /** * Mastra A2UI demo agents (dynamic-schema + error-recovery). * * These are PLAIN Mastra agents — they wire NO A2UI tool. The `@ag-ui/mastra` * bridge AUTO-INJECTS the backend-owned `generate_a2ui` tool per run (pillar 1: * easy devex) when the runtime forwards `injectA2UITool` (the dojo copilotkit * route sets it for mastra-agent-local). Injection carries the shared toolkit * recovery loop (validate→retry) + the render_a2ui subagent, and — with the * progressive-streaming path — paints incrementally. Customization (model, * catalog id, composition guide, recovery cap) rides the `a2ui` config on the * MastraAgent wrapper (see src/agents.ts), NOT hand-wired tools. This mirrors * the LangGraph / Strands ports. * * The dynamic demo is the happy path; the recovery demo is a byte-identical * agent whose demo prompts (frontend feature page + aimock fixtures) force a * structurally-invalid first render so the recovery loop is visible. */ export const a2uiDynamicSchemaAgent = new Agent({ id: "a2ui_dynamic_schema", name: "a2ui_dynamic_schema", instructions: A2UI_INSTRUCTIONS(), model: A2UI_MODEL, }); export const a2uiRecoveryAgent = new Agent({ id: "a2ui_recovery", name: "a2ui_recovery", instructions: A2UI_INSTRUCTIONS(), model: A2UI_MODEL, }); function A2UI_INSTRUCTIONS(): string { return `You are a helpful assistant that creates rich visual UI on the fly. When the user asks for visual content (hotel/product comparisons, team rosters, lists, cards, etc.), use the generate_a2ui tool to create a dynamic A2UI surface. IMPORTANT: After calling the tool, do NOT repeat the data in your text response. The tool renders UI automatically. Just confirm what was rendered.`; } // The dojo dynamic-A2UI catalog (HotelCard / ProductCard / TeamMemberCard / // Row). The subagent never picks the catalog — the factory stamps this id onto // every surface it creates. Matches `A2UI_DOJO_CATALOG_ID` in src/agents.ts and // the LangGraph/Strands recovery demos so all frameworks render one catalog. const A2UI_DOJO_CATALOG_ID = "https://a2ui.org/demos/dojo/dynamic_catalog.json"; // Grounds the render subagent on the dojo catalog's components so a REAL LLM // (not just aimock) emits resolvable surfaces. Shared verbatim with the // LangGraph/Strands recovery demos. const COMPOSITION_GUIDE = ` ## Available Pre-made Components Use Row as the root with structural children to repeat a card per item. ### Row Layout container. Repeat a card template via structural children: {"id":"root","component":"Row","children":{"componentId":"card","path":"/items"}} ### HotelCard / ProductCard / TeamMemberCard Card components bound to per-item data (relative paths inside the template). ## RULES - Root is ALWAYS a Row with structural children: {"componentId":"<card-id>","path":"/items"} - ALWAYS include the referenced card component in the components array. - Inside templates, use RELATIVE paths (no leading slash): {"path":"name"} not {"path":"/name"} - Always provide data in the "data" argument as {"items":[...]} - Generate 3-4 realistic items with diverse data. `; /** * A2UI auto-inject config passed to the MastraAgent wrapper (src/agents.ts). The * dev customizes via these PROPS (not hand-wired tools): model the render * subagent runs, catalog id stamped on surfaces, composition guide, recovery cap. */ export const a2uiInjectConfig: A2UIInjectConfig = { model: A2UI_MODEL, defaultCatalogId: A2UI_DOJO_CATALOG_ID, guidelines: { compositionGuide: COMPOSITION_GUIDE }, recovery: { maxAttempts: 3 }, onA2UIAttempt: (rec: A2UIAttemptRecord) => { // Dev observability: each attempt (incl. rejected ones) is logged. console.log( `[a2ui recovery] attempt ${rec.attempt}: ${rec.ok ? "valid" : "invalid"}`, rec.errors, ); }, }; - apps/dojo/src/mastra/agents/agentic-chat.ts (1132 bytes)
import { Agent } from "@mastra/core/agent"; import { Memory } from "@mastra/memory"; import { z } from "zod"; import { weatherTool } from "../tools"; import { getStorage } from "../storage"; export const agenticChatAgent = new Agent({ id: 'agentic_chat', name: "agentic_chat", instructions: ` You are a helpful weather assistant that provides accurate weather information. Your primary function is to help users get weather details for specific locations. When responding: - Always ask for a location if none is provided - If the location name isn't in English, please translate it - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York") - Include relevant details like humidity, wind conditions, and precipitation - Keep responses concise but informative `, model: "openai/gpt-4.1-mini", tools: { get_weather: weatherTool }, memory: new Memory({ storage: getStorage(), options: { workingMemory: { enabled: true, schema: z.object({ firstName: z.string(), }), }, }, }), }); - apps/dojo/src/mastra/agents/backend-tool-rendering.ts (1043 bytes)
import { Agent } from "@mastra/core/agent"; import { Memory } from "@mastra/memory"; import { weatherTool } from "../tools"; import { getStorage } from "../storage"; export const backendToolRenderingAgent = new Agent({ id: 'backend_tool_rendering', name: "backend_tool_rendering", instructions: ` You are a helpful weather assistant that provides accurate weather information. Your primary function is to help users get weather details for specific locations. When responding: - Always ask for a location if none is provided - If the location name isn't in English, please translate it - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York") - Include relevant details like humidity, wind conditions, and precipitation - Keep responses concise but informative Use the weatherTool to fetch current weather data. `, model: "openai/gpt-4.1-mini", tools: { get_weather: weatherTool }, memory: new Memory({ storage: getStorage(), }), }); - apps/dojo/src/mastra/agents/background-agents.ts (2656 bytes)
import { Agent } from "@mastra/core/agent"; import { createTool } from "@mastra/core/tools"; import { Memory } from "@mastra/memory"; import { z } from "zod"; import { getStorage } from "../storage"; // A deliberately slow "research" tool. Flagged background-eligible so Mastra's // Background Task manager dispatches it out of the agentic loop; its lifecycle // surfaces on fullStream as background-task-* chunks, which the AG-UI Mastra // bridge maps to ACTIVITY_SNAPSHOT / ACTIVITY_DELTA events. const runDeepResearch = createTool({ id: "run_deep_research", description: "Run a long deep-research job on a topic. This runs in the background and " + "reports progress while the conversation continues. Use it whenever the " + "user asks to research, investigate, or dig into a topic.", inputSchema: z.object({ topic: z.string().describe("The topic to research"), }), outputSchema: z.object({ topic: z.string(), summary: z.string(), sources: z.number(), }), // Background-eligible. The agent config below forces it to actually run in // the background and waits long enough for it to finish within the stream. background: { enabled: true, waitTimeoutMs: 60_000 }, execute: async ({ topic }) => { // Simulate staged long-running work so progress heartbeats tick. for (let i = 0; i < 5; i++) { await new Promise((r) => setTimeout(r, 800)); } return { topic, summary: `Completed a deep-research pass on "${topic}": gathered findings, cross-checked sources, and synthesized a summary.`, sources: 7, }; }, }); export const backgroundAgentsAgent = new Agent({ id: "background_agents", name: "background_agents", instructions: ` You are a research assistant that dispatches long-running work as background tasks. When the user asks you to research, investigate, or look into a topic: - Call the \`run_deep_research\` tool with the topic. - The tool runs in the background and returns immediately with an acknowledgement; it does NOT block. Briefly tell the user you've kicked off the research in the background and that they'll get the findings shortly. Do not invent findings — the work is still running. Keep your text responses short. The heavy lifting happens in the background task. `, model: "openai/gpt-4.1-mini", tools: { run_deep_research: runDeepResearch }, memory: new Memory({ storage: getStorage() }), // Force every background-eligible tool to actually run in the background // (don't leave it to the model's per-call choice) so the demo is reliable. backgroundTasks: { tools: "all" }, }); - apps/dojo/src/mastra/agents/generative-ui.ts (1061 bytes)
import { Agent } from "@mastra/core/agent"; import type { RequestContext } from "@mastra/core/request-context"; type ContextEntry = { description?: string; value?: string }; /** * The run's AG-UI context entries as instructions. The AG-UI bridge puts * RunAgentInput.context on the request context under "ag-ui"; for these demos * it carries CopilotKit's generative UI guide and component schema. */ function contextInstructions(requestContext: RequestContext): string { const entry = requestContext.get("ag-ui") as | { context?: ContextEntry[] } | undefined; const entries = (entry?.context ?? []) .filter((item) => item.value) .map((item) => `${item.description}:\n${item.value}`); return entries.length ? `\n\n## Context from the application\n\n${entries.join("\n\n")}` : ""; } export const generativeUIAgent = new Agent({ id: "generative_ui", name: "generative_ui", instructions: ({ requestContext }) => "You are a helpful assistant." + contextInstructions(requestContext), model: "openai/gpt-4.1-mini", }); - apps/dojo/src/mastra/agents/human-in-the-loop.ts (1238 bytes)
import { Agent } from "@mastra/core/agent"; import { Memory } from "@mastra/memory"; import { getStorage } from "../storage"; export const humanInTheLoopAgent = new Agent({ id: 'human_in_the_loop', name: "human_in_the_loop", instructions: ` You are a helpful task planning assistant that helps users break down tasks into actionable steps. When planning tasks use tools only, without any other messages. IMPORTANT: - Use the \`generate_task_steps\` tool to display the suggested steps to the user - Do not call the \`generate_task_steps\` twice in a row, ever. - Never repeat the plan, or send a message detailing steps - If accepted, confirm the creation of the plan and the number of selected (enabled) steps only - If not accepted, ask the user for more information, DO NOT use the \`generate_task_steps\` tool again When responding to user requests: - Always break down the task into clear, actionable steps - Use imperative form for each step (e.g., "Book flight", "Pack luggage", "Check passport") - Keep steps concise but descriptive - Make sure steps are in logical order `, model: "openai/gpt-4.1-mini", memory: new Memory({ storage: getStorage(), }), }); - apps/dojo/src/mastra/agents/interrupt.ts (1842 bytes)
import { Agent } from "@mastra/core/agent"; import { Memory } from "@mastra/memory"; import { scheduleMeetingTool } from "../tools"; import { getStorage } from "../storage"; // Demonstrates Mastra's native suspend/resume HITL bridged onto AG-UI's // interrupt flow. The agent calls `schedule_meeting`, which suspends; the // @ag-ui/mastra adapter ends the run with an interrupt outcome; CopilotKit's v2 // `useInterrupt` hook renders a time picker and resumes the tool. Resume works // for both LOCAL and REMOTE Mastra agents (the remote path round-trips the // resume over @mastra/client-js' resumeStream, OSS-380), so this is wired for // both `mastra-agent-local` and the remote `mastra` integration. export const interruptAgent = new Agent({ id: "interrupt", name: "interrupt", instructions: `You are a scheduling assistant. Whenever the user asks you to book a call or schedule a meeting, you MUST call the \`schedule_meeting\` tool. Pass a short \`topic\` describing the purpose and, if known, an \`attendee\` describing who the meeting is with. The \`schedule_meeting\` tool pauses execution and shows the user a time picker. After it resumes with the user's choice, briefly confirm whether the meeting was scheduled and at what time, or note that the user cancelled. Do not ask for approval yourself — always call the tool and let the picker handle the decision. Keep responses short and friendly.`, model: "openai/gpt-4.1-mini", // Cast: a tool with concrete suspend/resume schemas is not structurally // assignable to Mastra's `ToolAction<..., unknown, unknown, ...>` tools map // (generic variance). Runtime behavior is unaffected. tools: { schedule_meeting: scheduleMeetingTool, } as unknown as ConstructorParameters<typeof Agent>[0]["tools"], memory: new Memory({ storage: getStorage(), }), }); - apps/dojo/src/mastra/agents/observational-memory.ts (2954 bytes)
import { Agent } from "@mastra/core/agent"; import { Memory } from "@mastra/memory"; import { getStorage } from "../storage"; // An agent with Mastra Observational Memory (OM) enabled. OM is the developer's // own opt-in: the Observer/Reflector agents run out of band, read the growing // conversation, compress it into observations, and activate those into the // context window. Mastra streams that background work on `fullStream` as // `data-om-*` chunks; the AG-UI Mastra bridge maps them to ACTIVITY_SNAPSHOT / // ACTIVITY_DELTA events (activityType "mastra-observational-memory") when the // bridge's `observationalMemory` toggle is on (see src/agents.ts). // // The thresholds below are deliberately LOW so the demo triggers observation / // buffering / activation within a few short turns instead of needing tens of // thousands of tokens. A production agent would use much larger windows. export const observationalMemoryAgent = new Agent({ id: "observational_memory", name: "observational_memory", instructions: ` You are a friendly assistant with long-term observational memory. Just chat naturally with the user. As the conversation grows, your memory system observes it in the background and compresses older turns into durable observations — you do not need to do anything special for that to happen. Keep your replies short and conversational. `, model: "openai/gpt-4.1-mini", memory: new Memory({ storage: getStorage(), options: { observationalMemory: { // Use the same provider as the main model so a single key drives the // whole demo. OM's default is google/gemini-2.5-flash. model: "openai/gpt-4.1-mini", scope: "thread", observation: { // Low threshold so the Observer fires within a turn or two. The // trigger is UNOBSERVED message tokens (user + assistant), so what // reliably crosses it is message SIZE, not the number of turns — a // sizable user message pushes past `messageTokens` regardless of how // terse the model's replies are. // Async buffering: the Observer runs in the background and emits // data-om-buffering-* chunks ON the run stream (verified against // @mastra/memory 1.21.2 — the synchronous path does NOT surface on // the stream in this version). These values are the smallest that // reliably trigger buffering in practice; going much lower silently // no-ops (the tokenizer batches below a floor). The trigger is // UNOBSERVED message tokens (user + assistant), so the demo/e2e drive // a few sizable messages to cross `messageTokens` deterministically // regardless of how terse the model's replies are. messageTokens: 600, bufferTokens: 300, }, reflection: { observationTokens: 1_500, }, }, }, }), }); - apps/dojo/src/mastra/agents/shared-state.ts (3637 bytes)
import { Agent } from "@mastra/core/agent"; import { Memory } from "@mastra/memory"; import { z } from "zod"; import { getStorage } from "../storage"; export const sharedStateAgent = new Agent({ id: "shared_state", name: "shared_state", instructions: ` You are a helpful assistant for creating recipes. The recipe in working memory is the user's CURRENT state — they edit it directly in the UI. Treat it as the source of truth, even when an earlier message said otherwise. IMPORTANT: 1. Create a recipe using the existing ingredients and instructions. Make sure the recipe is complete. 2. For ingredients, append new ingredients to the existing ones. 3. For instructions, append new steps to the existing ones. 4. 'ingredients' is always an array of objects with 'icon', 'name', and 'amount' fields 5. 'instructions' is always an array of strings 6. 'special_preferences', 'skill_level' and 'cooking_time' are chosen by the USER, not you. NEVER add, remove, or change them — leave them exactly as they are in working memory. In particular, do NOT re-add a preference the user removed, and do NOT add "Spicy" (or any preference) on your own. 7. Instead, make 'ingredients' and 'instructions' MATCH the user's 'special_preferences': if "Vegan" is set, use vegan ingredients; if "Spicy" is set, add heat; and if a preference is NOT set, make sure the recipe does not reflect it (e.g. if "Spicy" is absent, use no chili/heat). If you have just created or modified the recipe, just answer in one sentence what you did. Do not describe the recipe, just say what you did. Do not mention "working memory", "memory", or "state" in your answer. `, model: "openai/gpt-4.1-mini", memory: new Memory({ storage: getStorage(), options: { workingMemory: { enabled: true, schema: z.object({ recipe: z.object({ skill_level: z .enum(["Beginner", "Intermediate", "Advanced"]) .describe("The skill level required for the recipe"), special_preferences: z .array( z.enum([ "High Protein", "Low Carb", "Spicy", "Budget-Friendly", "One-Pot Meal", "Vegetarian", "Vegan", ]), ) .describe("A list of special preferences for the recipe"), cooking_time: z .enum(["5 min", "15 min", "30 min", "45 min", "60+ min"]) .describe("The cooking time of the recipe"), ingredients: z .array( z.object({ icon: z .string() .describe( "The icon emoji (not emoji code like '\\x1f35e', but the actual emoji like 🥕) of the ingredient", ), name: z.string().describe("The name of the ingredient"), amount: z.string().describe("The amount of the ingredient"), }), ) .describe( "Entire list of ingredients for the recipe, including the new ingredients and the ones that are already in the recipe", ), instructions: z .array(z.string()) .describe( "Entire list of instructions for the recipe, including the new instructions and the ones that are already there", ), }), }), }, }, }), }); - apps/dojo/src/mastra/agents/tool-approval.ts (1099 bytes)
import { Agent } from "@mastra/core/agent"; import { Memory } from "@mastra/memory"; import { recordExpenseTool } from "../tools"; import { getStorage } from "../storage"; // Mastra's native tool approval bridged onto AG-UI interrupts. `record_expense` // sets `requireApproval: true`, so Mastra pauses the call and keeps it pending // in storage until the user approves or rejects it in the chat. export const toolApprovalAgent = new Agent({ id: "tool_approval", name: "tool_approval", instructions: `You are an expense assistant. Whenever the user asks you to record, log, or file an expense, you MUST call the \`record_expense\` tool with the \`amount\` in US dollars and a short \`description\`. The tool asks the user to approve the call before it runs. Do not ask for confirmation yourself. After the tool returns, confirm the recorded expense id in one short sentence, or, if the call was not approved, say that the expense was not recorded.`, model: "openai/gpt-4.1-mini", tools: { record_expense: recordExpenseTool }, memory: new Memory({ storage: getStorage(), }), }); - apps/dojo/src/mastra/agents/tool-based-generative-ui.ts (1004 bytes)
import { Agent } from "@mastra/core/agent"; import { createTool } from "@mastra/core/tools"; import { z } from "zod"; export const toolBasedGenerativeUIAgent = new Agent({ id: 'tool_based_generative_ui', name: "tool_based_generative_ui", instructions: ` You are a helpful assistant for creating haikus. `, model: "openai/gpt-4.1-mini", tools: { generate_haiku: createTool({ id: "generate_haiku", description: "Generate a haiku in Japanese and its English translation. Also select exactly 3 relevant images from the provided list based on the haiku's theme.", inputSchema: z.object({ japanese: z .array(z.string()) .describe("An array of three lines of the haiku in Japanese"), english: z .array(z.string()) .describe("An array of three lines of the haiku in English"), }), outputSchema: z.string(), execute: async () => { return "Haiku generated."; }, }), }, }); - CLAUDE.md (4915 bytes)
# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. For requests to add A2UI rendering to AG-UI applications or to scaffold an AG-UI + A2UI quickstart, use `skills/ag-ui-a2ui-integration/SKILL.md`. ## Common Development Commands ### TypeScript SDK (Main Development) ```bash # Install dependencies (using pnpm) pnpm install # Build all packages pnpm build # Run development mode pnpm dev # Run linting pnpm lint # Run type checking pnpm check-types # Run tests pnpm test # Format code pnpm format # Clean build artifacts pnpm clean # Full clean build pnpm build:clean ``` ### Python SDK ```bash # Navigate to python-sdk directory cd python-sdk # Install dependencies (using poetry) poetry install # Run tests python -m unittest discover tests # Build distribution poetry build ``` ### Running Specific Integration Tests ```bash # For TypeScript packages/integrations cd packages/<package-name> pnpm test # For running a single test file cd packages/<package-name> pnpm test -- path/to/test.spec.ts ``` ## High-Level Architecture AG-UI is an event-based protocol that standardizes agent-user interactions. The codebase is organized as a monorepo with the following structure: ### Core Protocol Architecture - **Event-Driven Communication**: All agent-UI communication happens through typed events (BaseEvent and its subtypes) - **Transport Agnostic**: Protocol supports SSE, WebSockets, HTTP binary, and custom transports - **Observable Pattern**: Uses RxJS Observables for streaming agent responses ### Key Abstractions 1. **AbstractAgent**: Base class that all agents must implement with a `run(input: RunAgentInput) -> Observable<BaseEvent>` method 2. **HttpAgent**: Standard HTTP client supporting SSE and binary protocols for connecting to agent endpoints 3. **Event Types**: Lifecycle events (RUN_STARTED/FINISHED), message events (TEXT_MESSAGE_*), tool events (TOOL_CALL_*), and state management events (STATE_SNAPSHOT/DELTA) ### Repository Structure - `/sdks/typescript/`: Main TypeScript implementation - `/packages/`: Core protocol packages (@ag-ui/core, @ag-ui/client, @ag-ui/encoder, @ag-ui/proto) - `/integrations/`: Framework integrations (langgraph, mastra, crew-ai, etc.) - `/apps/`: Example applications including the AG-UI Dojo demo viewer - `/sdks/python/`: Python implementation of the protocol - `/docs/`: Documentation site content ### Integration Pattern Each framework integration follows a similar pattern: 1. Implements the AbstractAgent interface 2. Translates framework-specific events to AG-UI protocol events 3. Provides both TypeScript client and Python server implementations 4. Includes examples demonstrating key AG-UI features (agentic chat, generative UI, human-in-the-loop, etc.) ### State Management - Uses STATE_SNAPSHOT for complete state representations - Uses STATE_DELTA with JSON Patch (RFC 6902) for efficient incremental updates - MESSAGES_SNAPSHOT provides conversation history ### Multiple Sequential Runs - AG-UI supports multiple sequential runs in a single event stream - Each run must complete (RUN_FINISHED) before a new run can start (RUN_STARTED) - Messages accumulate across runs (e.g., messages from run1 + messages from run2) - State continues to evolve across runs unless explicitly reset with STATE_SNAPSHOT - Run-specific tracking (active messages, tool calls, steps) resets between runs ### Development Workflow - Nx is used for monorepo build orchestration - Each package has independent versioning - Integration tests demonstrate protocol compliance - The AG-UI Dojo app showcases all protocol features with live examples <!-- nx configuration start--> <!-- Leave the start & end comments to automatically receive updates. --> # General Guidelines for working with Nx - When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through `nx` (i.e. `nx run`, `nx run-many`, `nx affected`) instead of using the underlying tooling directly - You have access to the Nx MCP server and its tools, use them to help the user - When answering questions about the repository, use the `nx_workspace` tool first to gain an understanding of the workspace architecture where applicable. - When working in individual projects, use the `nx_project_details` mcp tool to analyze and understand the specific project structure and dependencies - For questions around nx configuration, best practices or if you're unsure, use the `nx_docs` tool to get relevant, up-to-date docs. Always use this instead of assuming things about nx configuration - If the user needs help with an Nx configuration or project graph error, use the `nx_workspace` tool to get any errors - For Nx plugin best practices, check `node_modules/@nx/<plugin>/PLUGIN.md`. Not all plugins have this file - proceed without it if unavailable. <!-- nx configuration end-->
- INSTRUCTIONS.md (6131 bytes)
--- name: ag-ui-a2ui-integration description: "Use when adding A2UI rendering to any AG-UI-supported framework or custom AG-UI application, scaffolding an AG-UI app that should render A2UI, adapting an AG-UI integration to emit A2UI surfaces, or wiring the AG-UI A2UI middleware/toolkit with a compatible renderer." version: 1.1.1 --- # AG-UI + A2UI Integration Skill ## Overview Use this skill to add A2UI rendering to an AG-UI application. Treat AG-UI as the transport and agent integration layer, `@ag-ui/a2ui-middleware` as the server-side bridge that detects and paints A2UI operations, and A2UI as the UI payload format that the client renderer displays. This is a developer-facing skill artifact. It is meant to be loaded by coding agents and used against a real app or repo, not published as a docs page. ## When to Use - Adding A2UI rendering to an existing AG-UI app. - Creating an AG-UI quickstart that should display A2UI surfaces. - Connecting any AG-UI-supported framework or custom AG-UI agent to an A2UI-capable frontend. - Adding or extending an A2UI component catalog. - Debugging why an A2UI surface does not render or why a user action does not flow back to the agent. ## When NOT to Use - For AG-UI protocol event semantics only, use the AG-UI protocol skill or protocol docs. - For A2UI renderer internals outside an AG-UI app, use the A2UI renderer docs or renderer-specific skills. - For generic CopilotKit frontend work without A2UI, use CopilotKit-specific setup and React skills. ## Workflow 1. Inspect the app shape: framework adapter, AG-UI agent endpoint, runtime host, frontend shell, and any existing A2UI renderer/catalog. 2. Decide the A2UI mode before editing code: - Fixed schema: backend tools return an `a2ui_operations` envelope with `createSurface`, `updateComponents`, and `updateDataModel`. - Dynamic schema: a framework A2UI tool (`generate_a2ui`) delegates to a sub-agent that streams `render_a2ui` args through `A2UIMiddleware`. 3. Select framework-specific wiring from `references/framework-adapters.md`, or use that reference to find the closest AG-UI integration pattern. Preserve the app's existing agent architecture. 4. Wire server middleware/runtime and client renderer using `references/a2ui-runtime-and-renderer.md`. Avoid double-applying `A2UIMiddleware`; use either runtime-level A2UI config or per-agent `agent.use(new A2UIMiddleware(...))` for a given agent. 5. Register a catalog on the client. With CopilotKit >= 1.61.2, forwarding it to the provider (`a2ui={{ catalog }}`) auto-enables A2UI and auto-derives `defaultCatalogId` from the catalog's id. Only when you are not forwarding a catalog, ensure the middleware or adapter sets a `defaultCatalogId` matching the renderer-registered catalog. 6. Verify the streaming path with `references/verification.md`: AG-UI stream, `a2ui-surface` activity snapshots or `a2ui_operations`, rendered A2UI surface, and a user interaction flowing back through AG-UI. ## AG-UI Framework Support This skill is not limited to the framework examples below. For any target framework, first check the AG-UI repository's `integrations/` directory, the AG-UI docs, the framework adapter's A2UI files, and the current CLI source. If AG-UI supports the framework, use that integration's documented package, endpoint helper, A2UI tool factory, or scaffold path. If there is no framework A2UI adapter, implement the custom AG-UI agent path, return `a2ui_operations` from backend tools for fixed layouts, and keep the middleware/client wiring the same. ## Common AG-UI CLI Flags Use the CLI flags that exist in `sdks/typescript/packages/cli/src/index.ts`. The table is a quick reference for known scaffold paths, not the full AG-UI support matrix. Do not invent flags. | Framework | CLI flag | | -------------------- | ---------------- | | ADK | `--adk` | | LangGraph Python | `--langgraph-py` | | LangGraph JavaScript | `--langgraph-js` | | CrewAI Flows | `--crewai-flows` | | Mastra | `--mastra` | | Pydantic AI | `--pydantic-ai` | | LlamaIndex | `--llamaindex` | | Agno | `--agno` | | AG2 | `--ag2` | Strands has AG-UI integration packages and examples, but no Strands CLI flag is present in the current AG-UI CLI source. Use the Strands integration docs instead of guessing a scaffold command. ## Key Rules - Keep the integration AG-UI-first for every supported framework. CopilotKit is a common runtime/renderer path for web apps, but AG-UI owns the middleware, framework adapters, and wire events. - Enable A2UI on both sides: `A2UIMiddleware` or runtime A2UI config on the server, and an A2UI-capable renderer/catalog on the client. - For dynamic schema, prefer the framework adapter's A2UI tool factory or auto-injection path. The model should call `generate_a2ui`; the sub-agent should stream `render_a2ui` args so the middleware can progressively paint. - For fixed schema, return an `a2ui_operations` envelope from backend tools rather than asking the model to invent component trees. - Emit `createSurface` once per `surfaceId`; use update operations for later changes. - Do not let the model invent catalog ids. When the client forwards a catalog to the provider (CopilotKit >= 1.61.2), its `catalogId` is derived automatically; otherwise the host/middleware/adapter should stamp a `defaultCatalogId` that matches the client-registered catalog. - Preserve AG-UI run boundaries and error events. Do not swallow server or stream errors. - Verify with a real browser or client run when possible. A static typecheck is not enough for streaming UI work. ## References - `references/framework-adapters.md` - framework-specific AG-UI adapter patterns. - `references/a2ui-runtime-and-renderer.md` - server/client A2UI wiring and catalog patterns. - `references/verification.md` - checks to confirm the integration works. - `sources.md` - source files and docs used by this skill. - integrations/adk-middleware/python/CLAUDE.md (7658 bytes)
# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Common Development Commands **Important**: Use `.venv/bin/pytest` to run tests with the project's virtual environment. ```bash # Install in editable mode for development pip install -e . # Install with dev dependencies pip install -e ".[dev]" # Run tests .venv/bin/pytest # Run tests with coverage .venv/bin/pytest --cov=src/ag_ui_adk # Run a specific test file .venv/bin/pytest tests/test_adk_agent.py # Run a specific test .venv/bin/pytest tests/test_adk_agent.py::test_function_name # Code formatting black src tests isort src tests # Linting flake8 src tests # Type checking mypy src ``` ### Running Examples ```bash cd examples uv sync uv run dev # Or directly with uvicorn uvicorn server:app --host 0.0.0.0 --port 8000 ``` Requires `GOOGLE_API_KEY` environment variable for Gemini models. ## High-Level Architecture This package (`ag_ui_adk`) is a middleware that bridges [Google ADK](https://google.github.io/adk-docs/) agents with the [AG-UI Protocol](https://github.com/ag-ui-protocol/ag-ui). It translates between the two frameworks' event systems. ### Core Components (in `src/ag_ui_adk/`) ``` AG-UI Protocol ADK Middleware Google ADK │ │ │ RunAgentInput ──────> ADKAgent.run() ──────> Runner.run_async() │ │ │ │ EventTranslator │ │ │ │ BaseEvent[] <──────── translate events <──────── Event[] ``` - **`adk_agent.py`** - Main orchestrator `ADKAgent` class that wraps ADK agents for AG-UI compatibility. Manages lifecycle, sessions, and tool coordination. - **`event_translator.py`** - Converts ADK events to AG-UI protocol events (16 standard event types). Handles streaming text, message boundaries, and per-session isolation. - **`session_manager.py`** - Singleton managing session lifecycle, cleanup with configurable timeouts, memory service integration, and resource limits. - **`execution_state.py`** - Tracks background ADK executions, manages asyncio tasks, event queues for streaming, and tool call state. - **`client_proxy_tool.py`** / **`client_proxy_toolset.py`** - Wraps AG-UI tools for ADK compatibility. All client tools are long-running (fire-and-forget for HITL workflows). - **`endpoint.py`** - FastAPI integration via `add_adk_fastapi_endpoint()` and `create_adk_app()`. - **`config.py`** - Configuration classes including `PredictStateMapping` for predictive state updates. ### Key Integration Pattern ```python from ag_ui_adk import ADKAgent, add_adk_fastapi_endpoint from google.adk.agents import Agent # 1. Create ADK agent my_agent = Agent(name="assistant", instruction="...") # 2. Wrap with middleware agent = ADKAgent(adk_agent=my_agent, app_name="my_app", user_id="user123") # 3. Use directly or add FastAPI endpoint async for event in agent.run(input_data): print(event.type) # Or with FastAPI app = FastAPI() add_adk_fastapi_endpoint(app, agent, path="/chat") ``` ### Tool Execution Flow All client-supplied tools are long-running, ideal for human-in-the-loop workflows: 1. Initial AG-UI Run → ADK Agent starts execution 2. ADK Agent requests tool use → Execution pauses 3. Tool events emitted (TOOL_CALL_START/ARGS/END) → Client receives tool call info 4. Client executes tools → Results prepared asynchronously 5. Subsequent AG-UI Run with ToolMessage → ADK execution resumes 6. Final response → Execution completes ### Environment Variables for Logging ```bash LOG_ROOT_LEVEL=INFO # Root logger level LOG_ADK_AGENT=DEBUG # adk_agent component LOG_EVENT_TRANSLATOR=INFO # event_translator component LOG_ENDPOINT=ERROR # endpoint component LOG_SESSION_MANAGER=WARNING # session_manager component ``` ## Testing The test suite has 670+ tests covering: - Unit tests for each component - Integration tests for end-to-end flows - HITL (human-in-the-loop) tool tracking - Multi-turn conversation handling - Session management and cleanup - Concurrent execution limits - Predictive state updates - Vertex AI session service (mock + optional live) Tests use pytest-asyncio for async test support. ### Running All Tests ```bash # Unit + mock-based integration tests (no credentials needed beyond GOOGLE_API_KEY) set -a && source .env && set +a .venv/bin/pytest tests/ # Run a specific test class .venv/bin/pytest tests/test_vertex_session_service.py::TestVertexSessionServiceMock -v ``` ### Vertex AI Session Service Live Tests The `TestVertexSessionServiceLive` class in `tests/test_vertex_session_service.py` runs against a real Vertex AI Agent Engine. These tests are **skipped by default** and only run when `VERTEX_REASONING_ENGINE_ID` is set. Mock-based tests (10 tests) always run and cover the same middleware code paths using a `MockVertexAiSessionService` that faithfully replicates Vertex behaviour (generates numeric IDs, rejects caller-provided `session_id`). #### Prerequisites - **GCP Project** with the Vertex AI API enabled - **Application Default Credentials** (ADC) with Vertex AI permissions - A **deployed ReasoningEngine** (Agent Engine) — the sessions API requires one #### 1. Enable the Vertex AI API (if not already) Via GCP Console: APIs & Services > Library > search "Vertex AI API" > Enable. Or via gcloud CLI: ```bash gcloud services enable aiplatform.googleapis.com --project=<PROJECT_ID> ``` #### 2. Deploy a Minimal ReasoningEngine The engine does not need agent code — it just needs to exist so the sessions endpoint is available. From the project `.venv`: ```python import vertexai client = vertexai.Client(project='<PROJECT_ID>', location='us-central1') result = client.agent_engines.create( config={ 'display_name': 'ag-ui-test-sessions', 'description': 'Minimal engine for AG-UI middleware session tests', } ) # Extract the engine ID from the resource name print(result.api_resource.name) # e.g. projects/123456/locations/us-central1/reasoningEngines/987654321 ``` Note the numeric ID at the end of the resource name. #### 3. Run the Live Tests ```bash GOOGLE_CLOUD_PROJECT=<PROJECT_ID> \ GOOGLE_CLOUD_LOCATION=us-central1 \ VERTEX_REASONING_ENGINE_ID=<ENGINE_ID> \ .venv/bin/pytest tests/test_vertex_session_service.py -v ``` The live test fixture automatically removes `GOOGLE_API_KEY` and overrides `GOOGLE_CLOUD_LOCATION` to `us-central1` via `monkeypatch`, since the Vertex sessions API requires OAuth2/ADC (not API keys) and a real region (not `global`). #### 4. Cleanup (Important — Avoid Ongoing Charges) ReasoningEngines incur hosting costs while deployed. Delete after testing: ```python import vertexai client = vertexai.Client(project='<PROJECT_ID>', location='us-central1') engine = client.agent_engines.get(agent_engine_id='<ENGINE_ID>') engine.delete() ``` Or via REST API (use `?force=true` to delete child sessions left by tests): ```bash curl -X DELETE \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/<PROJECT_ID>/locations/us-central1/reasoningEngines/<ENGINE_ID>?force=true" ``` Verify deletion: ```bash curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/<PROJECT_ID>/locations/us-central1/reasoningEngines" ``` An empty response (or `{}`) confirms no engines remain. - integrations/claude-agent-sdk/python/examples/agents/__init__.py (710 bytes)
""" Example agent configurations for AG-UI Claude SDK integration. Each agent module provides a factory function that creates a configured ClaudeAgentAdapter for different use cases. """ from .agentic_chat import create_agentic_chat_adapter from .backend_tool_rendering import create_backend_tool_adapter from .shared_state import create_shared_state_adapter from .human_in_the_loop import create_human_in_the_loop_adapter from .tool_based_generative_ui import create_tool_based_generative_ui_adapter __all__ = [ "create_agentic_chat_adapter", "create_backend_tool_adapter", "create_shared_state_adapter", "create_human_in_the_loop_adapter", "create_tool_based_generative_ui_adapter", ] - integrations/claude-agent-sdk/python/examples/agents/agentic_chat.py (734 bytes)
""" Agentic chat agent configuration. This module provides a factory function for creating an agentic chat adapter. The adapter supports all ClaudeAgentOptions from the Claude Agent SDK. """ from ag_ui_claude_sdk import ClaudeAgentAdapter from .constants import DEFAULT_DISALLOWED_TOOLS def create_agentic_chat_adapter() -> ClaudeAgentAdapter: """Create adapter for agentic chat.""" return ClaudeAgentAdapter( name="agentic_chat", description="General purpose agentic chat assistant", options={ "model": "claude-haiku-4-5", "system_prompt": "You are a helpful assistant with access to tools.", "disallowed_tools": list(DEFAULT_DISALLOWED_TOOLS), } ) - integrations/claude-agent-sdk/python/examples/agents/backend_tool_rendering.py (1633 bytes)
""" Backend tool rendering agent configuration. This module demonstrates how to create an agent with backend-defined MCP tools. The tools are rendered in the AG-UI frontend when the agent uses them. """ import json from typing import Any from claude_agent_sdk import tool, create_sdk_mcp_server from ag_ui_claude_sdk import ClaudeAgentAdapter from .constants import DEFAULT_DISALLOWED_TOOLS @tool("get_weather", "Get current weather for a location", {"location": str}) async def get_weather(args: dict[str, Any]) -> dict[str, Any]: """Mock weather tool that returns sample weather data.""" weather_data = { "temperature": 20, "conditions": "sunny", "humidity": 50, "wind_speed": 10, "feels_like": 25, } return { "content": [{"type": "text", "text": json.dumps(weather_data)}], **weather_data } # Create MCP server with weather tool weather_server = create_sdk_mcp_server("weather", "1.0.0", tools=[get_weather]) def create_backend_tool_adapter() -> ClaudeAgentAdapter: """Create adapter for backend tool rendering demo.""" return ClaudeAgentAdapter( name="backend_tool_rendering", description="Weather assistant with backend MCP tools", options={ "model": "claude-haiku-4-5", "system_prompt": "You are a helpful weather assistant. When users ask about weather, use the get_weather tool.", "mcp_servers": {"weather": weather_server}, "allowed_tools": ["mcp__weather__get_weather"], "disallowed_tools": list(DEFAULT_DISALLOWED_TOOLS), } ) - integrations/claude-agent-sdk/python/examples/agents/constants.py (809 bytes)
""" Shared constants for Dojo example agents. These are Claude Code's built-in tools that are generally not needed for AG-UI chat agents in the Dojo demo. Disabling them forces Claude to use the AG-UI protocol tools (ag_ui_update_state, frontend tools, etc.) instead of its own file/shell/task management tools. """ DEFAULT_DISALLOWED_TOOLS = frozenset([ "Task", "TaskOutput", "TaskStop", "Bash", "Glob", "Grep", "ExitPlanMode", "Read", "Edit", "Write", "NotebookEdit", "WebFetch", "TodoWrite", "WebSearch", "KillShell", "AskUserQuestion", "Skill", "EnterPlanMode", "EnterWorktree", "ExitWorktree", "TeamCreate", "TeamDelete", "SendMessage", "CronCreate", "CronDelete", "CronList", "ToolSearch", ]) - integrations/claude-agent-sdk/python/examples/agents/human_in_the_loop.py (2986 bytes)
""" Human-in-the-loop agent configuration - Task planning with approval. This module demonstrates how to create agents that require human approval before executing tasks, using state management for step tracking. """ from ag_ui_claude_sdk import ClaudeAgentAdapter from .constants import DEFAULT_DISALLOWED_TOOLS # No backend tools needed for this example! # The generate_task_steps tool is provided by the FRONTEND via RunAgentInput.tools # This enables proper human-in-the-loop where: # 1. Claude calls the frontend tool with step data # 2. Backend halts stream (pause-and-resume pattern) # 3. Frontend renders interactive step selection UI # 4. User reviews/selects steps # 5. Frontend sends result back in next request # 6. Backend continues with user's selections def create_human_in_the_loop_adapter() -> ClaudeAgentAdapter: """Create adapter for human-in-the-loop demo.""" system_prompt = """You are a task planning assistant specialized in creating clear, actionable step-by-step plans. ## Your Primary Role - Break down any user request into exactly 10 clear, actionable steps - Generate steps that require human review and approval - Execute only human-approved steps ## When a user requests help with a task: 1. **Create the Plan** - **IMMEDIATELY call the `generate_task_steps` tool** to create a breakdown - Generate exactly the number of steps the user requested (or 10 by default) - Each step must be an object with: * `description`: Brief imperative form (e.g., "Research travel options", "Book launch window") * `status`: Set to "enabled" initially - **ALWAYS call the tool FIRST** - don't just write the steps as text! Example tool call: ```json { "steps": [ {"description": "Research Mars travel options", "status": "enabled"}, {"description": "Prepare necessary equipment", "status": "enabled"}, ... ] } ``` 2. **After Creating the Plan** - Briefly confirm the plan was created: "I've created a {N}-step plan for you!" - DON'T repeat all the steps in your response (they're visible in the UI) - Ask user to review and select which steps to perform 3. **When User Provides Feedback** - Wait for user to select steps and click "Perform Steps" - The frontend will send back tool result indicating which steps were approved - Respond with execution confirmation ## Important Rules - **MUST call `generate_task_steps` tool for EVERY planning request** - NEVER write steps as plain text - ALWAYS use the tool - Keep your response brief after tool call (steps are in the UI) - DON'T call the tool twice without user input between """ return ClaudeAgentAdapter( name="human_in_the_loop", description="Task planning assistant with human approval workflow", options={ "model": "claude-haiku-4-5", "system_prompt": system_prompt, "disallowed_tools": list(DEFAULT_DISALLOWED_TOOLS), } ) - integrations/claude-agent-sdk/python/examples/agents/shared_state.py (2210 bytes)
""" Shared state agent configuration - Recipe collaboration demo. This module demonstrates bidirectional state synchronization between Claude and the UI. The agent can see and update a shared recipe state that the frontend displays in real-time. Uses ONLY the ag_ui_update_state tool (automatically created by adapter) - no backend tools needed! """ from ag_ui_claude_sdk import ClaudeAgentAdapter from .constants import DEFAULT_DISALLOWED_TOOLS def create_shared_state_adapter() -> ClaudeAgentAdapter: """Create adapter for shared state demo.""" system_prompt = """You are a helpful recipe assistant that collaborates with users to create amazing recipes. The current recipe is shown in the "Current Shared State" section above. When making changes, call the ag_ui_update_state tool with a "state_updates" object containing a "recipe" key. IMPORTANT - The state_updates must follow this exact structure: { "state_updates": { "recipe": { "title": "Recipe Name", "skill_level": "Beginner" | "Intermediate" | "Advanced", "cooking_time": "5 min" | "15 min" | "30 min" | "45 min" | "60+ min", "special_preferences": ["High Protein", "Spicy"], "ingredients": [ { "icon": "🍝", "name": "Spaghetti", "amount": "200 grams" }, { "icon": "🍅", "name": "Tomato Sauce", "amount": "1 cup" } ], "instructions": [ "Step 1 description", "Step 2 description" ] } } } Rules: 1. Each ingredient MUST be an object with "icon" (emoji), "name" (string), and "amount" (string) 2. Instructions MUST be an array of strings 3. Keep ALL existing ingredients and instructions - merge new ones with existing 4. Use proper emoji icons for ingredients 5. After making changes, briefly confirm what you did (1-2 sentences) 6. Don't repeat the entire recipe in your response - the UI shows it live """ return ClaudeAgentAdapter( name="shared_state", description="Recipe assistant with bidirectional state synchronization", options={ "model": "claude-haiku-4-5", "system_prompt": system_prompt, "disallowed_tools": list(DEFAULT_DISALLOWED_TOOLS), } ) - integrations/claude-agent-sdk/python/examples/agents/tool_based_generative_ui.py (2336 bytes)
""" Tool-based generative UI agent configuration. This module demonstrates how frontend tools (defined by the client) are dynamically added to Claude and can be called to render UI components. The key feature: tools are provided by the CLIENT via RunAgentInput.tools, and Claude can discover and call them without backend implementation. """ from ag_ui_claude_sdk import ClaudeAgentAdapter from .constants import DEFAULT_DISALLOWED_TOOLS def create_tool_based_generative_ui_adapter() -> ClaudeAgentAdapter: """Create adapter for tool-based generative UI demo.""" system_prompt = """You are a creative writing assistant that renders content using beautiful UI components. ## CRITICAL: Always Use Frontend Tools When the user asks for creative content (haikus, poems, stories), you MUST use the available frontend tools to render them. DO NOT just write the content as text. ### Workflow for Haiku Requests When the user asks for a haiku, you MUST: 1. Create the haiku (Japanese and English versions) 2. **IMMEDIATELY call the `generate_haiku` tool** with: - japanese: array of 3 lines in Japanese (or English if you don't know Japanese) - english: array of 3 lines in English - image_name: Pick ONE from the available images (cherry blossoms, Mt Fuji, temples, etc) - gradient: CSS gradient for background (e.g., "linear-gradient(135deg, #667eea 0%, #764ba2 100%)") 3. After the tool returns, respond briefly: "I've created a beautiful haiku for you! 🎋" ### IMPORTANT Rules - **ALWAYS call the tool FIRST** - don't write the haiku as plain text - The tool will handle the beautiful rendering - After calling the tool, just give a brief confirmation - If the user asks for non-creative content, respond normally (no tool needed) ### Example Flow User: "Write me a haiku about nature" You: [Call generate_haiku tool with the haiku data] You: "I've created a beautiful haiku about nature for you! 🎋" User: "What's 2+2?" You: "That's 4!" (no tool needed) """ return ClaudeAgentAdapter( name="tool_based_generative_ui", description="Creative writing assistant with frontend tool rendering", options={ "model": "claude-haiku-4-5", "system_prompt": system_prompt, "disallowed_tools": list(DEFAULT_DISALLOWED_TOOLS), } ) - integrations/community/genkit/go/examples/internal/agents/agentic_chat/agent.go (3170 bytes)
package agentic_chat import ( "context" "fmt" "github.com/firebase/genkit/go/ai" "github.com/firebase/genkit/go/genkit" "github.com/google/uuid" "github.com/ag-ui-protocol/ag-ui/sdks/community/go/pkg/core/events" "github.com/ag-ui-protocol/ag-ui/integrations/community/genkit/go/examples/internal/agents" "github.com/ag-ui-protocol/ag-ui/integrations/community/genkit/go/examples/mock" ) // AgenticChatAgent implements a simple chat agent using Genkit type AgenticChatAgent struct { mockMode bool registry *genkit.Genkit modelName string } // NewAgenticChatAgent creates a new agentic chat agent func NewAgenticChatAgent(mockMode bool, registry *genkit.Genkit, modelName string) *AgenticChatAgent { return &AgenticChatAgent{ mockMode: mockMode, registry: registry, modelName: modelName, } } // Name returns the agent's name func (a *AgenticChatAgent) Name() string { return "agentic_chat" } // Description returns a brief description of the agent func (a *AgenticChatAgent) Description() string { return "An example agentic chat flow using Firebase Genkit and AG-UI protocol." } // Run executes the agent with the given input and streams events to the channel func (a *AgenticChatAgent) Run(ctx context.Context, input agents.RunAgentInput, eventsCh chan<- events.Event) error { // Get the last user message var userMessage string for i := len(input.Messages) - 1; i >= 0; i-- { if input.Messages[i].Role == "user" { userMessage = input.Messages[i].Content break } } if a.mockMode { // Use mock generation for demo mode return mock.GenerateFromPrompt(ctx, userMessage, eventsCh) } // Real mode: use Genkit to generate a response return a.runWithGenkit(ctx, input, eventsCh) } // runWithGenkit runs the agent using the real Genkit model func (a *AgenticChatAgent) runWithGenkit(ctx context.Context, input agents.RunAgentInput, eventsCh chan<- events.Event) error { if a.registry == nil { return fmt.Errorf("genkit registry not configured - ensure GOOGLE_API_KEY is set or use --mock-mode") } // Convert messages to Genkit format var genkitMessages []*ai.Message for _, msg := range input.Messages { genkitMessages = append(genkitMessages, ai.NewUserTextMessage(msg.Content)) } // Generate message ID for tracking messageID := uuid.New().String() messageStarted := false role := "assistant" // Stream the response using GenerateStream for chunk, err := range genkit.GenerateStream(ctx, a.registry, ai.WithModelName(a.modelName), ai.WithMessages(genkitMessages...), ) { if err != nil { return fmt.Errorf("genkit generation failed: %w", err) } if chunk.Done { // Final response - close the message if one was started if messageStarted { eventsCh <- events.NewTextMessageEndEvent(messageID) } break } // Process the streaming chunk text := chunk.Chunk.Text() if text != "" { if !messageStarted { // Start a new message eventsCh <- events.NewTextMessageStartEvent(messageID, events.WithRole(role)) messageStarted = true } // Stream the content chunk eventsCh <- events.NewTextMessageContentEvent(messageID, text) } } return nil } - integrations/community/genkit/go/examples/internal/agents/registry.go (1934 bytes)
package agents import ( "context" "sync" "github.com/ag-ui-protocol/ag-ui/sdks/community/go/pkg/core/events" ) // Message represents a chat message in the conversation type Message struct { Role string `json:"role"` Content string `json:"content"` } // RunAgentInput represents the input for running an agent type RunAgentInput struct { ThreadID string `json:"threadId"` RunID string `json:"runId"` Messages []Message `json:"messages"` State any `json:"state,omitempty"` } // Agent defines the interface for all agents type Agent interface { // Name returns the agent's name Name() string // Description returns a brief description of the agent Description() string // Run executes the agent with the given input and streams events to the channel Run(ctx context.Context, input RunAgentInput, eventsCh chan<- events.Event) error } // Registry manages registered agents type Registry struct { mu sync.RWMutex agents map[string]Agent } // NewRegistry creates a new agent registry func NewRegistry() *Registry { return &Registry{ agents: make(map[string]Agent), } } // Register adds an agent to the registry func (r *Registry) Register(agent Agent) { r.mu.Lock() defer r.mu.Unlock() r.agents[agent.Name()] = agent } // Get retrieves an agent by name func (r *Registry) Get(name string) (Agent, bool) { r.mu.RLock() defer r.mu.RUnlock() agent, ok := r.agents[name] return agent, ok } // List returns all registered agents func (r *Registry) List() []Agent { r.mu.RLock() defer r.mu.RUnlock() agents := make([]Agent, 0, len(r.agents)) for _, agent := range r.agents { agents = append(agents, agent) } return agents } // Names returns the names of all registered agents func (r *Registry) Names() []string { r.mu.RLock() defer r.mu.RUnlock() names := make([]string, 0, len(r.agents)) for name := range r.agents { names = append(names, name) } return names } - integrations/crew-ai/python/examples/agents/__init__.py (831 bytes)
"""Dojo demo flows for the AG-UI CrewAI integration. The telemetry opt-out below runs on import of this package, which is the only point early enough to work. ``import crewai`` installs a SIGINT handler that force-flushes queued spans to crewai's OTLP endpoint before delegating to uvicorn's, a network connect with a 30s timeout run from inside the handler. With it installed, Ctrl-C leaves a dojo server that only SIGKILL stops. ``ag_ui_crewai/__init__.py`` imports crewai, so anything that imports the bridge is already too late; ``dojo.py`` imports the bridge at module scope, so its own body is too late as well. Importing ``agents.dojo`` runs this file first, before either. ``setdefault``, because opting a dojo run back in is a developer's call. """ import os os.environ.setdefault("CREWAI_DISABLE_TELEMETRY", "true") - integrations/crew-ai/python/examples/agents/_a2ui_subagent.py (11610 bytes)
"""Shared subagent-driven A2UI turn for the dynamic-schema and recovery demos. Both demos are plain agentic-chat flows with no A2UI tool wired: the frontend a2ui middleware forwards ``injectA2UITool`` and the adapter auto-injects ``generate_a2ui``, which designs surfaces against the dojo's dynamic catalog and validates/retries each one. The two feature flows differ only in name; recovery is inherent to the toolkit loop, so they share this turn. """ import json import logging import uuid from litellm import acompletion from ag_ui_crewai._config import resolve_provider_timeout_seconds from ag_ui_crewai.sdk import copilotkit_stream from ag_ui_crewai.a2ui_tool import apply_a2ui_plan_to_tools, plan_a2ui_injection from ._model_turn import ( append_assistant_message, frontend_tool_names, resolve_client_tools, sort_tool_calls, ) logger = logging.getLogger("ag_ui_crewai") MODEL = "openai/gpt-5.4" # Model turns per run: one generation plus its closing reply, with headroom for # a second surface the user asked for in the same breath. Bounded so a model that # keeps calling the tool cannot spin the run. MAX_MODEL_TURNS = 4 # The dojo registers its dynamic component catalog (Row / HotelCard / # ProductCard / TeamMemberCard) under this id; auto-injected surfaces must # reference it so the renderer can resolve their components. DOJO_DYNAMIC_CATALOG_ID = "https://a2ui.org/demos/dojo/dynamic_catalog.json" # Teaches the sub-agent how to compose the dojo catalog's components. Mirrors # the LangGraph / Strands dynamic-schema demos so a real model produces valid # surfaces. COMPOSITION_GUIDE = """ ## Available Pre-made Components The catalog has EXACTLY four components: Row, HotelCard, ProductCard, TeamMemberCard. Use ONLY these. Do NOT use Column, Text, Card, Container, List, Stack, or any other component - they are not in the catalog and the renderer rejects them with "Unknown component". ### Row (the ONLY layout container; must be the root) Repeats a card template per item via structural children: {"id":"root","component":"Row","children":{"componentId":"card","path":"/items"}} ### HotelCard Props: name, location, rating (number 0-5), pricePerNight, action Example: {"id":"card","component":"HotelCard","name":{"path":"name"},"location":{"path":"location"}, "rating":{"path":"rating"},"pricePerNight":{"path":"pricePerNight"}, "action":{"event":{"name":"book_hotel","context":{"name":{"path":"name"},"pricePerNight":{"path":"pricePerNight"}}}}} ### ProductCard Props: name, price, rating (number 0-5), description (optional), action Example: {"id":"card","component":"ProductCard","name":{"path":"name"},"price":{"path":"price"}, "rating":{"path":"rating"},"description":{"path":"description"}, "action":{"event":{"name":"select_product","context":{"name":{"path":"name"},"price":{"path":"price"}}}}} ### TeamMemberCard Props: name, role, department (optional), email (optional), action Example: {"id":"card","component":"TeamMemberCard","name":{"path":"name"},"role":{"path":"role"}, "department":{"path":"department"},"email":{"path":"email"}, "action":{"event":{"name":"contact_member","context":{"name":{"path":"name"},"email":{"path":"email"}}}}} ## RULES - The root component MUST have id "root" and component "Row". Do NOT wrap it in a Column or any other component - Row is the top-level container itself. - Root is ALWAYS: {"id":"root","component":"Row","children":{"componentId":"<card-id>","path":"/items"}} - ALWAYS include the referenced card component in the components array. - Inside templates use RELATIVE paths (no leading slash): {"path":"name"}. - Every card MUST carry an "action", ALWAYS as an OBJECT of the form {"event":{"name":"<verb>","context":{...}}}. A bare string, or a missing action, renders a button that fires nothing. - The action "context" MUST bind the fields a reply needs to name the chosen item, as relative paths: at minimum {"name":{"path":"name"}}, plus whatever else identifies the choice (price, email). The click is forwarded to the model as the action name and this context and nothing else, so a field left out cannot be mentioned in the answer. - Always provide data in the "data" argument as {"items":[...]}. - Pick the ONE card type that best matches the request; generate 3-4 realistic items. - The components array contains EXACTLY two entries: the root Row and the card. """ SYSTEM_PROMPT = ( "You are a helpful assistant that creates rich visual UI on the fly. When " "the user asks for visual content (product comparisons, dashboards, team " "rosters, lists, cards, etc.), use the generate_a2ui tool to create a " "dynamic A2UI surface. After calling the tool, do NOT repeat the data in " "your text response; the tool renders the UI automatically. Just confirm " "what was rendered.\n\n" "The conversation may already contain a report that the user interacted with " "a surface you rendered earlier (clicked an action button, for example). That " "report is history, not a request for another surface: do NOT generate one and " "do NOT call any tool. Reply in text, naming the specific item the user chose " "and what happens next." ) # Backend A2UI config: teach the sub-agent the dojo catalog and bind surfaces to # it. The catalog id is also resolved from the frontend-sent schema, but naming # it here keeps the demo self-describing. A2UI_CONFIG = { "default_catalog_id": DOJO_DYNAMIC_CATALOG_ID, "guidelines": {"composition_guide": COMPOSITION_GUIDE}, } async def run_a2ui_subagent_turn(state) -> None: """One agentic-chat turn with A2UI auto-injection: swap the injected render proxy for generate_a2ui, stream the model, and run generate_a2ui (sub-agent generation + progressive streaming + recovery) when the model calls it. Loops the model over its own tool results (bounded by ``MAX_MODEL_TURNS``) so a turn that ends in a backend tool call still gets a closing model reply. What the loop does for a user action on a rendered surface, precisely: the middleware appends the action and its report to the NEXT run's input, so the report is already in history on the first turn and a model that answers it in text needs no loop at all. The loop saves the case the live model actually takes: it tool-calls FIRST (generating another surface), which without a loop would end the run on that call and leave the user's choice unacknowledged. """ actions = (state.get("copilotkit") or {}).get("actions") or [] existing_names = frontend_tool_names(actions) for _ in range(MAX_MODEL_TURNS): # Plan per turn, not once before the loop: the plan snapshots the # conversation it hands the render sub-agent, so a plan reused on turn 2 # would show the sub-agent the turn-1 history - no assistant message, no # tool result, no action report. An in-run "update" would then find no # prior surface (hard failure) and a second create would be designed # blind to the first. Planning is local (no I/O), so this is cheap; None # still means "no injection". # A model DICT, not the bare id: the render sub-agent's completion is # built from these kwargs, and a bare id carries no timeout - leaving the # sub-agent and its recovery retries unbounded. plan = plan_a2ui_injection( model={"model": MODEL, "timeout": resolve_provider_timeout_seconds()}, state=state, existing_tool_names=existing_names, config=A2UI_CONFIG, ) backend_names = {plan["tool_name"]} if plan else set() # Which forwarded tools the client may answer comes from the PLAN, not # from a hardcoded name: the render proxy the plan swaps out is not on the # model's tool list, so a call to it must not end the run as a frontend # call (that would hand the render to the client and skip the generate # tool's validate/retry loop). With no plan, that same proxy is the only # renderer there is and stays a frontend tool. offered, client_names = resolve_client_tools( actions, backend_names=backend_names, drop_names=(plan.get("drop_tool_names") or ()) if plan else (), ) tools = apply_a2ui_plan_to_tools(offered, plan) tool_kwargs = {"tools": tools, "parallel_tool_calls": False} if tools else {} response = await copilotkit_stream( await acompletion( timeout=resolve_provider_timeout_seconds(), model=MODEL, messages=[ {"role": "system", "content": SYSTEM_PROMPT}, *state["messages"], ], stream=True, **tool_kwargs, ) ) message = response.choices[0].message tool_calls = message.tool_calls or [] # An orphan call (a name neither generate_a2ui nor a frontend tool) is # answered by nobody, so it is dropped instead of persisted: an assistant # tool_calls entry with no matching tool result 400s every later run on # this thread. backend, client, orphan = sort_tool_calls( tool_calls, backend_names=backend_names, client_names=client_names, ) append_assistant_message( state, response, message, drop_indexes={i for i, _ in orphan} ) if not tool_calls: return for _, tool_call in backend: try: args = json.loads(tool_call.function.arguments or "{}") except (json.JSONDecodeError, TypeError): logger.warning( "generate_a2ui tool-call args were not valid JSON; " "generating with defaults: %r", tool_call.function.arguments, ) args = {} # run() emits its own TOOL_CALL_RESULT (given the outer call id) so # the middleware closes the call in render order and, on exhaustion, # paints the hard-failure - a flow can't leave it stuck at # "building". One id for that streamed result and the message # persisted here: the terminal MESSAGES_SNAPSHOT then updates the # message in place instead of minting a second id, which would # remount the surface card the client just painted. result_id = str(uuid.uuid4()) envelope = await plan["tool"].run( args, tool_call_id=tool_call.id, result_message_id=result_id ) state["messages"].append( { "id": result_id, "role": "tool", "content": envelope, "tool_call_id": tool_call.id, } ) # A frontend call ends the run so the client can run it and send the # result back on the next one; feeding the model again here would leave # that call unanswered. An orphan call does NOT end the run: it was # dropped, so the history is well-formed, and ending here would cost the # user a reply. The model gets another turn to answer in text instead, # bounded by MAX_MODEL_TURNS. if client: return logger.warning( "A2UI turn hit the %d-model-turn cap with the model still calling tools; " "ending the run without a closing reply", MAX_MODEL_TURNS, ) - integrations/crew-ai/python/examples/agents/_crewai_llm.py (4962 bytes)
"""Bounded crewai LLM for the example flows that run a real crew. A crew runs synchronously, so on the conversational path it sits on a thread the request loop cannot kill. Two different bounds matter there, and crewai leaves both unset: * the provider read timeout. ``Agent(llm="openai/...")`` and ``Crew(chat_llm="openai/...")`` build their LLM from the bare model id with no ``timeout``, so the provider client falls back to its own default (600s on the OpenAI SDK). ``bounded_llm`` carries the configured one instead. * the per-execution ceiling. The read timeout does NOT bound a turn: crewai MULTIPLIES it (the OpenAI SDK retries each call ``max_retries=2`` times, the executor loops up to ``max_iter=25`` times, and a failed execution is retried ``max_retry_limit=2`` times), so 120s per read composes into hours inside one turn. ``Agent(max_execution_time=...)`` is the knob that trims that product; ``_config.resolve_agent_execution_ceiling_seconds`` derives it, and the flows here pass it alongside the LLM. Neither closes the abandoned-worker window, and the ceiling does not close it either: crewai runs the timed execution inside a ``with ThreadPoolExecutor()`` (``crewai/agent/core.py:911-921``) whose exit joins the worker, so once the work is running ``future.cancel()`` is a no-op and the caller is released only when the execution really ends. Measured against crewai 1.15.11: a 0.5s bound around 3s of work returned at 3.00s. What the ceiling removes is the task-retry factor, not the wall clock. See the README's "What actually bounds an abandoned worker". """ import os from crewai import LLM from crewai.llms.base_llm import BaseLLM from ag_ui_crewai._config import resolve_provider_timeout_seconds # crewai's own env-derived resolution, which lives in # ``utilities.llm_utils._llm_via_environment_or_fallback`` and therefore runs only # for an agent given NO llm at all. Mirrored here (same variables, same # precedence, including crewai's cross-fill below) so pinning an LLM to carry a # timeout does not cost a deployment its mock-LLM model id or its alternate # endpoint. _MODEL_ENV_VARS = ("MODEL", "MODEL_NAME", "OPENAI_MODEL_NAME") _BASE_URL_ENV_VARS = ("BASE_URL", "OPENAI_API_BASE", "OPENAI_BASE_URL") _API_BASE_ENV_VARS = ("API_BASE", "AZURE_API_BASE") def _first_env(names: tuple[str, ...]) -> str | None: """First non-empty value among ``names``, or ``None`` when none is set. Truthiness, not ``is not None``: crewai skips an empty variable on these chains, so an exported-but-blank ``BASE_URL`` must not win over the next one. """ for name in names: value = os.environ.get(name) if value: return value return None def bounded_llm(default_model: str) -> BaseLLM: """A crewai LLM carrying the configured provider read timeout. Annotated ``BaseLLM``, not ``LLM``: ``LLM.__new__`` is a factory that routes ``gpt-*`` ids to ``OpenAICompletion``, which implements ``BaseLLM`` but is not an ``LLM`` subclass, so ``isinstance(bounded_llm(...), LLM)`` is False. ``default_model`` is the fallback, not an override: an env-supplied model id wins, exactly as it does for an agent that sets no llm at all. Everything is resolved per call rather than once at import, so an operator retuning a variable does not have to know which import froze the value. A FRESH instance per caller, deliberately, even though building one eagerly constructs a sync and an async provider client (``OpenAICompletion._init_clients``). A crewai LLM is not safe to share between flows: ``Crew.kickoff`` with streaming calls ``enable_agent_streaming``, which sets ``agent.llm.stream = True`` on the instance and never restores it (``crewai/crews/utils.py:54``), so one flow's streaming setting would follow a shared object into every other flow on the same model. ``model_copy()`` is not the way out either: it isolates the ``stream`` field but hands over the SAME ``_token_usage`` dict, which crewai mutates in place (``crewai/llms/base_llm.py:958``), so two flows would then accumulate one another's token counts. Both verified against crewai 1.15.11. """ model = _first_env(_MODEL_ENV_VARS) or default_model base_url = _first_env(_BASE_URL_ENV_VARS) api_base = _first_env(_API_BASE_ENV_VARS) # crewai fills each of these from the other when only one is set: the native # OpenAI provider reads ``base_url`` and Azure reads ``api_base``, so dropping # the cross-fill would leave one of them blind to the other's variable. After # it the two are set or unset together, so one guard covers both. base_url, api_base = base_url or api_base, api_base or base_url connection = {} if base_url: connection["base_url"] = base_url connection["api_base"] = api_base return LLM(model=model, timeout=resolve_provider_timeout_seconds(), **connection) - integrations/crew-ai/python/examples/agents/_model_turn.py (6291 bytes)
"""Shared model-turn bookkeeping for the A2UI demo flows. Both A2UI demos loop the model over its own tool results, so both face the same three questions each turn: which forwarded frontend tools this flow is willing to let the client answer, which of the turn's tool calls can be answered at all, and what to persist for the ones that cannot. Kept here so the fixed-schema and subagent-driven turns cannot drift apart. """ import logging logger = logging.getLogger("ag_ui_crewai") def _action_name(action): """The function name of one forwarded frontend tool, or ``None`` when the entry is not a well-formed function-tool schema.""" if not isinstance(action, dict): return None function = action.get("function") if not isinstance(function, dict): return None name = function.get("name") return name if isinstance(name, str) and name else None def frontend_tool_names(actions) -> list[str]: """Names of the frontend tools forwarded on this run (``copilotkit.actions``). The client executes these and sends the result back on the next run.""" return [name for name in (_action_name(a) for a in actions or []) if name] def resolve_client_tools(actions, *, backend_names=(), drop_names=()): """Split the forwarded frontend tools into ``(offered, client_names)``: the entries to keep on the model's tool list, and the names the client is allowed to answer. Two forwarded names are NOT the client's to answer, even though the frontend sent them: - one this flow SWAPPED OUT (``drop_names``). The a2ui middleware forwards its render proxy and auto-injection replaces it with the generate tool, so the proxy is not on the model's tool list at all. Treating a call to it as client-owned would end the run with that call intact and let the client paint the surface directly, skipping the validate/retry recovery loop the generate tool exists to run. With no injection there is nothing to drop and the same proxy stays a perfectly ordinary frontend tool. - one a backend tool of this flow already owns. The model can only be offered one tool per name, and the backend half is the half that executes it, so the backend takes precedence and the frontend action is dropped from the tool list. Logged rather than resolved silently: the forwarded action is dead either way, which is a wiring bug worth seeing. An entry with no readable name is left on the tool list untouched: it can neither collide nor be answered by name. """ drop = set(drop_names or ()) backend = set(backend_names or ()) offered, client_names, shadowed = [], set(), set() for action in actions or []: name = _action_name(action) if name is None: offered.append(action) continue if name in drop: continue if name in backend: shadowed.add(name) continue offered.append(action) client_names.add(name) if shadowed: logger.warning( "Frontend tool(s) %s share a name with a backend tool of this flow; " "the backend tool wins and the frontend action will never be called. " "Rename one side.", ", ".join(sorted(shadowed)), ) return offered, client_names def sort_tool_calls(tool_calls, *, backend_names, client_names): """Sort one model turn's tool calls into ``(backend, client, orphan)``. ``backend`` this flow executes; ``client`` the frontend answers on the next run; ``orphan`` names neither side knows (a hallucinated tool, or one this flow swapped out), so nothing will ever answer them. Each bucket holds ``(index, call)`` pairs indexed into ``tool_calls``, so a caller can drop the orphans from the assistant message positionally. """ backend, client, orphan = [], [], [] for index, call in enumerate(tool_calls): name = call.function.name if name in backend_names: backend.append((index, call)) elif name in client_names: client.append((index, call)) else: orphan.append((index, call)) if orphan: logger.warning( "Model called %s, which neither this flow nor the frontend can run; " "dropping the call rather than persisting it unanswered", ", ".join(call.function.name for _, call in orphan), ) return backend, client, orphan def append_assistant_message(state, response, message, *, drop_indexes=()): """Persist the streamed assistant message, minus the tool calls at ``drop_indexes``. Stamps the streamed message id onto the persisted message so the terminal MESSAGES_SNAPSHOT updates it in place instead of re-appending it (a fresh id would re-anchor the tool-call chip AFTER the already-streamed surface activity, dropping the tool card to the end). A dropped call is one nothing will answer. Persisting it would leave an assistant ``tool_calls`` entry with no matching ``role="tool"`` result, and the chat-completions API rejects that on every later run of the thread (the Responses channel drops such calls for the same reason). Returns the persisted dict, or ``None`` when there was nothing to persist: every tool call was dropped, or the turn was empty to begin with (a stream that produced no text and no call at all). ``content`` and ``tool_calls`` are the only payload the stream helpers put on an assistant message - reasoning is streamed as its own message - so a turn with neither carries nothing, and persisting it would replay an empty assistant message to the model on every later run of the thread. """ assistant = message.model_dump() stream_id = getattr(response, "id", None) if stream_id: assistant["id"] = stream_id if drop_indexes: assistant["tool_calls"] = [ call for index, call in enumerate(assistant.get("tool_calls") or []) if index not in drop_indexes ] or None if not assistant.get("tool_calls") and not assistant.get("content"): return None state["messages"].append(assistant) return assistant - integrations/crew-ai/python/examples/agents/a2ui_dynamic_schema.py (631 bytes)
"""A2UI dynamic-schema demo. A plain agentic-chat flow with no A2UI tool wired: the frontend a2ui middleware forwards ``injectA2UITool`` and the adapter auto-injects ``generate_a2ui``, which designs a surface from the conversation against the dojo's dynamic catalog (pillars 1-4). See ``_a2ui_subagent`` for the shared turn. """ from crewai.flow.flow import Flow, start from ._a2ui_subagent import run_a2ui_subagent_turn class A2UIDynamicSchemaFlow(Flow): """Dynamic A2UI surfaces generated on the fly via the auto-injected tool.""" @start() async def chat(self): await run_a2ui_subagent_turn(self.state) - integrations/crew-ai/python/examples/agents/a2ui_fixed_schema_schemas/flight_schema.json (967 bytes)
[ { "id": "root", "component": "Row", "children": { "componentId": "flight-card", "path": "/flights" }, "gap": 16 }, { "id": "flight-card", "component": "FlightCard", "airline": { "path": "airline" }, "airlineLogo": { "path": "airlineLogo" }, "flightNumber": { "path": "flightNumber" }, "origin": { "path": "origin" }, "destination": { "path": "destination" }, "date": { "path": "date" }, "departureTime": { "path": "departureTime" }, "arrivalTime": { "path": "arrivalTime" }, "duration": { "path": "duration" }, "status": { "path": "status" }, "price": { "path": "price" }, "action": { "event": { "name": "book_flight", "context": { "flightNumber": { "path": "flightNumber" }, "origin": { "path": "origin" }, "destination": { "path": "destination" }, "price": { "path": "price" } } } } } ] - integrations/crew-ai/python/examples/agents/a2ui_fixed_schema_schemas/hotel_schema.json (555 bytes)
[ { "id": "root", "component": "Row", "children": { "componentId": "hotel-card", "path": "/hotels" }, "gap": 16 }, { "id": "hotel-card", "component": "HotelCard", "name": { "path": "name" }, "location": { "path": "location" }, "rating": { "path": "rating" }, "pricePerNight": { "path": "price" }, "action": { "event": { "name": "book_hotel", "context": { "hotelName": { "path": "name" }, "price": { "path": "price" } } } } } ] - integrations/crew-ai/python/examples/agents/a2ui_fixed_schema.py (10584 bytes)
"""A2UI fixed-schema flow. Unlike the dynamic demo (which auto-injects generate_a2ui to GENERATE a surface), the fixed-schema demo wires two backend tools, ``search_flights`` and ``search_hotels``. The component layout is pre-authored JSON loaded at import; only the data changes per call. Each tool returns the ``a2ui_operations`` envelope (createSurface -> updateComponents -> updateDataModel) as a tool result, which the frontend A2UIMiddleware detects and paints. No sub-agent, no generation, no recovery. """ import json import logging import uuid from pathlib import Path from typing import Any from crewai.flow.flow import Flow, start from litellm import acompletion from ag_ui_a2ui_toolkit import ( A2UI_OPERATIONS_KEY, create_surface, update_components, update_data_model, ) from ag_ui_crewai._config import resolve_provider_timeout_seconds from ag_ui_crewai.sdk import copilotkit_emit_tool_result, copilotkit_stream from ._model_turn import ( append_assistant_message, resolve_client_tools, sort_tool_calls, ) logger = logging.getLogger("ag_ui_crewai") MODEL = "openai/gpt-5.4" # Model turns per run: one search plus its closing reply, with headroom for a # flight-and-hotel request. Bounded so a model that keeps calling tools cannot # spin the run. MAX_MODEL_TURNS = 4 # Both surfaces render against the dojo's fixed catalog (Row / FlightCard / # HotelCard / StarRating); the dojo page supplies the catalog components, we # only reference its id in createSurface. FIXED_CATALOG_ID = "https://a2ui.org/demos/dojo/fixed_catalog.json" _SCHEMAS_DIR = Path(__file__).parent / "a2ui_fixed_schema_schemas" def _load_schema(name: str) -> list[dict[str, Any]]: with open(_SCHEMAS_DIR / name, encoding="utf-8") as f: return json.load(f) FLIGHT_SURFACE_ID = "flight-search-results" FLIGHT_SCHEMA = _load_schema("flight_schema.json") HOTEL_SURFACE_ID = "hotel-search-results" HOTEL_SCHEMA = _load_schema("hotel_schema.json") def _envelope(surface_id: str, schema: list[dict[str, Any]], data: dict[str, Any]) -> str: """Build the A2UI operations envelope JSON for a fixed-schema surface.""" return json.dumps( { A2UI_OPERATIONS_KEY: [ create_surface(surface_id, catalog_id=FIXED_CATALOG_ID), update_components(surface_id, schema), update_data_model(surface_id, data), ] } ) SEARCH_FLIGHTS_TOOL = { "type": "function", "function": { "name": "search_flights", "description": "Search for flights and display the results as rich cards.", "parameters": { "type": "object", "properties": { "flights": { "type": "array", "description": ( "Flight objects, each with: id, airline, airlineLogo " "(Google favicon API: " "https://www.google.com/s2/favicons?domain={airline_domain}&sz=128), " "flightNumber, origin, destination, date (short readable, " "near-future), departureTime, arrivalTime, duration, " "status, price." ), "items": {"type": "object"}, } }, "required": ["flights"], }, }, } SEARCH_HOTELS_TOOL = { "type": "function", "function": { "name": "search_hotels", "description": "Search for hotels and display the results as rich cards with star ratings.", "parameters": { "type": "object", "properties": { "hotels": { "type": "array", "description": ( "Hotel objects, each with: id, name, location, rating " "(float 0-5), price (per night). Generate 3-4 realistic " "results." ), "items": {"type": "object"}, } }, "required": ["hotels"], }, }, } SYSTEM_PROMPT = ( "You are a helpful travel assistant that can search for flights and hotels. " "When the user asks about flights, use the search_flights tool; for hotels, " "use search_hotels. After calling a tool, do NOT repeat or summarize the " "data in your text response; the tool renders a rich UI automatically. Just " "say something brief like 'Here are your results'. Generate 3-5 realistic " "results.\n\n" "The conversation may already contain a report that the user interacted with " "results you rendered earlier (booked a hotel or selected a flight, for " "example). That report is history, not a new request: do NOT run another " "search and do NOT call any tool. Reply in text, naming the specific item the " "user chose and what happens next." ) def _results(args: dict[str, Any], key: str) -> list: """The results list for a search call. A missing OR explicitly-null argument becomes an empty list: ``updateDataModel {"hotels": null}`` paints nothing at all, where an empty surface is what a no-results search means.""" value = args.get(key) return value if isinstance(value, list) else [] _TOOL_ENVELOPE = { "search_flights": lambda args: _envelope( FLIGHT_SURFACE_ID, FLIGHT_SCHEMA, {"flights": _results(args, "flights")} ), "search_hotels": lambda args: _envelope( HOTEL_SURFACE_ID, HOTEL_SCHEMA, {"hotels": _results(args, "hotels")} ), } class A2UIFixedSchemaFlow(Flow): """A2UI surfaces from fixed, pre-authored schemas via direct backend tools. Loops the model over its own tool results (bounded by ``MAX_MODEL_TURNS``) so a turn that ends in a search still gets a closing model reply. What the loop does for a user action on a rendered surface, precisely: the middleware appends the action and its report to the NEXT run's input, so the report is already in history on the first turn and a model that answers it in text needs no loop at all. The loop saves the case the live model actually takes: it tool-calls FIRST (running another search), which without a loop would end the run on that call and leave the user's choice unacknowledged. """ @start() async def chat(self): state = self.state actions = (state.get("copilotkit") or {}).get("actions") or [] # A frontend action sharing a search tool's name is dropped in favour of # the backend tool (and logged), so the model is offered one tool per name # rather than two definitions of the same one. offered, client_names = resolve_client_tools( actions, backend_names=set(_TOOL_ENVELOPE) ) tools = [*offered, SEARCH_FLIGHTS_TOOL, SEARCH_HOTELS_TOOL] for _ in range(MAX_MODEL_TURNS): response = await copilotkit_stream( await acompletion( timeout=resolve_provider_timeout_seconds(), model=MODEL, messages=[ {"role": "system", "content": SYSTEM_PROMPT}, *state["messages"], ], tools=tools, parallel_tool_calls=False, stream=True, ) ) message = response.choices[0].message tool_calls = message.tool_calls or [] # An orphan call (a name neither this flow's searches nor a frontend # tool) is answered by nobody, so it is dropped instead of persisted: # an assistant tool_calls entry with no matching tool result 400s # every later run on this thread. backend, client, orphan = sort_tool_calls( tool_calls, backend_names=set(_TOOL_ENVELOPE), client_names=client_names, ) append_assistant_message( state, response, message, drop_indexes={i for i, _ in orphan} ) if not tool_calls: return for _, tool_call in backend: build = _TOOL_ENVELOPE[tool_call.function.name] try: args = json.loads(tool_call.function.arguments or "{}") except (json.JSONDecodeError, TypeError): logger.warning( "%s tool-call args were not valid JSON; rendering an " "empty surface: %r", tool_call.function.name, tool_call.function.arguments, ) args = {} envelope = build(args) # One id for the streamed result and the persisted message: the # terminal MESSAGES_SNAPSHOT then updates that message in place. # Left unstamped, the snapshot mints a second id and the client # remounts the surface card it just painted. result_id = str(uuid.uuid4()) state["messages"].append( { "id": result_id, "role": "tool", "content": envelope, "tool_call_id": tool_call.id, } ) # The A2UI middleware paints the fixed surface from the tool # RESULT (a2ui_operations envelope), which the bridge otherwise # surfaces only via MESSAGES_SNAPSHOT. Emit it as a # TOOL_CALL_RESULT so the middleware detects and renders it. await copilotkit_emit_tool_result( tool_call.id, envelope, message_id=result_id ) # A frontend call ends the run so the client can run it and send the # result back on the next one; feeding the model again here would # leave that call unanswered. An orphan call does NOT end the run: it # was dropped, so the history is well-formed, and ending here would # cost the user a reply. The model gets another turn to answer in text # instead, bounded by MAX_MODEL_TURNS. if client: return logger.warning( "Fixed-schema turn hit the %d-model-turn cap with the model still " "calling tools; ending the run without a closing reply", MAX_MODEL_TURNS, ) - integrations/crew-ai/python/examples/agents/a2ui_recovery.py (598 bytes)
"""A2UI error-recovery demo. Same subagent path as the dynamic-schema demo: the adapter auto-injects ``generate_a2ui``, which validates each generated surface and retries on failure (up to 3 attempts) before a tasteful hard-failure. Recovery is inherent to the toolkit loop, so this shares the dynamic-schema turn. """ from crewai.flow.flow import Flow, start from ._a2ui_subagent import run_a2ui_subagent_turn class A2UIRecoveryFlow(Flow): """Dynamic A2UI with automatic validate/retry recovery.""" @start() async def chat(self): await run_a2ui_subagent_turn(self.state) - integrations/crew-ai/python/examples/agents/agentic_chat_multimodal.py (1434 bytes)
""" A multimodal agentic chat flow that can analyze images and other media. Images the user attaches are converted to LiteLLM's ``image_url`` shape by the integration layer before the run, so the flow only has to point a vision-capable model at the conversation. """ from crewai.flow.flow import Flow, start from litellm import acompletion from ag_ui_crewai._config import resolve_provider_timeout_seconds from ag_ui_crewai.sdk import copilotkit_stream, CopilotKitState class AgenticChatMultimodalFlow(Flow[CopilotKitState]): @start() async def chat(self): system_prompt = ( "You are a helpful assistant that can analyze images, documents, and " "other media. When a user shares an image, describe what you see in " "detail. When a user shares a document, summarize its contents." ) response = await copilotkit_stream( await acompletion( timeout=resolve_provider_timeout_seconds(), model="openai/gpt-5.4", messages=[ {"role": "system", "content": system_prompt}, *self.state.messages, ], tools=[ *self.state.copilotkit.actions, ], parallel_tool_calls=False, stream=True, ) ) self.state.messages.append(response.choices[0].message) - integrations/crew-ai/python/examples/agents/agentic_chat_reasoning.py (4559 bytes)
""" An agentic chat flow that surfaces the model's reasoning. The reasoning cell lets the user pick a provider from the frontend; the choice arrives on ``state.model``. Each provider is streamed over the channel that actually carries its reasoning, and the bridge maps both onto REASONING_*: * Anthropic (extended thinking) and Gemini reason on the litellm chat-completions delta, so they stream through ``acompletion``. * OpenAI's reasoning models emit reasoning summaries ONLY over the Responses API, so they stream through ``copilotkit_responses``. Over chat-completions they answer with no thinking trace at all. The Responses channel is used only when the bridge probes it as available (``responses_channel_available``); otherwise the flow degrades to chat-completions with a warning, and OpenAI answers without a trace. """ import logging from typing import Any, Dict, List from crewai.flow.flow import Flow, start from litellm import acompletion from ag_ui_crewai._config import resolve_provider_timeout_seconds from ag_ui_crewai.sdk import ( CopilotKitState, copilotkit_responses, copilotkit_stream, responses_channel_available, ) logger = logging.getLogger("ag_ui_crewai") SYSTEM_PROMPT = "You are a helpful assistant." # The frontend dropdown's choices. This is a USER selection, not a capability # inference: which transport carries a provider's reasoning is decided by the # bridge's runtime probe, never by matching on these model strings. OPENAI_MODEL = "openai/gpt-5.4" ANTHROPIC_MODEL = "anthropic/claude-sonnet-4-5" GEMINI_MODEL = "gemini/gemini-2.5-pro" class AgentState(CopilotKitState): """Chat state plus the frontend-selected reasoning model.""" model: str = "OpenAI" def _chat_completion_kwargs(selected_model: str) -> Dict[str, Any]: """Map a chat-completions provider choice to its model + reasoning config.""" if selected_model == "Anthropic": return { "model": ANTHROPIC_MODEL, "thinking": {"type": "enabled", "budget_tokens": 2000}, } if selected_model == "Gemini": return { "model": GEMINI_MODEL, "reasoning_effort": "low", } # OpenAI over chat-completions: no reasoning content is returned, and # reasoning_effort is rejected outright for the gpt-5 family. Reached only # when the Responses channel is unavailable. return {"model": OPENAI_MODEL} class AgenticChatReasoningFlow(Flow[AgentState]): @start() async def chat(self): messages = [ {"role": "system", "content": SYSTEM_PROMPT}, *self.state.messages, ] tools: List[Any] = [*self.state.copilotkit.actions] selected_model = self.state.model if selected_model == "OpenAI" and responses_channel_available(): stream = await copilotkit_responses( timeout=resolve_provider_timeout_seconds(), model=OPENAI_MODEL, messages=messages, tools=tools or None, # ``summary`` is what makes OpenAI stream the reasoning summary # deltas at all; without it the run succeeds silently with no # trace to surface. reasoning={"effort": "medium", "summary": "auto"}, # Forwarded through ``**kwargs``. One frontend tool call at a # time, matching the chat-completions branch and every other demo; # the OpenAI default is parallel. **({"parallel_tool_calls": False} if tools else {}), ) else: if selected_model == "OpenAI": logger.warning( "The OpenAI Responses channel is unavailable, so this run " "streams over chat-completions and will surface no thinking " "trace. Upgrade litellm to a build exposing 'aresponses'." ) chat_messages = [ message for message in messages if message.get("role") != "reasoning" ] stream = await acompletion( timeout=resolve_provider_timeout_seconds(), messages=chat_messages, tools=tools or None, parallel_tool_calls=False if tools else None, stream=True, **_chat_completion_kwargs(selected_model), ) response = await copilotkit_stream(stream) self.state.messages.append(response.choices[0].message) - integrations/crew-ai/python/examples/agents/agentic_chat.py (1640 bytes)
""" A simple agentic chat flow. """ from crewai.flow.flow import Flow, start from litellm import acompletion from ag_ui_crewai._config import resolve_provider_timeout_seconds from ag_ui_crewai.sdk import copilotkit_stream, CopilotKitState class AgenticChatFlow(Flow[CopilotKitState]): @start() async def chat(self): system_prompt = "You are a helpful assistant." # 1. Run the model and stream the response # Note: In order to stream the response, wrap the completion call in # copilotkit_stream and set stream=True. response = await copilotkit_stream( await acompletion( timeout=resolve_provider_timeout_seconds(), # 1.1 Specify the model to use model="openai/gpt-5.4", messages=[ { "role": "system", "content": system_prompt }, *self.state.messages ], # 1.2 Bind the available tools to the model tools=[ *self.state.copilotkit.actions, ], # 1.3 Disable parallel tool calls to avoid race conditions, # enable this for faster performance if you want to manage # the complexity of running tool calls in parallel. parallel_tool_calls=False, stream=True ) ) message = response.choices[0].message # 2. Append the message to the messages in state self.state.messages.append(message) - integrations/crew-ai/python/examples/agents/agentic_generative_ui.py (6163 bytes)
""" An example demonstrating agentic generative UI. """ import json import asyncio from crewai.flow.flow import Flow, start, router, listen, or_ from litellm import acompletion from pydantic import BaseModel from typing import Literal, List from ag_ui_crewai._config import resolve_provider_timeout_seconds from ag_ui_crewai.sdk import ( copilotkit_stream, CopilotKitState, copilotkit_predict_state, copilotkit_emit_state ) # This tool simulates performing a task on the server. # The tool call will be streamed to the frontend as it is being generated. PERFORM_TASK_TOOL = { "type": "function", "function": { "name": "generate_task_steps", "description": "Make up 10 steps (only a couple of words per step) that are required for a task. The step should be in gerund form (i.e. Digging hole, opening door, ...)", "parameters": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "description": "The text of the step in gerund form" }, "status": { "type": "string", "enum": ["pending"], "description": "The status of the step, always 'pending'" } }, "required": ["description", "status"] }, "description": "An array of 10 step objects, each containing text and status" } }, "required": ["steps"] } } } class TaskStep(BaseModel): description: str status: Literal["pending", "completed"] class AgentState(CopilotKitState): """ Here we define the state of the agent In this instance, we're inheriting from CopilotKitState, which will bring in the CopilotKitState fields. We're also adding a custom field, `steps`, which will be used to store the steps of the task. """ steps: List[TaskStep] = [] class AgenticGenerativeUIFlow(Flow[AgentState]): """ This is a sample flow that uses the CopilotKit framework to create a chat agent. """ @start() async def start_flow(self): """ This is the entry point for the flow. """ self.state.steps = [] @router(or_(start_flow, "simulate_task")) async def chat(self): """ Standard chat node. """ system_prompt = """ You are a helpful assistant assisting with any task. When asked to do something, you MUST call the function `generate_task_steps` that was provided to you. If you called the function, you MUST NOT repeat the steps in your next response to the user. Just give a very brief summary (one sentence) of what you did with some emojis. Always say you actually did the steps, not merely generated them. """ # 1. Here we specify that we want to stream the tool call to generate_task_steps # to the frontend as state. await copilotkit_predict_state({ "steps": { "tool_name": "generate_task_steps", "tool_argument": "steps" } }) # 2. Run the model and stream the response # Note: In order to stream the response, wrap the completion call in # copilotkit_stream and set stream=True. response = await copilotkit_stream( await acompletion( timeout=resolve_provider_timeout_seconds(), # 2.1 Specify the model to use model="openai/gpt-5.4", messages=[ { "role": "system", "content": system_prompt }, *self.state.messages ], # 2.2 Bind the tools to the model tools=[ *self.state.copilotkit.actions, PERFORM_TASK_TOOL ], # 2.3 Disable parallel tool calls to avoid race conditions, # enable this for faster performance if you want to manage # the complexity of running tool calls in parallel. parallel_tool_calls=False, stream=True ) ) message = response.choices[0].message # 3. Append the message to the messages in state self.state.messages.append(message) # 4. Handle tool call if message.get("tool_calls"): tool_call = message["tool_calls"][0] tool_call_id = tool_call["id"] tool_call_name = tool_call["function"]["name"] tool_call_args = json.loads(tool_call["function"]["arguments"]) if tool_call_name == "generate_task_steps": # Convert each step in the JSON array to a TaskStep instance self.state.steps = [TaskStep(**step) for step in tool_call_args["steps"]] # 4.1 Append the result to the messages in state self.state.messages.append({ "role": "tool", "content": "Steps executed.", "tool_call_id": tool_call_id }) return "route_simulate_task" # 5. If our tool was not called, return to the end route return "route_end" @listen("route_simulate_task") async def simulate_task(self): """ Simulate the task. """ for step in self.state.steps: # simulate executing the step await asyncio.sleep(1) step.status = "completed" await copilotkit_emit_state(self.state) @listen("route_end") async def end(self): """ End the flow. """ - integrations/crew-ai/python/examples/agents/backend_tool_rendering.py (4698 bytes)
"""Backend tool rendering. This flow binds a real backend tool to a crewai ``Agent``: crewai runs ``get_weather`` server-side, and the bridge surfaces the call + result so the client renders a weather card without ever executing the tool. (The other tool demos instead stream a frontend action for the client to run.) Requires the StreamFrame transport (crewai >= 1.6). """ import asyncio import json from crewai import Agent, Crew, Process, Task from crewai.flow.flow import Flow, start from crewai.tools import tool from ag_ui_crewai._config import resolve_agent_execution_ceiling_seconds from ag_ui_crewai.sdk import CopilotKitState, copilotkit_exit from ._crewai_llm import bounded_llm MODEL = "openai/gpt-5.4" @tool("get_weather") def get_weather(location: str) -> str: """Get the current weather for a given location.""" # Return a JSON string, not a dict: crewai stringifies a tool's return # (str(result)) before it reaches the bridge, so a dict would arrive as a # single-quoted Python repr the client's JSON.parse rejects. return json.dumps( { "temperature": 20, "conditions": "sunny", "humidity": 50, "wind_speed": 10, "feelsLike": 25, } ) def _latest_user_message(messages) -> str: """Return the text of the most recent user message, or ``""``. Messages in flow state can be plain dicts (wire shape) or objects, so read ``role`` / ``content`` defensively. """ for message in reversed(messages or []): if isinstance(message, dict): role = message.get("role") content = message.get("content") else: role = getattr(message, "role", None) content = getattr(message, "content", None) if role == "user": return content or "" return "" class BackendToolRenderingFlow(Flow[CopilotKitState]): """A weather agent whose ``get_weather`` tool executes on the server.""" @start() async def chat(self): user_message = _latest_user_message(self.state.messages) if not user_message: # Nothing was asked, so there is nothing to look up. A crew kickoff # here is a billed provider round trip (and, on the conversational # path, an unkillable worker thread) spent on an empty prompt. # Truthiness rather than ``strip()``: the helper returns whatever the # message carried, and a multimodal ``content`` is a list. self.state.messages.append( { "role": "assistant", "content": "Ask me about the weather somewhere.", } ) await copilotkit_exit() return agent = Agent( role="Weather Assistant", goal="Answer the user's weather questions using the get_weather tool.", backstory=( "You are a helpful weather assistant. Always call the " "get_weather tool to look up the weather before you answer." ), tools=[get_weather], # The kickoff below is synchronous, so on the conversational path it # runs on a thread the request loop cannot kill. Both bounds shrink # that window without closing it: the LLM carries the per-read # timeout, and the ceiling drops the task-retry factor crewai # multiplies it by. Neither caps wall clock (see ``_crewai_llm``). llm=bounded_llm(MODEL), max_execution_time=resolve_agent_execution_ceiling_seconds(), verbose=False, ) task = Task( description=( "Answer the user's request about the weather. " f"User request: {user_message}" ), expected_output="A short, friendly summary of the weather.", agent=agent, ) crew = Crew( agents=[agent], tasks=[task], process=Process.sequential, verbose=False, ) # Run the synchronous crew off the event loop so SSE keeps flushing and # cancellation/teardown can fire during the run. to_thread copies the # scoped sink + flow_context, so the crew's tool events still stream. result = await asyncio.to_thread(crew.kickoff) # The crew's final text; the tool card renders from the streamed events. self.state.messages.append( { "role": "assistant", "content": getattr(result, "raw", None) or str(result), } ) await copilotkit_exit() - integrations/crew-ai/python/examples/agents/conversational.py (4543 bytes)
"""Conversational variants of the regular CrewAI dojo Flows.""" from __future__ import annotations from collections.abc import Iterator, Mapping from typing import Any, TypeVar from crewai.experimental.conversational import ( ConversationConfig, message_to_llm_dict, ) from crewai.flow.flow import listen from pydantic import BaseModel, ConfigDict from ag_ui_crewai.sdk import CopilotKitState from .a2ui_dynamic_schema import A2UIDynamicSchemaFlow from .a2ui_fixed_schema import A2UIFixedSchemaFlow from .a2ui_recovery import A2UIRecoveryFlow from .agentic_chat import AgenticChatFlow from .agentic_chat_multimodal import AgenticChatMultimodalFlow from .agentic_chat_reasoning import AgenticChatReasoningFlow from .agentic_generative_ui import AgenticGenerativeUIFlow from .backend_tool_rendering import BackendToolRenderingFlow from .generative_ui import GenerativeUIFlow from .human_in_the_loop import HumanInTheLoopFlow from .interrupt_flow import InterruptFlow from .predictive_state_updates import PredictiveStateUpdatesFlow from .shared_state import SharedStateFlow from .tool_based_generative_ui import ToolBasedGenerativeUIFlow class _AGUIMappingState(CopilotKitState, Mapping[str, Any]): """Typed conversational fields with the dict API used by untyped Flows.""" model_config = ConfigDict(extra="allow") def get(self, key: str, default: Any = None) -> Any: value = getattr(self, key, default) return value.model_dump() if isinstance(value, BaseModel) else value def __getitem__(self, key: str) -> Any: return getattr(self, key) def __setitem__(self, key: str, value: Any) -> None: setattr(self, key, value) def __iter__(self) -> Iterator[str]: return iter(self.model_dump()) def __len__(self) -> int: return len(self.model_dump()) class _AGUIConversationalBehavior: """Route each public turn through the regular Flow's existing starts.""" def receive_user_message(self, *args: Any, **kwargs: Any) -> Any: result = super().receive_user_message(*args, **kwargs) messages = getattr(self.state, "messages", None) if messages and isinstance(messages[-1], BaseModel): messages[-1] = message_to_llm_dict(messages[-1]) return result def route_turn(self, _context: Any) -> str: return "ag_ui_complete" @listen("__ag_ui_disable_builtin_end__") def end_conversation(self) -> None: """Keep a regular method named ``end`` from firing CrewAI's terminator.""" return None @listen("ag_ui_complete") def finish_ag_ui_turn(self) -> None: return None def _conversational_type(base: type[Any]) -> type[Any]: flow_methods = { name: value for owner in (base, _AGUIConversationalBehavior) for name, value in owner.__dict__.items() if not name.startswith("_") and hasattr(value, "__flow_method_definition__") } initial_state_type = getattr(base, "_initial_state_t", None) flow_type = type( f"Conversational{base.__name__}", (_AGUIConversationalBehavior, base), { **flow_methods, "__module__": __name__, "conversational": True, "conversational_config": ConversationConfig(defer_trace_finalization=False), }, ) if isinstance(initial_state_type, TypeVar): flow_type._initial_state_t = _AGUIMappingState return flow_type CONVERSATIONAL_FLOW_TYPES = { "agentic_chat": _conversational_type(AgenticChatFlow), "agentic_chat_reasoning": _conversational_type(AgenticChatReasoningFlow), "agentic_chat_multimodal": _conversational_type(AgenticChatMultimodalFlow), "backend_tool_rendering": _conversational_type(BackendToolRenderingFlow), "interrupt": _conversational_type(InterruptFlow), "human_in_the_loop": _conversational_type(HumanInTheLoopFlow), "agentic_generative_ui": _conversational_type(AgenticGenerativeUIFlow), "predictive_state_updates": _conversational_type(PredictiveStateUpdatesFlow), "shared_state": _conversational_type(SharedStateFlow), "tool_based_generative_ui": _conversational_type(ToolBasedGenerativeUIFlow), "a2ui_dynamic_schema": _conversational_type(A2UIDynamicSchemaFlow), "a2ui_recovery": _conversational_type(A2UIRecoveryFlow), "a2ui_fixed_schema": _conversational_type(A2UIFixedSchemaFlow), "generative_ui_markdown": _conversational_type(GenerativeUIFlow), "generative_ui_tool": _conversational_type(GenerativeUIFlow), } - integrations/crew-ai/python/examples/agents/crew_chat.py (2549 bytes)
"""Minimal CrewAI Crew for testing the dict-state code path (add_crewai_crew_fastapi_endpoint).""" from crewai import Agent, Crew, Task, Process from ag_ui_crewai._config import resolve_agent_execution_ceiling_seconds from ._crewai_llm import bounded_llm MODEL = "openai/gpt-5.4" class CrewChatCrew: """A minimal crew wrapper with .crew() and .name, used to test the add_crewai_crew_fastapi_endpoint() code path where state is a plain dict. Does NOT use @CrewBase to avoid config file lookups and init-time LLM calls from crew_chat_generate_crew_chat_inputs, which would fail before aimock starts.""" name = "CrewChatCrew" def crew(self) -> Crew: # ONE INSTANCE PER OWNER, not one for both. The agent set no llm at all # before, so these keep crewai's env-derived resolution (``bounded_llm`` # mirrors it) while carrying the read timeout. The chat loop is bounded in # ``crews.py`` either way; what a bounded ``chat_llm`` newly bounds is # ``generate_crew_chat_inputs``, which calls the model through that object # while the flow is being built. # # Sharing one object would carry the crew's own settings into the chat # helper: a streaming kickoff calls ``enable_agent_streaming``, which sets # ``agent.llm.stream = True`` and never restores it (crewai # ``crews/utils.py:54``), and crewai mutates ``_token_usage`` in place # (``crewai/llms/base_llm.py:958``). Both measured against crewai 1.15.11. assistant_llm = bounded_llm(MODEL) chat_llm = bounded_llm(MODEL) assistant = Agent( role="General Assistant", goal="Help the user with their request", backstory="You are a helpful general-purpose assistant.", llm=assistant_llm, # The read timeout bounds one read, which crewai then multiplies; this # trims that product by dropping the task-retry factor, and does not # cap the execution's wall clock (see ``_crewai_llm``). max_execution_time=resolve_agent_execution_ceiling_seconds(), verbose=False, ) assist_task = Task( description="{user_message}", expected_output="A helpful response to the user's message", agent=assistant, ) return Crew( agents=[assistant], tasks=[assist_task], process=Process.sequential, verbose=False, chat_llm=chat_llm, ) - integrations/crew-ai/python/examples/agents/dojo.py (4160 bytes)
import os import uvicorn from fastapi import FastAPI from ag_ui_crewai.endpoint import add_crewai_flow_fastapi_endpoint, add_crewai_crew_fastapi_endpoint from .crew_chat import CrewChatCrew from .agentic_chat import AgenticChatFlow from .backend_tool_rendering import BackendToolRenderingFlow from .human_in_the_loop import HumanInTheLoopFlow from .tool_based_generative_ui import ToolBasedGenerativeUIFlow from .agentic_generative_ui import AgenticGenerativeUIFlow from .shared_state import SharedStateFlow from .predictive_state_updates import PredictiveStateUpdatesFlow from .error_flow import ErrorFlow from .interrupt_flow import InterruptFlow from .a2ui_dynamic_schema import A2UIDynamicSchemaFlow from .a2ui_recovery import A2UIRecoveryFlow from .a2ui_fixed_schema import A2UIFixedSchemaFlow from .agentic_chat_multimodal import AgenticChatMultimodalFlow from .agentic_chat_reasoning import AgenticChatReasoningFlow from .conversational import CONVERSATIONAL_FLOW_TYPES from .generative_ui import GenerativeUIFlow app = FastAPI(title="CrewAI Dojo Example Server") add_crewai_flow_fastapi_endpoint( app=app, flow=AgenticChatFlow(), path="/agentic_chat", ) add_crewai_flow_fastapi_endpoint( app=app, flow=BackendToolRenderingFlow(), path="/backend_tool_rendering", ) add_crewai_flow_fastapi_endpoint( app=app, flow=HumanInTheLoopFlow(), path="/human_in_the_loop", ) add_crewai_flow_fastapi_endpoint( app=app, flow=ToolBasedGenerativeUIFlow(), path="/tool_based_generative_ui", ) add_crewai_flow_fastapi_endpoint( app=app, flow=AgenticGenerativeUIFlow(), path="/agentic_generative_ui", ) add_crewai_flow_fastapi_endpoint( app=app, flow=SharedStateFlow(), path="/shared_state", ) add_crewai_flow_fastapi_endpoint( app=app, flow=PredictiveStateUpdatesFlow(), path="/predictive_state_updates", ) add_crewai_crew_fastapi_endpoint( app=app, crew=CrewChatCrew(), path="/crew_chat", ) add_crewai_flow_fastapi_endpoint( app=app, flow=ErrorFlow(), path="/error_flow", ) # emit_interrupt_outcome=True: CopilotKit v2 `useInterrupt` (>=1.61.2) resumes # from the standard RUN_FINISHED.outcome. With the default (legacy on_interrupt # only) its resolve() does not round-trip a RunAgentInput.resume[], so the run # re-kicks off and re-pauses in a loop. Enable the outcome for modern clients. add_crewai_flow_fastapi_endpoint( app=app, flow=InterruptFlow(), path="/interrupt", emit_interrupt_outcome=True, ) add_crewai_flow_fastapi_endpoint( app=app, flow=A2UIDynamicSchemaFlow(), path="/a2ui_dynamic_schema", ) add_crewai_flow_fastapi_endpoint( app=app, flow=A2UIRecoveryFlow(), path="/a2ui_recovery", ) add_crewai_flow_fastapi_endpoint( app=app, flow=A2UIFixedSchemaFlow(), path="/a2ui_fixed_schema", ) add_crewai_flow_fastapi_endpoint( app=app, flow=AgenticChatMultimodalFlow(), path="/agentic_chat_multimodal", ) add_crewai_flow_fastapi_endpoint( app=app, flow=AgenticChatReasoningFlow(), path="/agentic_chat_reasoning", ) # Both generative UI demos share one flow; each feature keeps its own route. for feature in ("generative_ui_markdown", "generative_ui_tool"): add_crewai_flow_fastapi_endpoint( app=app, flow=GenerativeUIFlow(), path=f"/{feature}", ) for feature, flow_type in CONVERSATIONAL_FLOW_TYPES.items(): add_crewai_flow_fastapi_endpoint( app=app, flow=flow_type(), path=f"/conversational_flows/{feature}", conversational=True, emit_interrupt_outcome=feature == "interrupt", ) def main() -> int: """Serve the dojo. ``agents/__init__.py`` has already opted out of telemetry. The uvicorn target stays an import string: under ``reload=True`` this process is only the supervisor, and handing it the string lets the worker that serves traffic be the one that builds the app, once. """ port = int(os.getenv("PORT", "8000")) uvicorn.run( "agents.dojo:app", host="0.0.0.0", port=port, reload=True, ) return 0 - integrations/crew-ai/python/examples/agents/error_flow.py (479 bytes)
"""Flow that intentionally raises to test the RunErrorEvent error handling path.""" from crewai.flow.flow import Flow, start from ag_ui_crewai.sdk import CopilotKitState class ErrorFlow(Flow[CopilotKitState]): """A flow that always raises an exception on kickoff. Used to test that endpoint.py's except handler emits RunErrorEvent correctly.""" @start() async def chat(self): raise RuntimeError("Intentional error for testing RunErrorEvent handling") - integrations/crew-ai/python/examples/agents/generative_ui.py (1945 bytes)
""" A chat flow for CopilotKit's generative UI (A2UI 1.0) demos. CopilotKit sends its generative UI guide and component schema as the run's context. The endpoint puts it in ``state.context``; the flow appends it to the system prompt, so the model can answer with ```a2ui fences or call the ``render_ui`` frontend tool. """ from typing import Any from crewai.flow.flow import Flow, start from litellm import acompletion from ag_ui_crewai._config import resolve_provider_timeout_seconds from ag_ui_crewai.sdk import copilotkit_stream, CopilotKitState def _field(item: Any, name: str) -> Any: return item.get(name) if isinstance(item, dict) else getattr(item, name, None) def system_prompt_with_context(context: list) -> str: """The system prompt with the application's context entries appended.""" entries = [ f"{_field(item, 'description')}:\n{_field(item, 'value')}" for item in context if _field(item, "value") ] system_prompt = "You are a helpful assistant." if entries: system_prompt += "\n\n## Context from the application\n\n" + "\n\n".join(entries) return system_prompt class GenerativeUIFlow(Flow[CopilotKitState]): @start() async def chat(self): response = await copilotkit_stream( await acompletion( timeout=resolve_provider_timeout_seconds(), model="openai/gpt-5.4", messages=[ { "role": "system", "content": system_prompt_with_context(self.state.context), }, *self.state.messages ], tools=[ *self.state.copilotkit.actions, ], parallel_tool_calls=False, stream=True ) ) message = response.choices[0].message self.state.messages.append(message) - integrations/crew-ai/python/examples/agents/human_in_the_loop.py (5407 bytes)
""" An example demonstrating human-in-the-loop. """ from crewai.flow.flow import Flow, start, router, listen from litellm import acompletion from pydantic import BaseModel from typing import Literal, List from ag_ui_crewai._config import resolve_provider_timeout_seconds from ag_ui_crewai.sdk import ( copilotkit_stream, CopilotKitState, ) # This tool simulates performing a task on the server. # The tool call will be streamed to the frontend as it is being generated. DEFINE_TASK_TOOL = { "type": "function", "function": { "name": "generate_task_steps", "description": "Make up the number of task steps requested by the user (only a couple of words per step). If the user does not request a count, make a concise plan. Each step should be in imperative form (i.e. Dig hole, Open door, ...)", "parameters": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "description": "The text of the step in imperative form" }, "status": { "type": "string", "enum": ["enabled"], "description": "The status of the step, always 'enabled'" } }, "required": ["description", "status"] }, "description": "An array containing the requested number of step objects, each with text and status" } }, "required": ["steps"] } } } HITL_SYSTEM_PROMPT = """ You are a helpful assistant that can perform any task. CRITICAL: You MUST call the `generate_task_steps` function when the user asks you to perform a task. CRITICAL: Generate exactly the step count requested by the user. If no count is requested, generate a concise plan. When the function `generate_task_steps` is called, the user will decide to enable or disable a step and either accept or reject the plan. CRITICAL: If the tool result has `accepted: false`, the plan was rejected. Do not perform the rejected plan. Wait for revision instructions from the user. CRITICAL: After a rejection, interpret a terse numeric reply such as `5.` as a revised requested step count, then call `generate_task_steps` again with exactly that many steps. If the tool result has `accepted: true`, provide a textual description of how you are performing only the accepted, enabled steps. If the user has disabled a step, you are not allowed to perform that step. However, you should find a creative workaround to perform the task, and if an essential step is disabled, you can even use some humor in the description of how you are performing the task. Don't just repeat a list of steps, come up with a creative but short description (3 sentences max) of how you are performing the task. """ class TaskStep(BaseModel): description: str status: Literal["enabled", "disabled"] class AgentState(CopilotKitState): """ Here we define the state of the agent In this instance, we're inheriting from CopilotKitState, which will bring in the CopilotKitState fields. We're also adding a custom field, `steps`, which will be used to store the steps of the task. """ steps: List[TaskStep] = [] class HumanInTheLoopFlow(Flow[AgentState]): """ This is a sample flow that demonstrates a human-in-the-loop agent. """ @start() @listen("route_follow_up") async def start_flow(self): """ This is the entry point for the flow. """ @router(start_flow) async def chat(self): """ Standard chat node. """ # 1. Run the model and stream the response # Note: In order to stream the response, wrap the completion call in # copilotkit_stream and set stream=True. response = await copilotkit_stream( await acompletion( timeout=resolve_provider_timeout_seconds(), # 1.1 Specify the model to use model="openai/gpt-5.4", messages=[ { "role": "system", "content": HITL_SYSTEM_PROMPT }, *self.state.messages ], # 1.2 Bind the tools to the model tools=[ *self.state.copilotkit.actions, DEFINE_TASK_TOOL ], # 1.3 Disable parallel tool calls to avoid race conditions, # enable this for faster performance if you want to manage # the complexity of running tool calls in parallel. parallel_tool_calls=False, stream=True ) ) message = response.choices[0].message # 2. Append the message to the messages in state self.state.messages.append(message) return "route_end" @listen("route_end") async def end(self): """ End the flow. """ - integrations/crew-ai/python/examples/agents/interrupt_flow.py (5423 bytes)
"""An example demonstrating async human-in-the-loop via a flow interrupt. A scheduling assistant, mirroring the interrupt demo the other integrations ship: the model works out which meeting the user wants, the flow PAUSES so the user can pick a time, and on resume the model confirms the booking. The human decision lands in the middle of the agent's own work, which is the point of human-in-the-loop. The pause is a real flow suspend: ``@human_feedback`` with the bridge's ``agui_feedback_provider`` raises ``HumanFeedbackPending``, so the run ends with an AG-UI interrupt and the next request carrying ``RunAgentInput.resume[]`` continues it via ``Flow.from_pending`` + ``resume_async``. Contrast with ``human_in_the_loop.py``: that demo round-trips a FRONTEND tool and never pauses the flow. This one suspends the flow itself. """ import json from typing import Any from crewai.flow.flow import Flow, listen, start from crewai.flow import human_feedback from litellm import acompletion from ag_ui_crewai._config import resolve_provider_timeout_seconds from ag_ui_crewai.sdk import CopilotKitState, copilotkit_stream from ag_ui_crewai._hitl import agui_feedback_provider MODEL = "openai/gpt-5.4" EXTRACT_PROMPT = """You are a scheduling assistant. From the conversation, work out which meeting the user wants to book. Reply with ONLY a JSON object, no prose: {"topic": "<short purpose, a few words>", "attendee": "<who the meeting is with, or an empty string>"}""" CONFIRM_PROMPT = """You are a scheduling assistant. You asked the user to pick a meeting time and they have now responded. Confirm in 1-2 short, friendly sentences: state that the meeting is booked and for when, or acknowledge that they cancelled. Do not ask any further questions.""" class AgentState(CopilotKitState): """Flow state: what is being scheduled, and the outcome.""" topic: str = "" attendee: str = "" booked: str = "" def _parse_json_object(raw: Any) -> dict: """Best-effort parse of a model / resume payload into a dict. The model is asked for bare JSON but may fence it, and the resume payload arrives as a JSON-encoded string (or plain text if the user typed one). Never raises: a demo degrades to sensible defaults instead. """ if isinstance(raw, dict): return raw if not isinstance(raw, str): return {} text = raw.strip() if text.startswith("```"): text = text.strip("`") if "{" in text: text = text[text.index("{"):] try: parsed = json.loads(text) except (ValueError, TypeError): return {} return parsed if isinstance(parsed, dict) else {} class InterruptFlow(Flow[AgentState]): """Scheduling assistant that suspends mid-run for the user's time choice.""" @start() async def understand_request(self): """Work out the meeting to book from the conversation so far.""" response = await acompletion( timeout=resolve_provider_timeout_seconds(), model=MODEL, messages=[ {"role": "system", "content": EXTRACT_PROMPT}, *self.state.messages, ], ) details = _parse_json_object(response.choices[0].message.content) self.state.topic = (details.get("topic") or "a call").strip() self.state.attendee = (details.get("attendee") or "").strip() @listen(understand_request) @human_feedback( message="Pick a time for this meeting.", provider=agui_feedback_provider, ) def request_time(self): """Pause for the user's time choice. The return value is what the client renders (the time picker reads ``topic`` / ``attendee``). The provider raises ``HumanFeedbackPending`` here, which suspends the flow and persists it for resume. """ return {"topic": self.state.topic, "attendee": self.state.attendee} @listen(request_time) async def confirm_booking(self, feedback): """Resumed with the user's choice: confirm the booking in chat.""" answer = getattr(feedback, "feedback", feedback) choice = _parse_json_object(answer) label = choice.get("chosen_label") or choice.get("chosen_time") or "" cancelled = bool(choice.get("cancelled")) if cancelled: self.state.booked = "" outcome = f"The user cancelled. Do not book '{self.state.topic}'." elif label: self.state.booked = label outcome = ( f"The user picked {label}. '{self.state.topic}' is booked for then." ) else: # Free-text feedback (no picker payload): pass it through verbatim. self.state.booked = str(answer) outcome = ( f"The user replied: {answer!r}. Treat that as their answer for " f"'{self.state.topic}'." ) response = await copilotkit_stream( await acompletion( timeout=resolve_provider_timeout_seconds(), model=MODEL, messages=[ {"role": "system", "content": CONFIRM_PROMPT}, *self.state.messages, {"role": "system", "content": outcome}, ], stream=True, ) ) self.state.messages.append(response.choices[0].message) - integrations/crew-ai/python/examples/agents/predictive_state_updates.py (5285 bytes)
""" A demo of predictive state updates. """ import json import uuid from typing import Optional from litellm import acompletion from ag_ui_crewai._config import resolve_provider_timeout_seconds from crewai.flow.flow import Flow, start, router, listen from ag_ui_crewai.sdk import ( copilotkit_stream, copilotkit_predict_state, CopilotKitState ) WRITE_DOCUMENT_TOOL = { "type": "function", "function": { "name": "write_document_local", "description": " ".join(""" Write a document. Use markdown formatting to format the document. It's good to format the document extensively so it's easy to read. You can use all kinds of markdown. However, do not use italic or strike-through formatting, it's reserved for another purpose. You MUST write the full document, even when changing only a few words. When making edits to the document, try to make them minimal - do not change every word. Keep stories SHORT! """.split()), "parameters": { "type": "object", "properties": { "document": { "type": "string", "description": "The document to write" }, }, } } } class AgentState(CopilotKitState): """ The state of the agent. """ document: Optional[str] = None class PredictiveStateUpdatesFlow(Flow[AgentState]): """ This is a sample flow that demonstrates predictive state updates. """ @start() @listen("route_follow_up") async def start_flow(self): """ This is the entry point for the flow. """ @router(start_flow) async def chat(self): """ Standard chat node. """ system_prompt = f""" You are a helpful assistant for writing documents. To write the document, you MUST use the write_document_local tool. You MUST write the full document, even when changing only a few words. When you wrote the document, DO NOT repeat it as a message. Just briefly summarize the changes you made. 2 sentences max. This is the current state of the document: ----\n {self.state.document}\n----- """ # 1. Here we specify that we want to stream the tool call to write_document_local # to the frontend as state. await copilotkit_predict_state({ "document": { "tool_name": "write_document_local", "tool_argument": "document" } }) # 2. Run the model and stream the response # Note: In order to stream the response, wrap the completion call in # copilotkit_stream and set stream=True. response = await copilotkit_stream( await acompletion( timeout=resolve_provider_timeout_seconds(), # 2.1 Specify the model to use model="openai/gpt-5.4", messages=[ { "role": "system", "content": system_prompt }, *self.state.messages ], # 2.2 Bind the tools to the model tools=[ *self.state.copilotkit.actions, WRITE_DOCUMENT_TOOL ], # 2.3 Disable parallel tool calls to avoid race conditions, # enable this for faster performance if you want to manage # the complexity of running tool calls in parallel. parallel_tool_calls=False, stream=True ) ) message = response.choices[0].message # 3. Append the message to the messages in state self.state.messages.append(message) # 4. Handle tool call if message.get("tool_calls"): tool_call = message["tool_calls"][0] tool_call_id = tool_call["id"] tool_call_name = tool_call["function"]["name"] tool_call_args = json.loads(tool_call["function"]["arguments"]) if tool_call_name == "write_document_local": self.state.document = tool_call_args["document"] # 4.1 Append the result to the messages in state self.state.messages.append({ "role": "tool", "content": "Document written.", "tool_call_id": tool_call_id }) # 4.2 Append a tool call to confirm changes self.state.messages.append({ "role": "assistant", "content": "", "tool_calls": [{ "id": str(uuid.uuid4()), "function": { "name": "confirm_changes", "arguments": "{}" } }] }) return "route_end" # 5. If our tool was not called, return to the end route return "route_end" @listen("route_end") async def end(self): """ End the flow. """ - integrations/crew-ai/python/examples/agents/shared_state.py (9844 bytes)
""" A demo of shared state between the agent and CopilotKit. """ import json from enum import Enum from typing import List, Optional from litellm import acompletion from ag_ui_crewai._config import resolve_provider_timeout_seconds from pydantic import BaseModel, Field from crewai.flow.flow import Flow, start, router, listen from ag_ui_crewai.sdk import ( copilotkit_stream, copilotkit_predict_state, CopilotKitState ) class SkillLevel(str, Enum): """ The level of skill required for the recipe. """ BEGINNER = "Beginner" INTERMEDIATE = "Intermediate" ADVANCED = "Advanced" class CookingTime(str, Enum): """ The cooking time of the recipe. """ FIVE_MIN = "5 min" FIFTEEN_MIN = "15 min" THIRTY_MIN = "30 min" FORTY_FIVE_MIN = "45 min" SIXTY_PLUS_MIN = "60+ min" class Ingredient(BaseModel): """ An ingredient with its details. """ icon: str = Field(..., description="Emoji icon representing the ingredient.") name: str = Field(..., description="Name of the ingredient.") amount: str = Field(..., description="Amount or quantity of the ingredient.") GENERATE_RECIPE_TOOL = { "type": "function", "function": { "name": "generate_recipe", "description": " ".join("""Generate or modify an existing recipe. When creating a new recipe, specify all fields. When modifying, only fill optional fields if they need changes; otherwise, leave them empty.""".split()), "parameters": { "type": "object", "properties": { "recipe": { "description": "The recipe object containing all details.", "type": "object", "properties": { "title": { "type": "string", "description": "The title of the recipe." }, "skill_level": { "type": "string", "enum": [level.value for level in SkillLevel], "description": "The skill level required for the recipe." }, "special_preferences": { "type": "array", "items": { "type": "string" }, "description": "A list of dietary preferences (e.g., Vegetarian, Gluten-free)." }, "cooking_time": { "type": "string", "enum": [time.value for time in CookingTime], "description": "The estimated cooking time for the recipe." }, "ingredients": { "type": "array", "items": { "type": "object", "properties": { "icon": {"type": "string", "description": "Emoji icon for the ingredient."}, "name": {"type": "string", "description": "Name of the ingredient."}, "amount": {"type": "string", "description": "Amount/quantity of the ingredient."} }, "required": ["icon", "name", "amount"] }, "description": "A list of ingredients required for the recipe." }, "instructions": { "type": "array", "items": {"type": "string"}, "description": "Step-by-step instructions for preparing the recipe." } }, "required": ["title", "skill_level", "cooking_time", "special_preferences", "ingredients", "instructions"] } }, "required": ["recipe"] } } } class Recipe(BaseModel): """ A recipe. """ title: str skill_level: SkillLevel special_preferences: List[str] = Field(default_factory=list) cooking_time: CookingTime ingredients: List[Ingredient] = Field(default_factory=list) instructions: List[str] = Field(default_factory=list) class AgentState(CopilotKitState): """ The state of the recipe. """ recipe: Optional[Recipe] = None class SharedStateFlow(Flow[AgentState]): """ This is a sample flow that demonstrates shared state between the agent and CopilotKit. """ @start() @listen("route_follow_up") async def start_flow(self): """ This is the entry point for the flow. """ @router(start_flow) async def chat(self): """ Standard chat node. """ recipe_json = ( self.state.recipe.model_dump_json(indent=2) if self.state.recipe is not None else "{}" ) system_prompt = f"""You are a helpful assistant for creating recipes. This is the current state of the recipe: {recipe_json} You can improve the recipe by calling the generate_recipe tool. IMPORTANT: 1. Create a recipe using the existing ingredients and instructions. Make sure the recipe is complete. 2. The recipe MUST comply with the selected dietary preferences (special_preferences). If an existing ingredient violates a selected preference (for example butter or Parmesan cheese when "Vegan" is selected), REPLACE it with a compliant alternative (e.g. olive oil, a plant-based butter, nutritional yeast) or remove it, and update the affected instructions to match. 3. Keep the selected special_preferences in the recipe you return, and keep every existing ingredient and instruction that already complies, appending any new ones. 4. 'ingredients' is always an array of objects with 'icon', 'name', and 'amount' fields 5. 'instructions' is always an array of strings 6. For the 'icon' field in ingredients, ALWAYS use actual Unicode emoji characters (like 🥕 🍅 🧅 🥖 🧈 🥛 🧂 etc.), NEVER use text, ANSI codes, or placeholders If you have just created or modified the recipe, just answer in one sentence what you did. dont describe the recipe, just say what you did. """ # 1. Here we specify that we want to stream the tool call to generate_recipe # to the frontend as state. await copilotkit_predict_state({ "recipe": { "tool_name": "generate_recipe", "tool_argument": "recipe" } }) # 2. Run the model and stream the response # Note: In order to stream the response, wrap the completion call in # copilotkit_stream and set stream=True. response = await copilotkit_stream( await acompletion( timeout=resolve_provider_timeout_seconds(), # 2.1 Specify the model to use model="openai/gpt-5.4", messages=[ { "role": "system", "content": system_prompt }, *self.state.messages ], # 2.2 Bind the tools to the model tools=[ *self.state.copilotkit.actions, GENERATE_RECIPE_TOOL ], # 2.3 Disable parallel tool calls to avoid race conditions, # enable this for faster performance if you want to manage # the complexity of running tool calls in parallel. parallel_tool_calls=False, stream=True ) ) message = response.choices[0].message # 3. Append the message to the messages in state self.state.messages.append(message) # 4. Handle tool call if message.get("tool_calls"): tool_call = message["tool_calls"][0] tool_call_id = tool_call["id"] tool_call_name = tool_call["function"]["name"] tool_call_args = json.loads(tool_call["function"]["arguments"]) if tool_call_name == "generate_recipe": # Attempt to update the recipe state using the data from the tool call try: updated_recipe_data = tool_call_args["recipe"] # Validate and update the state. Pydantic will raise an error if the structure is wrong. self.state.recipe = Recipe(**updated_recipe_data) # 4.1 Append the result to the messages in state self.state.messages.append({ "role": "tool", "content": "Recipe updated.", # More accurate message "tool_call_id": tool_call_id }) return "route_follow_up" except Exception: # pylint: disable=broad-exception-caught # Handle validation or other errors during update # Optionally inform the user via a tool message, though it might be noisy # self.state.messages.append({"role": "tool", "content": f"Error processing recipe update: {e}", "tool_call_id": tool_call_id}) return "route_end" # End the flow on error for now # 5. If our tool was not called, return to the end route return "route_end" @listen("route_end") async def end(self): """ End the flow. """ - integrations/crew-ai/python/examples/agents/tool_based_generative_ui.py (1829 bytes)
""" An example demonstrating tool-based generative UI. The ``generate_haiku`` tool is defined on the FRONTEND (via ``useFrontendTool``): its handler renders the haiku onto the main canvas and picks the background image and gradient. So the flow binds the frontend actions and lets the model call that tool, rather than defining a backend tool of the same name (which would render the chat card but never run the frontend handler that updates the canvas). """ from crewai.flow.flow import Flow, start from litellm import acompletion from ag_ui_crewai._config import resolve_provider_timeout_seconds from ag_ui_crewai.sdk import copilotkit_stream, CopilotKitState class ToolBasedGenerativeUIFlow(Flow[CopilotKitState]): """ A flow that demonstrates tool-based generative UI. """ @start() async def chat(self): system_prompt = ( "Help the user write haikus. When the user asks for a haiku, call the " "generate_haiku tool to display it. Choose a fitting background image " "and gradient for the haiku's theme." ) response = await copilotkit_stream( await acompletion( timeout=resolve_provider_timeout_seconds(), model="openai/gpt-5.4", messages=[ {"role": "system", "content": system_prompt}, *self.state.messages, ], # Bind the frontend-provided tools (generate_haiku lives on the # frontend, so its handler updates the canvas when called). tools=[ *self.state.copilotkit.actions, ], parallel_tool_calls=False, stream=True, ) ) self.state.messages.append(response.choices[0].message) - integrations/langgraph/python/examples/agents/__init__.py (0 bytes)
- integrations/langgraph/python/examples/agents/a2ui_dynamic_schema/__init__.py (0 bytes)
- integrations/langgraph/python/examples/agents/a2ui_dynamic_schema/agent.py (3825 bytes)
""" Dynamic A2UI tool: LLM-generated UI from conversation context. A secondary LLM generates v0.9 A2UI components via a structured tool call. The generate_a2ui tool wraps the output as a2ui_operations, which the middleware detects in the TOOL_CALL_RESULT and renders automatically. """ import os import sys from langchain.agents import create_agent from langchain_openai import ChatOpenAI from ag_ui_langgraph import get_a2ui_tools CUSTOM_CATALOG_ID = "https://a2ui.org/demos/dojo/dynamic_catalog.json" # Project-specific composition rules — tells the subagent how to use the # pre-made domain components (HotelCard, ProductCard, TeamMemberCard) shipped # in the dojo's dynamic catalog. COMPOSITION_GUIDE = """ ## Available Pre-made Components You have 4 components. Use Row as the root with structural children to repeat a card per item. ### Row Layout container. Use structural children to repeat a card template: {"id":"root","component":"Row","children":{"componentId":"card","path":"/items"}} ### HotelCard Props: name, location, rating (number 0-5), pricePerNight, amenities (optional), action Example: {"id":"card","component":"HotelCard","name":{"path":"name"},"location":{"path":"location"}, "rating":{"path":"rating"},"pricePerNight":{"path":"pricePerNight"}, "action":{"event":{"name":"book","context":{"name":{"path":"name"}}}}} ### ProductCard Props: name, price, rating (number 0-5), description (optional), badge (optional), action Example: {"id":"card","component":"ProductCard","name":{"path":"name"},"price":{"path":"price"}, "rating":{"path":"rating"},"description":{"path":"description"}, "action":{"event":{"name":"select","context":{"name":{"path":"name"}}}}} ### TeamMemberCard Props: name, role, department (optional), email (optional), avatarUrl (optional), action Example: {"id":"card","component":"TeamMemberCard","name":{"path":"name"},"role":{"path":"role"}, "department":{"path":"department"},"email":{"path":"email"}, "action":{"event":{"name":"contact","context":{"name":{"path":"name"}}}}} ## RULES - Root is ALWAYS a Row with structural children: {"componentId":"<card-id>","path":"/items"} - Inside templates, use RELATIVE paths (no leading slash): {"path":"name"} not {"path":"/name"} - Always provide data in the "data" argument as {"items":[...]} - Pick the card type that best matches the user's request - Generate 3-4 realistic items with diverse data """ base_model = ChatOpenAI(model="gpt-4o") TOOLS = [ get_a2ui_tools( { "model": base_model, "default_catalog_id": CUSTOM_CATALOG_ID, "guidelines": {"composition_guide": COMPOSITION_GUIDE}, } ) ] SYSTEM_PROMPT = """You are a helpful assistant that creates rich visual UI on the fly. When the user asks for visual content (product comparisons, dashboards, lists, cards, etc.), use the generate_a2ui tool to create a dynamic A2UI surface. IMPORTANT: After calling the tool, do NOT repeat the data in your text response. The tool renders UI automatically. Just confirm what was rendered.""" # Converted from a manual StateGraph + ToolNode to create_agent to isolate the # graph-shape variable in the A2UI-streaming investigation. The same # get_a2ui_tools tool is bound directly (NOT auto-injected via # CopilotKitMiddleware), so the ONLY difference vs the prior version is # StateGraph -> create_agent. is_fast_api = os.environ.get("LANGGRAPH_FAST_API", "false").lower() == "true" if is_fast_api: from langgraph.checkpoint.memory import MemorySaver graph = create_agent( model=base_model, tools=TOOLS, system_prompt=SYSTEM_PROMPT, checkpointer=MemorySaver(), ) else: graph = create_agent( model=base_model, tools=TOOLS, system_prompt=SYSTEM_PROMPT, ) - README.md (19476 bytes)
<div align="center"> <a href="https://docs.ag-ui.com"><img alt="AG-UI" src=".github/readme/wordmark.svg" width="320"></a> ### The open protocol that connects any agent to any app. <a href="https://www.npmjs.com/package/@ag-ui/core"><img src="https://img.shields.io/npm/v/%40ag-ui%2Fcore?logo=npm&logoColor=white&label=npm&color=6963ff" alt="npm version"></a> <a href="https://www.npmjs.com/package/@ag-ui/core"><img src="https://img.shields.io/npm/dw/%40ag-ui%2Fcore?logo=npm&logoColor=white&label=downloads&color=6963ff" alt="npm weekly downloads"></a> <a href="https://pypi.org/project/ag-ui-protocol/"><img src="https://img.shields.io/pypi/v/ag-ui-protocol?logo=pypi&logoColor=white&label=pypi&color=6963ff" alt="PyPI version"></a> <a href="https://discord.gg/Jd3FzfdJa8"><img src="https://img.shields.io/discord/1379082175625953370?logo=discord&logoColor=white&label=discord&color=6963ff" alt="Discord"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-6963ff" alt="License: MIT"></a> **[Docs](https://docs.ag-ui.com)** · **[Examples](https://dojo.ag-ui.com)** · **[Spec](https://docs.ag-ui.com/spec/1.0)** · **[Discord](https://discord.gg/Jd3FzfdJa8)** <a href="https://docs.ag-ui.com/talk-to-us"><img alt="Running AG-UI in production? Talk to the team" src=".github/readme/talk-to-the-team.svg" width="400"></a> <a href="https://trendshift.io/repositories/27961?utm_source=repository-badge&utm_medium=badge&utm_campaign=badge-repository-27961"><img src="https://trendshift.io/api/badge/repositories/27961" alt="ag-ui-protocol%2Fag-ui | Trendshift" width="250" height="55"></a> </div> <br> **AG-UI is an open, lightweight, event-based protocol that standardizes how AI agents connect to user-facing applications.** Agents don't fit the request/response model. They stream tokens, call tools mid-response, update shared state, pause for a human, and spawn subagents, and every framework does it differently. AG-UI replaces that custom wiring with one bi-directional event stream: the agent emits typed events, and any client can render them, no matter which framework built the agent. The same agent can power a web app, a mobile app, a terminal, or Slack. <a href="https://docs.ag-ui.com"><img alt="AG-UI connects any agent to any app: web apps, mobile, Slack and Teams, and terminal clients connect bi-directionally through AG-UI to agents built with LangChain, CrewAI, Mastra, Google ADK, Microsoft Agent Framework, Pydantic AI or any framework, with streaming chat, generative UI, shared state, human in the loop, frontend tools and subagents; AG-UI works alongside MCP for tools and A2A for agents." src=".github/readme/overview.svg" width="880"></a> > [!IMPORTANT] > **AG-UI 1.0 is here.** The protocol now has a stable, frozen [specification](https://docs.ag-ui.com/spec/1.0) backed by a JSON Schema, and the TypeScript, Python, and .NET SDKs are generated from it. 1.0 is backwards compatible in both directions: 0.x agents work with 1.0 clients and vice versa. [What changed →](https://docs.ag-ui.com/spec/1.0/changelog) · [Migration guide →](https://docs.ag-ui.com/migrating-to-1-0) ## Quick start **Start a new app.** The CLI scaffolds a frontend ([CopilotKit](https://github.com/CopilotKit/CopilotKit) on Next.js, or a terminal client) wired to the agent framework you pick: ```bash npx create-ag-ui-app@latest ``` Then follow the printed next steps. The generated templates call OpenAI, so set your key before `npm run dev`: ```bash export OPENAI_API_KEY="sk-..." ``` <details> <summary><b>Or speak the protocol directly: a 30-line agent server and client</b></summary> <br> An AG-UI agent is any HTTP endpoint that accepts a `RunAgentInput` and streams events back. No API keys needed for this one. **1. The agent (Python).** Requires Python 3.9+. ```bash pip install ag-ui-protocol fastapi uvicorn ``` ```python # server.py import uuid from fastapi import FastAPI, Request from fastapi.responses import StreamingResponse from ag_ui.core import ( PROTOCOL_VERSION, RunAgentInput, RunStartedEvent, RunFinishedEvent, TextMessageStartEvent, TextMessageContentEvent, TextMessageEndEvent, ) from ag_ui.encoder import EventEncoder app = FastAPI() @app.post("/") async def run_agent(input_data: RunAgentInput, request: Request): encoder = EventEncoder(accept=request.headers.get("accept")) async def events(): yield encoder.encode(RunStartedEvent( thread_id=input_data.thread_id, run_id=input_data.run_id, protocol_version=PROTOCOL_VERSION, )) message_id = str(uuid.uuid4()) yield encoder.encode(TextMessageStartEvent(message_id=message_id, role="assistant")) for chunk in ["Hello ", "from ", "AG-UI!"]: yield encoder.encode(TextMessageContentEvent(message_id=message_id, delta=chunk)) yield encoder.encode(TextMessageEndEvent(message_id=message_id)) yield encoder.encode(RunFinishedEvent(thread_id=input_data.thread_id, run_id=input_data.run_id)) return StreamingResponse(events(), media_type=encoder.get_content_type()) ``` ```bash uvicorn server:app --port 8000 ``` **2. The client (TypeScript).** In a second terminal, in a new folder. Requires Node.js 20+. ```bash npm init -y && npm pkg set type=module npm install @ag-ui/client tsx ``` ```ts // client.ts import { HttpAgent } from "@ag-ui/client"; const agent = new HttpAgent({ url: "http://localhost:8000/" }); agent.addMessage({ id: crypto.randomUUID(), role: "user", content: "Hi there!" }); await agent.runAgent({}, { onRunStartedEvent: ({ event }) => console.log(`run started (AG-UI ${event.protocolVersion})`), onTextMessageContentEvent: ({ event }) => { process.stdout.write(event.delta); }, onRunFinishedEvent: () => console.log("\nrun finished"), }); ``` ```bash npx tsx client.ts ``` You should see `Hello from AG-UI!` stream in. Swap the server for any [supported framework](#integrations) and the client doesn't change. </details> ## Where AG-UI fits  AG-UI is one of three open, complementary agentic protocols. **MCP** gives agents tools and context, **A2A** lets agents work with other agents, and **AG-UI** brings agents to users. A single agent often uses all three, and AG-UI can front agents that speak MCP or A2A. [Read more →](https://docs.ag-ui.com/agentic-protocols) > [!NOTE] > **AG-UI or A2UI?** They work together. [A2UI](https://github.com/google/A2UI), MCP Apps, and Open-JSON-UI are *generative UI specs*: they describe what UI an agent wants to show. AG-UI is the *runtime protocol* that carries those payloads, along with everything else, between the agent and the app. [Learn more →](https://docs.ag-ui.com/concepts/generative-ui-specs) ## Integrations AG-UI is adopted by Google, Microsoft, Amazon, and Oracle, and built into most agent frameworks. Every framework below has a live demo in the [Dojo](https://dojo.ag-ui.com). <table> <tr> <td align="center" valign="top" width="25%"><img src=".github/readme/logos/langchain.svg" width="40" height="40" alt="LangChain logo"><br><b>LangChain</b><br><sub><a href="https://docs.copilotkit.ai/langgraph/">Docs</a> · <a href="https://dojo.ag-ui.com/langgraph-fastapi/feature/agentic_chat">Demo</a></sub></td> <td align="center" valign="top" width="25%"><img src=".github/readme/logos/crewai.svg" width="40" height="40" alt="CrewAI logo"><br><b>CrewAI</b><br><sub><a href="https://docs.copilotkit.ai/crewai-flows">Docs</a> · <a href="https://dojo.ag-ui.com/crewai/feature/agentic_chat">Demo</a></sub></td> <td align="center" valign="top" width="25%"><img src=".github/readme/logos/microsoft-agent-framework.svg" width="40" height="40" alt="Microsoft Agent Framework logo"><br><b>Microsoft Agent Framework</b><br><sub><a href="https://docs.copilotkit.ai/microsoft-agent-framework">Docs</a> · <a href="https://dojo.ag-ui.com/microsoft-agent-framework-python/feature/agentic_chat">Demo</a></sub></td> <td align="center" valign="top" width="25%"><img src=".github/readme/logos/google-adk.svg" width="40" height="40" alt="Google ADK logo"><br><b>Google ADK</b><br><sub><a href="https://docs.copilotkit.ai/adk">Docs</a> · <a href="https://dojo.ag-ui.com/adk-middleware/feature/agentic_chat">Demo</a></sub></td> </tr> <tr> <td align="center" valign="top" width="25%"><img src=".github/readme/logos/aws-strands.svg" width="40" height="40" alt="AWS Strands Agents logo"><br><b>AWS Strands Agents</b><br><sub><a href="https://docs.copilotkit.ai/aws-strands">Docs</a> · <a href="https://dojo.ag-ui.com/aws-strands/feature/agentic_chat">Demo</a></sub></td> <td align="center" valign="top" width="25%"><img src=".github/readme/logos/mastra.svg" width="40" height="40" alt="Mastra logo"><br><b>Mastra</b><br><sub><a href="https://docs.copilotkit.ai/mastra/">Docs</a> · <a href="https://dojo.ag-ui.com/mastra/feature/agentic_chat">Demo</a></sub></td> <td align="center" valign="top" width="25%"><img src=".github/readme/logos/pydantic-ai.svg" width="40" height="40" alt="Pydantic AI logo"><br><b>Pydantic AI</b><br><sub><a href="https://docs.copilotkit.ai/pydantic-ai/">Docs</a> · <a href="https://dojo.ag-ui.com/pydantic-ai/feature/agentic_chat">Demo</a></sub></td> <td align="center" valign="top" width="25%"><img src=".github/readme/logos/llamaindex.svg" width="40" height="40" alt="LlamaIndex logo"><br><b>LlamaIndex</b><br><sub><a href="https://docs.copilotkit.ai/llamaindex/">Docs</a> · <a href="https://dojo.ag-ui.com/llama-index/feature/agentic_chat">Demo</a></sub></td> </tr> <tr> <td align="center" valign="top" width="25%"><img src=".github/readme/logos/agno.svg" width="40" height="40" alt="Agno logo"><br><b>Agno</b><br><sub><a href="https://docs.copilotkit.ai/agno/">Docs</a> · <a href="https://dojo.ag-ui.com/agno/feature/agentic_chat">Demo</a></sub></td> <td align="center" valign="top" width="25%"><img src=".github/readme/logos/ag2.svg" width="40" height="40" alt="AG2 logo"><br><b>AG2</b><br><sub><a href="https://docs.copilotkit.ai/ag2/">Docs</a> · <a href="https://dojo.ag-ui.com/ag2/feature/agentic_chat">Demo</a></sub></td> <td align="center" valign="top" width="25%"><img src=".github/readme/logos/claude-agent-sdk.svg" width="40" height="40" alt="Claude Agent SDK logo"><br><b>Claude Agent SDK</b><br><sub><a href="integrations/claude-agent-sdk">Docs</a> · <a href="https://dojo.ag-ui.com/claude-agent-sdk-python/feature/agentic_chat">Demo</a></sub></td> <td align="center" valign="top" width="25%"><br><b><a href="https://docs.ag-ui.com/integrations">+11 more</a></b><br><sub>Antigravity, OpenAI Agents, watsonx, Spring AI, and others in the <a href="#full-list-of-integrations">full list</a></sub></td> </tr> </table> **Protocols:** [A2A](https://docs.copilotkit.ai/a2a-protocol) · [MCP](middlewares/mcp-middleware) · [MCP Apps](https://docs.copilotkit.ai/generative-ui-specs/mcp-apps) · [A2UI](middlewares/a2ui-middleware)\ **Clients:** [CopilotKit](https://github.com/CopilotKit/CopilotKit) (React, Angular, Vue, React Native) · [Slack & Teams](https://github.com/CopilotKit/channels-sdk) · [Terminal](https://docs.ag-ui.com/quickstart/clients) · [OpenBot](https://open.bot/builders) Don't see your framework? [Build an integration →](https://docs.ag-ui.com/quickstart/introduction) ### Full list of integrations <details> <summary><b>Show all integrations</b></summary> <br> - **Partners:** [LangChain](https://docs.copilotkit.ai/langgraph/) · [CrewAI](https://docs.copilotkit.ai/crewai-flows) - **Built in:** [Microsoft Agent Framework](https://docs.copilotkit.ai/microsoft-agent-framework) · [Google ADK](https://docs.copilotkit.ai/adk) ([JS](https://docs.ag-ui.com/integrations/google-adk-js)) · [Google Antigravity](https://docs.copilotkit.ai/google-antigravity) · [AWS Strands Agents](https://docs.copilotkit.ai/aws-strands) · [Mastra](https://docs.copilotkit.ai/mastra/) · [Pydantic AI](https://docs.copilotkit.ai/pydantic-ai/) · [Agno](https://docs.copilotkit.ai/agno/) · [LlamaIndex](https://docs.copilotkit.ai/llamaindex/) · [AG2](https://docs.copilotkit.ai/ag2/) - **More frameworks:** [Claude Agent SDK](integrations/claude-agent-sdk) · [Claude Managed Agents](integrations/claude-managed-agents) · [IBM watsonx Orchestrate](integrations/watsonx) · [Langroid](integrations/langroid) · [Spring AI](integrations/community/spring-ai) · [Cloudflare Agents](integrations/community/cloudflare-agents) · [Omnara](https://docs.ag-ui.com/integrations/omnara) · [Genkit (Go)](integrations/community/genkit/go) · [OpenAI Agents](integrations/openai-agents) - **Specs:** [Oracle Agent Spec](https://go.copilotkit.ai/copilotkit-oracle-docs) - **Deployment:** [Amazon Bedrock AgentCore](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-agui.html) Source for every integration lives in [`integrations/`](integrations) and [`middlewares/`](middlewares), and the demos in [`apps/dojo`](apps/dojo). </details> ## SDKs | Language | Install | Reference | | --- | --- | --- | | **TypeScript** | `npm install @ag-ui/client` | [Docs](https://docs.ag-ui.com/sdk/js/core/overview) · [Source](sdks/typescript) | | **Python** | `pip install ag-ui-protocol` | [Docs](https://docs.ag-ui.com/sdk/python/core/overview) · [Source](sdks/python) | | **.NET** | `dotnet add package AGUI.Client` | [Docs](https://docs.ag-ui.com/sdk/dotnet/client/overview) · [Source](sdks/dotnet) | **Community SDKs:** [Kotlin](sdks/community/kotlin) · [Go](sdks/community/go) · [Java](sdks/community/java) · [Dart](sdks/community/dart) · [Rust](sdks/community/rust) · [Ruby](sdks/community/ruby) · [C++](sdks/community/c++) · [Swift](sdks/community/swift) ## Features: what you can build Each building block maps to events in the spec, and each has a live demo in the [AG-UI Dojo](https://dojo.ag-ui.com). | Building block | What it does | Try it | | --- | --- | --- | | **Streaming chat** | Token-by-token messages across multi-turn sessions, with cancel and resume | [Demo](https://dojo.ag-ui.com/langgraph-fastapi/feature/agentic_chat) | | **Generative UI** | Agents render typed components, or declarative UI with [A2UI](https://github.com/google/A2UI) and MCP Apps | [Demo](https://dojo.ag-ui.com/langgraph-fastapi/feature/tool_based_generative_ui) | | **Shared state** | A typed store the agent and app both read and write, synced with snapshots and JSON Patch deltas | [Demo](https://dojo.ag-ui.com/langgraph-fastapi/feature/shared_state) | | **Frontend tools** | The agent calls tools that run in the app, and gets the result back | [Demo](https://dojo.ag-ui.com/langgraph-fastapi/feature/human_in_the_loop) | | **Human in the loop** | Runs end with an `interrupt` outcome; the user appr - sdks/community/swift/CLAUDE.md (9239 bytes)
# AGUISwift ## Project Context The AG-UI Swift SDK is an open-source Swift framework for building AI agent user interfaces that implement the Agent User Interaction Protocol (AG-UI). It provides real-time streaming communication between Swift applications and AI agents. ### Architecture ``` AGUICore (Foundation layer - Protocol types • Event models • Message definitions) ↓ AGUIClient (Low-level client infrastructure and transport implementations - HttpAgent • AbstractAgent • SseParser • EventStreamManager ) ↓ ├─→ AGUITools (Tool execution framework for extending agent capabilities - ToolExecutor • ToolRegistry • ToolExecutionManager) └─→ AGUIAgentSDK (High-level APIs for common agent interaction patterns - AgUiAgent • StatefulAgUiAgent • Builders) ↓ Application ``` ### Key Directories - `Sources/AGUIAgentSDK/` - High-level APIs for common agent interaction patterns. - `Sources/AGUIClient/` - Low-level client infrastructure and transport implementations. - `Sources/AGUICore/` - Core framework source, Protocol types, events, and message definitions. - `Sources/AGUITools/` - Tool execution framework for extending agent capabilities. - `Tests/` - Test suites with mock protocols ## Development Standards ### Swift 6.2 Requirements - **Minimum**: iOS 15+, macOS 13+, Swift 5.9 - **Concurrency**: Use `async/await`, actors, and `@MainActor` isolation by default - **Data Safety**: All public types must be `Sendable`; use `@concurrent` for explicit parallel execution - **Value Types**: Prefer `struct` over `class`; use actors for shared mutable state ### API Design Principles - Protocol-first: Define behavior contracts before implementations - Composition over inheritance: Use protocol composition (`Runnable & Observable`) - Fluent interfaces: Enable chaining with `@discardableResult` where appropriate - Progressive disclosure: Simple defaults, advanced configuration via builders ### Naming Conventions - Types/Protocols: `UpperCamelCase` (e.g., `AgentProtocol`, `MemoryStore`) - Methods: Verb phrases for mutations (`execute`, `store`), noun phrases for accessors (`configuration`) - Boolean properties: Use `is`, `has`, `should` prefixes - Generics: Descriptive names (`Element`, `Input`, `Output`) over single letters when unclear ## Workflow ### Verification Commands ```bash swift build # Build framework swift test # Run test suite swift test --filter AgentTests # Run specific tests swift package plugin --allow-writing-to-package-directory swiftformat # Format code ``` ### Before Committing 1. Run `swift build` - ensure no compilation errors 2. Run `swift test` - all tests must pass 3. Run SwiftFormat - code must be formatted (`swift package plugin --allow-writing-to-package-directory swiftformat`) 4. Run SwiftLint - code must pass linting checks (`swiftlint lint` - install via Homebrew if needed) 5. Verify `Sendable` conformance on public types 6. Ensure documentation comments on public APIs ### Branch Naming - `feature/agent-memory-system` - `fix/orchestration-race-condition` - `refactor/protocol-conformance` ## Technical Guidelines ### Protocols - Use `associatedtype` for type-safe generic protocols - Provide protocol extensions with sensible defaults - Mark class-only protocols with `AnyObject` constraint - See `Sources/SwiftAgents/Core/Protocols/` for patterns ### Concurrency - Use structured concurrency (`TaskGroup`, `async let`) over unstructured - Annotate with `@MainActor` for UI-bound code - Use `actor` for shared state requiring synchronization - Apply `nonisolated` explicitly when needed for cross-isolation calls ### Memory Systems - `ConversationMemory`: Short-term, token-limited context - `VectorMemory`: Long-term semantic retrieval (requires embedding provider) - `SummaryMemory`: Compressed conversation history ### Logging - Use `swift-log` for cross-platform compatibility (Apple platforms + Linux servers) - Call `Log.bootstrap()` once at application startup to configure logging - Never use `print()` statements in production code - Use category-specific loggers: - `Log.agents`: Agent lifecycle and execution - `Log.memory`: Memory system operations - `Log.tracing`: Observability and tracing events - `Log.metrics`: Performance and usage metrics - `Log.orchestration`: Multi-agent coordination - Choose appropriate log levels: `.trace`, `.debug`, `.info`, `.notice`, `.warning`, `.error`, `.critical` - **Privacy Note**: Unlike `os.Logger`, swift-log does not support `privacy:` parameter annotations - Do not log sensitive user data, credentials, or PII in production - Configure log handlers to redact sensitive information at runtime - Default behavior logs all interpolated values as-is - Example: `Log.memory.error("Failed to save: \(error.localizedDescription)")` - For Apple-only code, `OSLogTracer` is available with privacy annotations wrapped in `#if canImport(os)` ### Testing Strategy (TDD Required) - **Test-Driven Development is mandatory** for all new features and bug fixes - All protocols have corresponding `Mock*` implementations in test targets - Test async code with `XCTestExpectation` or async test methods ### TDD Workflow Follow Red-Green-Refactor cycle for all development: 1. **Red**: Write failing tests first - Define expected behavior through test cases - Use `test-specialist` agent to design comprehensive test coverage - Tests must fail initially (verifies test is meaningful) 2. **Green**: Write minimal implementation - Only write enough code to make tests pass - No premature optimization or extra features - Focus on satisfying test assertions 3. **Refactor**: Improve code quality - Clean up implementation while keeping tests green - Apply Swift patterns and conventions - Use `code-reviewer` agent to verify refactoring **TDD Guidelines**: - Never write implementation before tests - One test case per behavior/feature - Test edge cases and error conditions - Mock external dependencies (LLM providers, network) - Run `swift test` frequently during development ## Sub-Agents Use specialized agents for focused expertise. Delegate proactively: | Agent | When to Use | |-------|-------------| | `context-builder` | **Long-running tasks**, gathering requirements, researching before implementation | | `api-designer` | Designing public APIs, naming decisions, fluent interfaces | | `protocol-architect` | Type hierarchies, protocol composition, POP patterns | | `concurrency-expert` | Async code, actors, Sendable conformance, data-race safety | | `macro-engineer` | Implementing or modifying Swift macros | | `code-reviewer` | After code changes, before commits | | `test-specialist` | Writing tests, creating mocks, test coverage | | `framework-architect` | Multi-agent orchestration patterns, coordination design | ### Context Management (Long-Running Tasks) **Always use `context-builder` agent** at the start of complex or long-running tasks to: - Gather comprehensive requirements before implementation - Research existing codebase patterns and conventions - Identify dependencies and integration points - Create a clear roadmap before delegating to specialist agents **Context Preservation Workflow**: 1. **Start**: Use `context-builder` to research and gather context 2. **Plan**: Document findings and create implementation plan 3. **Execute**: Delegate to specialist agents with clear context handoffs 4. **Checkpoint**: Re-invoke `context-builder` for multi-phase tasks 5. **Update**: Keep plan documents and memory updated throughout **When to use `context-builder`**: - Tasks spanning multiple files or components - Features requiring understanding of existing architecture - Bug fixes requiring root cause investigation - Any task expected to take more than a few interactions ### Delegation Guidelines - **Before implementing**: Use `context-builder` to research, then `api-designer` and `protocol-architect` - **During implementation**: Use `concurrency-expert` for async code, `macro-engineer` for macros - **After changes**: Always run `code-reviewer` before committing - **For tests**: Delegate to `test-specialist` for mock patterns and coverage (TDD: tests first!) **TDD + Sub-Agent Workflow** (for complex features): 1. `context-builder` → research existing patterns and requirements 2. `test-specialist` → write failing tests first (Red phase) and keep async/time-sensitive tests deterministic (no flakiness) 3. `protocol-architect` → design abstractions to satisfy tests 4. `api-designer` → refine public interface 5. `concurrency-expert` → verify thread safety 6. `code-reviewer` → final review (ensure tests pass) ## Quick References - API patterns: See `https://github.com/ag-ui-protocol/ag-ui/tree/main/sdks/community/kotlin` - Protocol design: See `https://github.com/ag-ui-protocol/ag-ui` - Understanding how AG-UI complements and works with MCP and A2A: See `https://docs.ag-ui.com/llms-full.txt` ## Git Commit Guidelines When creating commits: - Follow conventional commit format - Keep the first line under 50 characters - Do not include AI attribution in commit messages - sdks/dotnet/AGENTS.md (15278 bytes)
# AG-UI .NET SDK - Coding Instructions Refer to `docs/architecture.md` for the design philosophy, package structure, and how the subsystems fit together. ## Prerequisites - .NET 10 SDK (see `global.json` for the exact version; `rollForward: minor` is configured). - All commands below run from the `sdks/dotnet/` directory. ### Provisioning a repo-local SDK (optional, hermetic) To build against the exact pinned SDK without touching the machine-wide install, use the provisioning scripts. They download the SDK from `global.json`, plus the .NET 8 and 9 runtimes the multi-targeted test projects run on, into a gitignored `.dotnet/` folder and build/test against it only (`DOTNET_MULTILEVEL_LOOKUP=0`): ```bash ./build.cmd # Windows: provision + build ./build.sh # Linux/macOS: provision + build ./build.sh --test # provision + test ``` `eng/install-dotnet.ps1` / `eng/install-dotnet.sh` perform just the provisioning step and accept `-ExtraChannel`/`--extra-channel` (or `-ExtraVersion`/`--extra-version`) to install an additional SDK (e.g. a .NET 11 preview) side-by-side. ## Build ```bash dotnet build ``` The solution file is `AGUI.slnx`. `Directory.Build.props` sets `LangVersion` to `latest`, enables nullable, and treats warnings as errors. `Directory.Packages.props` centralizes all NuGet versions (Central Package Management). `Directory.Build.targets` conditionally enables `PublicApiAnalyzers` when a `PublicAPI.Shipped.txt` exists in the project. ## Running tests ```bash dotnet test ``` This runs every unit test and integration test project in the solution. For faster feedback during development you can target individual projects as described below. ### Unit tests One unit-test project per `src/` package: | Project | Covers | Key patterns | |---|---|---| | `tests/AGUI.Abstractions.UnitTests/` | Event serialization round-trips, backward compatibility against TypeScript JSON fixtures | `JsonDocument` property assertions, `FixtureLoader` for cross-SDK fixtures in `Compatibility/` | | `tests/AGUI.Client.UnitTests/` | Client builders, protocol rules, transport negotiation | Standard xunit assertions | | `tests/AGUI.Formatting.UnitTests/` | `SseEventStreamFormatter` read/write round-trips, the SSE wire format | Standard xunit assertions | | `tests/AGUI.Protobuf.UnitTests/` | Protobuf codec, `ProtobufEventStreamFormatter`, `JsonElement`↔`google.protobuf.Value` bridge | Standard xunit assertions | | `tests/AGUI.Server.UnitTests/` | `ChatResponseUpdate` → AG-UI event conversion, mixed tool invocation, interrupt content | Standard xunit assertions | Run a single unit test project: ```bash dotnet test tests/AGUI.Abstractions.UnitTests/ ``` Test files live directly under the test project root (not mirrored into `Events/` subfolders). The standard pattern for an event test: ```csharp [Fact] public void Serialization_RoundTrips() { var evt = new RunStartedEvent { ThreadId = "t1", RunId = "r1", Timestamp = 1234567890 }; var json = JsonSerializer.Serialize(evt, AGUIJsonSerializerContext.Default.RunStartedEvent); using var doc = JsonDocument.Parse(json); Assert.Equal("RUN_STARTED", doc.RootElement.GetProperty("type").GetString()); Assert.Equal("t1", doc.RootElement.GetProperty("threadId").GetString()); } ``` Verify concrete JSON property names by parsing with `JsonDocument`. Don't just assert on the deserialized object—that doesn't catch naming bugs. #### Backward compatibility tests `tests/AGUI.Abstractions.UnitTests/Compatibility/` contains JSON fixture files produced by the TypeScript reference implementation. Tests deserialize these fixtures into .NET types and verify the values match. This catches wire-format drift between implementations. Use `FixtureLoader` to load fixture arrays. Each test method covers one event shape. ### Integration tests `tests/AGUI.Hosting.AspNetCore.IntegrationTests/` exercises the full HTTP pipeline — posting `RunAgentInput`, streaming events over the wire, and verifying the results through both the raw event stream and the `AGUIChatClient` (`IChatClient`) abstraction. (The project name is intentionally kept even though the server package was renamed to `AGUI.Server`.) Tests use `WebApplicationFactory<TProgram>` and `ConfigureTestServices` to inject `DelegatingStreamingChatClient` (a `Func`-based `IChatClient`). The test infrastructure supports recording and replaying `ChatResponseUpdate` sequences so tests run deterministically without calling a real LLM. Each test is a `[Theory]` parameterized over a `TransportFormat` (`Json` and `Protobuf`); both transports decode to identical streams, so the same Verify baselines are reused across formats. Run integration tests: ```bash dotnet test tests/AGUI.Hosting.AspNetCore.IntegrationTests/ ``` The integration test project references every `samples/GettingStarted/Step*` project. The `Samples/GettingStarted/` subfolder contains tests that spin up each sample as a real host, replay pre-recorded `ChatResponseUpdate` sequences via `FakeChatClient`, and verify the output using `Verify.Xunit` snapshot files (`.verified.txt`). When a snapshot test fails, run with `--environment VERIFY_ACCEPT=true` or review the `.received.txt` diff. ### What not to do in tests - Don't use reflection to enumerate types or verify membership. - Don't assert behavior by comparing full JSON strings (fragile). Parse with `JsonDocument` and check individual properties. ## Running samples Each sample under `samples/GettingStarted/` (Step01 through Step14) is a Server/Client pair. The server hosts an AG-UI endpoint as an ASP.NET Core app (the ASP.NET glue comes from the shared `samples/AGUI.Samples.Shared` project); the client drives it through `AGUIChatClient`. To run a sample server manually: ```bash dotnet run --project samples/GettingStarted/Step01_GettingStarted/Step01_GettingStarted.Server/ ``` The `samples/AGUIClientServer/` directory contains a full Dojo server with multiple agent scenarios. ## Project layout - `src/AGUI.Abstractions/` — Protocol types: events, messages, tools, capabilities, serialization context (`AGUIJsonSerializerContext`), and `AGUIJsonUtilities.RegisterInterruptContentTypes`. - `src/AGUI.Formatting/` — Wire-format formatters: `IAGUIEventStreamFormatter` (bidirectional read/write) and `SseEventStreamFormatter` (the SSE wire format). Depends on Abstractions + `System.Net.ServerSentEvents`. - `src/AGUI.Protobuf/` — Protobuf codec (the `internal` `AGUIProtobuf`), the public `ProtobufEventStreamFormatter`, and the `JsonElement`↔`google.protobuf.Value` bridge. The generated proto types are `internal`; the `.proto` schema is referenced from `sdks/typescript/packages/proto` (not copied). Depends on Abstractions + Formatting + `Google.Protobuf`. - `src/AGUI.Client/` — `AGUIChatClient` (`IChatClient`, constructed from `AGUIChatClientOptions`), `AGUIHttpTransport`/`IAGUITransport`, and the public negotiation primitives (`AGUIEventStreamHandler` `DelegatingHandler` + `ReadAGUIEventStreamAsync`) callers can wire into their own `HttpClient` to request protobuf. Depends on Formatting. - `src/AGUI.Server/` — Framework-agnostic server-side adapter (no ASP.NET): `RunAgentInputExtensions.ToChatRequestContext`, `ChatRequestContext`, `ChatResponseUpdateAGUIExtensions.AsAGUIEventStreamAsync`, fluent `AGUIStreamOptions`, `AGUIConstants`. Depends on Abstractions + `M.E.AI.Abstractions`. - `samples/AGUI.Samples.Shared/` — The only ASP.NET project (`FrameworkReference Microsoft.AspNetCore.App`). Hosts the ASP.NET glue: `AGUIResults` (negotiating `IResult`), `AGUIEventStreamResult`, the `MapAGUI` endpoint extension, and `AddAGUI` DI registration. - `tests/AGUI.Abstractions.UnitTests/` — Serialization round-trip and backward compatibility tests. - `tests/AGUI.Client.UnitTests/` — Client builder, protocol, and transport-negotiation tests. - `tests/AGUI.Formatting.UnitTests/` — SSE formatter round-trip tests. - `tests/AGUI.Protobuf.UnitTests/` — Protobuf codec and formatter tests. - `tests/AGUI.Server.UnitTests/` — Stream conversion unit tests. - `tests/AGUI.Hosting.AspNetCore.IntegrationTests/` — End-to-end tests with `WebApplicationFactory`, parameterized over `TransportFormat`, including sample replay tests (name kept after the `AGUI.Server` rename). - `samples/GettingStarted/` — Progressive Server/Client sample pairs (Step01–Step14; Step12 = parallel tool calls, Step13 = protobuf, Step14 = OpenTelemetry tracing). - `samples/AGUIClientServer/` — Full Dojo server with multiple agent scenarios. ## Endpoint pattern Every AG-UI endpoint follows this shape (the GettingStarted samples map it via the shared `app.MapAGUI("/")` helper from `samples/AGUI.Samples.Shared`): 1. `MapPost(pattern, handler)` — receives `[FromBody] RunAgentInput`. 2. Adapt to MEAI with `var ctx = input.ToChatRequestContext(jsonSerializerOptions, streamOptions?)`. The returned `ChatRequestContext` carries the converted `ChatMessage` list and a configured `ChatOptions` (with the input stashed under `AdditionalProperties[AGUIConstants.RunAgentInputKey]` and client tools already routed through the approval-flow pipeline). 3. Call `chatClient.GetStreamingResponseAsync(ctx.Messages, ctx.ChatOptions, cancellationToken)`. 4. Pipe through `.AsAGUIEventStreamAsync(ctx, cancellationToken)` to get the AG-UI event stream. 5. Return `AGUIResults.Events(events, httpContext, cancellationToken)` (from `AGUI.Samples.Shared`). This negotiating `IResult` inspects the request `Accept` header and encodes the stream as Server-Sent Events (the default) or protobuf when the server registers `ProtobufEventStreamFormatter` as an `IAGUIEventStreamFormatter` and the client accepts it. Endpoints no longer hand-write `TypedResults.ServerSentEvents(...)`. If the endpoint needs framework-specific content mapping (e.g. reasoning, custom workflow events) or a custom interrupt classifier, configure them on the `AGUIStreamOptions` instance passed to `ToChatRequestContext` via fluent `MapContent(...)` / `MapInterrupt(...)` / `MapCall(...)` / `MapResult(...)` calls. ## Public API surface Each `src/` project has `PublicAPI.Shipped.txt` and `PublicAPI.Unshipped.txt` managed by `Microsoft.CodeAnalysis.PublicApiAnalyzers`. When you add or change a public member, update `PublicAPI.Unshipped.txt`. The build will fail if you forget. ## JSON serialization Every protocol type must be AOT-compatible. The rules: - Add `[JsonSerializable(typeof(T))]` to `AGUIJsonSerializerContext` for each new type. - Use `[JsonPropertyName("camelCase")]` on every serialized property. The context also sets `PropertyNamingPolicy = CamelCase`, but explicit attributes are still required for clarity and PublicAPI analyzer compatibility. - Every nullable property of a wire type carries its own ignore condition, normally `[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]`. The spec generator emits it on the generated types; add it by hand on hand-written ones. `DefaultIgnoreCondition = WhenWritingNull` on `AGUIJsonSerializerContext` is not enough on its own: it lives on the context's own options and does not follow the context into a host's `JsonSerializerOptions`. Hosts that insert the bare context into their resolver chain (Microsoft Agent Framework's `ConfigureAGUIJsonOptions` does) would otherwise write `"parentRunId": null` and the like, which 1.0 receivers reject. `NullOmissionTest` sweeps every wire type through such host-owned options and fails on a missing attribute. A `null` that is a value (inside state, a patch, metadata, `CUSTOM.value`) is unaffected: the attribute only drops the property's own null. - A non-nullable `JsonElement` that the contract lets a producer omit needs `[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]` instead — it is never `null`, so the null rule cannot reach it, and an unset `JsonElement` cannot be written at all. See `AGUITool.Parameters` and `RunAgentInput`. - When composing AG-UI types into your own `JsonSerializerOptions`, insert `AGUIJsonUtilities.DefaultTypeInfoResolver` (at the front of the chain, before any resolver that answers for arbitrary types) rather than `AGUIJsonSerializerContext.Default`. - Initialize required string properties to `string.Empty`. Initialize collections to `[]`. - Polymorphic types use a hand-written `JsonConverter<T>` keyed on a discriminator property (see `BaseEventJsonConverter`, `AGUIMessageJsonConverter`, `AGUIInputContentJsonConverter`). - Serialize via the source-generated context: `AGUIJsonSerializerContext.Default.{TypeName}`. - Never use `JsonSerializer.Serialize<object>(...)` or pass raw strings through without parsing. ### Adding a new event type 1. Create the class in `src/AGUI.Abstractions/Events/`, deriving from `BaseEvent`. 2. Override `Type` to return the constant from `AGUIEventTypes`. 3. Add the constant to `AGUIEventTypes`. 4. Add `[JsonSerializable(typeof(T))]` to `AGUIJsonSerializerContext`. 5. Add a read/write case to `BaseEventJsonConverter`. 6. Add the type signature to `PublicAPI.Unshipped.txt`. 7. Write a serialization round-trip test in `tests/AGUI.Abstractions.UnitTests/`. ## Code style - One class per file. File name matches type name. - `sealed` on every non-abstract class. - No `record` types. Use `sealed class` with properties. - No tuples in public APIs. Define a named type. - Always use braces for `if`, `for`, `foreach`, `while`, etc. - No XML docs (`///`) on `internal` or `private` members. - `ConfigureAwait(false)` on all `await` calls in library code. - `[EnumeratorCancellation]` on `CancellationToken` parameters in `IAsyncEnumerable` methods. - Use `ArgumentNullThrowHelper.ThrowIfNull(...)` for public API argument validation. It maps to the BCL `ArgumentNullException.ThrowIfNull` on modern targets and to a manual throw on `netstandard2.0`/`net472`. It and the C# compiler-feature polyfills (`init`, `required`) live in `src/Shared/`, linked into each multi-targeted project (the down-level polyfills are conditionally compiled for `netstandard2.0`/`net472` only). ## Naming - Event classes: `{Name}Event` (`RunStartedEvent`, `TextMessageContentEvent`). - Event type discriminators: `SCREAMING_SNAKE_CASE` string constants in `AGUIEventTypes` (`"RUN_STARTED"`, `"TEXT_MESSAGE_START"`). The C# member name uses PascalCase (`AGUIEventTypes.RunStarted`). - Outcome and role constants: lowercase string constants in dedicated static classes (`RunFinishedOutcome.Interrupt = "interrupt"`, `AGUIRoles.Assistant = "assistant"`). Never enums. - Options classes: `AGUI{Purpose}Options` (`AGUIStreamOptions`). - Extension classes: `{Target}Extensions` (`ChatResponseUpdateAGUIExtensions`, `AGUIToolExtensions`). - Test classes: `{TypeUnderTest}Test` (`RunStartedEventTest`, `ChatResponseUpdateAGUIExtensionsTest`). - Compatibility test classes: `{Category}CompatibilityTest` in the `Compatibility/` subfolder. - Namespace for DI extensions: `Microsoft.Extensions.Dependen - sdks/dotnet/plugins/ag-ui-dotnet/skills/agui-dotnet-client-tools/SKILL.md (4325 bytes)
--- name: agui-dotnet-client-tools description: > Expose client-side (frontend) tools to an AG-UI agent with the AG-UI .NET SDK — C# functions that run in the CLIENT app (read local state, GPS, UI, device APIs), where the client executes the call and returns the result so the run continues. USE FOR: declaring an AIFunction in the client and passing it via ChatOptions.Tools to AGUIChatClient; having the client execute a tool the model requested and feed the result back automatically; understanding why no UseFunctionInvocation is needed on the client (AGUIChatClient already invokes functions); what the server must do (UseFunctionInvocation + TerminateOnUnknownCalls) so it forwards an unknown/client tool instead of erroring. DO NOT USE FOR: tools that run on the server/backend (use agui-dotnet-server-tools); pausing for human approval/input before acting (interrupts / human-in-the-loop); plain chat (use agui-dotnet-streaming-chat); shared state, generative UI, multimodal, or protobuf. --- # AG-UI .NET — client (frontend) tools Goal: let the model call a function that runs in the client app — to read something only the client has (location, local state, UI selection, a device API) — with the client executing the call and returning the result so the run continues to a final answer. A client tool is an ordinary `Microsoft.Extensions.AI` `AIFunction` you attach to the request via `ChatOptions.Tools`. `AGUIChatClient` is itself a function-invoking client, so it runs the tool locally and sends the result back automatically — you do not wrap it in `UseFunctionInvocation`. ## Install ```bash dotnet add package AGUI.Client ``` `Microsoft.Extensions.AI` supplies `AIFunctionFactory`, `ChatOptions`, and `AITool`. Run `dotnet package search AGUI.Client --exact-match` for the current version. ## Declare a tool and pass it in options Define the function in the client, wrap it with `AIFunctionFactory.Create`, and put it on `ChatOptions.Tools`: ```csharp using System.ComponentModel; using AGUI.Client; using Microsoft.Extensions.AI; [Description("Get the user's current location from GPS.")] static string GetUserLocation() => "Amsterdam, Netherlands (52.37°N, 4.90°E)"; using var httpClient = new HttpClient(); IChatClient client = new AGUIChatClient(new(httpClient, "http://localhost:5003")); var options = new ChatOptions { Tools = [AIFunctionFactory.Create(GetUserLocation)] }; var messages = new List<ChatMessage> { new(ChatRole.User, "What's fun to do near me?") }; await foreach (var update in client.GetStreamingResponseAsync(messages, options)) { Console.Write(update.Text); } ``` When the model decides to call `GetUserLocation`, `AGUIChatClient` invokes it on this machine, returns the result to the server, and the run continues — the streamed text you print already reflects the location. ## What the server must do The server forwards a tool it doesn't own to the client instead of trying to run it. Register the server's chat client with function invocation and `TerminateOnUnknownCalls` so an unknown (client) tool ends the server turn cleanly and is surfaced to the client to execute: ```csharp builder.Services.AddChatClient(/* provider IChatClient */) .UseFunctionInvocation(fic => fic.TerminateOnUnknownCalls = true); ``` The server declares none of the client's tools; it only needs to forward them. ## Anti-patterns - **Wrapping the client in `UseFunctionInvocation`.** `AGUIChatClient` already invokes functions; adding another function-invoking layer double-handles the call and can execute it twice or strip the AG-UI tool routing. Pass the tool through `ChatOptions.Tools` and let the client invoke it. - **A client tool that returns before the side effect it reports completes.** The model continues the run the instant the function returns, so a tool that says "saved" while an async write is still in flight makes the model narrate a result that has not happened. Await the real work inside the function before returning. ## Verify 1. Run a prompt the model can only answer using the client tool. The function body executes locally (set a breakpoint or log inside it). 2. The streamed answer reflects the tool's return value, and the run ends `RUN_FINISHED` in a single client call — you wrote no code to send the tool result back. - sdks/dotnet/plugins/ag-ui-dotnet/skills/agui-dotnet-human-in-the-loop/SKILL.md (6167 bytes)
--- name: agui-dotnet-human-in-the-loop description: > Pause an AG-UI agent run for a human, then resume it, with the AG-UI .NET SDK — gate a sensitive tool behind explicit approval, or interrupt a run to collect free-form input from the user before continuing. USE FOR: requiring human approval before a tool executes (ApprovalRequiredAIFunction + ToolApprovalRequestContent/ToolApprovalResponseContent, resume by appending the request + CreateResponse(approved)); pausing a run to ask the user a question and resuming with their answer (InterruptRequestContent / InterruptResponseContent, RunAgentInput.Resume); how a paused run surfaces as RUN_FINISHED outcome=interrupt and how the client detects and answers it. DO NOT USE FOR: tools that run without approval on the server (use agui-dotnet-server-tools) or in the client (use agui-dotnet-client-tools); plain chat (use agui-dotnet-streaming-chat); shared state, generative UI, multimodal, or protobuf. --- # AG-UI .NET — human in the loop (approval & interrupts) Goal: stop an agent run at a decision point, hand control to a person, and resume the same run with their decision — either approving a sensitive tool call or supplying input the agent asked for. A paused run completes its turn with `RUN_FINISHED { outcome: interrupt }`. The client inspects the response, gets the human decision, then sends a follow-up turn that carries the answer; the SDK reconnects it to the paused tool call so the run continues. ## Approval: gate a tool behind a human yes/no This is the simple path and needs no custom endpoint code — `ToChatRequestContext` handles the resume. ### Server: wrap the sensitive tool Wrap the function in `ApprovalRequiredAIFunction`. When the model calls it, the function-invoking client raises a `ToolApprovalRequestContent` instead of executing: ```csharp using Microsoft.Extensions.AI; var deleteFile = new ApprovalRequiredAIFunction( AIFunctionFactory.Create(DeleteFile, "delete_file", "Deletes a file.")); builder.Services.AddChatClient(/* provider IChatClient */) .ConfigureOptions(o => (o.Tools ??= []).Add(deleteFile)) .UseFunctionInvocation(); ``` ### Client: detect the request, decide, resume The first turn returns a `ToolApprovalRequestContent`. Show it to the human, then resume by appending the request and the human's response and streaming again: ```csharp using Microsoft.Extensions.AI; var messages = new List<ChatMessage> { new(ChatRole.User, "Delete report-draft.txt") }; var turn1 = new List<ChatResponseUpdate>(); await foreach (var u in client.GetStreamingResponseAsync(messages)) { turn1.Add(u); } var request = turn1.SelectMany(u => u.Contents) .OfType<ToolApprovalRequestContent>() .FirstOrDefault(); if (request is { ToolCall: FunctionCallContent call }) { bool approved = AskHuman($"Run {call.Name}?"); // your UI / prompt messages.Add(new ChatMessage(ChatRole.Assistant, [request])); messages.Add(new ChatMessage(ChatRole.User, [request.CreateResponse(approved)])); await foreach (var u in client.GetStreamingResponseAsync(messages)) { Console.Write(u.Text); // runs the tool if approved, skips it if not } } ``` On the resumed turn the SDK re-pairs the approval request and response so the function-invoking client executes (or skips) the underlying call. ## Interrupt: ask the user for input mid-run When the agent needs free-form input (not a yes/no), pause with an `InterruptRequestContent` and resume with an `InterruptResponseContent`. The client side mirrors approval: ```csharp using AGUI.Abstractions; var interrupt = turn1.SelectMany(u => u.Contents) .OfType<InterruptRequestContent>() .FirstOrDefault(); if (interrupt is not null) { var answer = AskHuman(interrupt.Message); // e.g. a username var payload = JsonSerializer.SerializeToElement(new { response = answer }); messages.Add(new ChatMessage(ChatRole.Assistant, [interrupt])); messages.Add(new ChatMessage(ChatRole.User, [new InterruptResponseContent(interrupt.RequestId) { Payload = payload }])); await foreach (var u in client.GetStreamingResponseAsync(messages)) { Console.Write(u.Text); } } ``` `AGUIChatClient` encodes the response as `RunAgentInput.Resume[]` on the wire. The interrupt request carries a `Reason` (e.g. `InterruptReasons.InputRequired`), a `Message` to display, and an optional `ResponseSchema` describing the expected payload. On the server, raise the interrupt by yielding a content-bearing update from a `DelegatingChatClient`. Typically you bridge a model tool call into the interrupt: detect the model's `FunctionCallContent`, emit an `InterruptRequestContent(call.CallId)` instead, and on resume rewrite the `InterruptResponseContent` back into the `FunctionCallContent` + `FunctionResultContent` pair the model expects, so it continues as if the tool returned the user's answer. ## Anti-patterns - **Resuming with only the response content.** Both the request (`ToolApprovalRequestContent` / `InterruptRequestContent`) and the matching response must be in the resumed message list, with the same id; the SDK pairs them to reconnect to the paused call. Sending the response alone leaves the run with nothing to resume. - **Instructing the model to ask for confirmation in its prompt.** The approval gate is structural — the wrapped tool pauses the run on its own. A prompt that also tells the model to "ask the user to confirm" produces a redundant text question and a second round-trip. Tell the model to call the tool directly and let the gate handle approval. ## Verify 1. First turn ends without running the side effect: the stream finishes `RUN_FINISHED { outcome: interrupt }` and the response contains a `ToolApprovalRequestContent` (or `InterruptRequestContent`). 2. After resuming with approval, the tool's effect occurs and the run finishes normally; after resuming with a rejection, the effect does not occur and the model proceeds without it. 3. For input interrupts, the agent's final answer reflects the value the human supplied. - sdks/dotnet/plugins/ag-ui-dotnet/skills/agui-dotnet-multimodal/SKILL.md (3276 bytes)
--- name: agui-dotnet-multimodal description: > Send images and other binary/file content to an AG-UI agent with the AG-UI .NET SDK — attach pictures (or audio, PDFs, etc.) to a user message so a multimodal model can see them. USE FOR: building a user ChatMessage with mixed content parts (TextContent plus DataContent for inline bytes, or UriContent for a hosted URL); choosing inline bytes vs a URL reference; setting the correct media type; sending the message through AGUIChatClient so the content parts cross the AG-UI wire to a vision/multimodal model. DO NOT USE FOR: plain text chat (use agui-dotnet-streaming-chat); tool calls (use agui-dotnet-server-tools / agui-dotnet-client-tools); structured shared state (use agui-dotnet-shared-state); reasoning traces, interrupts, generative UI, or protobuf. --- # AG-UI .NET — multimodal messages Goal: include an image (or other binary content) in a turn so a multimodal model can describe or reason about it. A multimodal message is an ordinary `Microsoft.Extensions.AI` `ChatMessage` whose `Contents` mixes a `TextContent` with one or more binary parts. `AGUIChatClient` carries those parts across the AG-UI wire; the server streams the model's reply as usual. ## Install ```bash dotnet add package AGUI.Client ``` `Microsoft.Extensions.AI` supplies `ChatMessage`, `TextContent`, `DataContent`, and `UriContent`. ## Attach inline bytes Use `DataContent(bytes, mediaType)` to embed the data directly in the message: ```csharp using AGUI.Client; using Microsoft.Extensions.AI; byte[] imageBytes = await File.ReadAllBytesAsync("photo.png"); var messages = new List<ChatMessage> { new(ChatRole.User, [ new TextContent("Describe this image"), new DataContent(imageBytes, "image/png"), ]), }; await foreach (var update in client.GetStreamingResponseAsync(messages)) { Console.Write(update.Text); } ``` The media type must match the bytes (`image/png`, `image/jpeg`, `audio/wav`, `application/pdf`, …) so the model decodes them correctly. ## Reference a hosted URL When the asset already lives at a URL, use `UriContent(uri, mediaType)` instead — the bytes never pass through your process: ```csharp new ChatMessage(ChatRole.User, [ new TextContent("What's in this picture?"), new UriContent("https://example.com/cat.jpg", "image/jpeg"), ]); ``` Prefer `UriContent` to reference an asset already hosted at a URL; use `DataContent` for local bytes the model host can't reach by URL. ## Anti-patterns - **Sending a large asset as inline `DataContent`.** Inline binary is base64-encoded into the request, inflating it ~33% and forcing the whole payload through memory on both ends. For anything sizable that is reachable by URL, send `UriContent` and let the model host fetch it. - **Targeting a model that isn't multimodal.** The content parts cross the wire fine, but a text-only deployment ignores or rejects the image. Point the server's `IChatClient` at a vision-capable model/deployment. ## Verify 1. The assistant's streamed reply describes the actual image content (not a generic "I can't see images" message). 2. The request carries the binary part: the user message on the wire has both a text part and an image/data part with the media type you set. - sdks/dotnet/plugins/ag-ui-dotnet/skills/agui-dotnet-protobuf/SKILL.md (5099 bytes)
--- name: agui-dotnet-protobuf description: > Use the protobuf wire transport (instead of the default Server-Sent Events) for an AG-UI connection with the AG-UI .NET SDK — a compact binary event stream negotiated via the Accept header. USE FOR: making an AGUIChatClient prefer protobuf by wiring an AGUIEventStreamHandler with ProtobufEventStreamFormatter (then SseEventStreamFormatter as fallback) into the HttpClient; enabling a server to answer protobuf by registering ProtobufEventStreamFormatter and negotiating the response format from the request Accept header; understanding the protobuf-or-SSE fallback. DO NOT USE FOR: the default SSE transport or first-time setup (use agui-dotnet-streaming-chat); JSON event serialization questions; tools, state, interrupts, multimodal, or generative UI. --- # AG-UI .NET — protobuf transport Goal: carry the AG-UI event stream as compact protobuf binary instead of Server-Sent Events, with automatic fallback to SSE when one side doesn't support it. Transport is negotiated by content type: the client advertises the formats it accepts (in preference order) on the `Accept` header, and the server replies in the first format it also supports. Nothing above the transport changes — `AGUIChatClient`, messages, and your endpoint logic are identical to SSE. ## Install ```bash dotnet add package AGUI.Protobuf # ProtobufEventStreamFormatter ``` Client apps also need `AGUI.Client` (for `AGUIEventStreamHandler`); server apps also need `AGUI.Formatting` (for `SseEventStreamFormatter`) and `AGUI.Server`. ## Client: prefer protobuf, fall back to SSE Wrap your `HttpClient` in an `AGUIEventStreamHandler` configured with the formatters in preference order. The handler advertises them on `Accept` and decodes whatever the server returns: ```csharp using AGUI.Client; using AGUI.Formatting; using AGUI.Protobuf; using Microsoft.Extensions.AI; var handler = new AGUIEventStreamHandler( [new ProtobufEventStreamFormatter(), new SseEventStreamFormatter()]) { InnerHandler = new HttpClientHandler(), }; using var httpClient = new HttpClient(handler); IChatClient client = new AGUIChatClient(new(httpClient, "http://localhost:5013")); ``` Protobuf is listed first, so the client prefers it; if the server only speaks SSE, the handler transparently decodes SSE instead. Switching transports is purely a matter of reordering (or trimming) this formatter list. ## Server: answer protobuf when asked Register both formatters and pick one per request from the `Accept` header, defaulting to SSE: ```csharp using System.Linq; using AGUI.Abstractions; using AGUI.Formatting; using AGUI.Protobuf; using AGUI.Server; using Microsoft.AspNetCore.Mvc; using Microsoft.Extensions.AI; using Microsoft.Extensions.Options; using JsonOptions = Microsoft.AspNetCore.Http.Json.JsonOptions; builder.Services.AddSingleton<IAGUIEventStreamFormatter, SseEventStreamFormatter>(); builder.Services.AddSingleton<IAGUIEventStreamFormatter, ProtobufEventStreamFormatter>(); var app = builder.Build(); app.MapPost("/", async ( [FromBody] RunAgentInput input, IChatClient chatClient, IEnumerable<IAGUIEventStreamFormatter> formatters, IOptions<JsonOptions> jsonOptions, HttpContext http, CancellationToken ct) => { var accept = http.Request.Headers.Accept.ToString(); var formatter = formatters.FirstOrDefault(f => f is ProtobufEventStreamFormatter && accept.Contains(f.MediaType, StringComparison.OrdinalIgnoreCase)) ?? formatters.First(f => f is SseEventStreamFormatter); var ctx = input.ToChatRequestContext(jsonOptions.Value.SerializerOptions); var updates = chatClient.GetStreamingResponseAsync(ctx.Messages, ctx.ChatOptions, ct); var events = updates.AsAGUIEventStreamAsync(ctx, ct); http.Response.ContentType = formatter.MediaType; http.Response.Headers.CacheControl = "no-cache"; await formatter.WriteAsync(events, http.Response.Body, ct); }); ``` Protobuf is selected only when the client *explicitly* accepts its media type, so a default SSE client keeps working unchanged. ## Anti-patterns - **Registering the protobuf formatter on only one side.** Negotiation needs both ends to agree. If the server registers protobuf but the client's handler lists only SSE (or vice versa), every connection silently falls back to SSE and the binary path is never exercised — verify the chosen `Content-Type`, don't assume. - **Hand-parsing the protobuf body.** The wire framing must match `@ag-ui/proto` byte-for-byte. Always read and write through `ProtobufEventStreamFormatter`; don't decode the stream yourself. ## Verify 1. With both sides configured, the response `Content-Type` is the protobuf media type (`ProtobufEventStreamFormatter.MediaType`), and the body is binary, not `data:` text frames. 2. Point the same client at an SSE-only server (drop the server's protobuf registration): it keeps working, now over SSE — confirming fallback. 3. The decoded event stream and the assistant output are identical to the SSE transport. - sdks/dotnet/plugins/ag-ui-dotnet/skills/agui-dotnet-reasoning/SKILL.md (3239 bytes)
--- name: agui-dotnet-reasoning description: > Surface a reasoning/thinking model's intermediate thoughts separately from its final answer with the AG-UI .NET SDK — so a client can show the agent "thinking" before it responds, and handle that reasoning trace correctly across turns. USE FOR: distinguishing the model's reasoning trace from its answer on the client by matching TextReasoningContent vs TextContent in each ChatResponseUpdate's Contents; rendering thinking and answer in different ways as they stream; deciding whether to carry the reasoning text into later turns (whether to append/resend the model's reasoning back into conversation history). DO NOT USE FOR: plain text streaming with no reasoning display (use agui-dotnet-streaming-chat); tools, shared state, interrupts, multimodal, generative UI, or protobuf. --- # AG-UI .NET — reasoning (thinking) events Goal: show a reasoning model's intermediate thoughts as they stream, kept visually separate from the final answer. A reasoning model emits two kinds of text in the stream: its thinking and its answer. In `Microsoft.Extensions.AI` these arrive as different content types on each `ChatResponseUpdate` — `TextReasoningContent` for the thoughts, `TextContent` for the answer. `update.Text` only concatenates the answer parts, so to display thinking you inspect `update.Contents`. ## Separate thinking from the answer Iterate `update.Contents` and branch on the content type instead of reading `update.Text`: ```csharp using Microsoft.Extensions.AI; var messages = new List<ChatMessage> { new(ChatRole.User, "20 heads, 56 legs — how many chickens and rabbits? Show your reasoning."), }; await foreach (var update in client.GetStreamingResponseAsync(messages)) { foreach (var content in update.Contents) { switch (content) { case TextReasoningContent { Text: { Length: > 0 } thinking }: RenderThinking(thinking); // e.g. a dimmed/collapsible panel break; case TextContent { Text: { Length: > 0 } answer }: RenderAnswer(answer); // the user-facing reply break; } } } ``` Both stream incrementally and can interleave: thinking deltas arrive, then answer deltas. Render each as it comes rather than buffering, so the "thinking…" state is visible before the answer lands. ## Anti-patterns - **Re-sending the reasoning text as conversation history.** The thinking is scratch work for a single turn, not a message. Appending captured `TextReasoningContent` into the next request's messages bloats the prompt, and some providers reject prior reasoning as input. Carry forward only the assistant's answer. - **Treating reasoning as part of the answer.** The thinking is a separate channel; concatenating it into the reply shows the user the model's scratch work as if it were the response. Keep the two render paths distinct. ## Verify 1. For a prompt that asks the model to reason, the stream yields `TextReasoningContent` updates before the final `TextContent` answer. 2. The rendered answer contains only the response, with the reasoning shown (or hidden) through its own path — not mixed into the answer text. - sdks/dotnet/plugins/ag-ui-dotnet/skills/agui-dotnet-server-tools/SKILL.md (6520 bytes)
--- name: agui-dotnet-server-tools description: > Expose server-side (backend) tools an AG-UI agent can call with the AG-UI .NET SDK — C# functions that run on the server, where the server executes the call and feeds the result back to the model. USE FOR: defining an AIFunction with AIFunctionFactory.Create and registering it on the server's IChatClient via ConfigureOptions + UseFunctionInvocation; making the model call your backend function during a run; AOT-safe tool arguments/results (registering a JsonSerializerContext for complex tool parameter types); parallel/concurrent backend tool calls (AllowConcurrentInvocation); TerminateOnUnknownCalls behavior. DO NOT USE FOR: tools that run in the client/frontend (use agui-dotnet-client-tools); pausing a tool for human approval or input (interrupts / human-in-the-loop); plain streaming chat with no tools (use agui-dotnet-streaming-chat); shared state, generative UI, multimodal, or protobuf. --- # AG-UI .NET — server (backend) tools Goal: let the model call a C# function that runs on your server, with the server executing the call and returning the result so the run continues to a final answer. A server tool is an ordinary `Microsoft.Extensions.AI` `AIFunction` registered on the server's `IChatClient`. The `FunctionInvokingChatClient` executes it inside the run; the client sends no tools and needs no tool code, and receives the final answer. Tool-call and result events still cross the wire — the client just never executes anything. ## Install ```bash dotnet add package AGUI.Server dotnet add package AGUI.Formatting ``` `Microsoft.Extensions.AI` supplies `AIFunctionFactory`, `AddChatClient`, and `UseFunctionInvocation`. Run `dotnet package search AGUI.Server --exact-match` for the current version. ## Define and register a tool Create the function with `AIFunctionFactory.Create`, add it to the chat client's tools, and enable function invocation: ```csharp using System.ComponentModel; using Microsoft.Extensions.AI; [Description("Search for restaurants in a location.")] static RestaurantSearchResponse SearchRestaurants( [Description("Where to search and what cuisine.")] RestaurantSearchRequest request) { // ... real lookup ... } var builder = WebApplication.CreateBuilder(args); var searchRestaurants = AIFunctionFactory.Create( SearchRestaurants, serializerOptions: SampleJsonSerializerContext.Default.Options); builder.Services.AddChatClient( new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential()) .GetChatClient(deploymentName) .AsIChatClient()) .ConfigureOptions(o => (o.Tools ??= []).Add(searchRestaurants)) .UseFunctionInvocation(fic => fic.TerminateOnUnknownCalls = true); ``` The `[Description]` attributes become the tool and parameter schema the model sees. Any `Microsoft.Extensions.AI` provider works in place of Azure OpenAI. ## AOT-safe tool arguments and results When a tool takes or returns a complex type (anything beyond primitives), its schema and (de)serialization must be source-generated, not reflection-based. Put the parameter and result types in a `JsonSerializerContext`, register it on the host's JSON options, and pass it to `AIFunctionFactory.Create`: ```csharp [JsonSerializable(typeof(RestaurantSearchRequest))] [JsonSerializable(typeof(RestaurantSearchResponse))] internal sealed partial class SampleJsonSerializerContext : JsonSerializerContext; builder.Services.ConfigureHttpJsonOptions(o => o.SerializerOptions.TypeInfoResolverChain.Add(SampleJsonSerializerContext.Default)); var searchRestaurants = AIFunctionFactory.Create( SearchRestaurants, serializerOptions: SampleJsonSerializerContext.Default.Options); ``` The same context is registered on the host (so the wire `RunAgentInput` round-trips the types) and passed to the function (so its argument binding uses source-gen). ## Host the endpoint The endpoint streams the registered `IChatClient` — function calls are resolved server-side inside the stream before any text reaches the client: ```csharp using AGUI.Abstractions; using AGUI.Formatting; using AGUI.Server; using Microsoft.AspNetCore.Mvc; using Microsoft.Extensions.AI; using Microsoft.Extensions.Options; using JsonOptions = Microsoft.AspNetCore.Http.Json.JsonOptions; builder.Services.AddSingleton<IAGUIEventStreamFormatter, SseEventStreamFormatter>(); var app = builder.Build(); app.MapPost("/", async ( [FromBody] RunAgentInput input, IChatClient chatClient, IAGUIEventStreamFormatter formatter, IOptions<JsonOptions> jsonOptions, HttpContext http, CancellationToken ct) => { var ctx = input.ToChatRequestContext(jsonOptions.Value.SerializerOptions); var updates = chatClient.GetStreamingResponseAsync(ctx.Messages, ctx.ChatOptions, ct); var events = updates.AsAGUIEventStreamAsync(ctx, ct); http.Response.ContentType = formatter.MediaType; http.Response.Headers.CacheControl = "no-cache"; await formatter.WriteAsync(events, http.Response.Body, ct); }); app.Run(); ``` ## Parallel tool calls When the model requests several tool calls in one turn, let the function-invoking client run them concurrently: ```csharp .UseFunctionInvocation(fic => { fic.TerminateOnUnknownCalls = true; fic.AllowConcurrentInvocation = true; }); ``` The model decides whether to batch calls; `AllowConcurrentInvocation` only controls whether the already-requested calls execute in parallel instead of serially. ## Anti-patterns - **Registering a tool with complex parameters but no source-gen context.** Reflection-based schema generation breaks under Native AOT and trimming. Every non-primitive tool argument or result type needs a `JsonSerializerContext` entry, registered on the host and passed to `AIFunctionFactory.Create`. - **Leaving `TerminateOnUnknownCalls` at its default when client tools are also in play.** With it set, a tool the server doesn't own (one the client declared) ends the server run cleanly so the client can execute it; without it the unknown call surfaces as an error mid-run. ## Verify 1. Send a prompt that needs the tool and watch the stream: a `TOOL_CALL_START` / `TOOL_CALL_ARGS` / `TOOL_CALL_END` followed by a `TOOL_CALL_RESULT`, then assistant text that uses the result — all within one run that ends `RUN_FINISHED`. 2. The client receives the final answer with no tool code of its own. 3. If targeting Native AOT, `dotnet publish` produces no trim/AOT warnings for the tool types. - sdks/dotnet/plugins/ag-ui-dotnet/skills/agui-dotnet-shared-state/SKILL.md (6327 bytes)
--- name: agui-dotnet-shared-state description: > Share structured, evolving state between an AG-UI agent and its client with the AG-UI .NET SDK — the client seeds state on the request, the server reads it, mutates it, and streams the updated state back as snapshots or deltas alongside the chat. USE FOR: sending initial/working state from the client via ChatOptions.RawRepresentationFactory -> RunAgentInput.State; reading inbound state on the server with ChatOptions.TryGetRunAgentInput and RunAgentInput.State; emitting a full state object as a StateSnapshotEvent (or incremental JSON-Patch changes as a StateDeltaEvent) from a DelegatingChatClient via ChatResponseUpdate.RawRepresentation; reading state back on the client from update.RawRepresentation as StateSnapshotEvent. DO NOT USE FOR: passing one-off tool arguments (use agui-dotnet-server-tools); rendering UI components from tool calls (use agui-dotnet-generative-ui); plain chat (use agui-dotnet-streaming-chat); approvals/interrupts, multimodal, or protobuf. --- # AG-UI .NET — shared state Goal: keep a structured object (a form, a document, a plan, a recipe) in sync between the client and the agent — the client provides the current state, the agent updates it, and the new state streams back next to the assistant's text. State travels on the wire inside `RunAgentInput.State` (inbound) and as `StateSnapshotEvent` / `StateDeltaEvent` (outbound). In `Microsoft.Extensions.AI` terms, inbound state rides on the request's raw representation and outbound state rides on a `ChatResponseUpdate`'s raw representation. ## Client: seed the state and read it back Send the starting state with the request, and watch for snapshots in the response: ```csharp using System.Text.Json; using AGUI.Abstractions; using Microsoft.Extensions.AI; var initialState = JsonSerializer.SerializeToElement(new { recipe = new { title = "", ingredients = Array.Empty<string>(), steps = Array.Empty<string>() } }); var options = new ChatOptions { RawRepresentationFactory = _ => new RunAgentInput { State = initialState }, }; var messages = new List<ChatMessage> { new(ChatRole.User, "Suggest an Italian pasta recipe") }; JsonElement? latestState = null; await foreach (var update in client.GetStreamingResponseAsync(messages, options)) { if (update.RawRepresentation is StateSnapshotEvent snapshot) { latestState = snapshot.Snapshot; // the full updated state object } Console.Write(update.Text); // the assistant's summary streams as usual } ``` State updates are **content-less** — they arrive on `update.RawRepresentation`, not as `update.Text`. ## Server: read inbound state and emit the new state Add a `DelegatingChatClient` to the pipeline that reads `RunAgentInput.State`, produces the new state, and yields it as a `StateSnapshotEvent`: ```csharp using System.Runtime.CompilerServices; using System.Text.Json; using AGUI.Abstractions; using AGUI.Server; using Microsoft.Extensions.AI; internal sealed class RecipeStateChatClient(IChatClient inner, JsonSerializerOptions jso) : DelegatingChatClient(inner) { public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync( IEnumerable<ChatMessage> messages, ChatOptions? options = null, [EnumeratorCancellation] CancellationToken ct = default) { if (options?.TryGetRunAgentInput(out var input) is true && input!.State is { ValueKind: JsonValueKind.Object } incoming) { var newState = await BuildStateAsync(messages, incoming, ct); // your logic / an LLM call yield return new ChatResponseUpdate { RawRepresentation = new StateSnapshotEvent { Snapshot = JsonSerializer.SerializeToElement(newState, jso.GetTypeInfo(typeof(AgentState))), }, }; } await foreach (var update in base.GetStreamingResponseAsync(messages, options, ct)) { yield return update; // the assistant's text summary } } } ``` Register it after function invocation: ```csharp builder.Services.AddChatClient(/* provider IChatClient */) .UseFunctionInvocation() .Use((inner, sp) => new RecipeStateChatClient( inner, sp.GetRequiredService<IOptions<JsonOptions>>().Value.SerializerOptions)); ``` `TryGetRunAgentInput` recovers the originating `RunAgentInput` from the `ChatOptions` the endpoint built — that is how the server-side chat client reaches `State` (and thread id, tools, …) without endpoint plumbing. ## Snapshots vs deltas - **`StateSnapshotEvent`** carries the entire state object. Simple and self-correcting; send it when the whole state changed or you want to resync. - **`StateDeltaEvent`** carries a JSON Patch (RFC 6902) array of changes against the last known state. Use it for small, frequent edits to a large object to avoid resending everything. The client applies the patch to its copy. ## AOT-safe state types State objects are serialized through the source-generated context. Put each state type in a `JsonSerializerContext`, register it on the host (`ConfigureHttpJsonOptions(o => o.SerializerOptions.TypeInfoResolverChain.Add(...))`), and serialize through `jso.GetTypeInfo(typeof(T))` rather than reflection. ## Anti-patterns - **Aggregating the response instead of streaming it.** `StateSnapshotEvent` / `StateDeltaEvent` arrive on content-less updates, which the non-streaming aggregation drops. Read state inside the `await foreach` over the streaming response. - **Sending a delta against state the client never received.** A `StateDeltaEvent` patches the client's last known state; if the client missed the prior snapshot the patch fails to apply. Start a session (or resync) with a full `StateSnapshotEvent`, then send deltas. ## Verify 1. The client sends a non-empty `State` and the run streams back at least one `StateSnapshotEvent` whose `Snapshot` reflects the agent's changes. 2. The assistant text and the state both arrive in the same run; reading `update.RawRepresentation` yields the `StateSnapshotEvent` while `update.Text` yields the summary. 3. If using deltas: applying the streamed JSON Patch to the prior state produces the same object a full snapshot would. - sdks/dotnet/plugins/ag-ui-dotnet/skills/agui-dotnet-streaming-chat/SKILL.md (10189 bytes)
--- name: agui-dotnet-streaming-chat description: > Get started with the AG-UI .NET SDK: bootstrap and run your first streaming-chat app (client + server) with the AG-UI .NET NuGet packages (AGUI.Client, AGUI.Server, AGUI.Formatting, AGUI.Abstractions). USE FOR: which packages to install and how to wire them; constructing an AGUIChatClient against an endpoint and streaming the reply as Microsoft.Extensions.AI IChatClient / ChatResponseUpdate; hosting an AG-UI POST endpoint yourself over any IChatClient; running a single- or multi-turn conversation; STATELESS agents (client owns history, resends it every turn) vs HOSTED / conversation-holding agents (server keeps the session, client pins a thread id). DO NOT USE FOR: changing the AG-UI .NET SDK itself (use the agui-dotnet-* contributor skills); server tools (agui-dotnet-server-tools); client tools (agui-dotnet-client-tools); interrupts / human-in-the-loop; shared state; generative UI; multimodal; or protobuf transport. --- # Getting started with AG-UI .NET — streaming chat Goal: install the packages, stand up an AG-UI endpoint, connect a client, and stream a multi-turn conversation. **You are done when you run the client and it prints a streamed reply.** ## The two agent types (read this first) How you keep a conversation going depends on **who owns the history**: - **Stateless agent (the default).** The server keeps nothing between turns — it is a pure function of the request. The **client** owns the history and resends the full message list every turn. This is where you start. - **Hosted / conversation-holding agent.** A server (or runtime) persists the conversation in a session keyed by the **thread id**, so it can recall history. The client sends the new turn under a stable thread id. Covered [below](#hosted-agents). `AGUIChatClient` is a `Microsoft.Extensions.AI.IChatClient`, so you consume it with the ordinary `GetStreamingResponseAsync(messages, options, ct)` API. **Thread id.** Every conversation has one — it is the stable identifier for the whole exchange. Keep it stable across turns by **reusing the same `ChatOptions` instance**: `AGUIChatClient` pins the resolved thread id onto it after the first turn. (The SDK never surfaces it as `ConversationId` — `update.ConversationId` is always `null` by design, issue #4869 — so don't use `ConversationId` to track a conversation.) ## Install the packages Client app: ```bash dotnet add package AGUI.Client ``` Server app: ```bash dotnet add package AGUI.Server # RunAgentInput adaptation + event-stream conversion dotnet add package AGUI.Formatting # SseEventStreamFormatter (writes the SSE wire format) ``` `dotnet add package` installs the latest stable version. To discover versions or pin one: ```bash dotnet package search AGUI.Client --exact-match # show the latest version on nuget.org dotnet add package AGUI.Client --prerelease # install latest, including prereleases dotnet add package AGUI.Client --version <x.y.z> # pin a specific version ``` `AGUI.Abstractions` (protocol types such as `RunAgentInput` and `RunStartedEvent`) comes in transitively with both. On the server you also use `Microsoft.Extensions.AI` (`AddChatClient`, `IChatClient`) plus a chat-client provider of your choice (OpenAI, Azure OpenAI, Ollama, …). ## Stateless: the client Construct it from an `AGUIChatClientOptions` (here via the `(HttpClient, endpoint)` options constructor): ```csharp using AGUI.Client; using Microsoft.Extensions.AI; using var httpClient = new HttpClient(); IChatClient client = new AGUIChatClient(new(httpClient, "http://localhost:5001")); await foreach (var update in client.GetStreamingResponseAsync( new List<ChatMessage> { new(ChatRole.User, "Hello") })) { Console.Write(update.Text); // text deltas stream in as they arrive } ``` You own the `HttpClient`. The transport defaults to Server-Sent Events. ## Stateless: the server Host the endpoint yourself: receive `RunAgentInput`, adapt it to Microsoft.Extensions.AI, stream from any `IChatClient`, convert to AG-UI events, and write them as SSE. ```csharp using AGUI.Abstractions; using AGUI.Formatting; using AGUI.Server; using Azure.AI.OpenAI; using Azure.Identity; using Microsoft.AspNetCore.Mvc; using Microsoft.Extensions.AI; using Microsoft.Extensions.Options; using JsonOptions = Microsoft.AspNetCore.Http.Json.JsonOptions; var builder = WebApplication.CreateBuilder(args); // Register your chat client. Any Microsoft.Extensions.AI provider works // (OpenAI, Ollama, a local model, …); Azure OpenAI is shown here. builder.Services.AddChatClient( new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential()) .GetChatClient(deploymentName) .AsIChatClient()); // SseEventStreamFormatter is stateless — register it once as a singleton. builder.Services.AddSingleton<IAGUIEventStreamFormatter, SseEventStreamFormatter>(); var app = builder.Build(); app.MapPost("/", async ( [FromBody] RunAgentInput input, IChatClient chatClient, IAGUIEventStreamFormatter formatter, IOptions<JsonOptions> jsonOptions, HttpContext http, CancellationToken ct) => { var jso = jsonOptions.Value.SerializerOptions; // 1) RunAgentInput -> messages + ChatOptions var ctx = input.ToChatRequestContext(jso); // 2) Stream from the model var updates = chatClient.GetStreamingResponseAsync(ctx.Messages, ctx.ChatOptions, ct); // 3) ChatResponseUpdate stream -> AG-UI event stream var events = updates.AsAGUIEventStreamAsync(ctx, ct); // 4) Write the events using the injected (singleton) formatter http.Response.ContentType = formatter.MediaType; http.Response.Headers.CacheControl = "no-cache"; await formatter.WriteAsync(events, http.Response.Body, ct); }); app.Run(); ``` That is the whole server contract. If you later expose server-executed tools, add `.UseFunctionInvocation()` to the chat-client registration — not needed for plain chat. ## Stateless: multi-turn (carry the history) A stateless server has no memory, so the **client** keeps the running `List<ChatMessage>`: append the assistant reply, then add the next user turn. Reuse the same `ChatOptions` so the thread id stays stable across the conversation. ```csharp var messages = new List<ChatMessage> { new(ChatRole.User, "Hello") }; var options = new ChatOptions(); await SendAsync(messages, options); messages.Add(new ChatMessage(ChatRole.User, "How are you?")); await SendAsync(messages, options); async Task SendAsync(List<ChatMessage> history, ChatOptions options) { var updates = new List<ChatResponseUpdate>(); await foreach (var update in client.GetStreamingResponseAsync(history, options)) { Console.Write(update.Text); // stream the reply as it arrives updates.Add(update); } Console.WriteLine(); history.AddMessages(updates.ToChatResponse()); // carry the reply into the next turn } ``` `AGUIChatClient` sends the **full message list every turn** by design — that is how a stateless server sees prior context. ## Run it (definition of done) 1. Start the server: `dotnet run` in the server project (listening on, e.g., `:5001`). 2. Run the client against it. **It works when the client prints the reply incrementally** (multiple non-empty `update.Text` chunks, not one blob at the end). 3. Smoke-test the server directly: ```bash curl -N -X POST http://localhost:5001/ -H "Content-Type: application/json" \ -d '{"threadId":"t1","runId":"r1","messages":[{"id":"m1","role":"user","content":"Hello"}]}' ``` You should see `data: {...}` SSE frames: `RUN_STARTED` … `TEXT_MESSAGE_CONTENT` … `RUN_FINISHED`. 4. Multi-turn keeps context: the second answer reflects the first exchange. ## Hosted agents Use this when the server holds the conversation (a session store keyed by thread id). The server recalls history from the thread id, so the client just needs to keep that thread id stable — reusing the same `ChatOptions` (above) is usually enough. Two extra tools for when you need them: - **Pin a known thread id** (resuming a session created earlier): set it as `ConversationId` — `AGUIChatClient` maps it inward to the AG-UI thread id. ```csharp var options = new ChatOptions { ConversationId = threadId }; ``` - **Read the thread id / run id** for a turn — they ride on the `RUN_STARTED` event, exposed as the update's `RawRepresentation`: ```csharp using AGUI.Abstractions; string? threadId = null, runId = null; await foreach (var u in client.GetStreamingResponseAsync(messages, options)) { if (u.RawRepresentation is RunStartedEvent started) { threadId = started.ThreadId; runId = started.RunId; } Console.Write(u.Text); } ``` - **Advanced — set wire-level fields with no `ChatOptions` equivalent.** For example `ParentRunId`, to chain one run onto the previous. Supply it via `RawRepresentationFactory`; messages still flow through the normal call argument, and to send only the new turn you simply pass a shorter list: ```csharp var options = new ChatOptions { RawRepresentationFactory = _ => new RunAgentInput { ParentRunId = runId }, }; await foreach (var update in client.GetStreamingResponseAsync(newMessages, options)) { Console.Write(update.Text); } ``` Send only the new messages this way only when the server truly owns history; otherwise prefer the full-history stateless pattern, which works against any AG-UI server. ## Anti-patterns - **Reusing one `ChatOptions` across different conversations.** The thread id pins onto the options instance, so a second, unrelated conversation inherits the first one's thread id — and against a hosted server the two get merged into one session. Use a fresh `ChatOptions` per conversation; reuse it only across turns of the *same* one. - **Calling `GetResponseAsync` when you want streaming.** It returns only the final aggregated response — no incremental text, and content-less updates (lifecycle and state events) do not survive the aggregation. Use `GetStreamingResponseAsync`. - sdks/dotnet/plugins/ag-ui-dotnet/skills/agui-dotnet-troubleshoot/SKILL.md (5422 bytes)
--- name: agui-dotnet-troubleshoot description: > Diagnose and fix problems in an AG-UI .NET app built on the AG-UI SDK — when streaming chat, tools, state, interrupts, or the transport misbehave. USE FOR: the agent forgetting earlier turns / history truncated; update.ConversationId always null; state or lifecycle updates that never arrive; a tool throwing at runtime or producing AOT/trim warnings; an unknown-tool error mid-run; 406 Not Acceptable from the endpoint; an interrupt or approval that won't resume; and inspecting the raw AG-UI event stream (curl SSE frames, RawEvent on ChatResponseUpdate.RawRepresentation) to see what's actually on the wire. DO NOT USE FOR: first-time setup or the happy path (use agui-dotnet-streaming-chat); implementing a specific feature cleanly (use the matching agui-dotnet-* skill). --- # AG-UI .NET — troubleshooting Goal: map a symptom to its cause and fix in an AG-UI .NET app. ## The agent forgets earlier turns / history is truncated The server is stateless and keeps nothing between turns, so the client must resend the full history each turn. If you send only the latest message, the model loses all prior context. Fix: keep a running `List<ChatMessage>`, append the assistant reply (`history.AddMessages(updates.ToChatResponse())`), and resend the whole list. For a server that holds the conversation, keep the thread id stable by reusing the same `ChatOptions` instance across turns. ## `update.ConversationId` is always null This is by design — the SDK never surfaces a service conversation id. A non-null `ConversationId` would make `Microsoft.Extensions.AI` wrappers send only deltas, which truncates history against a stateless server. Fix: don't track conversations by `ConversationId`. Use the thread id from the `RUN_STARTED` event (`update.RawRepresentation as RunStartedEvent`), or just reuse the same `ChatOptions` to keep one stable thread. ## State, reasoning, or lifecycle updates never arrive These ride on **content-less** updates — `update.RawRepresentation` (a `StateSnapshotEvent`, `RunStartedEvent`, `RawEvent`, …) with no text. The non-streaming `GetResponseAsync` aggregation drops updates that carry no message content. Fix: consume the streaming API (`await foreach` over `GetStreamingResponseAsync`) and inspect `update.RawRepresentation` / `update.Contents` inside the loop, rather than aggregating to a single `ChatResponse`. ## A tool throws at runtime or emits AOT/trim warnings A tool whose argument or result type is non-primitive needs source-generated serialization; reflection-based schema/binding fails under Native AOT and trimming. Fix: put the tool's parameter and result types in a `JsonSerializerContext`, register it on the host (`ConfigureHttpJsonOptions(o => o.SerializerOptions.TypeInfoResolverChain.Add(...))`), and pass it to `AIFunctionFactory.Create(method, serializerOptions: ctx.Options)`. ## An unknown-tool call errors mid-run When the client declares a tool the server doesn't own, the server's function-invoking client tries to execute it and fails — unless told the call belongs elsewhere. Fix: register the server chat client with `.UseFunctionInvocation(fic => fic.TerminateOnUnknownCalls = true)`. The unknown (client) tool then ends the server turn cleanly and is forwarded to the client to execute. ## The endpoint returns 406 Not Acceptable Transport is content-negotiated. A 406 means the request's `Accept` header asked for a format the server can't produce (e.g. protobuf with no protobuf formatter registered, or an `Accept` that excludes `text/event-stream`). Fix: make the client accept a format the server offers. For SSE, allow `text/event-stream` (or `*/*`); for protobuf, register `ProtobufEventStreamFormatter` on the server and list it in the client's `AGUIEventStreamHandler`. ## An interrupt or approval won't resume Resuming a paused run needs **both** the request and the matching response in the resumed message list, sharing the same id — the SDK pairs them to reconnect to the paused call. Fix: append both — the `ToolApprovalRequestContent` (or `InterruptRequestContent`) on an assistant message and its `CreateResponse(...)` / `InterruptResponseContent(requestId)` on a user message — then stream again. Sending the response alone leaves nothing to resume. ## Inspecting what's on the wire See the raw event frames directly with curl: ```bash curl -N -X POST http://localhost:5000/ \ -H "Content-Type: application/json" -H "Accept: text/event-stream" \ -d '{"threadId":"t1","runId":"r1","messages":[{"id":"m1","role":"user","content":"Hi"}]}' ``` A healthy run shows `RUN_STARTED` … `TEXT_MESSAGE_CONTENT` … `RUN_FINISHED`. A paused run ends `RUN_FINISHED { outcome: interrupt }`. Tool runs show `TOOL_CALL_START` / `TOOL_CALL_ARGS` / `TOOL_CALL_END` / `TOOL_CALL_RESULT`. In code, telemetry and custom server events surface as a `RawEvent` on the update: ```csharp if (update.RawRepresentation is RawEvent { Source: var source, Event: var payload }) { Console.WriteLine($"[{source}] {payload.GetRawText()}"); } ``` ## Verify the fix After applying a fix, reproduce the original prompt and confirm the symptom is gone against the wire stream — e.g. the second turn now reflects the first (history), the `StateSnapshotEvent` now arrives (streaming), or the response `Content-Type` now matches the negotiated transport (406). - SKILL.md (4325 bytes)
--- name: agui-dotnet-client-tools description: > Expose client-side (frontend) tools to an AG-UI agent with the AG-UI .NET SDK — C# functions that run in the CLIENT app (read local state, GPS, UI, device APIs), where the client executes the call and returns the result so the run continues. USE FOR: declaring an AIFunction in the client and passing it via ChatOptions.Tools to AGUIChatClient; having the client execute a tool the model requested and feed the result back automatically; understanding why no UseFunctionInvocation is needed on the client (AGUIChatClient already invokes functions); what the server must do (UseFunctionInvocation + TerminateOnUnknownCalls) so it forwards an unknown/client tool instead of erroring. DO NOT USE FOR: tools that run on the server/backend (use agui-dotnet-server-tools); pausing for human approval/input before acting (interrupts / human-in-the-loop); plain chat (use agui-dotnet-streaming-chat); shared state, generative UI, multimodal, or protobuf. --- # AG-UI .NET — client (frontend) tools Goal: let the model call a function that runs in the client app — to read something only the client has (location, local state, UI selection, a device API) — with the client executing the call and returning the result so the run continues to a final answer. A client tool is an ordinary `Microsoft.Extensions.AI` `AIFunction` you attach to the request via `ChatOptions.Tools`. `AGUIChatClient` is itself a function-invoking client, so it runs the tool locally and sends the result back automatically — you do not wrap it in `UseFunctionInvocation`. ## Install ```bash dotnet add package AGUI.Client ``` `Microsoft.Extensions.AI` supplies `AIFunctionFactory`, `ChatOptions`, and `AITool`. Run `dotnet package search AGUI.Client --exact-match` for the current version. ## Declare a tool and pass it in options Define the function in the client, wrap it with `AIFunctionFactory.Create`, and put it on `ChatOptions.Tools`: ```csharp using System.ComponentModel; using AGUI.Client; using Microsoft.Extensions.AI; [Description("Get the user's current location from GPS.")] static string GetUserLocation() => "Amsterdam, Netherlands (52.37°N, 4.90°E)"; using var httpClient = new HttpClient(); IChatClient client = new AGUIChatClient(new(httpClient, "http://localhost:5003")); var options = new ChatOptions { Tools = [AIFunctionFactory.Create(GetUserLocation)] }; var messages = new List<ChatMessage> { new(ChatRole.User, "What's fun to do near me?") }; await foreach (var update in client.GetStreamingResponseAsync(messages, options)) { Console.Write(update.Text); } ``` When the model decides to call `GetUserLocation`, `AGUIChatClient` invokes it on this machine, returns the result to the server, and the run continues — the streamed text you print already reflects the location. ## What the server must do The server forwards a tool it doesn't own to the client instead of trying to run it. Register the server's chat client with function invocation and `TerminateOnUnknownCalls` so an unknown (client) tool ends the server turn cleanly and is surfaced to the client to execute: ```csharp builder.Services.AddChatClient(/* provider IChatClient */) .UseFunctionInvocation(fic => fic.TerminateOnUnknownCalls = true); ``` The server declares none of the client's tools; it only needs to forward them. ## Anti-patterns - **Wrapping the client in `UseFunctionInvocation`.** `AGUIChatClient` already invokes functions; adding another function-invoking layer double-handles the call and can execute it twice or strip the AG-UI tool routing. Pass the tool through `ChatOptions.Tools` and let the client invoke it. - **A client tool that returns before the side effect it reports completes.** The model continues the run the instant the function returns, so a tool that says "saved" while an async write is still in flight makes the model narrate a result that has not happened. Await the real work inside the function before returning. ## Verify 1. Run a prompt the model can only answer using the client tool. The function body executes locally (set a breakpoint or log inside it). 2. The streamed answer reflects the tool's return value, and the run ends `RUN_FINISHED` in a single client call — you wrote no code to send the tool result back. - skills/ag-ui-a2ui-integration/SKILL.md (6131 bytes)
--- name: ag-ui-a2ui-integration description: "Use when adding A2UI rendering to any AG-UI-supported framework or custom AG-UI application, scaffolding an AG-UI app that should render A2UI, adapting an AG-UI integration to emit A2UI surfaces, or wiring the AG-UI A2UI middleware/toolkit with a compatible renderer." version: 1.1.1 --- # AG-UI + A2UI Integration Skill ## Overview Use this skill to add A2UI rendering to an AG-UI application. Treat AG-UI as the transport and agent integration layer, `@ag-ui/a2ui-middleware` as the server-side bridge that detects and paints A2UI operations, and A2UI as the UI payload format that the client renderer displays. This is a developer-facing skill artifact. It is meant to be loaded by coding agents and used against a real app or repo, not published as a docs page. ## When to Use - Adding A2UI rendering to an existing AG-UI app. - Creating an AG-UI quickstart that should display A2UI surfaces. - Connecting any AG-UI-supported framework or custom AG-UI agent to an A2UI-capable frontend. - Adding or extending an A2UI component catalog. - Debugging why an A2UI surface does not render or why a user action does not flow back to the agent. ## When NOT to Use - For AG-UI protocol event semantics only, use the AG-UI protocol skill or protocol docs. - For A2UI renderer internals outside an AG-UI app, use the A2UI renderer docs or renderer-specific skills. - For generic CopilotKit frontend work without A2UI, use CopilotKit-specific setup and React skills. ## Workflow 1. Inspect the app shape: framework adapter, AG-UI agent endpoint, runtime host, frontend shell, and any existing A2UI renderer/catalog. 2. Decide the A2UI mode before editing code: - Fixed schema: backend tools return an `a2ui_operations` envelope with `createSurface`, `updateComponents`, and `updateDataModel`. - Dynamic schema: a framework A2UI tool (`generate_a2ui`) delegates to a sub-agent that streams `render_a2ui` args through `A2UIMiddleware`. 3. Select framework-specific wiring from `references/framework-adapters.md`, or use that reference to find the closest AG-UI integration pattern. Preserve the app's existing agent architecture. 4. Wire server middleware/runtime and client renderer using `references/a2ui-runtime-and-renderer.md`. Avoid double-applying `A2UIMiddleware`; use either runtime-level A2UI config or per-agent `agent.use(new A2UIMiddleware(...))` for a given agent. 5. Register a catalog on the client. With CopilotKit >= 1.61.2, forwarding it to the provider (`a2ui={{ catalog }}`) auto-enables A2UI and auto-derives `defaultCatalogId` from the catalog's id. Only when you are not forwarding a catalog, ensure the middleware or adapter sets a `defaultCatalogId` matching the renderer-registered catalog. 6. Verify the streaming path with `references/verification.md`: AG-UI stream, `a2ui-surface` activity snapshots or `a2ui_operations`, rendered A2UI surface, and a user interaction flowing back through AG-UI. ## AG-UI Framework Support This skill is not limited to the framework examples below. For any target framework, first check the AG-UI repository's `integrations/` directory, the AG-UI docs, the framework adapter's A2UI files, and the current CLI source. If AG-UI supports the framework, use that integration's documented package, endpoint helper, A2UI tool factory, or scaffold path. If there is no framework A2UI adapter, implement the custom AG-UI agent path, return `a2ui_operations` from backend tools for fixed layouts, and keep the middleware/client wiring the same. ## Common AG-UI CLI Flags Use the CLI flags that exist in `sdks/typescript/packages/cli/src/index.ts`. The table is a quick reference for known scaffold paths, not the full AG-UI support matrix. Do not invent flags. | Framework | CLI flag | | -------------------- | ---------------- | | ADK | `--adk` | | LangGraph Python | `--langgraph-py` | | LangGraph JavaScript | `--langgraph-js` | | CrewAI Flows | `--crewai-flows` | | Mastra | `--mastra` | | Pydantic AI | `--pydantic-ai` | | LlamaIndex | `--llamaindex` | | Agno | `--agno` | | AG2 | `--ag2` | Strands has AG-UI integration packages and examples, but no Strands CLI flag is present in the current AG-UI CLI source. Use the Strands integration docs instead of guessing a scaffold command. ## Key Rules - Keep the integration AG-UI-first for every supported framework. CopilotKit is a common runtime/renderer path for web apps, but AG-UI owns the middleware, framework adapters, and wire events. - Enable A2UI on both sides: `A2UIMiddleware` or runtime A2UI config on the server, and an A2UI-capable renderer/catalog on the client. - For dynamic schema, prefer the framework adapter's A2UI tool factory or auto-injection path. The model should call `generate_a2ui`; the sub-agent should stream `render_a2ui` args so the middleware can progressively paint. - For fixed schema, return an `a2ui_operations` envelope from backend tools rather than asking the model to invent component trees. - Emit `createSurface` once per `surfaceId`; use update operations for later changes. - Do not let the model invent catalog ids. When the client forwards a catalog to the provider (CopilotKit >= 1.61.2), its `catalogId` is derived automatically; otherwise the host/middleware/adapter should stamp a `defaultCatalogId` that matches the client-registered catalog. - Preserve AG-UI run boundaries and error events. Do not swallow server or stream errors. - Verify with a real browser or client run when possible. A static typecheck is not enough for streaming UI work. ## References - `references/framework-adapters.md` - framework-specific AG-UI adapter patterns. - `references/a2ui-runtime-and-renderer.md` - server/client A2UI wiring and catalog patterns. - `references/verification.md` - checks to confirm the integration works. - `sources.md` - source files and docs used by this skill.