Agent Engine: Deploy to the Managed Runtime

Before you start: this is a billed cloud service

This lab follows the series conventions, with one thing to call out hard:

• Cost and account. You need a Google Cloud project with billing enabled and the Agent Engine / Vertex AI APIs turned on. A deployed Agent Engine instance bills for as long as it exists — this is the first lab that leaves a resource running, so the cleanup step at the end is not optional.
• Authored against the docs, not executed live. The Python here is written against the official SDK docs and syntax-checked, but not run against a billed project during authoring. The managed-runtime SDK moves quickly and a few method names differ across versions — pin your SDK version, run it yourself, and use operation_schemas() (shown below) to confirm the exact operations your version exposes.
• SDK-first. Unlike Lab 1 (console-only), this lab ships code. A starter repo is attached; the snippets below are the important parts.

About this series

This is Part 2 of the eleven-part Gemini Enterprise Agent Platform series. Lab 1 oriented you in the platform and built a no-code agent in Agent Studio. This lab introduces Agent Engine — the managed runtime where agents actually run in production — and deploys a real, code-defined agent to it.

If you've done the ADK series, this is the moment the two tracks connect: in ADK Lab 5 you deployed an agent yourself (to a container you operate). Here you deploy the same kind of agent to a runtime Google operates for you. Same agent, different target — and that difference is the whole point.

What you'll build

You'll take the Acme Orders assistant — a small ADK agent with one tool — and:

1. Run it locally to confirm it works.
2. Deploy it to Agent Engine with a few lines of the Agent Platform SDK.
3. Call the deployed agent over the network, using managed sessions for multi-turn state.
4. Inspect the session and watch the agent in the console.
5. Tear it down so it stops billing.

By the end you'll understand the hosted execution model — what you hand off to the platform, and what you give up — and you'll have the deploy target that the rest of the series plugs into.

Why this matters (the 5-minute business case)

Read this before handing the lab to your team.

Writing an agent is the easy 20%. Operating it is the other 80%. A working agent on a developer's laptop is a demo. Turning it into something the business can rely on means a server that's always up, scales with traffic, holds conversation state, streams responses, and can be monitored and rolled back. Agent Engine is Google running that 80% for you.

Three reasons this is a leadership-level concern:

1. No infrastructure to operate. Without a managed runtime, shipping an agent means provisioning compute, wiring autoscaling, managing a session store, and owning the on-call for all of it. Agent Engine removes that operational surface — you deploy the agent and call an endpoint. For a team without a platform group, that's the difference between "we shipped" and "we're still building plumbing."
2. Managed sessions and scale come built in. The runtime handles concurrency, autoscaling, and conversation state as a service. The in-memory session you used in development (and the stub in ADK Lab 2) becomes a managed backend you don't run — the production answer to a problem every agent eventually hits.
3. It's the foundation the rest of the platform assumes. Grounding, memory, evaluation, safety, identity, and observability (Labs 3–10) all attach to a deployed agent. Lab 2 is the hinge: once an agent runs on Agent Engine, the managed capabilities become available to it.

The honest caveats:

• It bills while it exists, not just while it's used. A deployed reasoning engine is a live resource. Track it, and delete what you're not using (Lab 10 covers cost and observability properly). This lab's cleanup step is mandatory for a reason.
• Managed means less control. You trade the knobs of running your own container for the convenience of not running it. For most teams that's a good trade — but if you have hard requirements about the execution environment, weigh it against the self-operated path from ADK Lab 5.
• The SDK is young and moving. Method names and the session API have shifted across versions. Pin the version, and treat the exact call signatures here as current-as-of-authoring, not eternal.

A framing for a non-technical stakeholder: "Agent Engine is a managed home for our agents to run in — Google keeps it up, scales it, and remembers conversations, so our team ships the agent instead of operating a service. We pay for it while it's deployed, so we delete what we're not using."

Concepts you'll use (2-minute primer)

• Agent Engine — the managed runtime for agents (the resource type is reasoningEngines under the hood). You deploy an agent to it and get a callable, hosted instance.
• The Agent Platform SDK — the Python vertexai client you use to deploy and call agents. You'll create a vertexai.Client(...) and use client.agent_engines.
• The agent — for this lab, an ordinary ADK agent (model + instruction + tools), exactly like ADK Lab 1. Agent Engine is the target; ADK is how the agent is written.
• Sessions — managed conversation state. You create a session for a user, then send messages against it; the runtime keeps the history. (Lab 5 goes deep on sessions and long-term Memory Bank.)
• A staging bucket — deployment packages your code and dependencies; the SDK stages that in a Cloud Storage bucket in your project.

One sentence: you write an ADK agent, hand it to `client.agent_engines.create()`, and get back a hosted agent you call with managed sessions.

Prerequisites

We standardize on `us-central1` and a current Gemini model across this series; adjust to your org's defaults.

Step 1 — Set up the SDK and auth

python -m venv .venv && source .venv/bin/activate
pip install "google-cloud-aiplatform[agent_engines,adk]"
gcloud auth application-default login

Initialize the client (used by every step that follows):

import vertexai

PROJECT_ID = "your-project-id"
LOCATION = "us-central1"
STAGING_BUCKET = "gs://your-staging-bucket"  # used when deploying

client = vertexai.Client(project=PROJECT_ID, location=LOCATION)

