Weather Agent

This repository contains a full-stack weather assistant built around Microsoft Agents and AG-UI streaming:

• A .NET 10 API that hosts a chat agent and exposes it over an AG-UI endpoint.
• A Next.js 16 web UI that streams assistant output and renders tool results as structured weather cards.

Purpose

The purpose of this codebase is to serve as an "ideal target state" reference implementation for autonomous coding agent experiments in Agents.Code.

Structure

• weather/api: .NET solution with API host and console client.
• weather/ui: Next.js frontend with AG-UI event translation and custom rendering components.
• weather/docker-compose.development.yaml: local multi-container orchestration for API + UI.

End-to-End Runtime Flow

At runtime, chat requests move through four stages:

1. The browser submits a message to POST /api/chat in the Next.js app.
2. The Next.js route converts UI messages to AG-UI request format and forwards them to POST /chat on the API.
3. The .NET agent streams AG-UI events while producing text and invoking tools.
4. The Next.js route maps incoming AG-UI events back into AI SDK UI stream events, which are rendered incrementally in the chat interface.

When the agent calls weather tooling, structured tool output is passed through the stream and rendered as componentized weather cards and 7-day forecast blocks.

Backend (Agents.Api)

• Microsoft.Agents.AI
• Microsoft.Agents.AI.AGUI
• Microsoft.Agents.AI.Hosting.AGUI.AspNetCore
• OllamaSharp

Frontend (Next.js UI)

The frontend is an App Router Next.js app that combines AI SDK chat state with AG-UI event translation.

• Uses useChat<ChatMessage> from @ai-sdk/react.
• Renders each message part by type:
  • Text parts -> animated MessageResponse.
  • Tool part tool-GetWeatherForecast -> WeatherRenderer with structured output.

Server route: AG-UI bridge

src/app/api/chat/route.ts is the protocol bridge between AI SDK UI streams and AG-UI SSE.

Main responsibilities:

• Validate inbound POST body with Zod (schema.ts).
• Convert UI message model to AG-UI RunAgentInput payload.
• Forward request to backend ${BACKEND_URL}/chat with Accept: text/event-stream.
• Parse SSE data lines into AG-UI events.
• Map AG-UI event types into AI SDK writer events.

Event mapping implemented:

• RUN_STARTED -> start
• RUN_FINISHED -> finish
• TOOL_CALL_START -> tool-input-start
• TOOL_CALL_ARGS -> tool-input-delta
• TOOL_CALL_RESULT -> tool-output-available
• TEXT_MESSAGE_START -> text-start
• TEXT_MESSAGE_CONTENT -> text-delta
• TEXT_MESSAGE_END -> text-end
• RUN_ERROR -> error

Weather UI composition model

Weather rendering is schema-driven using @json-render.

Core pieces:

• src/lib/weather-catalog.ts
  • Defines typed component catalog and prop schemas.
• src/components/weather/registry.tsx
  • Binds catalog components to concrete React implementations.
• src/lib/weather-spec.ts
  • Converts WeatherResult into JSON spec tree (Container -> WeatherCard + ForecastGrid -> multiple ForecastDay).
• src/components/weather/weather-renderer.tsx
  • Creates spec and renders through JSONUIProvider + Renderer.
• src/components/weather/weather-components.tsx
  • Implements presentational cards and condition icons.

This gives clean separation between:

• Data shape from tool output.
• Declarative UI spec generation.
• Actual visual component rendering.

Two protocol boundaries are central:

1. UI <-> Next route (/api/chat)
   • Validated with Zod (schema.ts).
   • Accepts role + text-part messages.
2. Next route <-> API AG-UI endpoint (/chat)
   • Uses AG-UI event schema and SSE frames.
   • Tool outputs can be structured JSON payloads.

Tool output contract used by UI:

• Weather output shape includes location, current metrics, and forecast array.
• Forecast day values are rendered directly into compact forecast cards.