Introduction

Travel planning can be overwhelming. Where should you go? What attractions are worth visiting? What do you need to know before arriving in a new country? I built WanderWise, an AI-powered tour guide agent that answers these questions and more, integrated seamlessly with Telex.im using Mastra’s A2A protocol.

The Problem

Travelers often struggle with:

• Finding authentic tourist attractions in unfamiliar cities
• Getting reliable country information (currency, languages, customs)
• Accessing travel tips and cultural insights in one place
• Navigating through scattered information across multiple websites

I wanted to create a single AI agent that could be a traveler’s comprehensive companion.

Why WanderWise?

The name combines “Wander” (exploring new places) with “Wise” (knowledgeable guidance). It’s clear, memorable, and perfectly captures what the agent does — helps you wander wisely through the world.

While the technical project is called tourguide-ai-agent on GitHub (for clarity and searchability), the user-facing brand is WanderWise - because travelers deserve a companion, not just a tool.

Technical Architecture

Tech Stack

• Framework: Mastra (for AI agent orchestration)
• Language: TypeScript
• Model: Google Gemini 2.5 Flash
• Integration: A2A Protocol (Agent-to-Agent communication)
• Platform: Telex.im
• APIs:
• OpenStreetMap Overpass API (tourist attractions)
• REST Countries API (country information)
• Wikipedia API (travel insights and city overviews)

Why These APIs?

I chose 100% free, no-API-key-required services to ensure:

• Zero cost: No billing surprises
• Reliability: Mature, community-maintained APIs
• Global coverage: Works for any country or city worldwide
• Rich data: Comprehensive information about destinations

Building WanderWise

Step 1: Creating Mastra Tools

I built three core tools using Mastra’s createTool function with Zod schemas for type safety:

1. Tourist Attractions Tool

export const touristAttractionsTool = createTool({
  id: 'get-tourist-attractions',
  description: 'Get tourist attractions, museums, monuments, and points of interest',
  inputSchema: z.object({
    city: z.string(),
    country: z.string(),
    limit: z.number().optional().default(10),
  }),
  execute: async ({ context }) => {
    // Geocode the city using Nominatim
    // Query Overpass API for attractions
    // Return formatted results
  },
});

This tool:

• Geocodes city names to coordinates using Nominatim (OpenStreetMap’s geocoding service)
• Searches OpenStreetMap for attractions within city boundaries
• Returns up to 10 tourist spots with descriptions, addresses, and coordinates

2. Country Information Tool

export const countryInfoTool = createTool({
  id: 'get-country-info',
  description: 'Get general information about a country',
  inputSchema: z.object({
    country: z.string(),
  }),
  execute: async ({ context }) => {
    // Fetch from REST Countries API
    // Return capital, languages, currency, timezone, etc.
  },
});

This provides essential travel information: capital city, languages spoken, currency, population, timezone, and driving side.

3. Travel Tips Tool

export const travelTipsTool = createTool({
  id: 'get-travel-tips',
  description: 'Get travel tips and city overview',
  inputSchema: z.object({
    city: z.string(),
    country: z.string(),
  }),
  execute: async ({ context }) => {
    // Search Wikipedia for city information
    // Extract summary and overview
    // Combine with general travel tips
  },
});

This tool fetches Wikipedia summaries about cities and combines them with practical travel advice.

Step 2: Creating the WanderWise Agent

export const tourGuideAgent = new Agent({
  name: 'Tour Guide Agent',
  instructions: `
    You are WanderWise, an expert tour guide AI assistant specializing in helping travelers discover amazing destinations around the world.
    
    Your capabilities:
    - Find tourist attractions, museums, monuments, and points of interest
    - Provide comprehensive country information
    - Share travel tips, cultural insights, and safety recommendations
    - Help travelers plan trips with specific, actionable advice
    
    Always be enthusiastic, helpful, and encouraging about travel.
    Make travelers excited about their destinations!
  `,
  model: 'google/gemini-2.5-flash',
  tools: {
    touristAttractionsTool,
    countryInfoTool,
    travelTipsTool,
  },
  memory: new Memory({
    storage: new LibSQLStore({
      url: 'file:../mastra.db',
    }),
  }),
});

