11. OpenAPI Tools with Authentication

This blog is part of the ADK Masterclass - Hands-On Series. Manually writing tool functions for a large API with dozens of endpoints is tedious and error-prone. Fortunately, ADK provides a better way.

If our target API has an OpenAPI Specification (Swagger), ADK can automatically ingest it and generate tools for every endpoint, complete with input validation and documentation.

1. What are OpenAPI Tools?

OpenAPI Tools allow us to instantly create agent tools from existing API documentation. The OpenAPIToolset class parses an OpenAPI specification (JSON or YAML) and generates a RestApiTool for each operation defined in the spec.

This means we don't need to write manual wrapper functions for every API endpoint. The agent automatically understands the API's capabilities, parameters, and response formats.

2. Architecture

3. Tutorial: Building a GitHub Agent

In this tutorial, we'll build an agent that can interact with your GitHub repositories using natural language. We'll use the official GitHub OpenAPI specification to power our agent.

Prerequisites

• Python 3.11 or higher.
• A GitHub Personal Access Token (Classic or Fine-grained).
• Google ADK installed (pip install google-adk).

Step 1: Create the Project

Create a new directory for our project and set up the environment:

adk create github_agent
cd github_agent
cp .env.example .env

Edit .env to include your keys:

GOOGLE_API_KEY=your_gemini_key
GITHUB_TOKEN=your_github_token

Step 2: Get the OpenAPI Spec

Download the GitHub REST API specification. We'll use a fixed version for stability.

curl -o api.github.com.fixed.json https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json

Step 3: Define the Agent

Open agent.py and replace its content with the following code. This script loads the OpenAPI spec, configures authentication using your GitHub token, and initializes the agent.

import os
import json
import logging
from google.adk.agents import Agent
from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset
from google.adk.tools.openapi_tool.auth.auth_helpers import token_to_scheme_credential

# Configure logging
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
logger = logging.getLogger("github_agent")

def create_github_agent():
    # 1. Load Configuration
    token = os.getenv("GITHUB_TOKEN")
    api_spec_path = os.path.join(os.path.dirname(__file__), "api.github.com.fixed.json")
    
    if not token:
        logger.error("GITHUB_TOKEN missing from environment.")
        return None

    # 2. Load OpenAPI Spec
    try:
        with open(api_spec_path, "r") as f:
            spec = json.load(f)
    except FileNotFoundError:
        logger.error(f"Spec file not found: {api_spec_path}")
        return None

    # 3. Configure Authentication
    # GitHub uses "Authorization: token " header format
    auth_scheme, auth_credential = token_to_scheme_credential(
        "apikey", "header", "Authorization", f"token {token}"
    )

    # 4. Initialize Toolset
    toolset = OpenAPIToolset(
        spec_str=json.dumps(spec),
        spec_str_type="json",
        auth_scheme=auth_scheme,
        auth_credential=auth_credential
    )
    
    tools = toolset.get_tools()
    logger.info(f"Found {len(tools)} GitHub API tools")

    # 5. Create Agent
    return Agent(
        name="github_agent",
        description="GitHub API Agent",
        instruction="""
        You are a GitHub API agent. Use the provided tools to interact with GitHub.
        - When listing items, summarize the key details.
        - If a user asks to create a repo or issue, confirm the details first.
        - Use parameters exactly as specified by the user.
        """,
        model="gemini-2.5-pro-preview-03-25",
        tools=tools
    )

# Initialize the agent
root_agent = create_github_agent()

Step 4: Run the Agent

Start the agent using the ADK web interface:

adk web

4. Usage Examples

Once our agent is running, try these natural language commands:

• "List my recent repositories."
• "Create a new private repository named 'adk-test-project'."
• "What are the open issues in the 'google/adk' repository?"
• "Create an issue in 'my-repo' titled 'Bug Report' with body 'Something is broken'."

Next Steps

Now that we've mastered single-domain agents, let's combine them into a versatile multi-functional assistant:

• 12. Multi-Tool Agents: Build an agent that can switch between search, code execution, and external APIs seamlessly.
• 13. Third Party Tools: Explore pre-built integrations for popular services.

Resources

• Official ADK OpenAPI Tools Documentation
• GitHub Agent Repository (Example Code)