Until recently, I thought creating AI agents was too complex, but the reality is that getting started is quite accessible. In this article, I explain step by step how to build a weather AI agent using TypeScript and Node.js, and how to turn it into a useful tool that responds with the current time, checks the weather, and suggests activities based on the situation.
Prerequisites: install Node.js and TypeScript. You will need an API key for the language model that will power your agent. A practical option is Gemini if you have a Google account, although you can also use OpenAI or Claude models by following their documentation to generate an API key. Add your key to the .env file as the value of the GOOGLE_GENERATIVE_AI_API_KEY variable.
Project scaffold: use the Mastra SDK for JavaScript and TypeScript. An example command to create the project is npx create-mastra@latest --project-name weather-ai --example --components tools,agents,workflows --llm google. The generated project includes an agent and an example weather tool. Run npm run dev and open the local interface at https://localhost:4111 to test the playground.
Architecture and structure: Mastra's convention separates logic into three main folders: agents, tools, and workflows. The weather-agent.ts file defines the weather agent with its model, system instructions, and the tools it can use. The agent's instructions act as the system prompt that guides its behavior: ask for location if missing, translate place names when they are not in English, include relevant details like humidity and wind, and suggest activities if the user requests them.
Tools and how they work: tools allow the LLM's brain to interact with the world. For example, weatherTool queries geocoding services and uses the open-meteo API to get temperature, feels-like temperature, humidity, wind speed, gusts, and condition code. Mastra allows defining input and output schemas with Zod to validate the data passing between agent and tool.
Expanding capabilities with new tools: to make the agent smarter, add a timeTool that returns the date and time according to a time zone. Create a file src/mastra/tools/time-tool.ts that implements a tool that formats the date, the time, and returns a timestamp. Then import timeTool in the agent definition and add it to the tools list so the agent can invoke it.
Integration and behavior: update the agent's instructions to indicate that, when the user asks for activities, the agent should use timeTool to get the local time and suggest appropriate options based on the time of day and the forecast. With this, the agent not only communicates the weather status but also proposes plans like going for a walk, going to the beach, bringing an umbrella, or nighttime activities depending on the time and weather.
Recommended practices: experiment with system instructions to adjust the agent's style and conciseness, always validate tool responses with schemas, and manage memory if you want the agent to remember past conversations. Adding more tools, such as web searches or integrations with external APIs, greatly expands the possibilities.
At Q2BSTUDIO, we are experts in custom software development and custom applications, and we can help you create personalized AI agents for your business. We offer services in artificial intelligence, AI for businesses, cybersecurity, and AWS and Azure cloud services to deploy scalable and secure solutions. We also work on business intelligence services and implementations with Power BI to transform data into actionable decisions.
If you are looking for custom software or custom applications that integrate AI agents with specific capabilities, Q2BSTUDIO accompanies you from design to production deployment. Our expertise in artificial intelligence and cybersecurity guarantees reliable implementations, while our AWS and Azure cloud services ensure scalability and availability.
Conclusion: building an AI agent in TypeScript is a straightforward process when you follow the right steps: prepare the environment, create the project with Mastra, define agents and tools, and adjust system instructions. With additional skills in artificial intelligence, cloud service integration, and data analysis with Power BI, you can enhance real solutions for businesses. If you want to develop an AI agent, improve your custom software, or implement business intelligence services, contact Q2BSTUDIO for specialized consulting in AI agents, AI for businesses, and secure solutions with a focus on cybersecurity and cloud.