Key features:

• Conversational AI: Uses Google Gemini 2.5 Flash for intelligent, natural responses
• Tool integration: Automatically decides which tool to use based on user queries
• Memory: Maintains conversation history for context-aware interactions
• Personality: Friendly and enthusiastic, like a real tour guide

Step 3: Building the A2A Route Handler

The crucial bridge between Mastra and Telex is the A2A protocol handler. This was one of the most challenging parts of the project:

export const a2aAgentRoute = registerApiRoute('/a2a/agent/:agentId', {
  method: 'POST',
  handler: async (c) => {
    // Parse JSON-RPC 2.0 request
    const body = await c.req.json();
    const { jsonrpc, id: requestId, method, params } = body;
    
    // Validate format
    if (jsonrpc !== '2.0' || !requestId) {
      return c.json({ /* error response */ });
    }
    
    // Get agent
    const agent = mastra.getAgent(agentId);
    
    // Extract and convert messages
    const mastraMessages = messagesList.map((msg) => ({
      role: msg.role,
      content: msg.parts?.map((part: { kind: 'text' | 'data', text?: string, data?: object}) => {
        if (part.kind === 'text') return part.text || '';
        if (part.kind === 'data') return JSON.stringify(part.data);
        return '';
      }).join('\n') || ''
    }));
    
    // Execute agent
    const response = await agent.generate(mastraMessages);
    
    // Return A2A-compliant response with artifacts and history
    return c.json({
      jsonrpc: '2.0',
      id: requestId,
      result: { /* properly formatted A2A response */ }
    });
  }
});

This handler:

• Validates JSON-RPC 2.0 format (critical for A2A compliance)
• Converts A2A messages to Mastra’s expected format
• Executes the WandaWise agent with proper context
• Wraps responses in A2A format with artifacts and conversation history
• Handles errors gracefully with proper JSON-RPC error codes

Step 4: Registering with Mastra

export const mastra = new Mastra({
  agents: { tourGuideAgent },
  storage: new LibSQLStore({ url: ':memory:' }),
  logger: new PinoLogger({ 
    name: 'Mastra', 
    level: 'debug' 
  }),
  server: {
    build: {
      openAPIDocs: true,
      swaggerUI: true,
    },
    apiRoutes: [a2aAgentRoute]
  }
});

Challenges and Solutions

Challenge 1: Finding Reliable Free APIs

Problem: Many tourist APIs require paid subscriptions or have strict usage limits.

Solution: After researching multiple options, I discovered OpenStreetMap’s Overpass API, which provides comprehensive point-of-interest data globally without any authentication. Combined with REST Countries and Wikipedia APIs, I had a complete free solution that rivals paid services.

Challenge 2: TypeScript Type Safety with A2A Protocol

Problem: The A2A protocol has complex nested structures. TypeScript was throwing errors about implicit any types and type mismatches in the message parts.

Solution: I took a pragmatic approach using inline type annotations where needed:

// Inline type for message parts with union types
const mastraMessages = messagesList.map((msg) => ({
  role: msg.role,
  content: msg.parts?.map((part: { kind: 'text' | 'data', text?: string, data?: object}) => {
    if (part.kind === 'text') return part.text;
    if (part.kind === 'data') return JSON.stringify(part.data);
    return '';
  }).join('\n') || ''
}));

For the artifacts type mismatch with tool results, I used type assertion:

artifacts.push({
  artifactId: randomUUID(),
  name: 'ToolResults',
  parts: response.toolResults.map((result) => ({
    kind: 'data',
    data: result
  }))
} as any);  // Type assertion for flexibility

This pragmatic approach balanced type safety with development speed. For a focused project like this, inline types were more maintainable than creating extensive interface definitions.

Challenge 3: JSON Formatting in Workflow Definition

