How to deploy an ADK + NextJS Fullstack AI Application

Key Concepts

• ADK (Agent Development Kit): A framework for building AI agents.
• Agent Engine: A managed service for deploying and running ADK agents in the cloud.
• Next.js: A React framework for building web applications.
• Vercel: A platform for deploying web applications.
• Server-Side Events (SSE): A protocol for pushing data from a server to a client over HTTP.
• JSON Fragments: Individual JSON objects sent in a stream.
• Service Account: A Google Cloud identity used by applications to access resources.
• Vertex AI: Google Cloud's platform for machine learning.
• Deployment: The process of making an application available for use.
• Streaming: Sending data in real-time, chunk by chunk.
• Make: A build automation tool.
• UV: A Python package installer and resolver.
• Pi Project Toml: A configuration file for Python projects.

Phase 1: ADK Agent Deployment

Local ADK Agent Review

• The video focuses on deploying a goal planning ADK agent.
• The agent takes a goal as input and breaks it down into actionable steps.
• The agent uses planning, allowing it to take multiple attempts at solving the problem.
• The agent has a specific output format: agent's understanding of the goal, tasks in order, and subtasks.
• The agent.py file contains the agent's logic, including name, model, description, and instructions.
• The make file simplifies running commands like adk web (for web interaction) and adk api (for backend API server).
• The pi project total file lists ADK dependencies.

Example: The agent is given the goal "get hired at a FANG company in the next 12 months" and breaks it down into subtasks.

ADK Agent Deployment to Agent Engine

• Prerequisites: A Google Cloud account with billing enabled.
• Steps:
  1. Create a new Google Cloud project: Named "deploy ADK dev YouTube" in the video.
  2. Enable necessary APIs: Vertex AI, Google Cloud Storage, Cloud Build, Cloud Run, and Artifact Registry.
  3. Create a service account: Named "ADK FE service" with roles "Vertex AI User" and "Service Account Token Creator." This account allows the Next.js frontend to securely access the deployed agent.
  4. Create a Cloud Storage bucket: Named "deploy adev YouTube" (must be globally unique) to store the agent's code and dependencies.
  5. Install and configure Google Cloud CLI: Authenticate with gcloud auth login and set the default project with gcloud config set project [project-id].
  6. Update environment variables: In the .env file, set GOOGLE_CLOUD_STAGING_BUCKET to the bucket name and GOOGLE_CLOUD_PROJECT_ID to the project ID. Leave US Central 1 as the location.
  7. Deploy the agent: Run make deploy ADK. This command exports dependencies to requirements.txt and executes the deployment script.
• Deployment Script Details:
  • The script retrieves deployment configurations from environment variables.
  • It creates a new bucket for logs.
  • It initializes Vertex AI with the project, location, and staging bucket.
  • It reads the requirements.txt file.
  • It uses the Agent Engine API to create or update the agent.
  • It saves deployment metadata.
• Post-Deployment Verification:
  • Two buckets should exist: one for staging and one for logs.
  • The Agent Engine dashboard should show the deployed agent.
• Agent Engine API URLs:
  • Query: For standard, synchronous queries.
  • Stream Query: For streaming responses (though currently returns JSON fragments instead of server-side events).
• Important Note: Server-Side Events (SSE) are currently broken in Agent Engine deployments. The system returns JSON objects instead, requiring workarounds in the Next.js application.

ADK in the Cloud: Key Concepts

• Agent Engine simplifies deployment by handling complexity like Docker images.
• The agent's code is shipped to the cloud, built with dependencies, and stored in Cloud Storage.
• The number of workers determines how many parallel instances of the agent are running.
• Each deployed agent has a unique reasoning engine ID.

Phase 2: Next.js Application Deployment

Next.js Application Overview

• The Next.js application provides a frontend for interacting with the ADK agent.
• It uses a chat provider to manage state across different components (header, message list, input area).
• The application requires creating a session for each user before sending messages.
• The backend acts as a proxy, forwarding requests between the frontend and the ADK agent.

