Creating an Agent Platform resource identifier

To use Agent Platform services like Memory Bank, and Sessions from other environments, you need to first create a resource that is currently known as an “agent engine”.

Note: if you are familiar with the Python ADK libraries, you can follow these instructions instead, to create an instance via the SDK.

Here’s a single API call to create a resource identifier that you can use right away:

# 1. Set your variables
PROJECT_ID=$(gcloud config get-value project)
LOCATION="us-west1" # Replace with your target region
RESOURCE_DISPLAY_NAME="My Memory Bank"

# 2. Execute the REST API request
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/reasoningEngines" \
  -d "{
    \"displayName\": \"${RESOURCE_DISPLAY_NAME}\"
  }"

The creation returns immediately with an operation id, and executes async, you can query the API with the operation, or look up the Deployments UI to get the resource.

For a more robust script, let’s wrap this creation call, wait for the resource to be created and write a test memory:

# 1. Set your variables
PROJECT_ID=$(gcloud config get-value project)
LOCATION="us-west1" # Replace with your target region
RESOURCE_DISPLAY_NAME="My Memory Bank"

# 2. Build the request payload
SETTINGS="{
    \"displayName\": \"${RESOURCE_DISPLAY_NAME}\"
  }"

# 3. Execute the REST API request, capturing the response body
RESPONSE=$(curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/reasoningEngines" \
  -d "${SETTINGS}")

# 4. Check for errors in the response
if [ -z "$RESPONSE" ]; then
  echo "Error: empty response from API" >&2
  exit 1
fi

if echo "$RESPONSE" | grep -q '"error"'; then
  echo "Error: API request failed" >&2
  echo "$RESPONSE" >&2
  exit 1
fi

# 5. Parse the "name" field from the response
NAME=$(echo "$RESPONSE" | jq -r '.name')

if [ -z "$NAME" ] || [ "$NAME" = "null" ]; then
  echo "Error: could not parse 'name' from response" >&2
  echo "$RESPONSE" >&2
  exit 1
fi

echo "Operation name: $NAME"

# 6. Derive the engine resource name from the operation name
ENGINE_NAME="${NAME%/operations/*}"

# 6b. Wait for the create operation to complete (engine is provisioned async)
echo "Waiting for engine to be created..."
until [ "$(curl -s \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://${LOCATION}-aiplatform.googleapis.com/v1/${NAME}" | jq -r '.done')" = "true" ]; do
  sleep 5
done
echo "Engine ready: $ENGINE_NAME"

echo
echo "Add these env variables to your deployment:"
echo "SESSION_SERVICE_URI=agentengine://${ENGINE_NAME}"
echo "MEMORY_SERVICE_URI=agentengine://${ENGINE_NAME}"
echo

As a follow-on, we can create an example memory and session to test (and have it show in the UI):

# 7. Create a memory under the engine
echo "Creating a test memory"
MEMORY="{
    \"fact\": \"My first memory.\",
    \"scope\": {\"placeholder\": \"true\"}
  }"
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://${LOCATION}-aiplatform.googleapis.com/v1/${ENGINE_NAME}/memories" \
  -d "${MEMORY}"

# 8. Create a session under the engine
echo "Creating a test session"
SESSION="{
    \"userId\": \"user-123\"
  }"
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://${LOCATION}-aiplatform.googleapis.com/v1/${ENGINE_NAME}/sessions" \
  -d "${SESSION}"

We can now use the $ENGINE_NAME resource for other environments, like GKE.