Problem: Telex.im workflow JSON doesn’t accept multi-line strings with actual line breaks — it would throw parsing errors.

Solution: Used \n escape sequences instead of actual newlines in the long_description field:

"long_description": "I'm WanderWise, your expert AI tour guide...\n\nMy capabilities:\n- Find attractions\n- Get country info"

This is standard JSON practice, but easy to forget when copying from formatted text.

Integration with Telex.im

Deployment

Deploying WandaWise to Mastra Cloud was straightforward:

# Build the project
npm run build

# Deploy to Mastra Cloud
mastra deploy

After deployment, Mastra Cloud provides a unique A2A endpoint URL:

https://your-deployment.mastra.cloud/a2a/agent/tourGuideAgent

Workflow Definition

I created a Telex workflow JSON that defines how WanderWise appears on the platform:

{
  "active": true,
  "category": "travel",
  "description": "WanderWise - Your AI travel companion for discovering amazing destinations",
  "id": "tour_guide_agent",
  "name": "wanderwise_tour_guide",
  "long_description": "I'm WanderWise, your expert AI tour guide...",
  "short_description": "Your AI travel companion - discover attractions, get travel tips, and explore the world",
  "nodes": [
    {
      "id": "tour_guide_agent_node",
      "name": "Tour Guide Agent",
      "type": "a2a/mastra-a2a-node",
      "typeVersion": 1,
      "url": "https://your-deployment.mastra.cloud/a2a/agent/tourGuideAgent"
    }
  ]
}

The critical field is type: "a2a/mastra-a2a-node" which tells Telex to use the A2A protocol for communication with WanderWise.

How It Works: A Complete Flow

Let me walk you through what happens when a user interacts with WanderWise:

1. User asks a question on Telex: “What are tourist attractions in Lagos, Nigeria?”
2. Telex constructs an A2A request:

{
  "jsonrpc": "2.0",
  "id": "request-001",
  "method": "message/send",
  "params": {
    "message": {
      "kind": "message",
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "What are tourist attractions in Lagos, Nigeria?"
        }
      ],
      "messageId": "msg-001",
      "taskId": "task-001"
    }
  }
}

3. WanderWise processes the request:

• A2A route handler receives the JSON-RPC request
• Extracts the user’s message from the A2A format
• Converts it to Mastra’s message format
• WanderWise agent analyzes the query
• Decides to use touristAttractionsTool
• Tool geocodes “Lagos, Nigeria” to coordinates
• Queries OpenStreetMap Overpass API for attractions in that area
• Returns structured data about 10 tourist spots

4. Agent generates response:

• Gemini processes the tool results
• Crafts a friendly, conversational response
• Includes relevant details about each attraction

5. Returns A2A-compliant response:

{
  "jsonrpc": "2.0",
  "id": "request-001",
  "result": {
    "id": "task-001",
    "status": {
      "state": "completed",
      "message": {
        "role": "agent",
        "parts": [
          {
            "kind": "text",
            "text": "Here are 10 amazing places to visit in Lagos..."
          }
        ]
      }
    },
    "artifacts": [
      {
        "name": "tourGuideAgentResponse",
        "parts": [{"kind": "text", "text": "Here are..."}]
      },
      {
        "name": "ToolResults",
        "parts": [{"kind": "data", "data": {...}}]
      }
    ],
    "history": [...]
  }
}

6. Telex displays the response to the user in a beautiful, formatted way

Example Conversations with WanderWise

Finding Tourist Attractions

User: “What are the top attractions in Cape Town, South Africa?”

WanderWise: “Here are 10 amazing places to visit in Cape Town:

1. Table Mountain (Attraction) — The iconic flat-topped mountain offering stunning panoramic views of the city and coastline
2. Robben Island (Museum) — Historic prison island where Nelson Mandela was held for 18 years
3. V&A Waterfront (Attraction) — Vibrant harbor area with shopping, dining, and entertainment
4. Kirstenbosch Botanical Gardens (Attraction) — World-renowned botanical garden at the foot of Table Mountain
5. Cape Point (Viewpoint) — Dramatic cliffs and lighthouse at the southern tip of the peninsula …”

