OpenAPI Tools

Integrate REST APIs documented with OpenAPI specifications into your ADK agents. You can use the built-in HttpRequestTool for general API access or create type-safe custom tools with generated TypeScript types.

ADK-TS does not include automatic tool generation from OpenAPI specs. Use HttpRequestTool for quick integration or create custom typed tools for better type safety and control.

Two Approaches

Approach	Type Safety	Setup Time	Best For
`HttpRequestTool`	None	Instant	Quick prototypes, dynamic APIs, general HTTP requests
Custom Typed Tools	Full	Medium	Production apps, complex APIs, IDE autocomplete

Quick Integration: Use HttpRequestTool

For simple API access, use the built-in HttpRequestTool:

import { HttpRequestTool, AgentBuilder } from "@iqai/adk";

const { runner } = await AgentBuilder.create("api-agent")
  .withModel("gemini-2.5-flash")
  .withTools(new HttpRequestTool())
  .withInstruction(
    `
    You can make HTTP requests using http_request tool.
    Include authentication headers and handle responses appropriately.
  `
  )
  .build();

// Agent can now call any API by constructing requests
await runner.ask(
  "Get the current weather for London from api.openweathermap.org"
);

Type-Safe Integration: Generate TypeScript Types

For better type safety and IDE support, generate types from your OpenAPI spec and create custom tools:

Step 1: Generate Types

Install and run openapi-typescript against your OpenAPI spec:

# Install the package
pnpm add -D openapi-typescript

# From a local file
pnpx openapi-typescript ./your-api-spec.json -o ./api-types.ts

# From a URL
pnpx openapi-typescript https://your-api.com/openapi.json -o ./api-types.ts

Step 2: Create Custom Typed Tools

Option A: With Native Fetch

Use the generated types for full type safety with standard fetch:

import { BaseTool } from "@iqai/adk";
import type { paths } from "./api-types";

class UserApiTool extends BaseTool {
  constructor(private baseUrl: string, private apiKey: string) {
    super({
      name: "user_api",
      description: "Manage users via API",
    });
  }

  async runAsync(args: { userId: string }) {
    // Extract types from your OpenAPI spec
    type GetUserResponse =
      paths["/users/{userId}"]["get"]["responses"]["200"]["content"]["application/json"];

    const response = await fetch(`${this.baseUrl}/users/${args.userId}`, {
      headers: { Authorization: `Bearer ${this.apiKey}` },
    });

    // Response is fully typed
    const data: GetUserResponse = await response.json();
    return { success: true, user: data };
  }
}

Option B: With openapi-fetch (Recommended)

For cleaner code and built-in error handling:

Install openapi-fetch:

pnpm add openapi-fetch

Create the tool:

import { BaseTool } from "@iqai/adk";
import createClient from "openapi-fetch";
import type { paths } from "./api-types";

class UserApiTool extends BaseTool {
  private client: ReturnType<typeof createClient<paths>>;

  constructor(baseUrl: string, apiKey: string) {
    super({
      name: "user_api",
      description: "Manage users via API",
    });

    this.client = createClient<paths>({
      baseUrl,
      headers: { Authorization: `Bearer ${apiKey}` },
    });
  }

  async runAsync(args: { userId: string }) {
    // Fully typed request and response with automatic path substitution
    const { data, error } = await this.client.GET("/users/{userId}", {
      params: { path: { userId: args.userId } },
    });

    if (error) return { success: false, error };
    return { success: true, user: data };
  }
}

Using Schema Components

Extract reusable types from your OpenAPI spec:

import type { paths, components } from "./api-types";

// Use schema definitions
type User = components["schemas"]["User"];
type CreateUserRequest = components["schemas"]["CreateUserRequest"];

// Use path types
type GetUserResponse =
  paths["/users/{userId}"]["get"]["responses"]["200"]["content"]["application/json"];

When to Use Each Approach

Approach	Best For
`HttpRequestTool`	Quick prototypes, agents that need general API access, simple integrations
Custom Typed Tools	Production apps, type safety requirements, complex APIs with many endpoints

Best Practices

Use HttpRequestTool for quick prototypes and general API access
Create custom tools when you need type safety and specific API operations
Regenerate types when your OpenAPI spec changes
Handle errors appropriately in your tool implementations
Store API keys securely using environment variables

🔧 Function Tools

Create custom tools for API operations

🌐 Built-in Tools

Explore other built-in tool capabilities

🔐 Authentication

Secure API access and credential management

🤖 Agents

Learn how agents use tools

OpenAPI Tools

🔧 Function Tools

🌐 Built-in Tools

🔐 Authentication

🤖 Agents

On this page