Gemini AI Agent with MCP: Use Google Models in Promptise

Create an API key in Google AI Studio, put it in GOOGLE_API_KEY (or GEMINI_API_KEY), and pass "gemini:gemini-3.8-flash" or Model("gemini-3.8-flash", provider="gemini") to build_agent(). Promptise reaches Gemini through Google's OpenAI-compatible endpoint with langchain-openai, which is part of the core install, so there is nothing else to install. Add your MCP servers in servers=. The agent sends their tools to Gemini as function declarations, runs the calls Gemini makes and loops until it answers.

• Two ways in. provider="gemini" uses an AI Studio API key. provider="vertex" uses Vertex AI with a Google Cloud project and Application Default Credentials.

• Use current model ids. Google retires models regularly. Check the models page before you pin one.

• Control reasoning with `reasoning_effort`. Gemini 3 models always reason, and the effort level sets how much.

• The free tier trains on your content. Google's pricing page says free-tier content is used to improve its products and paid-tier content isn't.

• Check before you call. promptise models check gemini:<model> shows the route and what is missing.

You need Python 3.10 or later, Promptise Foundry 1.4.2 or later, and an API key from Google AI Studio.

pip install "promptise>=1.4.2"

Put the key in a .env file next to your script. Promptise loads the nearest .env file automatically, and a variable already exported in your shell wins. It reads GOOGLE_API_KEY first and accepts GEMINI_API_KEY as an alias:

# Google Gemini (AI Studio API key) — model string example: gemini:gemini-2.5-pro
export GOOGLE_API_KEY=AIza...
#   ↳ aistudio.google.com → Get API key

Then check the configuration. With the key set (here as GEMINI_API_KEY), the check reports the endpoint and stops before calling anything:

$ promptise models check gemini:gemini-3.8-flash
gemini:gemini-3.8-flash → google_genai:gemini-3.8-flash  (Google Gemini (AI Studio API key))
  model part: gemini-3.8-flash — the model name
  route: OpenAI-compatible endpoint https://generativelanguage.googleapis.com/v1beta/openai/ (core, nothing to install)
  GOOGLE_API_KEY: set — aistudio.google.com → Get API key
  For Gemini through Google Cloud (no API key, ADC) use provider='vertex'.
Configuration OK — every required setting is in place; nothing was called. Add --ping to make a real one-token call to the model.

"Configuration OK" means the key is set, not that it works. --ping makes one real call. This is the real output with a key that isn't valid:

$ promptise models check gemini:gemini-3.8-flash --ping
Configuration OK.
Pinging… failed
OpenAIInvalidRequestError: Error code: 400 - [{'error': {'code': 400, 'message': 'Please pass a valid API key', 'status': 'INVALID_ARGUMENT'}}]

Which model id to use

Copy ids from Google's models page. At the time of writing, Google recommends these for new projects:

Older ids such as gemini-2.5-pro still appear in many tutorials, including Promptise's own provider table, but Google now lists the 2.5 models with limited access. Preview models (ids ending in -preview) can change or disappear with little notice, so avoid them for production agents. To compare Gemini with other providers on your own tool calls, see the best LLM for AI agents.

The agent answers questions about a shop's products. The model is configured once at the top of the file:

import asyncio
import sys

from promptise import Model, build_agent
from promptise.config import StdioServerSpec

# The key comes from GOOGLE_API_KEY or GEMINI_API_KEY (environment or .env).
GEMINI = Model("gemini-3.8-flash", provider="gemini")


async def make_agent(model=GEMINI):
    return await build_agent(
        model=model,
        servers={"shop": StdioServerSpec(command=sys.executable, args=["shop_server.py"])},
        instructions="You answer questions about the shop's products. "
                     "Use the tools for stock and prices. Never guess them.",
        max_agent_iterations=10,
    )


async def main():
    agent = await make_agent()
    try:
        result = await agent.ainvoke(
            {"messages": [{"role": "user", "content": "Is KB-101 in stock, and what does it cost?"}]}
        )
        calls = [c["name"] for m in result["messages"] for c in getattr(m, "tool_calls", None) or []]
        print("tool calls:", ", ".join(calls) or "none")
        print(result["messages"][-1].text)
    finally:
        await agent.shutdown()


if __name__ == "__main__":
    asyncio.run(main())

What each part does:

• `Model("gemini-3.8-flash", provider="gemini")` names the model and the provider. gemini, google and google_genai all select the same provider. The key comes from the environment. Pass api_key= instead when it comes from a secret store.

• `max_agent_iterations=10` stops a run that keeps calling tools without finishing.

• `result["messages"][-1].text` reads the answer text.

Run it with python gemini_agent.py. With a valid key, the script prints the tools Gemini called and then its answer. With a key that isn't valid, the run fails with the same Please pass a valid API key error as the ping above, raised as a GraphExecutionError from the agent's reasoning step.

The tools come from a small MCP server that the agent starts over stdio:

"""A small MCP tool server: product stock and prices for a shop."""
from promptise.mcp.server import MCPServer

server = MCPServer("shop")

STOCK = {"KB-101": 14, "MS-220": 0, "HD-350": 3}
PRICES = {"KB-101": 89.00, "MS-220": 39.50, "HD-350": 129.00}


