Building PostCraft Agent

Introduction: The HNG Internship Challenge

As an intern at the HNG internship program, I was given a broad task: create an AI agent and submit it to the Telex ecosystem. While the assignment was open-ended, I chose to build something that I believed would be genuinely useful: an AI agent that transforms blog posts into engaging social media content. This wasn't just another coding exercise, it was an opportunity to look into AI agents, specifically within the Telex ecosystem.

Understanding the Telex Ecosystem

Before diving into development, I needed to understand what Telex actually is. Telex is a collaboration workspace where humans and AI agents work side by side. Unlike traditional chatbot platforms, Telex treats AI agents as actual coworkers, complete with defined roles, tasks, and skills.

The key insight was that Telex agents aren't just about responding to messages; they're about taking action. Each agent has:

• Role-driven behavior: You define what they do (blogger, analyst, etc.)
• Task configuration: You specify their responsibilities
• Skill-enabled capabilities: You equip them with tools to complete tasks
• Autonomous operation: They respond to data, prompts, and events in real-time

This understanding fundamentally shaped how I approached the PostCraft Agent development.

The Initial Vision: Simple Content Conversion

My initial goal seemed straightforward: take a blog URL and generate social media posts. The requirements were:

1. Extract content from a blog URL
2. Generate posts for different platforms
3. Return formatted social media content

I started with a basic architecture using FastAPI, Pydantic models, and Google's Gemini AI for content generation. The initial flow was simple: URL → Content Extraction → AI Generation → Social Media Posts.

The First Major Challenge: Understanding Telex Communication Protocol

Here's where I hit my first significant roadblock. Telex doesn't use standard REST APIs for agent communication. Instead, it uses JSON-RPC 2.0 protocol with specific message structures that I had to learn and implement.

The JSON-RPC Learning Curve

The incoming messages from Telex followed this structure:

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "id": "unique-task-id",
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "https://example.com/blog/my-post"
        }
      ]
    }
  },
  "id": 1
}

I had to build a message parser that could:

1. Extract the blog URL from nested message parts
2. Handle both text and data parts in messages
3. Filter out system messages and metadata
4. Return structured data for processing

Task Management and Response Formatting

Telex also expects responses in a specific format with task status, artifacts, and history. I learned that every response needed:

• Task status tracking (submitted, working, completed, failed)
• Artifact objects containing the actual content
• Message history for conversation context
• Proper JSON-RPC 2.0 compliance

This was more complex than I initially thought, but it taught me the importance of protocol compliance in agent development.

Architecture Evolution

As I worked through the communication protocol challenges, my architecture evolved significantly:

Phase 1: Basic Extraction and Generation

• Simple URL extraction using regex
• Basic AI prompts for different platforms
• Single-post generation per platform

Phase 2: Enhanced Content Processing

• Better blog content extraction with error handling
• Platform-specific content strategies
• Better error handling and fallbacks

Phase 3: The Platform Strategy Shift

This was the most significant evolution. Initially, I was trying to detect which platforms the user wanted based on their message content. But then I had a realization: why not always generate for both LinkedIn and Twitter?

This led to a fundamental design change:

• Removed platform detection logic entirely
• Always generate Twitter threads (not single posts)
• Always generate comprehensive LinkedIn posts
• Focus on quality over quantity

The AI Prompt Engineering Challenge

The next major challenge was crafting prompts that would generate high-quality, platform-specific content. This required deep understanding of each platform's nuances:

Twitter Thread Strategy

Instead of single tweets, I focused on creating multi-tweet threads:

• 3-5 tweets with proper numbering (1/n, 2/n, etc.)
• Hook → Development → Call-to-action structure
• Smooth narrative flow across tweets
• Relevant hashtags in the final tweet

LinkedIn Comprehensive Posts

For LinkedIn, I went beyond simple summaries:

• 300-800 word comprehensive posts
• Professional tone with actionable insights
• Structured content with bullet points
• Engagement-focused questions
• Original blog URL inclusion

The prompt engineering process involved multiple iterations, testing different approaches, and refining the AI's understanding of each platform's unique requirements.

Technical Implementation Details

Core Components

1. MessageParser: Handles Telex protocol parsing and URL extraction
2. BlogExtractor: Fetches and processes blog content
3. AIGenerator: Creates platform-specific content using Gemini AI
4. PostProcessor: Orchestrates the entire workflow
5. API Layer: FastAPI endpoints for Telex integration

