HazelJS Meal Planner Shows the Real Shape of Agentic Application Design

Problem

The DEV Community article describes a TypeScript meal-planning and grocery-shopping agent built with HazelJS. The example is framed around a familiar consumer workflow: collect dietary constraints, search recipes, generate a week of meals, and turn the result into a shopping list. That sounds simple until the system has to behave like software rather than a demo prompt.

Meal planning is a good distributed-systems exercise in disguise. The user asks for something broad, but the application has to break that request into smaller operations with different reliability and consistency expectations. Dietary intake needs structured extraction. Recipe lookup needs retrieval over a knowledge base. Meal planning needs constraint satisfaction. Shopping-list generation needs aggregation, deduplication, and cost estimation. Nutrition guidance needs guardrails because a confident hallucination can become harmful advice.

The article’s architecture splits those responsibilities across agents: DietaryIntakeAgent, RecipeSearchAgent, MealPlanAgent, ShoppingListAgent, and NutritionCoachAgent. In HazelJS terms, decorators such as @Agent, @Tool, and @Delegate define the control surface between the language model and application code. That matters because agent systems fail most often at the boundaries: unclear tool contracts, missing state, weak validation, and unobservable delegation chains.

The implementation uses TypeScript and presents HazelJS as a production-oriented framework for AI-native applications. The sample combines retrieval-augmented generation, supervisor routing, retries, circuit breakers, rate limiting, guardrails, and an inspector endpoint. Those are not ornamental pieces. They are the difference between an agent that works in a README and one that can survive real users, repeated calls, partial failures, and changing data.

Solution Approach

The core design is a supervisor pattern. The NutritionCoachAgent owns the workflow and delegates narrower tasks to specialized agents. That gives the application a clear control plane: one agent decides the sequence, but the work is performed by components with smaller prompts, smaller tool sets, and more predictable outputs.

That separation is a practical API design choice. A single large prompt could ask the model to extract preferences, search recipes, plan meals, and produce a shopping list in one pass. It would be cheaper to wire up, but harder to test and harder to recover when one part fails. By making dietary intake, retrieval, planning, and shopping-list generation explicit operations, the system creates checkpoints. Each checkpoint can be logged, validated, retried, cached, or replaced.

The dietary intake step is the first consistency boundary. The agent extracts fields such as dietary restrictions, budget, cooking time, cuisine preferences, and nutritional goals. This should not be treated as free-form text once extracted. It becomes application state. If the user says they are vegetarian and have a $150 weekly budget, every later step needs to read from the same structured profile rather than reinterpret the original sentence independently.

In database terms, the extracted profile is a materialized view of the user’s request. It may be incomplete or wrong, but it is the version the rest of the workflow depends on. A production system would usually attach confidence scores, preserve the raw input, and allow correction. Without that, the application risks silent inconsistency: the recipe search might respect vegetarian constraints while the shopping list accidentally includes chicken stock because another model call inferred preferences differently.

The recipe search step uses retrieval-augmented generation. The article shows a RecipeKnowledgeBaseService backed by MemoryVectorStore, local embeddings, and a RAGPipeline using hybrid retrieval. The important design point is that recipe selection is not left entirely to the model’s parametric memory. The model retrieves from a known recipe corpus, then the response includes source metadata such as recipe IDs, cuisine, dietary labels, and scores.

That is the right pattern for bounded domains. Recipes, prices, availability, allergens, and nutrition data change. A model cannot be the database. RAG gives the system a way to combine semantic search with controlled source material. Hybrid retrieval also matters because user requests mix semantic intent and exact constraints. “High-protein vegetarian dinners under 30 minutes” needs both meaning and filters. Pure vector search may retrieve thematically similar recipes that violate a hard constraint. Pure keyword search may miss close matches. Hybrid retrieval gives the system more room to balance both.

The shopping-list step is where agent output starts to look like a database aggregation problem. A meal plan produces repeated ingredients across recipes. The list generator has to normalize names, combine quantities, group by category, estimate costs, and preserve traceability back to meals. This is the kind of operation that should be deterministic wherever possible. Let the model help with classification or substitution suggestions, but keep arithmetic and deduplication in ordinary code.

A useful rule for systems like this is simple: use the model where ambiguity is the input, and use code where correctness is the output. Extracting “cheap vegetarian dinners for a busy week” requires language understanding. Adding quantities and enforcing a budget requires deterministic logic. If the framework makes every step look like an agent call, the engineering discipline is to resist that temptation.

HazelJS’s configuration in the article includes retries, circuit breakers, rate limiting, metrics, observability, and guardrails. Those features map directly to known failure modes in distributed systems. LLM providers time out. Tool calls fail. Retrieval returns empty sets. Users send prompt-injection attempts, sometimes intentionally and sometimes because copied web content contains hostile instructions. Downstream APIs impose quotas. A multi-agent workflow magnifies those problems because one user request may expand into several model calls and tool invocations.

