Connecting to “backend-api” in aitana-multivac-production

This guide explains how to connect to the “backend-api” Cloud Run service in the aitana-multivac-production project (located in europe-west1 region) that is protected via Google Cloud authentication and accessed via a proxy.

Windows-Specific Setup Instructions

Prerequisites

  1. Install the Google Cloud SDK for Windows
  2. Install PowerShell 7 (recommended for better terminal experience)
  3. Install Windows Terminal (optional but recommended)
    • Download from Microsoft Store or GitHub

Connection Steps

1. Verify your permissions

Your account has already been granted the necessary permissions (Cloud Run Invoker role) to access the backend-api service. You can verify this with:

# Check your current permissions
gcloud projects get-iam-policy aitana-multivac-production --format="table(bindings.role,bindings.members)" | findstr run.invoker

No additional permission setup is required as this has already been handled for you.

2. Set up authentication

# Log in with your Google account
gcloud auth login

# Set the default project
gcloud config set project aitana-multivac-production

# Set the default region
gcloud config set run/region europe-west1

This ensures that your gcloud commands will use the correct project and region by default.

3. Set up the proxy connection

Make sure no other proxies are running before you start.

# Use the gcloud run services proxy command to create a local proxy to the Cloud Run service
gcloud run services proxy backend-api `
    --project=aitana-multivac-production `
    --port=8080 `
    --region=europe-west1

This command creates a local proxy that forwards requests to your Cloud Run service while handling authentication automatically. It’s specifically designed for Cloud Run services and is the recommended approach.

4. Connect and make requests

With the proxy running, you can now make requests to the service:

# Using Invoke-RestMethod (PowerShell's equivalent to curl)
# Note: When using gcloud run services proxy, you don't need to include the authentication token
# as the proxy handles authentication for you
Invoke-RestMethod -Uri "http://localhost:8080/endpoint" -Method GET

# For POST requests with JSON data
$data = @{
    key = "value"
    anotherKey = "anotherValue"
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://localhost:8080/endpoint" -Method POST -Body $data -ContentType "application/json"

If you need to make requests from a different application or script while the proxy is running, just point them to http://localhost:8080 and the proxy will handle the authentication.

Testing Your Connection

After setting up the proxy, you should verify that the connection is working properly. Here are test calls you can use to check the connection.

1. Initial Test - Raw Endpoint

First, test the connection using a simple call to the raw endpoint:

# Create a test JSON payload
$testPayload = @{
    user_input = "hello"
    stream_only = $true
    stream_wait_time = 1
    chat_history = @(
        @{
            name = "AI"
            content = "Welcome to Aitana. I am an assistant that has been set up to help connect to the various data sources available for Our New Energy."
        }
    )
    instructions = "You are the API assistant for Aitana."
    emissaryConfig = @{
        botId = "api-call"
        botName = "Aitana API"
        senderName = "Your Name"
        shareId = "api-call20250325"
        tools = @("code_execution", "vertex_search", "file-browser")
        toolConfigs = @{
            file_browser = @{
                bucketUrl = "aitana-documents-bucket"
            }
            vertex_search = @{
                datastore_id = "aitana3"
            }
        }
        selectedItems = @()
        currentUser = @{
            email = "you@your-email.com"
            sessionId = "XXXX"
        }
    }
} | ConvertTo-Json -Depth 10

# Send the request
Invoke-RestMethod -Uri "http://localhost:8080/vac/streaming/aitana3" -Method Post -Body $testPayload -ContentType "application/json"

After confirming basic connectivity, switch to using the assistantId endpoint which is the preferred method:

# Example assistantIds to test with:
# - echo: 360762b1-5f00-4b3c-847c-83959e36aad7
# - vanilla-anthropic: ffa74615-f2e4-42e2-8f92-4b403d4ee223
# - ONE news anchor: 566aa49b-9e58-42b2-b76f-5d31c19c5600

# Create a simpler JSON payload for the assistantId endpoint
$assistantPayload = @{
    user_input = "Hello"
    chat_history = @()
    currentUser = @{
        email = "you@your-email.com"
        sessionId = "session-123"
    }
    selectedItems = @()
} | ConvertTo-Json -Depth 5

# Test with the echo assistant
Invoke-RestMethod -Uri "http://localhost:8080/vac/assistant/360762b1-5f00-4b3c-847c-83959e36aad7" -Method Post -Body $assistantPayload -ContentType "application/json"

The response should include both an “answer” field and a “metadata” field, confirming that your connection is working properly.

3. Finding an AssistantId

To find an assistantId for a specific assistant:

  1. Go to the assistant in the Aitana web interface
  2. The assistantId is in the URL: https://ai.aitana.chat/assistant/YOUR-ASSISTANT-ID
  3. Use this ID in your API calls

For example, if an assistant has the URL https://ai.aitana.chat/assistant/ffa74615-f2e4-42e2-8f92-4b403d4ee223, then its assistantId is ffa74615-f2e4-42e2-8f92-4b403d4ee223.

Advanced Usage

Running the proxy as a background process

To run the proxy in the background and keep using your PowerShell session:

# Start the proxy in a new PowerShell window
Start-Process powershell -ArgumentList "-Command gcloud run services proxy backend-api --project=aitana-multivac-production --port=8080 --region=europe-west1"

# To stop it later, find and stop the process
Get-Process -Name powershell | Where-Object {$_.CommandLine -like "*gcloud run services proxy*"} | Stop-Process

Using Python instead of PowerShell

If you prefer using Python on Windows:

import requests

def call_backend_api(endpoint, data=None):
    # No auth token needed when using the proxy
    url = f"http://localhost:8080/{endpoint}"
    
    if data:
        response = requests.post(url, json=data)
    else:
        response = requests.get(url)
    
    return response.json()

# Example usage
result = call_backend_api("users", {"action": "list"})
print(result)

Connecting to Specific Cloud Run Versions

If you need to connect to a specific version of the backend-api service, you can use Cloud Run tags:

# Connect to a specific tagged version (e.g., "init")
gcloud run services proxy backend-api `
    --project=aitana-multivac-production `
    --port=8080 `
    --region=europe-west1 `
    --tag=init

This ensures you’re connecting to a specific version of the service, which can be important for testing or when API changes are being rolled out.

Troubleshooting on Windows

If you encounter issues:

  1. Verify IAM permissions - Ensure you have the correct roles assigned
  2. Check service status - Make sure the service is deployed and running: 
    gcloud run services describe backend-api --project=aitana-multivac-production --region=europe-west1
  3. Verify proxy connection - Check if your local port is listening: 
    netstat -an | findstr 8080
  4. Check for proxy errors - Look at the command window running the proxy for any error messages
  5. Check Windows Firewall - Make sure outbound connections are allowed 
    # If needed, open port 8080 in Windows Firewall
New-NetFirewallRule -DisplayName "Cloud Run Proxy" -Direction Inbound -LocalPort 8080 -Protocol TCP -Action Allow
  6. Inspect Cloud Run logs - Look for any errors: 
    gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=backend-api" --project=aitana-multivac-production
  7. Test with network diagnostic tools: 
    # Test connection
Test-NetConnection -ComputerName localhost -Port 8080
  8. Restart the proxy - Sometimes simply restarting the proxy can fix issues: 
    # Kill any existing proxy processes
Get-Process -Name powershell | Where-Object {$_.CommandLine -like "*gcloud run services proxy*"} | Stop-Process
   
# Start a new proxy
gcloud run services proxy backend-api --project=aitana-multivac-production --port=8080 --region=europe-west1

Additional Resources