Step 2 — Bring an ADK agent (agent.py)

This is the same shape as ADK Lab 1: a model, an instruction, and one read-only tool. The tool is a stub for the lab — Lab 4 wires real systems.

# agent.py
from google.adk.agents import Agent


def get_order_status(order_id: str) -> dict:
    """Look up the status of an Acme order by its ID.

    Args:
        order_id: The customer's order identifier, e.g. "AC-10231".

    Returns:
        A dict with the order's status, total, and estimated delivery date.
    """
    # Stub for the lab. Lab 4 replaces this with a real connector/API call.
    return {
        "order_id": order_id,
        "status": "shipped",
        "total_usd": 79.90,
        "eta": "2026-07-02",
    }


root_agent = Agent(
    name="acme_orders_assistant",
    model="gemini-3.5-flash",  # or your org's current default Gemini model
    instruction=(
        "You are the Acme Orders assistant. You help customers check the "
        "status, total, and delivery date of their orders. Always ask for an "
        "order ID if the customer hasn't provided one. Be concise and "
        "friendly. If you don't have the information, say so plainly — never "
        "guess an order's status."
    ),
    tools=[get_order_status],
)

Step 3 — Test locally before you deploy

Always confirm the agent works on your machine before paying to host it. Wrap it in an AdkApp and query it locally:

# local_test.py
from vertexai.preview import reasoning_engines
from agent import root_agent

app = reasoning_engines.AdkApp(agent=root_agent, enable_tracing=True)

session = app.create_session(user_id="u_123")
for event in app.stream_query(
    user_id="u_123",
    session_id=session.id,
    message="Where is order AC-10231?",
):
    print(event)

You should see the agent call get_order_status and answer from the result. If it asks for an order ID when you omit one, your instruction is doing its job.

Step 4 — Deploy to Agent Engine

Now hand the agent to the managed runtime. Deployment packages your code plus the dependencies you declare, stages it, and creates a hosted reasoningEngines resource:

# deploy.py
import vertexai
from agent import root_agent

client = vertexai.Client(project="your-project-id", location="us-central1")

remote_app = client.agent_engines.create(
    agent=root_agent,
    config={
        "display_name": "Acme Orders assistant",
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
        "staging_bucket": "gs://your-staging-bucket",
    },
)

# The resource name is your handle to the deployed agent — save it.
print(remote_app.api_resource.name)
# -> projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/RESOURCE_ID

Deployment takes a few minutes (it builds and provisions the runtime). When it returns, your agent is live.

Confirm the operations your SDK version exposes. Method names around querying and sessions have changed across releases. Run remote_app.operation_schemas() to list the exact operations available on your deployed agent, and pin your SDK version so a later upgrade doesn't silently change them.

Step 5 — Call the deployed agent

Fetch the deployed agent by its resource name (from any machine with access), create a managed session, and stream a query:

# query.py
import vertexai

client = vertexai.Client(project="your-project-id", location="us-central1")

remote_app = client.agent_engines.get(
    name="projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/RESOURCE_ID"
)

session = remote_app.create_session(user_id="u_123")
for event in remote_app.stream_query(
    user_id="u_123",
    session_id=session["id"],  # session shape varies by SDK version
    message="What's the status of order AC-10231?",
):
    print(event)

The same agent now answers over the network, and the runtime is keeping the session state — send a follow-up against the same session_id and it remembers the order in context. That managed continuity is exactly what you'd otherwise have to build and run yourself.

Some SDK versions expose async variants (async_create_session, async_stream_query) and return a session object (session.id) rather than a dict (session["id"]). If the snippet above doesn't match, check operation_schemas() and the docs for your pinned version.

Step 6 — Inspect the session and monitor in the console

1. In the Google Cloud console, open the Agent Engine section of the Gemini Enterprise Agent Platform and find your deployed agent by its display name.
2. Look at its sessions and recent activity — you should see the session you created and the turns you sent.
3. Note the monitoring surface (requests, latency, errors). This is the front door to Lab 10's deeper observability and tracing.

This console view is how a team watches a deployed agent in production without touching code.

Cost & cleanup

A deployed Agent Engine instance bills until you delete it. Do this when you're done:

# cleanup.py
import vertexai

client = vertexai.Client(project="your-project-id", location="us-central1")
remote_app = client.agent_engines.get(
    name="projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/RESOURCE_ID"
)
remote_app.delete(force=True)  # force=True also removes child sessions

Then confirm in Billing → Reports that nothing is still accruing, and remove the staging bucket if you created it only for this lab. The series rule stands: if a lab created it and you're done, delete it today.

Verified against

• Agent Engine deployment docs and the `google-cloud-aiplatform[agent_engines,adk]` SDK, June 2026.
• The deploy/query/session method names and the session return shape differ across SDK versions. The code here is syntax-checked against the docs but not executed during authoring — pin your version, run it yourself, and verify with operation_schemas().

What's next

You now have a real agent running on the managed runtime — the deploy target the rest of the series builds on.

• Lab 3 — Grounding with Vertex AI Search & RAG Engine: make the deployed agent answer from your documents, with citations.
• Compare with ADK Lab 5 (deploy): there you ran the agent in a container you operate; here Google operates it. Reading them side by side is the clearest way to feel the managed-vs-self-hosted trade-off — and to decide which fits a given workload.