The inspector endpoint at /__hazel is especially relevant. Agent systems need traces, not just logs. When a meal plan is wrong, the developer needs to know whether the failure came from intake extraction, retrieval, planning, shopping aggregation, or final response synthesis. Without tracing, the whole workflow collapses into “the model gave a bad answer,” which is not actionable.

For production observability, the same idea should extend beyond a local inspector into trace and metric systems such as OpenTelemetry. Each request should carry a correlation ID. Each agent step should record latency, token usage, tool calls, retrieval scores, retry count, and failure classification. That is basic operational hygiene once agent calls become part of a user-facing API.

Trade-offs

The main scalability trade-off is orchestration overhead. A supervisor-agent design is easier to reason about than one huge prompt, but it costs more calls. One request can turn into intake extraction, recipe retrieval, meal-plan synthesis, shopping-list generation, and final coaching. If each step calls a remote model, latency and cost grow quickly.

Caching helps, but only if the system defines cache keys carefully. Recipe retrieval for “high-protein vegetarian meals” can be cached by normalized query and constraints. Dietary intake should usually not be cached across unrelated requests unless attached to a user profile with versioning. Shopping lists may be cached for a specific meal-plan ID, but not for a mutable plan. The cache invalidation problem is not exotic here. It is the same old problem with a model-shaped interface on top.

The consistency model should also be explicit. A meal plan and its shopping list are derived data. If the user edits Tuesday dinner after the list is generated, the system must decide whether to update the list synchronously, mark it stale, or regenerate it asynchronously. For a small demo, synchronous regeneration is fine. For a production grocery workflow, eventual consistency may be acceptable if the UI shows state clearly: “shopping list generated from plan version 4.”

Versioning matters because agent output is nondeterministic even at low temperature when upstream dependencies change. Recipe databases evolve, embedding models change, providers update models, and prompts get revised. If a user asks why their saved shopping list changed, the system needs a record of the recipe IDs, plan version, prompt version, model name, retrieval scores, and generated output. Otherwise, reproducibility is mostly fiction.

There is also an API design trade-off around how much of the agent system should be exposed. The article shows endpoints such as /meal/intake, /meal/recipes, and /meal/supervisor. That is a useful split. Low-level endpoints help with testing and debugging. The supervisor endpoint gives clients a simpler workflow API. In production, I would keep both layers but treat them differently: internal or developer-facing endpoints for individual steps, and a stable public endpoint for the full meal-planning operation.

The request and response schemas should be boring and strict. A good /meal/supervisor response would include a normalized user profile, selected recipes with source IDs, meal-plan entries, shopping-list items, warnings, and trace metadata. Free-form markdown is useful for display, but it should not be the system of record. If another service needs to order groceries, estimate cost, or check allergens, it needs structured fields.

Guardrails are another trade-off. The article enables PII redaction, prompt-injection blocking, and toxicity blocking by default. That is a sensible baseline, but guardrails should not be treated as a final security boundary. Prompt injection is an application design problem as much as a model-filtering problem. Retrieved recipe content should be separated from instructions. Tool permissions should be narrow. The recipe-search agent should not have access to user-account mutation tools. The shopping-list agent should not be able to change dietary preferences. The OWASP prompt injection guidance is a useful reference because it frames the issue as input handling, trust boundaries, and control isolation.

Provider choice is another practical concern. The article suggests replacing the local provider with hosted models from OpenAI, Anthropic, or Google Generative AI. That swap is attractive, but it changes the system’s latency, cost, privacy posture, and failure modes. A local model gives more control and easier offline testing. A hosted model may give better reasoning and extraction quality. The abstraction should make provider replacement possible, but product behavior still needs to be revalidated whenever the model changes.

The RAG layer has its own scaling path. An in-memory vector store is fine for a tutorial and local evaluation. It is not enough for a large recipe corpus, multi-tenant users, freshness requirements, or high query volume. Production systems usually need persistent indexing, metadata filters, batch ingestion, re-embedding jobs, and relevance evaluation. More retrieval also means more consistency questions: when a recipe is updated, are old meal plans pinned to the old recipe version or automatically moved to the new one?

The cleanest part of the article is that it treats agent orchestration as application architecture rather than prompt decoration. The meal planner has agents, tools, retrieval, guardrails, and observability because the workflow needs boundaries. That is the lesson worth carrying over. Agent systems are distributed systems with probabilistic components. They need the same old engineering habits: stable contracts, typed state, retries with limits, traceability, source attribution, access control, and clear consistency rules.

A meal planner does not sound like infrastructure, but it exposes the problems early. The user’s request is vague. The data is external. The workflow has multiple steps. Some constraints are hard, some are preferences, and some are safety-related. The final answer must be readable, but the intermediate state must be structured. That is exactly where many AI applications break after the demo phase.

HazelJS, as presented in the article, is trying to give developers a framework for those boundaries. The real test for any framework in this category is not whether it can call a model. Everyone can call a model. The test is whether it helps engineers keep state coherent, failures visible, APIs stable, and behavior understandable after the first happy path stops being representative.