How mhkaycey/ai-content-planner works
Purpose and Runtime
This is a TypeScript Mastra AI service that turns a user-supplied topic into a concise summary and cross-platform content ideas. It runs through Mastra’s development/build/deployment runtime and calls Google Gemini using GEMINI_API_KEY. Primary bootstrap: src/mastra/index.ts.
Public Agent Boundary
The externally consumable interface is an Agent-to-Agent (A2A) endpoint for contentPlanner. Clients send JSON-RPC message/send requests containing user text; the route adapts that protocol into the Mastra agent execution path. Relevant boundary: src/mastra/routes/a2a-agent-route.ts.
Agent Orchestration
The content-planning agent owns conversational behavior: requesting a topic when absent, framing the strategist task, and invoking its specialized tool. It is the main reasoning/orchestration component rather than a general web controller. Path: src/mastra/agents/contentPlannerAgent.ts.
Content Generation Tool
contentPlannerTool is the modular capability responsible for Gemini-backed generation of topic insights and platform-specific recommendations, such as captions, post concepts, and hashtags. This separates model/API work from agent instructions and enables reuse in larger Mastra pipelines. Path: src/mastra/tools/contentPlannerTool.ts.
Workflow Layer
A dedicated Mastra workflow packages the planning operation as an executable staged process. This is the natural extension point for adding validation, research, approvals, scheduling, or additional generation steps without changing the A2A contract. Path: src/mastra/workflows/contentPlannerWorkflow.ts.
Quality Evaluation
Scoring definitions provide a quality-control boundary for generated planner output, likely usable in Mastra evaluation/observability workflows. They distinguish output assessment from generation logic. Path: src/mastra/scores/contentPlannerScores.ts.
Composition and Deployment
The Mastra entrypoint registers or exports the agent, workflow, routes, and related capabilities for local development and Mastra deployment. telex.json represents the external workflow/agent integration configuration, including the A2A endpoint reference. Paths: src/mastra/index.ts, telex.json, .env.example.
Main entry points: a2a-agent-route.ts A2A agent route · contentPlannerTool.ts Content planner tool · index.ts Mastra entrypoint · contentPlannerWorkflow.ts Content planner workflow
Components 10
Public Boundary
- A2A clients
- A2A agent route · Adapts message/send requests into Mastra agent execution.
src/mastra/routes/a2a-agent-route.ts
Planning Runtime
- Mastra entrypoint · Registers agents, workflows, and routes for Mastra runtime.
src/mastra/index.ts - Content planner agent · Manages conversation and invokes the planning capability.
src/mastra/agents/contentPlannerAgent.ts - Content planner tool · Generates topic insights and platform-specific recommendations.
src/mastra/tools/contentPlannerTool.ts - Google Gemini
- Content planner workflow · Extension point for validation, research, approvals, and scheduling.
src/mastra/workflows/contentPlannerWorkflow.ts
Quality & Deployment
- Telex integration config · Declares the external A2A integration.
telex.json - Content planner scores · Assesses generated planner output independently of generation.
src/mastra/scores/contentPlannerScores.ts - Environment template · Documents GEMINI_API_KEY configuration.
.env.example
Connections 11
- A2A clients → A2A agent route: JSON-RPC message/send
- Telex integration config → A2A agent route: A2A endpoint
- A2A agent route → Content planner agent: execute agent
- Mastra entrypoint → A2A agent route: registers
- Mastra entrypoint → Content planner agent: registers
- Mastra entrypoint → Content planner workflow: registers
- Content planner agent → Content planner tool: invokes
- Content planner workflow → Content planner tool: planning stage
- Content planner tool → Google Gemini: generate content
- Environment template → Content planner tool: GEMINI_API_KEY
- Content planner workflow → Content planner scores: evaluate output