Getting Country Information

User: “Tell me about Kenya”

WanderWise: “🇰🇪 Here’s what you should know about Kenya:

Capital: Nairobi Languages: Swahili, English Currency: Kenyan Shilling (KES) Population: 54.9 million Timezone: EAT (UTC+3) Region: Eastern Africa Driving: Left side of the road

Kenya is known for its stunning wildlife, beautiful beaches, and the Great Rift Valley. It’s home to world-famous national parks and reserves!”

Travel Tips

User: “Give me travel tips for Abuja”

WanderWise: “Here are essential tips for visiting Abuja, Nigeria:

About Abuja: Abuja is the capital city of Nigeria, located in the center of the country. It was built in the 1980s and officially became the capital in 1991, replacing Lagos. The city is known for its modern architecture, including the Aso Rock and the Nigerian National Mosque.

Travel Tips: ✅ Carry Nigerian Naira for local markets and small vendors ✅ Learn basic Hausa or Pidgin English phrases — locals appreciate the effort ✅ Respect local dress codes, especially when visiting government areas or religious sites ✅ Stay hydrated — Abuja has a tropical climate ✅ Be cautious with street food initially until your stomach adjusts ✅ Keep copies of important documents (passport, visa) ✅ Use reputable transportation services like registered taxis or ride-sharing apps ✅ The best time to visit is during the dry season (November to March)

Safe travels! 🌍✈️”

What I Learned Building WanderWise

1. The Power of Mastra’s Tool System

Mastra’s createTool with Zod schemas made it incredibly easy to build type-safe, composable tools. The agent automatically handles tool selection and execution based on the user's query - I didn't have to write any routing logic.

2. A2A Protocol is the Future

The Agent-to-Agent protocol provides a standardized way for AI agents to communicate across platforms. Once you implement it correctly, your agent can work with any A2A-compliant system without modification. This interoperability is game-changing.

3. Free APIs Can Be Enterprise-Grade

You don’t always need expensive APIs. OpenStreetMap has better coverage than some paid services, Wikipedia provides rich contextual information, and REST Countries is more reliable than many paid alternatives. The key is knowing where to look.

4. Type Safety Saves Time

Taking the time to properly type A2A messages saved me from countless runtime errors. TypeScript caught bugs before they reached production, and the autocomplete made development much faster.

5. User Experience is Everything

The way you write agent instructions directly impacts how users perceive the AI. WanderWise’s friendly, enthusiastic tone makes travel planning feel exciting rather than overwhelming. Users don’t just get information — they get inspired.

6. Error Handling Matters

Implementing proper JSON-RPC error codes and graceful degradation meant WanderWise could handle edge cases smoothly. When a city isn’t found, it suggests alternatives rather than crashing.

Project Structure

For anyone wanting to replicate this, here’s the complete structure:

tourguide-ai-agent/
├── src/
│   └── mastra/
│       ├── agents/
│       │   └── tour-guide-agent.ts
│       ├── tools/
│       │   └── tour-guide-tools.ts
│       ├── routes/
│       │   └── a2a-agent-route.ts
│       └── index.ts
├── package.json
├── tsconfig.json
└── README.md

Future Enhancements for WanderWise

I’m planning to add:

• Weather integration: Real-time weather forecasts for destinations
• Flight search: Find and compare flight prices
• Hotel recommendations: AI-curated accommodation suggestions based on budget and preferences
• Itinerary builder: Multi-day trip planning with optimized routes
• Budget calculator: Estimate total trip costs including accommodation, food, and activities
• Local events: Discover festivals, concerts, and events happening during your visit
• Photo suggestions: Best spots and times for photography at each attraction
• Safety alerts: Real-time travel advisories and safety information
• Language phrases: Essential phrases in the local language
• Currency converter: Real-time exchange rates and cost comparisons

Performance and Scalability

WanderWise handles requests efficiently:

