🚀 Next-Generation AI Personal Assistant

Next.js 15 + OpenAI Agents SDK + GPT-4o + TypeScript + Cutting-Edge UI/UX

⚡️ Enterprise-grade, location-aware AI assistant with terminal-inspired interface ⚡️

AI Agent // Personal Assistant represents the pinnacle of modern full-stack AI development—a sophisticated, enterprise-ready application that seamlessly blends cutting-edge AI capabilities with stunning user experience design. This isn't just another chatbot; it's a context-aware, location-intelligent AI assistant that demonstrates mastery of contemporary web technologies and AI integration patterns.

Built with Next.js 15's latest App Router, OpenAI's Agents SDK, and React 19's newest features, this application showcases advanced architectural patterns, real-time AI interactions, and pixel-perfect UI craftsmanship that would impress any technical recruiter or engineering team.

🔥 Status: Under active development with continuous feature additions and architectural improvements!

• OpenAI Agents SDK: Leveraging the latest @openai/agents package with GPT-4o-mini
• Tool-Calling Architecture: Extensible agent with custom tools and real-time execution
• Context-Aware Responses: AI that understands and responds based on user location and context
• Intelligent Error Recovery: Robust error handling with graceful fallbacks

• Real-Time IP Geolocation: Dynamic user location detection via advanced IP-API integration
• Contextual Responses: AI assistant provides location-specific information and recommendations
• Privacy-Conscious: Uses IP-based approximation without compromising user privacy
• Global Compatibility: Supports worldwide location detection and regional customization

• Cyberpunk Aesthetic: Dark-themed, terminal-style UI with cyan accent colors
• Split-Panel Architecture: Professional left-right layout for input and output
• Responsive Grid System: Seamlessly adapts from desktop to mobile devices
• Status Indicators: Real-time connection status and processing feedback

• Typewriter Animation: Character-by-character response rendering for engaging interactions
• Markdown Support: Full GitHub Flavored Markdown with react-markdown and remark-gfm
• Interactive States: Loading animations, success indicators, and error boundaries
• Accessibility: ARIA-compliant design with keyboard navigation support

• Type-Safe Development: 100% TypeScript with strict type checking
• Server Actions: Next.js 15's latest server-side action patterns
• Edge-Compatible: Optimized for serverless and edge deployment
• Environment Security: Secure API key management and environment configuration

The application follows a sophisticated, layered architecture designed for scalability, maintainability, and optimal user experience:

graph TD A["🌐 User Interface<br/>Terminal-Inspired Design"] --> B["📡 Next.js Server Actions<br/>submitPrompt()"] B --> C["🚀 API Route Handler<br/>/api/agent"] C --> D["🤖 OpenAI Agent<br/>GPT-4o-mini"] D --> E["🛠️ Tool: getUserLocation"] E --> F["🌍 External APIs<br/>IP-API.com"] F --> G["📊 Location Data<br/>City, Region, Country"] G --> D D --> H["💬 AI Response<br/>Context-Aware"] H --> C C --> I["📤 JSON Response<br/>aiAgentFinalOutput"] I --> B B --> J["⌨️ Typewriter Effect<br/>Markdown Rendering"] J --> A subgraph "Frontend Layer" A J K["🎨 TailwindCSS<br/>Custom Styling"] L["📱 Responsive Grid<br/>Split Panel Layout"] end subgraph "Backend Layer" B C M["🔒 Server-Side Security<br/>Environment Variables"] end subgraph "AI Layer" D E N["🧠 Tool-Calling Architecture<br/>Extensible Design"] end subgraph "External Services" F O["☁️ OpenAI API<br/>GPT-4o-mini"] end style A fill:#1e293b,stroke:#06b6d4,stroke-width:2px,color:#fff style D fill:#065f46,stroke:#10b981,stroke-width:2px,color:#fff style F fill:#4c1d95,stroke:#8b5cf6,stroke-width:2px,color:#fff 

1. User Interaction: User submits a prompt via the terminal-style interface
2. Server Action: Next.js server action validates and processes the request
3. API Gateway: Route handler receives the prompt and initializes the AI agent
4. AI Processing: OpenAI agent analyzes the prompt and determines if tools are needed
5. Tool Execution: If location context is required, the agent calls the getUserLocation tool
6. External Data: IP-API services provide real-time geolocation data
7. AI Response: Agent synthesizes a contextual response using all available information
8. Data Return: Response flows back through the API to the client
9. UI Rendering: Typewriter effect displays the response with markdown formatting

