hunfabric/modules/agent-engine/README.md

Agent Engine Module

The module creates Agent Engine and related dependencies.

• It can automatically generate and update the Pickle file for you, given a source file.
• It optionally creates a GCS storage bucket or can use an existing one and loads on it all your dependencies (pickle, dependencies.tar.gz, requirements.txt)
• Manages the service accounts lifecycle

• Packaging dependencies
• Minimal deployment
• Service accounts
• Specify an encryption key
• Define environment variables and use secrets
• Getting values from context
• Variables
• Outputs

Packaging dependencies

To deploy an agent, you first need package your dependencies. This consists of a folder with

• The source Python file defining your agent to be pickled (or the equivalent pickle file).
• The dependencies.tar.gz.
• The requirements.txt file.

By default, the module expects these files to be in an src subfolder.

You can decide to let the module create the pickle file for you, starting from a source agent file. In this case, the module expects you to have in src a source file called agent.py with a variable referencing your agent function definition called local_agent.

This is an example of agent.py file for ADK:

from google.adk.agents import LlmAgent
from vertexai.agent_engines import AdkApp

def get_exchange_rate(
    currency_from: str = "USD",
    currency_to: str = "EUR",
    currency_date: str = "latest",
):
    import requests
    response = requests.get(
        f"https://api.frankfurter.app/{currency_date}",
        params={"from": currency_from, "to": currency_to},
    )
    return response.json()

root_agent = LlmAgent(
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant",
    name='currency_exchange_agent',
    tools=[get_exchange_rate],
)

local_agent = AdkApp(agent=root_agent)

The tools/serialize_agent.py is used to generate the pickle.pkl file. You module needs these packages to work.

If you already have a pickle file, the module expects you to have in the src subfolder a pickle.pkl file.

You can customize these values by using the source_files variable.

Minimal deployment

This example assumes you are providing the source packages (agent.py, dependencies.tar.gz and requirements.txt) in the src subfolder. Every time you will change the agent definition, the module will generate the new pickle file for you, will update it on the GCS bucket and will update your agent.

module "agent_engine" {
  source     = "./fabric/modules/agent-engine"
  name       = "my-agent"
  project_id = var.project_id
  region     = var.region

  agent_engine_config = {
    agent_framework = "google-adk"
  }

  source_files = {
    path = "assets/src/"
  }
}
# tftest inventory=minimal.yaml

Alternatively, you can pass a pre-generated pickle.pkl file.

module "agent_engine" {
  source          = "./fabric/modules/agent-engine"
  name            = "my-agent"
  project_id      = var.project_id
  region          = var.region
  generate_pickle = false

  agent_engine_config = {
    agent_framework = "google-adk"
  }

  source_files = {
    path = "assets/src/"
  }
}
# tftest inventory=minimal-pickle.yaml

Service accounts

By default, the module creates a dedicated service account for your agent and grants it the roles needed to deploy the agent. The default roles are defined in var.service_account_config.roles. You can add more roles, as needed.

You can also use the default Agent Engine (Reasoning Engine) service agent. In this case, it will be your responsibility to grant any other role needed to the service agent service account. At the moment, you'll need at least to grant to it the roles/viewer role.

module "agent_engine" {
  source     = "./fabric/modules/agent-engine"
  name       = "my-agent"
  project_id = var.project_id
  region     = var.region

  agent_engine_config = {
    agent_framework = "google-adk"
  }

  service_account_config = {
    create = false
  }

  source_files = {
    path = "assets/src/"
  }
}
# tftest inventory=sa-default.yaml

Alternatively, you can use an existing service account.

module "agent_engine" {
  source     = "./fabric/modules/agent-engine"
  name       = "my-agent"
  project_id = var.project_id
  region     = var.region

  agent_engine_config = {
    agent_framework = "google-adk"
  }

  service_account_config = {
    create = false
    email  = "my-sa@${var.project_id}.iam.gserviceaccount.com"
  }

  source_files = {
    path = "assets/src/"
  }
}
# tftest inventory=sa-custom.yaml

Specify an encryption key

You can optionally specify an existing encryption key, created in KMS.

To use KMS keys you'll need to grant the AI Platform Service Agent (service-YOUR_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) the roles/cloudkms.cryptoKeyEncrypterDecrypter role on the key.

module "agent_engine" {
  source         = "./fabric/modules/agent-engine"
  name           = "my-agent"
  project_id     = var.project_id
  region         = var.region
  encryption_key = "projects/${var.project_id}/locations/${var.region}/keyRings/my-keyring/cryptoKeys/my-key"

  agent_engine_config = {
    agent_framework = "google-adk"
  }

  source_files = {
    path = "assets/src/"
  }
}
# tftest inventory=encryption.yaml

Define environment variables and use secrets

You can define environment variables and load existing secrets as environment variables into your agent.

module "agent_engine" {
  source     = "./fabric/modules/agent-engine"
  name       = "my-agent"
  project_id = var.project_id
  region     = var.region

  agent_engine_config = {
    agent_framework = "google-adk"

    environment_variables = {
      FOO = "my-foo-variable"
    }
    secret_environment_variables = {
      BAR = {
        secret_id = "projects/YOUR_PROJECT_NUMBER/secrets/my-bar-secret"
      }
    }
  }

  source_files = {
    path = "assets/src/"
  }
}
# tftest inventory=environment.yaml

Getting values from context

The module allows you to dynamically reference context values for resources created outside this module, through the context variable. This includes the definition of custom roles, iam_principals, locations, kms_keys and project ids.

Variables

name	description	type	required	default
agent_engine_config	The agent configuration.	object({…})	✓
name	The name of the agent.	string	✓
project_id	The id of the project where to deploy the agent.	string	✓
region	The region where to deploy the agent.	string	✓
bucket_config	The GCS bucket configuration.	object({…})		{}
context	Context-specific interpolations.	object({…})		{}
description	The Agent Engine description.	string		"Terraform managed."
encryption_key	The full resource name of the Cloud KMS CryptoKey.	string		null
generate_pickle	Generate the pickle file from a source file.	bool		true
service_account_config	Service account configurations.	object({…})		{}
source_files	The to source files path and names.	object({…})		{}

Outputs

name	description	sensitive
id	Fully qualified Agent Engine id.
service_account	Service account resource.