Creating an Agent Platform resource identifier

2 min read

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}\"
  }"
Code language: PHP (php)

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

Code language: PHP (php)

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}"
Code language: PHP (php)

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