Author: Muhammad Ahmad El-kufahn

GitHub: KhalifahMB/HNG13_Intenship

Live Agent: Live Link to Agent

🌍 Overview

EduSimplify is an AI-powered educational assistant that simplifies complex science topics — especially Physics, Math, and related fields — into clear, easy-to-understand explanations.

Built with Django, Django REST Framework (DRF), and Google Gemini, EduSimplify integrates seamlessly into the Telex.im platform using the Mastra A2A (Agent-to-Agent) Protocol.

The goal is simple:

When a user sends a complex topic like “Explain quantum entanglement,” EduSimplify responds with a concise 2–3 sentence explanation, one real-world example, and a short note or formula.

🧩 Understanding Telex A2A Protocol (in plain English)

Telex’s A2A (Agent-to-Agent) protocol allows external applications (agents) to connect and communicate with Telex channels using the JSON-RPC 2.0 format.

This format ensures that every message follows a consistent structure — each with an id, method, and params.

For example, Telex might send a message to EduSimplify like this:

{ "jsonrpc": "2.0", "id": "001", "method": "message/send", "params": { "message": { "role": "user", "messageId": "12345", "parts": [ { "kind": "text", "text": "Explain Newton's third law" } ] } } } 

Your agent then processes that request, runs the AI model, and sends a structured JSON-RPC response back to Telex with an explanation, artifacts, and history.

🧠 How EduSimplify Works Internally

EduSimplify’s architecture follows a clean modular design:

agents/
├── views.py # Core logic handling A2A JSON-RPC requests
├── serializers.py # DRF validation for JSON-RPC schema
├── models.py # Conversation, Message, Artifact models
├── utils.py # Google Gemini integration

🧩 Request Flow:

Telex sends a JSON-RPC request (e.g., message/send) to your public endpoint.

The A2AAgentView validates the request using DRF serializers.

A unique context_id identifies each conversation.

The user message is stored in the database.

The text is passed to the ask_gemini() helper function.

Gemini generates a simplified explanation.

EduSimplify returns a structured A2A-compliant JSON response with the answer.

⚙️ The Google Gemini Integration

EduSimplify uses the official Google Generative AI Python SDK (google-genai) for calling Gemini models.

import os from google import genai from django.conf import settings def _get_genai_client(): api_key = getattr(settings, "GEMINI_API_KEY", None) or os.environ.get("GEMINI_API_KEY") if not api_key: raise RuntimeError("Gemini API key not configured (GEMINI_API_KEY)") return genai.Client(api_key=api_key) def ask_gemini(prompt, model="gemini-2.5-flash"): client = _get_genai_client() try: response = client.models.generate_content(model=model, contents=prompt) except Exception as exc: raise RuntimeError(f"genai request failed: {exc}") from exc text = getattr(response, "text", str(response)) if not text: raise RuntimeError("genai returned empty response") return text 

This keeps the integration clean, secure, and reusable — ask_gemini() is imported anywhere in your Django app to generate AI content on demand.

🧾 Core View Explained

The main view that powers EduSimplify is A2AAgentView. It receives JSON-RPC data, validates it, extracts user prompts, and responds.

Key Concepts

Message IDs (messageId): Every message (incoming or outgoing) has a unique UUID to track it.

Context IDs: Represent a user’s conversation thread across multiple messages.

Task IDs: Used when Telex runs multiple tasks within one context.

History: Holds both the user’s query and the agent’s reply for Telex display.

Example excerpt:

class A2AAgentView(APIView): def post(self, request, *args, **kwargs): raw = request.data or {} top_serializer = JSONRPCRequestSerializer(data=raw) ... if method == "message/send": pser = MessageParamsSerializer(data=params) ... user_prompt = last["text"] # Call Gemini  explanation = ask_gemini( f"You are EduSimplify... Concept: {user_prompt}\nAnswer:" ) # Respond to Telex  result = { "id": task_id, "contextId": conv.context_id, "status": { "state": "completed", "timestamp": datetime.utcnow().isoformat() + "Z", "message": { "role": "agent", "parts": [{"kind": "text", "text": explanation}] }, }, ... } return Response(make_a2a_success(request_id, result)) 

Each new request gets a unique messageId to prevent collisions and maintain consistent message threading inside Telex.

🧮 Example: How to Talk to EduSimplify

🔹 Using curl

curl -X POST https://el-kufahn-hng13.up.railway.app/a2a/agent/edusimplify \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": "001", "method": "message/send", "params": { "message": { "role": "user", "messageId": "abc123", "parts": [ {"kind": "text", "text": "Explain photosynthesis in simple terms"} ] } } }' 

✅ Response Example

{ "jsonrpc": "2.0", "id": "001", "result": { "status": { "state": "completed", "message": { "role": "agent", "parts": [ { "kind": "text", "text": "Photosynthesis is how plants convert sunlight into energy..." } ] } } } } 

🔹 Using Postman

Method: POST

URL: https://el-kufahn-hng13.up.railway.app/a2a/agent/edusimplify

Body (raw JSON): same as above.

🔗 Telex Workflow Configuration

To connect EduSimplify to Telex.im, add a workflow JSON like this:

{ "active": true, "category": "education", "description": "Simplifies science topics for better understanding.", "id": "EduSimplifyAgent_v1", "name": "edusimplify_agent", "short_description": "Simplify complex topics in simple terms", "long_description": " EduSimplify helps users understand science topics easily. It breaks down complex concepts into short explanations, gives real-world examples, and provides simple formulas or notes when applicable. ", "nodes": [ { "id": "edusimplify_agent", "name": "EduSimplify Agent", "parameters": {}, "position": [816, -112], "type": "a2a/mastra-a2a-node", "typeVersion": 1, "url": "https://el-kufahn-hng13.up.railway.app/a2a/agent/edusimplify" } ], "settings": { "executionOrder": "v1" }, "pinData": {} } 

💻 Source Code & Setup

All setup details (environment variables, Django configuration, and deployment steps) are explained in the GitHub repository provided at the top.

Interact directly with the deployed agent:

👉 https://el-kufahn-hng13.up.railway.app/a2a/agent/edusimplify

Send it any science concept — from “Explain gravity like I’m 10” to “What is a black hole?” — and get clear, simple answers.

🧭 Conclusion

EduSimplify demonstrates how Django + DRF can be used to build robust, production-ready AI agents that integrate cleanly into Telex.im using the A2A protocol.

By combining Google Gemini’s intelligence with a simple, structured API design, this project shows how AI can transform learning experiences — one simplified concept at a time.

django #ai #education #telex #google-gemini #python