plan-flichClone

Prompt file imported from buisihung11/prototype-zero (.github/prompts/plan-flichClone.prompt.md). Copyright stays with the author.

Plan: Flich-Clone — Conversational AI Ride-Hailing Agent

TL;DR: Scaffold a C# Azure Functions (Durable) project named flich-clone inside the Nx monorepo at packages/flich-clone. The project uses the Microsoft Agent Framework with Azure Durable Functions to host a multi-agent ride-hailing system inspired by Uber's Finch architecture. Five specialized durable agents (Supervisor, RideRequest, DriverMatch, Pricing, RideStatus) are orchestrated via fan-out/fan-in patterns. Azure OpenAI provides the LLM backbone, Durable Task Scheduler manages state, and azd handles infrastructure provisioning. The Nx workspace gets custom targets wrapping dotnet, func, and azd CLI commands so all operations go through nx run flich-clone:<target>.

Steps

1. Install prerequisites tooling — Ensure .NET 9 SDK, Azure Functions Core Tools v4, Azure Developer CLI (azd), and Docker Desktop are available locally. No Nx plugins to install — the project uses custom Nx targets wrapping CLI commands.

2. Scaffold the C# Azure Functions project — Create packages/flich-clone/ with the following structure:

   • flich-clone.csproj — .NET 9 isolated worker project referencing NuGet packages: Azure.AI.OpenAI (prerelease), Azure.Identity, Microsoft.Agents.AI.OpenAI (prerelease), Microsoft.Agents.AI.Hosting.AzureFunctions (prerelease), Microsoft.Azure.Functions.Worker (≥2.2.0)
   • Program.cs — Entry point that creates 5 AIAgent instances via AzureOpenAIClient and registers them with ConfigureDurableAgents()
   • host.json — Azure Functions host configuration with Durable Task extension settings
   • local.settings.json — Local dev config pointing to Azurite and DTS emulator, with AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_DEPLOYMENT env vars

3. Define domain models — Create Models/ directory with C# records:

   • RideRequest (pickup, dropoff, riderName, timestamp)
   • Driver (driverId, name, location, available)
   • FareEstimate (baseFare, surgeFactor, totalFare, currency)
   • RideStatus (rideId, status enum, driverInfo, estimatedArrival)
   • Shared response types: TextResponse, RoutingDecision

4. Implement 5 durable agents in Program.cs — Each as an AIAgent with specialized instructions:

   • SupervisorAgent — "You are a ride-hailing assistant router. Analyze the user's request and determine which operation is needed: ride_request, driver_match, pricing, or ride_status. Return a JSON routing decision."
   • RideRequestAgent — "You process ride booking requests. Extract pickup/dropoff locations and rider details from natural language. Return structured ride request data."
   • DriverMatchAgent — "You match riders with available drivers based on proximity and availability. Given ride details, return the best matching driver."
   • PricingAgent — "You calculate ride fares. Given pickup/dropoff locations and current demand, compute base fare, surge multiplier, and total fare."
   • RideStatusAgent — "You track ride status. Given a ride ID, return current status, driver location, and estimated arrival time."

5. Create orchestration functions in Orchestrations/:

   • RideBookingOrchestration.cs — Sequential+parallel pattern: SupervisorAgent routes → RideRequestAgent extracts details → fan-out to PricingAgent and DriverMatchAgent in parallel → fan-in and return combined booking result (fare + assigned driver)
   • RideStatusOrchestration.cs — Simple sequential: SupervisorAgent routes → RideStatusAgent returns status
   • Both use context.GetAgent() to obtain DurableAIAgent instances and RunAsync<T>() for typed responses

6. Create Nx project configuration — Add packages/flich-clone/project.json with custom targets:

   • build → dotnet build
   • serve → func start (requires Azurite + DTS emulator running)
   • test → dotnet test
   • provision → azd provision
   • deploy → azd deploy
   • docker:azurite → starts Azurite container
   • docker:dts → starts DTS emulator container

7. Set up azd infrastructure — Create packages/flich-clone/azure.yaml and infra/ directory with Bicep templates:

   • infra/main.bicep — Orchestrates all modules
   • Modules for: Azure OpenAI (gpt-4o-mini deployment), Azure Functions (Flex Consumption plan), Azure Storage account, Durable Task Scheduler (Consumption plan), managed identity with RBAC
   • azure.yaml — azd project definition pointing to the function app

8. Add workspace integration — Update root tsconfig.base.json paths if needed for any shared TS types in the future. No npm workspace linking needed since C# uses NuGet, not npm.

9. Local development setup — Document the startup sequence:

   • Terminal 1: nx run flich-clone:docker:azurite (Azurite on ports 10000-10002)
   • Terminal 2: nx run flich-clone:docker:dts (DTS emulator on ports 8080, 8082)
   • Terminal 3: nx run flich-clone:serve (Azure Functions on port 7071)
   • DTS dashboard at http://localhost:8082 for observability

Verification

• nx run flich-clone:build — compiles without errors
• nx run flich-clone:serve — starts locally; test with curl -X POST http://localhost:7071/api/agents/SupervisorAgent/run -H "Content-Type: text/plain" -d "I need a ride from Times Square to JFK airport"
• Verify multi-agent orchestration: curl -X POST http://localhost:7071/runtime/webhooks/durabletask/orchestrators/RideBookingOrchestration -H "Content-Type: application/json" -d '"I need a ride from Times Square to JFK airport"' then poll status endpoint until Completed
• Verify conversation continuity by reusing x-ms-thread-id from first response in follow-up requests
• Check DTS dashboard at http://localhost:8082 to see agent sessions and orchestration visualizations
• nx run flich-clone:provision + nx run flich-clone:deploy for Azure deployment

Decisions

• C# over TypeScript: Microsoft Agent Framework durable agents have full C# support (auto state persistence, multi-agent orchestrations, DTS observability). TypeScript would require reimplementing these features manually.
• Custom Nx targets over Nx plugin: No @nx/dotnet or @nx/azure-functions plugin exists. Wrapping dotnet/func/azd CLI in Nx executor commands keeps the monorepo workflow consistent (nx run flich-clone:*).
• 5 agent architecture: Mirrors Finch's modular agent pattern (Supervisor → specialized sub-agents) adapted for ride-hailing domain.
• azd for infra: Follows the Microsoft docs recommendation; provides one-command provisioning and deployment with Bicep IaC templates included in the project.