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.
SOCIAL SHARE CARD GENERATOR