• Average response time: 2–3 seconds for attraction queries
• API reliability: 99.9% uptime (thanks to robust free APIs)
• Cost: $0 for API calls, completely free with Gemini 2.5 Flash free tier
• Scalability: Mastra Cloud handles auto-scaling seamlessly

Conclusion

Building WanderWise taught me how to:

• Design and implement AI agents using Mastra’s framework
• Integrate with platforms using the standardized A2A protocol
• Work with free, high-quality APIs to build production-ready solutions
• Create type-safe TypeScript applications with complex data structures
• Build user-friendly conversational AI that feels natural and helpful
• Handle real-world challenges like API limitations and type mismatches

The combination of Mastra’s powerful framework, the A2A protocol’s standardization, and Telex.im’s platform made it possible to build a production-ready AI tour guide in just a few days. What would have taken weeks with custom infrastructure was accomplished quickly thanks to these modern tools.

Whether you’re planning a trip to Lagos, exploring Cape Town, curious about Kenya, or dreaming about any destination worldwide, WanderWise is ready to be your travel companion. 🌍✈️

Try It Yourself

Want to build your own Mastra agent? Here’s the quick-start path:

1. Install Mastra: npm create mastra@latest
2. Create your tools using createTool with Zod schemas
3. Build your agent with clear instructions and tool integration
4. Implement A2A route for Telex integration
5. Deploy: mastra deploy
6. Integrate with Telex: Create workflow JSON and test

The possibilities are endless. Customer support bots, data analysis agents, code reviewers, content generators — what will you build?

Links and Resources

• GitHub Repository: https://github.com/Henshaw-knight/tourguide-ai-agent
• Live Demo on Telex: telex.im/
• Mastra Documentation: https://docs.mastra.ai
• A2A Protocol Spec: https://a2a.ai
• OpenStreetMap Overpass API: https://overpass-api.de
• REST Countries API: https://restcountries.com
• Wikipedia API: https://www.mediawiki.org/wiki/API

Built with ❤️ by Henshaw.
Tech Stack: Mastra, TypeScript, Google Gemini 2.5 Flash, free APIs
Special Thanks: Mastra team for the amazing framework, HNG Internship for the challenge

Have questions about WanderWise or want to collaborate? Reach out on Twitter [@Henshaw_knight] or GitHub!

In today’s digital age, technology is advancing at an unprecedented pace, transforming industries and creating exciting career opportunities. In this rapidly evolving tech landscape, the journey to success often begins with finding the right opportunities. Whether you are a seasoned professional looking for your next career move or a budding enthusiast eager to break into the industry, the quest for the perfect opportunity can be both thrilling and overwhelming. And that is where TechUp comes in.

What is TechUp?

TechUp is a website designed to help users find and manage tech opportunities. TechUp is an innovative online platform tailored to the needs of individuals seeking to navigate the vast landscape of opportunities within the dynamic tech industry. This array of opportunities includes internships, jobs, freelance projects, mentorship programs and much more. This empowers users to maximize their potential and succeed in the tech industry.

Its Conception

It was a crisp night when Usman and I found ourselves immersed in a spirited discussion about the project we were going to build. Little did we know that this seemingly routine conversation would lead to a big realization.

As Usman and I had the meeting, we found ourselves in remarkable alignment. Our ideas of the project to build, for the end of our Foundation period at ALX Software Engineering Program, were remarkably in sync. It was as if we were reading each other’s minds.

For me, the idea came when I remembered the challenges and struggles I had in securing an organization for my SIWES placement in my penultimate year of college. It was at that point that the seeds of inspiration were planted in my mind to develop something that would make it easier to find opportunities.

Usman and I shared the same vision, a platform that leverages technology to empower individuals and revolutionize the way opportunities are discovered and accessed in the tech industry. In that moment of synchronicity, I knew that we were meant to embark on this journey of building the project together, and we were committed to doing our best.

After talking more, we decided to pick the technologies we thought best to make TechUp. We both wanted to use technology that was really good and would help people use TechUp easily.

Technologies Chosen