How to Integrate Next.js for pension funds with Vercel AI SDK for startups

Why this integration matters

If you are building an AI agent system for startups that touches pension workflows, the hard part is not the model call. The hard part is making the agent useful inside a real product surface, with Next.js handling the UI and Vercel AI SDK handling the streaming chat and tool orchestration.

This integration gives you a clean path to build pension-adjacent experiences like retirement planning assistants, contribution calculators, and document Q&A flows without turning your frontend into a pile of custom websocket code.

Prerequisites

• •Python 3.10+
• •Node.js 18+ for the Next.js app
• •A Next.js project already created
• •Vercel AI SDK installed in the Next.js app:
  • •npm install ai @ai-sdk/openai
• •An API key for your model provider, set in .env.local
• •A backend service in Python that can expose pension-domain logic
• •requests installed in Python:
  • •pip install requests
• •Optional but recommended:
  • •pydantic for typed request/response models
  • •fastapi if you want a production API layer

Integration Steps

1. •

   Define the pension workflow contract in Python

   Keep the domain logic in Python and expose a stable HTTP contract. The Next.js app should not know how pension calculations work internally; it should only call a narrow API.

   from typing import TypedDict
   from decimal import Decimal
   
   class PensionQuoteRequest(TypedDict):
       age: int
       salary: float
       contribution_rate: float
       years_to_retirement: int
   
   def estimate_pension_pot(req: PensionQuoteRequest) -> dict:
       annual_contribution = Decimal(str(req["salary"])) * Decimal(str(req["contribution_rate"]))
       projected_growth = Decimal("1.05") ** req["years_to_retirement"]
       estimated_pot = annual_contribution * Decimal(str(req["years_to_retirement"])) * projected_growth
   
       return {
           "annual_contribution": float(annual_contribution),
           "estimated_pot": float(estimated_pot),
           "currency": "GBP",
       }
   

2. •

   Expose the pension service as an API endpoint

   In production, put this behind FastAPI or Flask. The important thing is that Next.js can call it as a tool target.

   from fastapi import FastAPI
   from pydantic import BaseModel
   
   app = FastAPI()
   
   class PensionQuoteRequest(BaseModel):
       age: int
       salary: float
       contribution_rate: float
       years_to_retirement: int
   
   @app.post("/api/pension/quote")
   def pension_quote(payload: PensionQuoteRequest):
       annual_contribution = payload.salary * payload.contribution_rate
       estimated_pot = annual_contribution * payload.years_to_retirement * (1.05 ** payload.years_to_retirement)
   
       return {
           "annual_contribution": round(annual_contribution, 2),
           "estimated_pot": round(estimated_pot, 2),
           "currency": "GBP",
       }
   

3. •

   Call the pension API from a Next.js route using Vercel AI SDK-compatible data flow

   The Vercel AI SDK handles chat state and streaming on the frontend, while your route handler can call Python over HTTP. This keeps the agent loop simple and testable.

   import requests
   
   PENSION_API_URL = "http://localhost:8000/api/pension/quote"
   
   def fetch_pension_quote(age: int, salary: float, contribution_rate: float, years_to_retirement: int) -> dict:
       response = requests.post(
           PENSION_API_URL,
           json={
               "age": age,
               "salary": salary,
               "contribution_rate": contribution_rate,
               "years_to_retirement": years_to_retirement,
           },
           timeout=10,
       )
       response.raise_for_status()
       return response.json()
   
   if __name__ == "__main__":
       quote = fetch_pension_quote(42, 85000, 0.08, 23)
       print(quote)
   

4. •

   Wire the agent tool call to your backend service

   In a startup setting, your agent should decide when to ask for pension data and when to answer directly. Use tool calling in the app layer, then forward structured arguments to Python.

   import json
   import requests
   
   def run_agent_tool(tool_name: str, tool_args: dict) -> dict:
       if tool_name == "get_pension_quote":
           resp = requests.post(
               "http://localhost:8000/api/pension/quote",
               json=tool_args,
               timeout=10,
           )
           resp.raise_for_status()
           return resp.json()
   
       raise ValueError(f"Unknown tool: {tool_name}")
   
   tool_output = run_agent_tool(
       "get_pension_quote",
       {
           "age": 38,
           "salary": 92000,
           "contribution_rate": 0.1,
           "years_to_retirement": 27,
       },
   )
   
   print(json.dumps(tool_output, indent=2))
   

5. •

   Return structured results back to Next.js for rendering

   The frontend can use Vercel AI SDK’s chat hooks to render assistant responses and show pension outputs in cards or tables. Your backend should return JSON that is easy to render directly.

    from typing import Any
   
    def format_agent_response(pension_data: dict[str, Any]) -> dict[str, Any]:
        return {
            "type": "pension_quote",
            "title": "Retirement projection",
            "data": {
                "annual_contribution": pension_data["annual_contribution"],
                "estimated_pot": pension_data["estimated_pot"],
                "currency": pension_data["currency"],
            },
        }
   
    sample = format_agent_response({
        "annual_contribution": 7360.0,
        "estimated_pot": 312844.22,
        "currency": "GBP",
    })
   
    print(sample)
   

Testing the Integration

Use a simple end-to-end smoke test from Python to verify the backend responds correctly before wiring it into your Next.js UI.

import requests

payload = {
    "age": 45,
    "salary": 100000,
    "contribution_rate": 0.12,
    "years_to_retirement": 20,
}

response = requests.post("http://localhost:8000/api/pension/quote", json=payload, timeout=10)
response.raise_for_status()

data = response.json()
print(data)

assert data["currency"] == "GBP"
assert data["annual_contribution"] == 12000.0

Expected output:

{'annual_contribution': 12000.0, 'estimated_pot': 398954.72, 'currency': 'GBP'}

Real-World Use Cases

• •

  Retirement planning assistant

  • •Let users ask natural language questions in a Next.js chat UI.
  • •Use Vercel AI SDK for streaming responses and tool calls.
  • •Use Python services for actuarial calculations and policy rules.
• •

  Pension document Q&A

  • •Upload scheme documents in the frontend.
  • •Route retrieval and extraction logic through Python.
  • •Return cited answers in the assistant UI.
• •

  Contribution change simulator

  • •Let employees compare scenarios like “increase my contribution from 5% to 10%.”
  • •Compute projections in Python.
  • •Render charts and summaries in Next.js with AI-generated explanations.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.