Local Development Setup

• Run make dev frontend to start the Next.js application on port 3000.
• Run make dev to start both the frontend and backend.
• The application allows creating users and sessions.
• Messages are displayed in a chat-like interface.

Session Creation and Management

• The handleCreateNewSession function in the useSession hook creates a new session.
• It sends a POST request to the /api/apps/[app-name]/users/[user-id]/sessions endpoint on the backend.
• The backend then forwards the request to the ADK agent.
• The fetchActiveSessions function retrieves existing sessions for a user.
• It sends a GET request to the /api/apps/[app-name]/users/[user-id]/sessions endpoint.
• It then fetches the events (messages) associated with each session.

Message Sending

• The handleSubmitMessage function in the chat provider sends a message to the ADK agent.
• It adds the message to the UI immediately.
• It then sends a request to the /api/runServersideEvent endpoint on the backend.
• The backend forwards the request to the ADK agent.
• The ADK agent streams back responses as server-side events.
• The frontend handles different event types (thoughts, text) and updates the UI accordingly.
• The system checks for a termination signal (the full message being resent) to indicate that the agent is done.

Next.js Application Deployment to Vercel

• Steps:
  1. Create a new Vercel project: Connect to the GitHub repository.
  2. Configure the project: Specify the Next.js application directory.
  3. Set environment variables:
     • GOOGLE_CLOUD_PROJECT: Google Cloud project ID.
     • ADK_APP_NAME: Name of the ADK agent.
     • REASONING_ENGINE_ID: Reasoning engine ID of the deployed agent.
     • AGENT_ENGINE_ENDPOINT: Agent Engine API endpoint (without /query).
     • GOOGLE_CLOUD_SERVICE_KEY: Base64 encoded JSON key for the service account.
  4. Create a service account key: In Google Cloud, create a JSON key for the service account.
  5. Convert the JSON key to Base64: Use a command-line tool like cat [key-file] | base64 to encode the key.
  6. Deploy the application: Vercel automatically builds and deploys the application.
• Post-Deployment Verification:
  • The Vercel dashboard should show the deployed application.
  • The application should be accessible via the provided URL.
  • The application should be able to communicate with the deployed ADK agent.

Cloud Deployment Specifics

• The deployed Next.js application needs to authenticate with Google Cloud using a service account.
• The service account key is stored as a Base64 encoded environment variable.
• The Next.js backend converts the Base64 key back to JSON and uses it to obtain an access token.
• The access token is then used to authenticate requests to the Agent Engine API.
• Agent Engine currently returns JSON fragments instead of server-side events, requiring data massage in the Next.js backend.

Code Deep Dive: Cloud Communication

• The runServersideEvents endpoint handles requests from the frontend.
• It checks if the application is running in the cloud or locally.
• If running in the cloud, it calls the handleAgentEngineStream function.
• The handleAgentEngineStream function:
  • Converts the request data into a payload suitable for Agent Engine.
  • Gets the Agent Engine API endpoint.
  • Obtains an access token using the service account key.
  • Sends a request to the Agent Engine API.
  • Converts the JSON fragments received from Agent Engine into server-side events.
  • Streams the server-side events back to the frontend.

Synthesis/Conclusion

The video provides a comprehensive guide to deploying ADK agents to the cloud using Agent Engine and connecting them to Next.js applications deployed on Vercel. It covers the entire process, from setting up Google Cloud and Agent Engine to configuring environment variables and handling communication between the frontend and backend. While the current limitations of Agent Engine's streaming support require workarounds, the video offers practical solutions and detailed explanations to enable full-stack AI web application development with ADK. The key takeaways are the importance of service accounts for authentication, the need for data massage to handle JSON fragments, and the overall architecture of a Next.js application acting as a proxy between the frontend and the deployed ADK agent. The provided source code and deployment guides are valuable resources for developers looking to implement this architecture.