@server.tool()
async def check_stock(sku: str) -> dict:
    """How many units of a product (by SKU) are in stock."""
    if sku not in STOCK:
        return {"sku": sku, "error": "unknown SKU"}
    return {"sku": sku, "in_stock": STOCK[sku]}


@server.tool()
async def get_price(sku: str) -> dict:
    """The current price of a product (by SKU), in USD."""
    if sku not in PRICES:
        return {"sku": sku, "error": "unknown SKU"}
    return {"sku": sku, "price_usd": PRICES[sku]}


if __name__ == "__main__":
    server.run()  # stdio by default

your code ──▶ Promptise agent ──HTTPS──▶ generativelanguage.googleapis.com/v1beta/openai/
                  │     ▲                     │  (Gemini)
                  │     └── tool_calls ◀──────┘
                  ▼
           MCP client ──stdio──▶ shop_server.py ──▶ tool result ──▶ next Gemini call

Promptise is the MCP client. When the agent is built, it connects to each server in servers=, lists the tools and converts their input schemas into function definitions in the OpenAI format, which Google's compatible endpoint accepts. When Gemini returns a tool call, Promptise runs it against the MCP server and calls Gemini again with the result. Promptise binds tools with automatic tool choice, so Gemini decides when a tool is needed.

Gemini never connects to your MCP server, so the server can stay on your machine or a private network. For a remote server, use HTTPServerSpec(url=..., bearer_token=...) from promptise.config. The MCP connection guide covers transports and authentication.

Reasoning effort

Gemini 3 models reason before they answer, and you can't turn that off. You can set how much with reasoning_effort, which the compatibility endpoint accepts as minimal, low, medium or high:

GEMINI = Model("gemini-3.8-flash", provider="gemini", extra={"reasoning_effort": "low"})

Lower effort means fewer reasoning tokens, lower cost and faster replies. That suits lookups like the example. Raise it for agents that plan across several tools. Google's thinking guide explains how effort maps onto Gemini's own thinking settings.

The OpenAI-compatible route and the native route

The default route uses Google's OpenAI compatibility layer, which supports tool calling, streaming and structured output. Google labels it beta and says feature support is still expanding. Gemini features that the OpenAI format can't express need Google's own client. Promptise reaches it with native=True once you install langchain-google-genai:

GEMINI = Model("gemini-3.8-flash", provider="gemini", native=True)

Start with the default route. Move to native=True only when you need a feature it doesn't expose, and test the agent again after the switch.

Gemini on Vertex AI

On Google Cloud, use the vertex provider. It needs your project id and, optionally, a region. Authentication uses an OAuth access token instead of an API key:

GEMINI = Model("gemini-3.8-flash", provider="vertex", project="my-project-123", region="us-central1")

Install google-auth and run gcloud auth application-default login (or use the service account of the machine). Promptise then gets a token for you and refreshes it before it expires, so a long-running agent keeps working. A token set by hand in GOOGLE_OAUTH_ACCESS_TOKEN or api_key= expires after about an hour, which is fine for one-off runs only. A bare Gemini name is prefixed with google/ for Vertex's endpoint. Check that the model you want is available in your region on Vertex before you deploy.

Pricing, limits and data use

Prices per million tokens are on Google's pricing page, and request and token limits per tier are on the rate limits page. An agent makes several model calls per question, so it reaches per-minute limits faster than a chat app. The pricing page also says content sent on the free tier is used to improve Google's products and content on the paid tier isn't. Don't send customer data through a free-tier key. Put a budget on the agent before it handles real traffic.

Do I need the Google Gen AI SDK to build a Gemini agent with Promptise?

No. Promptise reaches Gemini through Google's OpenAI-compatible endpoint with langchain-openai, which is installed with Promptise. You only need Google's own LangChain integration, langchain-google-genai, if you opt into the native route with native=True for a feature the compatible endpoint doesn't expose.

Can Gemini call MCP tools?

Yes. Promptise is the MCP client: it reads the tools from your MCP servers and sends them to Gemini as function definitions. Gemini returns a function call, Promptise runs it against the MCP server and sends back the result. Gemini never connects to the MCP server itself, so private and local servers work.

Should I use the Gemini API or Vertex AI for an agent?

Use the Gemini API with an AI Studio key to get started and for projects outside Google Cloud. Use Vertex AI when your organization runs on Google Cloud and needs its identity and access controls, billing or regional data handling. In Promptise, the switch is the provider: gemini or vertex. The rest of the agent stays the same.

Which Gemini model is best for an AI agent?

Start with gemini-3.8-flash, which Google recommends for new projects and which supports tool calling and reasoning. Use gemini-3.5-flash-lite for simple steps where cost matters most. Test both on your own questions and tools, because the right choice depends on how hard the agent's tasks are.

Is my data used for training when I use the Gemini API?

According to Google's pricing page, content sent on the free tier is used to improve Google's products, and content on the paid tier isn't. Check the current terms for your account before you send customer or confidential data, and use a paid-tier key or Vertex AI for production.

• Build the full agent step by step: how to build an AI agent.

• Compare Gemini with other models: best LLM for AI agents.

• Use the long context well: context engineering for AI agents.

• Write the tool side: build a production MCP server.

• Trace every model and tool call: AI agent observability.

• Every provider setting: Models and providers reference.