Generative AI Google Brain

agents-agent-engine-tutorial-deploy-your-containerised-agent

3 min read

Deploy your containerized agent on Agent Runtime (prev. Agent Engine)

Source notebook

Repo path: agents/agent_engine/tutorial_deploy_your_containerised_agent.ipynb · Open on GitHub · advanced

Deploys a BYOC ADK weather agent to Agent Runtime and queries it through the Vertex AI API.

Summary

This notebook teaches how to containerize a Google ADK agent, build and push its Docker image to Artifact Registry with Cloud Build, and deploy it to Agent Runtime using the Vertex AI SDK client. It defines a FastAPI runtime around agent_engines.AdkApp, configures IAM for build, Agent Runtime, AI Platform, and tenant service accounts, then calls the deployed agent’s streamQuery endpoint. The example agent uses a Gemini model and a get_temperature tool that returns simulated weather data.

Key code patterns

ADK tool agent

def get_temperature(place: str) -> str:
    temp = random.randint(-10, 40)
    return f"The current temperature in {place} is {temp}°C."
 
root_agent = Agent(
    model=llm_model,
    name="weather_agent",
    tools=[get_temperature],
)

Defines an ADK agent with a Python function tool that the LLM can call.

Global Gemini override

class GlobalGemini(Gemini):
  @cached_property
  def api_client(self) -> Client:
    return Client(vertexai=True, location="global")
 
llm_model = GlobalGemini(model=MODEL) if MODEL_REGION == "global" else Gemini(model=MODEL)

Handles models configured to use the global endpoint instead of a regional endpoint.

FastAPI runtime wrapper

app = FastAPI()
adk_app = agent_engines.AdkApp(agent=root_agent)
 
@app.post("/api/reasoning_engine")
async def query(request: QueryRequest):
    method = getattr(adk_app, request.class_method)
    output = await _invoke_callable_or_raise(method, request.input or {})
    return responses.JSONResponse(content={"output": output})

Exposes ADK app methods through the container contract expected by Agent Runtime.

BYOC deployment

remote_agent = client.agent_engines.create(
    config={
        "display_name": "byoc_weather_agent",
        "container_spec": {"image_uri": image_uri},
        "class_methods": [{"api_mode": "stream", "name": "stream_query"}],
        "agent_framework": "google-adk",
    },
)

Deploys a pre-built container image instead of relying on platform bundling.

streamQuery call

response = requests.post(
    f"https://{LOCATION}-aiplatform.googleapis.com/v1/{remote_agent.api_resource.name}:streamQuery",
    headers={"Authorization": f"Bearer {get_identity_token()}"},
    data=json.dumps({"class_method": "async_stream_query", "input": input}),
    stream=True,
)

Shows how to invoke the deployed remote agent with an authenticated streaming request.

Models & APIs used

  • Models: gemini-3.1-flash-lite
  • APIs / services: Vertex AI, Agent Runtime, Agent Platform API, Artifact Registry, Cloud Build, Compute Engine, IAM
  • SDKs / libraries: google-cloud-aiplatform, vertexai, google-adk, google-genai, FastAPI, pydantic, uvicorn, requests, google-auth

When to use this

Use this pattern when an enterprise agent needs a fully controlled custom container runtime on Agent Runtime.

Gotchas & caveats

  • Requires an existing Google Cloud project with Agent Platform API enabled.
  • Notebook installs google-cloud-aiplatform[agent_engines,adk]>=1.144.
  • Requires authentication through Colab auth or application default credentials.
  • PROJECT_ID and LOCATION must be set or available from GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_REGION.
  • Artifact Registry, Cloud Build, and Compute Engine APIs are enabled with gcloud.
  • Default Compute Service Account needs Artifact Registry Writer and Storage Object Viewer roles.
  • Reasoning Engine Service Agent, AI Platform Service Agent, and tenant service account need Artifact Registry Reader role.
  • If iam.allowedPolicyMemberDomains is enforced, Google’s customer domain must be allowed before granting tenant service account permissions.
  • The weather tool returns simulated random temperatures, not real weather API data.

Best practices

  • Stores project, model, model region, and location settings in config.json for the containerized agent.
  • Uses a Dockerfile and requirements.txt to make the agent runtime reproducible.
  • Wraps the ADK root_agent with agent_engines.AdkApp before exposing runtime endpoints.
  • Defines both regular and streaming FastAPI endpoints for agent invocation.
  • Uses agent_framework=“google-adk” so the deployed agent can be used through the Google Cloud console playground.
  • Deletes temporary agents, Artifact Registry repository, and local directories during cleanup.

Graph View

Backlinks