🤖 Agentic AI and A2A Showcase - The weatherman you didn't ask for

Agent-to-Agent (A2A) Protocol featuring an AI-powered weather agent with a unique Azerbaijani cultural personality, powered by Azure OpenAI and modern TypeScript tooling.

🚀 What Makes This Special

This project showcases a production-ready implementation of agent-to-agent communication, combining multiple technologies into a cohesive, event-driven architecture. Demonstration of how AI agents can communicate using standardised protocols whilst having their own tools independently.

🎯 Key Features

🏗️ A2A Protocol Implementation

• Protocol-Compliant Communication: Full implementation of the Agent-to-Agent protocol v0.3.0
• Agent Card Discovery: Exposes agent capabilities via .well-known/agent-card.json endpoint
• Multi-Part Message Handling: Sophisticated message parsing supporting multiple content types
• Event-Driven Architecture: Uses ExecutionEventBus for asynchronous message processing

🧠 OpenAI Agents SDK Integration

• Agentic Workflows: Leverages the @openai/agents SDK for autonomous decision-making
• Tool Chaining: Dynamically chains multiple tools (weather fetching → personality transformation)
• Azure OpenAI: Production-grade integration with Azure's OpenAI service
• Zod Schema Validation: Type-safe parameter validation for all tool inputs

🛠️ Custom Tool System

1. Weather Tool: Real-time weather data from WeatherAPI.com
2. Qedeshator Tool: Cultural personality injection using GPT-4, transforming responses into authentic Azerbaijani street slang

🎭 Personality Engineering

The agent features a unique Azerbaijani qədeş persona that:

• Speaks in po-bratski style with authentic dialect
• Uses culturally-specific phrases
• Employs grammatical patterns specific to Yasamal street culture
• Maintains character consistency through system prompt engineering

🏛️ Architecture Highlights

• Client-Server Separation: Clean separation of concerns with dedicated client and server implementations
• In-Memory Task Store: Efficient task tracking with InMemoryTaskStore
• UUID-Based Message Tracking: Ensures message traceability and idempotency
• Express 5.x Integration: Modern Express setup with type-safe routing via A2AExpressApp
• TypeScript + ESM: Full TypeScript with ES modules for modern JavaScript features

📋 Tech Stack

Technology	Purpose	Why It's Cool
@a2a-js/sdk	Agent-to-Agent protocol	Standardised agent communication, future-proofing AI interoperability
@openai/agents	Agentic AI framework	Autonomous tool selection and execution
Azure OpenAI	LLM inference	Enterprise-grade AI with GPT-4
TypeScript	Type safety	Catch errors at compile-time, not runtime
Zod	Schema validation	Runtime type safety for API boundaries
Express 5.x	Web server	Latest Express with improved async/await support
WeatherAPI.com	Weather data	Real-time weather information
dotenv	Configuration	Secure environment variable management
tsx	TypeScript execution	Fast, modern TS execution without build steps

🏗️ Architecture

┌─────────────┐                    ┌─────────────────────────────────────┐
│   Client    │───── A2A ─────────▶│     Server  WeatherAgentExecutor    │
│  (client.ts)│    Protocol        │         (Express + A2A SDK)         │
└─────────────┘                    └─────────────┬───────────────────────┘
                                                  │
                                   ┌──────────────▼──────────────────┐
                                   │        Weather Agent            │
                                   │   (@openai/agents -- JS)        │
                                   └──────────────┬──────────────────┘
                                                  │
                          ┌───────────────────────┴────────────────────┐
                          │                                            │
                  ┌───────▼──────┐                          ┌──────────▼────────┐
                  │ Weather Tool │                          │  Qedeshator Tool  │
                  │(WeatherAPI)  │                          │  (Azure OpenAI)   │
                  └──────────────┘                          └───────────────────┘

🚦 Getting Started

Prerequisites

• Node.js 18+
• Azure OpenAI API access
• WeatherAPI.com API key (free tier works!)

Installation

npm install

Configuration

Create a .env file with your credentials:

AZURE_OPENAI_API_KEY=your_key_here
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_VERSION=2024-08-01-preview
AZURE_OPENAI_DEPLOYMENT=gpt-4
WEATHER_API_KEY=your_weatherapi_key_here

Running the Server

npm start

For development with hot-reload:

npm run dev

The server will start on http://localhost:4000

Using the Client

npx tsx client.ts "What's the weather in Baku?"

Expected output (with personality!):

Agent response: Bakida hava indi 16.2°C-dədi, günəş də çıxıbdı, can-cigər. Belə havada şəhərdə fırlanmaq lazımdü, özünü göstərmək gərəkdi. "Günəş çıxanda, qədeşlər şəhərdədi."

🎨 Code Highlights

Event-Driven Message Processing

The executor uses an event bus pattern for non-blocking message handling:

const responseMessage: Message = {
  kind: 'message',
  messageId: uuidv4(),
  role: 'agent',
  parts,
  contextId: requestContext.contextId,
};

eventBus.publish(responseMessage);
eventBus.finished();

Tool Chaining Magic

The agent automatically chains tools based on context:

const weatherAgent = new Agent({
  instructions: `If the question is about weather, use the weather tool. 
    Before sending output, send it to qedeshator tool and output whatever text it gives back.`,
  tools: [weatherTool, qedeshatorTool],
});

Protocol-Compliant Agent Card

The server exposes its capabilities via standard A2A agent card:

const weatherAgentCard: AgentCard = {
  name: 'Weather Agent',
  description: 'An Azerbaijani qədeş who tells you the weather with style',
  protocolVersion: '0.3.0',
  skills: [{ 
    id: 'weatherTool',
    name: 'Weather Tool', 
    description: 'Tells you the weather in a city', 
    tags: ['weather', 'city', 'temperature']
  }],
};

🔮 Future Enhancements

• Streaming responses for real-time interaction
• Push notifications for weather alerts
• State transition history tracking
• Multi-modal inputs (images, audio)
• Agent-to-agent direct communication
• Redis-backed task store for horizontal scaling
• WebSocket support for bidirectional streaming

📚 Learning Resources

• A2A Protocol Specification
• OpenAI Agents SDK Documentation
• Azure OpenAI Service

🤝 Contributing

This project demonstrates advanced AI agent patterns. Feel free to fork and experiment!

📝 Licence

MIT

---

Builing the future with ☕ and curiosity