Building the "Watchman" AI Agent

From Zero to Security Hero: Building a Wanted Persons Agent on Mastra & Integrating with Telex.im

I. Introduction: Defining the Mission

• Hook: Briefly introduce the concept—using AI for security screening in chat platforms.

• The Agent: Introduce the Watchman agent and its purpose: checking names against the FBI Wanted Persons API.

• The Tools: State the core technologies: Mastra.ai (TypeScript), Gemini Model, FBI Wanted API, and Telex.im.

II. Step 1: Core Logic & Tool Development

• API Choice: Explain why the FBI Wanted API was chosen (free, public interest).

• Mastra Tool: Explain the creation of the fbiSearchTool.

  • Key Success: Defining the inputSchema (for the name) and the outputSchema (for the result) using zod.

  • Code Highlight: Show the axios.get call inside the execute function.

• Critical Fix (403 Error): Discuss the roadblock of the 403 Forbidden error and how adding a User-Agent header to the axios call was essential for successful communication with the FBI API.

III. Step 2: Agent Brain & LLM Configuration

• Agent Setup: Describe creating the watchmanAgent and defining its instructions.

• API Key Crisis: Detail the initial "API Key not found" error (ECOMPROMISED, OPENAI_API_KEY vs. GOOGLE_GENERATIVE_AI_API_KEY).

• Solution: Explain that you successfully switched the model to google/gemini-2.5-flash and used the correct GOOGLE_GENERATIVE_AI_API_KEY in the .env file, finally bringing the LLM online.

• Instruction Focus: Highlight the importance of the disclaimer ("not a guarantee of safety") and the CAUTION warning to meet safety requirements.

IV. Step 3: The Integration Battle with Telex

• Initial Setup: Briefly mention using npm run dev and ngrok to get a public URL (https://.../).

• The Great Protocol Mismatch (The Biggest Challenge): Detail the persistent 404 Not Found and 400 Bad Request errors when using the standard A2A paths (/api/a2a/agent/watchman).

  • Analysis: Explain that the endpoint expects the Chat Stream format, but the Telex A2A Node sends the JSON-RPC format.

  • The Workaround: Explain that the final, successful integration required using the non-standard but functional /agents/watchman/chat path in the Telex Workflow JSON. This is where you overcame platform-specific routing challenges.

• Workflow JSON: Show a snippet of the final, working JSON (including your ngrok URL) to demonstrate the integration.

V. Conclusion & Key Takeaways

• Achievement: The Watchman agent is fully deployed, functional, and successfully performs a high-stakes tool call.

• Lesson Learned: The biggest lesson was that backend integration requires rigid adherence to protocol formats (A2A vs. Chat Stream) and robust external API error handling (403 fix).