3. Connecting to the Game API

Now that your agent is running, it's time to give it the ability to interact with the game. In this section, you'll provide your agent with tools to call the game's API and give it instructions on how to behave.

Give Your Agent Tools

ADK provides a way to give agents the ability to do things (such as calling APIs) through tools. For APIs that have an OpenAPI specification (such as our Game API), you can use the OpenAPIToolset to automatically create a whole set of tools for your agent, that correspond to the API endpoints.

Replace the code in agent.py with the following listing to connect it to the game's API. This code fetches the OpenAPI spec, creates a toolset from it, and initializes an agent with those tools.

import os
import requests
from google.adk.agents.llm_agent import Agent
from google.adk.tools.openapi_tool import OpenAPIToolset
from google.adk.tools.openapi_tool.auth.auth_helpers import token_to_scheme_credential

openapi_spec = requests.get("https://adventure.wietsevenema.eu/openapi.json").text


auth_scheme, auth_credential = token_to_scheme_credential(
    "apikey",
    "header",
    "Authorization",
    f"ApiKey {os.environ.get('ADK_API_KEY')}",
)

adventure_game_toolset = OpenAPIToolset(
    spec_str=openapi_spec,
    auth_scheme=auth_scheme,
    auth_credential=auth_credential,
)


root_agent = Agent(
    model="gemini-2.5-flash",
    name="root_agent",
    description="An expert adventure game player.",
    instruction=(
        "You are a narrator in a text adventure game that operates in a strict turn-by-turn format.\n\n"
        "On your turn, you take the player's request, translate it into a single tool call, execute it, and describe the outcome. "
        "**Do not, under any circumstances, plan or execute more than one action.** After your turn, you must stop and wait for the player's next command. The player is always in the lead.\n\n"
        "**If the player asks for help or suggestions (e.g., 'What should I do now?'), do not take any action with your tools.** "
        "Instead, analyze the current situation and suggest a few possible actions the player could take. It is the player's job to decide on the next step.\n\n"
        "**If the player's command is ambiguous and doesn't directly map to an available tool, do not infer their intent.** "
        "Instead, suggest concrete actions based on the tools in their inventory and the objects in the room."
    ),
    tools=[adventure_game_toolset],
)

Breaking Down the Code

Let's take a closer look at the key parts of this code listing:

Downloading the API Specification

First, the code fetches the OpenAPI specification from the game's server. This file describes all the available API endpoints, their parameters, and what they return. The OpenAPIToolset uses this to automatically create tools for the agent.
```
openapi_spec = requests.get("https://adventure.wietsevenema.eu/openapi.json").text
```
Setting up Authentication
- The game API requires an API key to be sent with each request. The token_to_scheme_credential function is a helper that creates and returns a tuple containing an AuthScheme and an AuthCredential object. These objects are then passed to the OpenAPIToolset to configure authentication for the tools it generates.
- The API key is pulled from the environment variable ADK_API_KEY. I'll show you how to add it later.
```
auth_scheme, auth_credential = token_to_scheme_credential(
    "apikey",
    "header",
    "Authorization",
    f"ApiKey {os.environ.get('ADK_API_KEY')}",
)

adventure_game_toolset = OpenAPIToolset(
    spec_str=openapi_spec,
    auth_scheme=auth_scheme,
    auth_credential=auth_credential,
)
```
Configuring the Agent

Finally, the agent itself is created. There are two important parts here:
- The instruction tells the agent its purpose and how it should behave. In this case, it's told to act as a turn-by-turn operator for a text adventure game.
- The tools list is given the adventure_game_toolset you created. This gives the agent the ability to call all the game's API endpoints.
```
root_agent = Agent(
    ...
    instruction=("..."),
    tools=[adventure_game_toolset],
)
```

How Instructions Determine Agent Behavior

The instructions you provide to an agent are crucial for shaping its behavior. A well-crafted set of instructions guides the agent to use its tools in the way you intend, leading to more reliable and predictable outcomes. In this case, the instructions tell the agent to act as a simple operator, translating the player's commands into single API calls. This prevents the agent from acting on its own, which is a behavior you'll encourage in the next section.

Set Your Game API Key

Your agent needs an API key to interact with the game. The OpenAPIToolset is configured to read this key from a .env file in your agent's directory (find it right next to agent.py)

Create or open the .env file (right next to agent.py) and add the following line:

ADK_API_KEY=[YOUR-API-KEY]

You can find your API key on the Game API page.

A note for Cloud Shell users

If you can't find the .env file, it might be hidden. You can reveal it by going to View > Toggle Hidden Files in the Cloud Shell editor.

Play Level 1 with the Agent

With your agent configured, it's time to play the game through ADK's interface.

Restart the Development Web UI: To make it pick up the environment variable you added to .env
Interact with the Agent: In the chat interface, you can now give commands to your agent in natural language.
- "look around"
- "go north"
- "examine the pedestal"
Guide the Agent: Your agent translates your commands into the appropriate API calls. Guide it through the level and solve the puzzles to reach the end.

At this stage, the agent is acting as turn-by-turn operator. In the next section, you'll give it the ability to act on its own by creating an autonomous explorer.