• Terminal Aesthetic: Authentic command-line interface with cyan accents and monospace fonts
• Split-Panel Layout: Professional workspace with dedicated input and output areas
• Real-Time Feedback: Live status indicators showing "ONLINE", "EXECUTING", and response states
• Responsive Design: Seamlessly adapts from desktop workstations to mobile devices

• Instant Validation: Client-side form validation prevents empty submissions
• Loading States: Smooth transitions with "EXECUTING..." and "Awaiting response..." indicators
• Error Boundaries: Graceful error handling with informative user feedback
• Accessibility: Full keyboard navigation and screen reader compatibility

• Custom Color Palette: Deep space blues with electric cyan highlights
• Typography Hierarchy: Perfect balance of Geist Sans and Mono fonts
• Micro-Animations: Subtle hover effects and active states for enhanced interactivity
• Visual Feedback: Clear distinction between user input and AI responses

// Sophisticated OpenAI Agent with Tool Integration const agent = new Agent({ name: "Personal Assistant", model: "gpt-4o-mini", instructions: `You are a personal assistant that can help with tasks and   answer questions based on the user's IP address. You address   the user as Sir. Remember to use proper grammar and punctuation   with proper spacing and formatting in your response.`, tools: [getUserLocation] }); const result = await run(agent, prompt);

// Real-time IP-based geolocation with error handling const getUserLocation = tool({ name: 'get_user_location', description: 'Get the location of the user', execute: async () => { try { // Primary IP detection via EDNS const ipResponse = await fetch("http://edns.ip-api.com/json"); const ipData = await ipResponse.json(); const userIp = ipData.dns.ip; // Geolocation lookup with comprehensive data const locationResponse = await fetch(`http://ip-api.com/line/${userIp}`); const locationData = await locationResponse.text(); return locationData; // Returns: Country, Region, City, Timezone, ISP } catch (error) { return "Location unavailable"; } }, parameters: { type: 'object', properties: {}, required: [], additionalProperties: false, }, });

// Character-by-character rendering with React hooks function Typewriter({ text }: { text: string }) { const [displayedText, setDisplayedText] = useState(""); useEffect(() => { setDisplayedText(""); let i = 0; const interval = setInterval(() => { if (i < text.length) { setDisplayedText((prev) => prev + text.charAt(i)); i++; } else { clearInterval(interval); } }, 10); // 10ms per character for smooth animation return () => clearInterval(interval); }, [text]); return ( <div className="prose prose-invert prose-sm max-w-none"> <ReactMarkdown remarkPlugins={[remarkGfm]}> {displayedText} </ReactMarkdown>  </div> ); }

// Next.js 15 Server Actions with comprehensive error handling "use server"; export async function submitPrompt(prevState: any, formData: FormData) { const prompt = formData.get('prompt') as string; if (!prompt) { return { error: 'Prompt is required' }; } try { const response = await fetch( `${process.env.NEXT_PUBLIC_BASE_URL || 'http://localhost:3000'}/api/agent`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ prompt }), } ); if (!response.ok) { return { error: 'Failed to get response' }; } const data = await response.json(); return { success: true, data: data.aiAgentFinalOutput }; } catch (error) { return { error: 'Something went wrong' }; } }

/* Terminal-inspired design with perfect color harmony */ body { background-color: rgb(2 6 23 / 1); /* Deep space blue */ color: rgb(203 213 225 / 1); /* Soft white text */ font-family: 'Menlo', 'Consolas', 'Monaco', monospace; text-transform: uppercase; letter-spacing: 0.05em; } .prose { --tw-prose-headings: theme(colors.cyan.400); /* Electric cyan headers */ --tw-prose-code: theme(colors.cyan.400); /* Code highlighting */ --tw-prose-bullets: theme(colors.cyan.400); /* List styling */ }

ai-agent-openai-api-nextjs-app/ ├── 📂 src/ │ ├── 📂 app/ # Next.js 15 App Router │ │ ├── 📂 api/ │ │ │ └── 📂 agent/ │ │ │ └── 📄 route.ts # 🤖 AI Agent API endpoint │ │ ├── 📄 favicon.ico # 🎨 Custom branding │ │ ├── 📄 globals.css # 🎨 Terminal design system │ │ ├── 📄 layout.tsx # 🏗️ Root layout & typography │ │ └── 📄 page.tsx # 💻 Main interface & typewriter │ └── 📂 features/ │ └── 📄 actions.ts # 🚀 Server actions & validation ├── 📂 public/ # 🖼️ Static assets & icons │ ├── 📄 globe.svg # 🌍 Location-aware branding │ ├── 📄 file.svg # 📁 File system icons │ ├── 📄 window.svg # 🖥️ Interface elements │ └── 📄 next.svg # ⚡ Framework branding ├── 📄 package.json # 📦 Dependencies & scripts ├── 📄 next.config.ts # ⚙️ Next.js configuration ├── 📄 tsconfig.json # 🔧 TypeScript config ├── 📄 eslint.config.mjs # 📏 Code quality rules ├── 📄 postcss.config.mjs # 🎨 CSS processing └── 📄 README.md # 📚 This documentation 

