🚀 Technical Briefing:This tutorial is part of our deep-dive series on Agentic Workflows at[Gate of AI]. For the full technical breakdown, interactive code sandbox, and the native Arabic translation, visit the[original article here].
Tutorial
Design a weather assistant that treats the language model as an orchestrator, keeps factual measurements in trusted tools, and enforces explicit policies before data is shown to a user.
A weather assistant sounds simple: a person asks for rain, temperature, wind, or a recommendation such as whether to carry an umbrella. But the application is making factual claims about an external, changing environment. A language model can write a clear explanation, yet it is not itself a weather instrument, forecast service, numerical solver, or authorization system.
The verified research context supports a practical principle for this kind of agent: a numerical result should be reported only when it originates from a trusted tool and passes explicit verification. The principle comes from research on LLM and agentic systems for smart grids, a domain where outputs can appear numerically plausible while remaining physically infeasible or untrustworthy. Weather applications are different from grid control, but the design lesson transfers directly. Do not let polished prose substitute for a verified measurement.
This tutorial therefore focuses on an architecture rather than claiming a particular SDK, model, weather provider, framework version, or endpoint contract. Before implementing any code, verify current vendor documentation for your chosen Next.js release, OpenAI API, weather-data provider, authentication system, deployment environment, and applicable organisational requirements.
The finished pattern has five clear responsibilities. The browser collects a user question. A server-side route accepts only a constrained request shape. A language model may decide that an approved weather capability is needed. The server validates that proposed capability call, invokes a trusted weather-data service, verifies the returned result, and gives a small structured result back to the model. Finally, the model produces an explanation based on that verified result.
The central rule is simple: the model may request an approved tool, but it must not receive authority to define the tool, choose arbitrary network destinations, alter authorization, or invent measurements when a tool fails.
This separation also makes the design useful beyond weather. The same pattern can support controlled access to internal data, forecasting solvers, analytics systems, and business workflows. In every case, the application—not the model—remains responsible for the action boundary.
Do not start with a broad prompt such as “help users with weather.” Start with a policy that an engineer can implement and test. This is important because the verified symbolic-guardrails research found that 85% of reviewed agent safety and security benchmarks lacked concrete policies. High-level goals and common sense are not precise enough for reliable enforcement.
For a read-only weather assistant, a practical policy could state the following: These are not merely prompt instructions. Convert them into deterministic checks in server code. The symbolic-guardrails study reports that 74% of specified policy requirements can be enforced by symbolic guardrails, often with simple, low-cost mechanisms. An allowlist, schema validator, date parser, maximum-call counter, and field-level verifier are examples of straightforward controls that do not rely on the model obeying prose.
A narrow tool contract is easier to authorize and verify than a universal network tool. Your weather capability should express the smallest useful action: retrieve a forecast for one resolved location and one date. It should not accept a raw URL or a generic request method. It should not accept arbitrary headers. It should not allow the model to select a data provider.
At a conceptual level, the input contract contains a city or location query and an optional date. The output contract contains only the fields your answer needs: a canonical location name, a country or region when available, the forecast date, weather condition, temperature, precipitation information, wind information, units, source timestamp or freshness metadata where the provider supplies it, and a verification status.
Keep the raw provider response inside the tool implementation. Returning an entire external payload to the model is unnecessary and expands the chance that unexpected text or fields influence the assistant. Instead, normalize the source response into a small data object. Treat all tool output as untrusted input until your verification layer has checked it.
For example, if the question is “Will it rain in Dubai tomorrow?”, a suitable internal result is not a paragraph. It is a structured record indicating the resolved location, the relevant local date, precipitation information, units, and whether the record passed verification. The model can then transform that record into a concise answer without being asked to calculate or guess the underlying values. The application should run the loop on the server. The browser should send a limited conversation representation to your own endpoint, not provider credentials, model configuration, tool definitions, or previous tool outputs. The server creates the system instructions, selects the approved model and tools, and applies policy checks.
A safe loop follows this sequence:
Do not allow recursive execution without limits. Bound the number of tool calls, total elapsed time, request size, and any cost-related budget your deployment can measure. A limit turns an unexpected chain of requests into a controlled failure instead of an open-ended operational event.
When a request fails, return a useful user message such as “I could not confirm live weather data for that location and date.” Keep detailed operational information in protected server-side logs, with a request identifier and appropriate redaction. Do not return provider secrets, internal stack traces, or raw upstream payloads to the browser.
Tool use alone is not enough. A tool can fail, return incomplete data, resolve the wrong city, return stale records, or provide values in a unit the application does not expect. The solver-grounded principle requires an explicit verification step between retrieval and reporting.
Your verifier should check at least the following conditions:
If any critical check fails, do not pass a “best effort” measurement to the model. Pass a structured failure result instead. The final answer can explain the limitation and request a more specific city or date. This is more trustworthy than a fluent answer built on incomplete or mismatched data. The user experience should reflect the actual state of the system. While the server is retrieving and verifying data, show a state such as “Checking forecast data.” Disable duplicate submissions for a single ordered conversation, or deliberately implement request IDs and reconciliation rules if your product supports parallel questions.
Label the assistant as a weather information interface rather than implying direct observation. Show the resolved place and forecast date in the final answer whenever the data is available. If the system cannot verify live data, show an error state rather than leaving a blank response or presenting generic weather advice as a current forecast.
For audiences in Saudi Arabia, the UAE, and the wider GCC, localisation should be a product decision backed by verified requirements: clarify place names, time zones, date formats, languages, units, accessibility needs, retention rules, and operational ownership before launch. Do not make data-residency, regional-cloud, or government-initiative claims unless they are supported by current authoritative sources and your actual deployment configuration. Testing a tool-calling agent should focus on what must always remain true regardless of model output. A model may phrase a correct answer in many ways, so sentence matching is not the core safety test. Instead, create tests around policy enforcement, tool validation, verification, and failure handling.
Use mocked provider responses for these cases. This keeps tests deterministic and lets you model outages, malformed data, ambiguous locations, and unexpected tool output without depending on a live external service. Maintain a versioned evaluation set containing normal weather questions, vague place names, invalid dates, adversarial instructions, and multi-turn requests. Before publishing, verify current official documentation for every concrete library and provider used in your implementation. Store secrets only in server-side deployment configuration. Apply authentication and appropriate quotas when the endpoint is not a private demo. Use protected logging, set clear retention rules, monitor tool failures and latency, and maintain an incident process for upstream weather-data failures.
Most importantly, preserve the architectural boundary as the system grows. A model can identify that a trusted capability is useful. The server decides whether the capability is allowed, validates inputs, performs the request, verifies the result, and records the outcome. That is the foundation for a weather agent that is helpful without treating model-generated text as a substitute for verified external facts.
A reliable Next.js OpenAI weather agent is not defined by a chat box or a single tool call. It is defined by a solver-grounded workflow: trusted tools produce factual values, explicit checks verify those values, and the language model explains only what the verified workflow permits it to explain. This pattern gives teams a durable starting point for weather experiences and for more consequential agentic applications.
Sources: LLMs and Agentic AI Systems for Smart Grids: A Tutorial on Architectures and Applications; Symbolic Guardrails for Domain-Specific Agents.