Key Technical Decisions

• Pydantic Models: Used throughout for data validation and serialization
• FastAPI: Chosen for its performance and automatic documentation
• Google Gemini AI: Selected for its content generation capabilities
• Modular Architecture: Each component is independent and testable

Error Handling Strategy

I implemented comprehensive error handling:

• Network connectivity issues
• Invalid blog URLs
• AI API failures
• Malformed requests
• Missing configuration

Lessons Learned

1. Protocol Understanding is Crucial

The biggest lesson was that understanding the communication protocol is more important than the core functionality. I spent more time getting the JSON-RPC implementation right than I did on the actual content generation.

2. Simplicity Trumps Complexity

My initial platform detection logic was overly complex. The decision to always generate for LinkedIn and Twitter simplified the codebase and improved user experience.

3. AI Prompt Engineering is an Art

Crafting effective prompts requires understanding both the AI model and the target platform. It's an iterative process that involves testing, refinement, and continuous improvement.

4. Error Handling is Non-Negotiable

In a production environment, things will fail. Comprehensive error handling and graceful degradation are essential for a reliable agent.

5. Documentation is Your Best Friend

Building this agent taught me the importance of good documentation. Not just for others, but for my future self. The README, API documentation, and code comments saved me countless hours during development.

The HNG Internship Experience

Building the PostCraft Agent as part of the HNG internship program was more than just a coding exercise. It was a journey into:

• Real-world AI development: Working with actual AI APIs and understanding their limitations
• Protocol implementation: Learning to work within existing ecosystems
• Problem-solving: Facing and overcoming unexpected challenges
• Professional development: Understanding code quality, documentation, and maintainability

The internship provided me with the opportunity to work on a project that has real-world applications while learning from experienced developers and receiving guidance throughout the process.

Future Enhancements

While the current version is fully functional, there are several enhancements I'm considering:

• Additional Platforms: Instagram, Facebook, and TikTok support
• Content Scheduling: Integration with social media scheduling APIs
• Analytics Integration: Track post performance and engagement
• Custom Templates: Allow users to define their own content templates
• Multi-language Support: Generate content in different languages

Telex Integration Workflow

To integrate the PostCraft Agent into Telex, you'll need to create a workflow using the following configuration:

{
  "category": "utilities",
  "description": "A workflow that converts blog posts into social media content",
  "id": "blogToSocialAgent",
  "name": "PostCraft - Blog to Social Media",
  "long_description": "You are a helpful blog content assistant that transforms blog posts into engaging social media content. Your primary function is to help users create social media posts from their blog articles. When responding: - Always ask for a blog post URL if none is provided - If you blog URL isn't valid, please inform the user - Keep responses concise but informative - Provide social media posts formatted for different platforms (Twitter, LinkedIn, Facebook, Instagram) - Extract key points from the blog post - Create engaging captions and hashtags - Be friendly and professional in your responses - Make sure to give reasonable content based on the blog data you have - Don't make up content that isn't in the original blog post",
  "short_description": "Convert blog posts into social media content for Twitter and LinkedIn",
  "nodes": [
    {
      "id": "blogToSocialAgent",
      "name": "PostCraft Agent",
      "parameters": {},
      "position": [816, -112],
      "type": "a2a/generic-a2a-node",
      "typeVersion": 1,
      "url": "agent-url-here"
    }
  ],
  "pinData": {},
  "settings": {
    "executionOrder": "v1"
  }
}

Note: Replace "agent-url-here" with your actual deployed agent URL when setting up the integration.

Conclusion

Building the PostCraft Agent was a transformative experience that took me from a basic understanding of AI to building a sophisticated, production-ready agent. The journey through understanding Telex protocols, implementing robust error handling, and mastering AI prompt engineering has prepared me for future challenges in AI development.

The agent now successfully transforms blog posts into engaging Twitter threads and comprehensive LinkedIn posts, demonstrating the power of AI automation when built with proper architecture and understanding of the ecosystem.

For other developers looking to build Telex agents, my advice is simple: start with understanding the protocol, focus on simplicity, and never underestimate the importance of good prompt engineering. The rewards of building something that truly works and provides value are worth every challenge faced along the way.

The HNG internship provided me with the freedom to choose a meaningful project, and I'm proud to have created an agent that solves a real problem for content creators and social media managers. PostCraft Agent is now ready to join the Telex ecosystem and help users amplify their blog content across social media platforms.