• /app Directory: Leveraging Next.js 15's App Router for file-based routing and layouts
• Server Actions: Co-located in /features for reusable business logic
• API Routes: RESTful endpoints under /api with proper error handling
• Component Structure: Single-file components with embedded logic for this MVP
• Type Safety: Strict TypeScript configuration across all layers

• Node.js: 18+ (recommended: 20+)
• Package Manager: pnpm (recommended for performance)
• OpenAI API Key: Required for AI functionality

# Clone the repository git clone https://github.com/hemants1703/ai-agent-openai-api-nextjs-app.git cd ai-agent-openai-api-nextjs-app # Install dependencies with pnpm (ultra-fast) pnpm install # Set up environment variables cp .env.example .env.local # Add your OpenAI API key to .env.local # Start development server with Turbopack pnpm dev

Open http://localhost:3000 and experience the AI agent in action!

Try these example prompts:

• "What's the weather like in my location?"
• "Tell me about my current city"
• "What time zone am I in?"

• ✅ AI Agent Foundation: OpenAI integration with location awareness
• ✅ Terminal UI: Cyberpunk-inspired interface design
• ✅ Typewriter Effect: Smooth character-by-character rendering
• 🔄 Enhanced Error Handling: More robust error boundaries
• 🔄 Performance Optimization: Response caching and lazy loading

• 🎯 Multi-Tool Architecture: Weather, calendar, and productivity tools
• 🔐 Authentication System: User accounts and personalization
• 💾 Conversation Memory: Persistent chat history with context
• 📱 Mobile Optimization: PWA capabilities and offline support
• 🌍 Internationalization: Multi-language support

• 📊 Analytics Dashboard: Usage metrics and performance insights
• 🔒 Enterprise Security: Role-based access and audit logs
• 🚀 Microservices: Scalable backend architecture
• ☁️ Cloud Deployment: Multi-region deployment on Vercel/AWS

• Frontend Excellence: React 19, Next.js 15, advanced hooks, and custom components
• Backend Sophistication: Server actions, API routes, and external service integration
• AI Integration: OpenAI Agents SDK, tool-calling, and context management
• DevOps Awareness: Turbopack, ESLint, TypeScript, and modern build tools

• Type Safety: 100% TypeScript with strict configuration
• Performance: Optimized rendering, lazy loading, and efficient state management
• User Experience: Accessibility, responsive design, and micro-interactions
• Code Quality: Clean architecture, reusable components, and comprehensive error handling

• AI-First Design: Contextual intelligence with real-time data integration
• Visual Identity: Custom terminal aesthetic with professional polish
• Technical Depth: Advanced React patterns and Next.js 15 features
• Scalable Foundation: Extensible architecture ready for enterprise features

"This project showcases the perfect blend of cutting-edge AI technology, modern web development practices, and exceptional user experience design."

• ✅ Latest Technologies: Next.js 15, React 19, OpenAI Agents SDK
• ✅ Full-Stack Capabilities: Frontend excellence + backend sophistication
• ✅ AI Integration: Real-world AI application with tool-calling
• ✅ Production Ready: Type-safe, error-handled, and scalable

• ✅ Code Quality: Clean, maintainable, and well-documented
• ✅ User Focus: Intuitive interface with exceptional UX
• ✅ Technical Depth: Advanced patterns and modern best practices
• ✅ Delivery Speed: Rapid prototyping with production-quality results

Specializations:

• 🤖 AI-Powered Applications: OpenAI, LangChain, vector databases
• ⚛️ Modern Frontend: React, Next.js, TypeScript, advanced UI patterns
• 🏗️ Scalable Backend: Node.js, serverless, microservices architecture
• 🎨 Design Systems: Tailwind, custom CSS, responsive design

What Sets Me Apart:

• 💡 Innovation: Bleeding-edge technology adoption and creative problem solving
• 🎯 Quality: Obsessive attention to detail and user experience
• 🚀 Speed: Rapid prototyping without compromising on quality
• 🤝 Collaboration: Clear communication and team-first mentality

Let's Build Something Amazing Together!

MIT License - feel free to use this project as inspiration for your own AI applications!