Deploy to Cloud Run

Feature Coming Soon

Cloud Run deployment commands are currently being developed for @iqai/adk. The examples below show the planned API, but the deployment functionality is not yet available.

Cloud Run is a fully managed platform that enables you to run your code directly on top of Google's scalable infrastructure.

Current Status

While the ADK CLI deployment tools are in development, you can manually deploy your agents to Cloud Run using standard Docker and gcloud commands.

Manual Deployment (Available Now)

Prerequisites

Set your environment variables:

export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_CLOUD_LOCATION=us-central1

Authenticate with Google Cloud:

gcloud auth login
gcloud config set project your-project-id

Project Structure

your-project-directory/
├── src/
│   ├── agent/
│   │   └── index.ts       # Your agent code
│   └── server.ts          # Express server entry point
├── package.json           # Node.js dependencies
├── tsconfig.json          # TypeScript configuration
└── Dockerfile             # Container build instructions

Express Server Setup

src/server.ts

import express from 'express';
import { LlmAgent, Runner, InMemorySessionService } from '@iqai/adk';

const app = express();
app.use(express.json());

// Create your agent
const agent = new LlmAgent({
  name: "my_agent",
  description: "A helpful assistant",
  model: "gemini-2.5-flash",
  instruction: "Be helpful and concise"
});

// Set up session service and runner
const sessionService = new InMemorySessionService();
const runner = new Runner({
  appName: "cloud-run-app",
  agent,
  sessionService
});

// API endpoint
app.post('/api/chat', async (req, res) => {
  try {
    const { message, userId = 'default-user' } = req.body;

    // Create or get session
    const sessions = await sessionService.listSessions('cloud-run-app', userId);
    let session;
    if (sessions.sessions.length > 0) {
      session = await sessionService.getSession('cloud-run-app', userId, sessions.sessions[0].id);
    } else {
      session = await sessionService.createSession('cloud-run-app', userId);
    }

    // Run agent
    const events = [];
    for await (const event of runner.runAsync({
      userId,
      sessionId: session.id,
      newMessage: { parts: [{ text: message }] }
    })) {
      if (event.isFinalResponse()) {
        events.push(event);
        break;
      }
    }

    res.json({
      response: events[0]?.content?.parts?.[0]?.text || 'No response',
      sessionId: session.id
    });
  } catch (error) {
    console.error('Error:', error);
    res.status(500).json({ error: error.message });
  }
});

// Health check
app.get('/health', (req, res) => {
  res.json({ status: 'healthy' });
});

const PORT = parseInt(process.env.PORT || '8080', 10);
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Package Configuration

package.json

{
  "name": "@iqai/adk-cloud-run-agent",
  "version": "1.0.0",
  "description": "ADK TypeScript Agent for Cloud Run deployment",
  "main": "dist/server.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js",
    "dev": "ts-node src/server.ts"
  },
  "dependencies": {
    "@iqai/adk": "^0.1.1",
    "express": "^4.18.2"
  },
  "devDependencies": {
    "@types/express": "^4.17.17",
    "@types/node": "^22.0.0",
    "ts-node": "^10.9.1",
    "typescript": "^5.3.2"
  },
  "engines": {
    "node": ">=22.0.0"
  }
}

TypeScript Configuration

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "esModuleInterop": true,
    "strict": true,
    "outDir": "dist",
    "rootDir": "src",
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Dockerfile

FROM node:22-slim
WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 8080
CMD ["npm", "start"]

Deploy Command

gcloud run deploy my-adk-agent \
  --source . \
  --region=$GOOGLE_CLOUD_LOCATION \
  --project=$GOOGLE_CLOUD_PROJECT \
  --allow-unauthenticated \
  --memory=1Gi \
  --cpu=1 \
  --port=8080

Planned ADK CLI Integration

The upcoming ADK CLI will provide simplified deployment:

Planned Environment Variables

export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
export AGENT_PATH="./my_agent"
export SERVICE_NAME="my-agent-service"

Planned Commands

# Minimal command (coming soon)
npx @iqai/adk deploy cloud-run \
  --project=$GOOGLE_CLOUD_PROJECT \
  --region=$GOOGLE_CLOUD_LOCATION \
  $AGENT_PATH

# Full command with options (coming soon)
npx @iqai/adk deploy cloud-run \
  --project=$GOOGLE_CLOUD_PROJECT \
  --region=$GOOGLE_CLOUD_LOCATION \
  --service-name=$SERVICE_NAME \
  --with-ui \
  $AGENT_PATH

Planned Command Options

AGENT_PATH: (Required) Path to your agent's source code directory
--project: (Required) Your Google Cloud project ID
--region: (Required) Google Cloud location for deployment
--service-name: (Optional) Cloud Run service name
--with-ui: (Optional) Deploy a web UI alongside the API server
--port: (Optional) Port number for the API server (defaults to 8080)

Testing Your Deployment

After deployment, you'll receive a URL. Test your agent:

curl -X POST https://your-service-url/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello!", "userId": "test_user"}'

Upon successful deployment, you'll receive the URL of your deployed Cloud Run service.

Authentication

During deployment, you may be prompted about unauthenticated access:

Yes: Allow public access to your agent's API endpoint
No: Require authentication for access

What's Coming

The ADK CLI will provide:

One-command deployment: Automated containerization and deployment
Built-in UI: Optional web interface for testing your agent
Environment management: Easy configuration management
Monitoring integration: Built-in logging and monitoring setup

Deploy to Cloud Run

On this page