Building a Self-Adaptive Goal-Oriented AI Agent with Google Gemini and SAGE Framework: A Complete Coding Guide

Overview of the SAGE Framework

This tutorial explores building an advanced AI agent using the SAGE framework (Self-Adaptive Goal-oriented Execution) powered by Google's Gemini API. The framework integrates four core components: Self-Assessment, Adaptive Planning, Goal-oriented Execution, and Experience Integration. These components enable the agent to break down high-level goals into manageable tasks, execute them systematically, and learn from the outcomes to improve future performance.

Key Components and Code Structure

The agent uses Python with the google.generativeai library to interact with the Gemini model. Task management is handled via a Task data class, including fields such as id, description, priority, status, dependencies, and result. A TaskStatus enum tracks task progress states: pending, in progress, completed, or failed.

import google.generativeai as genai
import json
import time
from typing import Dict, List, Any, Optional
from dataclasses import dataclass, asdict
from enum import Enum
 
class TaskStatus(Enum):
   PENDING = "pending"
   IN_PROGRESS = "in_progress"
   COMPLETED = "completed"
   FAILED = "failed"
 
@dataclass
class Task:
   id: str
   description: str
   priority: int
   status: TaskStatus = TaskStatus.PENDING
   dependencies: List[str] = None
   result: Optional[str] = None
  
   def __post_init__(self):
       if self.dependencies is None:
           self.dependencies = []

The SAGEAgent class encapsulates the agent logic. It initializes with the Gemini API key and model, maintains memory and task records, and manages context and iterations.

Self-Assessment

The agent evaluates its current progress, resources, gaps, risks, and recommendations by generating a JSON response from the Gemini model based on the goal and context.

Adaptive Planning

Based on the self-assessment, the agent dynamically generates 3-4 actionable tasks with priorities and dependencies, allowing flexible and context-aware task decomposition.

Goal-Oriented Execution

Each task is executed step-by-step by prompting Gemini to break down actions, perform them methodically, validate results, and generate detailed outputs.

Experience Integration

After task execution, the agent learns from outcomes by analyzing key insights, patterns, and adjustments, updating its internal memory to refine future iterations.

Complete SAGE Cycle

The agent executes multiple iterations of the SAGE cycle, repeating assessment, planning, execution, and learning until the goal is achieved or maximum iterations are reached.

Example Usage

if __name__ == "__main__":
   API_KEY = "Use Your Own API Key Here"
   
   try:
       agent = SAGEAgent(API_KEY, model_name="gemini-1.5-flash")
      
       goal = "Research and create a comprehensive guide on sustainable urban gardening practices"
      
       results = agent.execute_sage_cycle(goal, max_iterations=2)
      
       print("\n" + "="*50)
       print(" SAGE EXECUTION SUMMARY")
       print("="*50)
       print(f"Goal: {results['goal']}")
       print(f"Status: {results['final_status']}")
       print(f"Iterations: {len(results['iterations'])}")
      
       for i, iteration in enumerate(results['iterations'], 1):
           print(f"\nIteration {i}:")
           print(f"  Assessment Score: {iteration['assessment'].get('progress_score', 0)}/100")
           print(f"  Tasks Generated: {iteration['tasks_generated']}")
           print(f"  Tasks Completed: {iteration['tasks_completed']}")
      
       print("\n Agent Memory Entries:", len(agent.memory))
       print(" Total Tasks Processed:", len(agent.tasks))
      
   except Exception as e:
       print(f"Demo requires valid Gemini API key. Error: {e}")
       print("Get your free API key from: https://makersuite.google.com/app/apikey")

Insights

This modular design allows the creation of a self-improving AI agent capable of complex decision-making and adaptive task management. The framework is extendable for multi-agent systems or specialized domains by leveraging Google Gemini's generative capabilities.

For full source code, tutorials, and further resources, visit the GitHub page and community channels linked in the original post.