@makaio/ai-adapters-gemini-sdk

Google Gemini SDK adapter for the Makaio AI framework.

Quick Start

import { createGeminiSDKAdapter, GeminiAdapter } from '@makaio/ai-adapters-gemini-sdk';
import { MakaioBus } from '@makaio/bus-core';
import { AdapterSubjects } from '@makaio/contracts';

// Using the factory function (recommended)
const adapter = await createGeminiSDKAdapter();

const result = await MakaioBus.request(AdapterSubjects.startAgent, {
  adapterId: adapter.adapterId,
  role: 'lead',
  initialMessage: 'Inspect this repository',
});

// Or using the class directly
const directAdapter = new GeminiAdapter();
await directAdapter.init();

Architecture

This adapter follows the three-layer architecture pattern:

GeminiAdapter extends AIAdapter
    -> creates via agentFactory()
GeminiAgent extends AIAgent
    -> receives connector via connectorFactory()
GeminiConnector extends AIAgentConnector

Layers:

Layer	Class	Responsibility
Adapter	`GeminiAdapter`	Factory for agents, handles `adapter.startAgent` RPC
Agent	`GeminiAgent`	Wires events to global bus, manages lifecycle
Connector	`GeminiConnector`	SDK-level bridge to Google Gemini

Session/Turn Management:

Class	Purpose
`GeminiConnectorSession`	Session lifecycle, prompt cache preservation
`GeminiConnectorTurn`	Individual turn handling
`UserMessageQueue`	Internal connector queue from adapter core

Capabilities

tools - Tool/function calling support
streaming - Streaming responses
systemPrompt:override - Replace/set the system prompt
systemPrompt:append - Append to the adapter’s default system prompt
Tool approval workflow via registerToolApprovalHandler
Replace and interrupt delivery modes

Exports

Adapter

Export	Description
`GeminiAdapter`	Main adapter class
`createGeminiSDKAdapter`	Factory function (creates and initializes)
`GeminiSdkAdapterName`	Adapter identifier constant

Agent & Connector

Export	Description
`GeminiAgent`	Agent class (middle layer)
`GeminiConnector`	Connector class (SDK bridge)
`GeminiAgentLegacy`	Legacy alias for GeminiConnector

Session Management

Export	Description
`GeminiConnectorSession`	Session abstraction
`GeminiConnectorTurn`	Turn abstraction
`UserMessageQueue`	Internal connector queue from adapter core

Namespaces & Types

Export	Description
`GeminiConnectorNamespace`	Bus namespace for connector events
`GeminiConnectorSubjects`	Subject constants for bus messaging
`GeminiAgentMetadata`	Agent metadata type
`GeminiConnectorConfig`	Connector configuration type
`GeminiAgentConnectorConfig`	Agent connector config type
`GeminiSessionConfig`	Session configuration type

Tool Handling

Export	Description
`registerToolApprovalHandler`	Register handler for tool approval requests
`requestToolApproval`	Request tool approval
`toGlobalToolApproval`	Convert to global approval format
`fromGlobalToolApproval`	Convert from global approval format

Configuration & Schemas

Export	Description
`GeminiSdkProviderConfigSchema`	Zod schema for provider config

Prerequisites and Authentication

Install the peer SDK packages provided by the framework workspace or your package manager. Runtime sessions require Google Gemini credentials. The adapter supports:

API-key auth via the canonical Google provider credential, mapped to GEMINI_API_KEY.
OAuth auth via the google-oauth provider path used by the Gemini CLI core.

If an API-key credential ref is configured, the adapter uses API-key auth and fails fast when the resolved key is empty. OAuth fallback is used only when no API-key credential is supplied.

File Structure

src/
├── index.ts              # Package exports
├── adapter.ts            # GeminiAdapter class
├── agent.ts              # GeminiAgent class
├── connector.ts          # GeminiConnector class
├── session.ts            # Session management
├── turn.ts               # Turn management
├── config.ts             # Configuration utilities
├── constants.ts          # Adapter constants
├── definition.ts         # Internal adapter definition
├── models.ts             # Model catalog
├── package.ts            # MakaioExtension package descriptor
├── provider.ts           # Provider registration
├── provider.fetcher.ts   # Model fetcher
├── rate-limiter.ts       # Rate limiting
├── server.ts             # Server entrypoint exporting the package descriptor
├── schemas.ts            # Zod schemas
├── tool-handling.ts      # Tool approval utilities
├── namespaces/           # Bus namespace definitions
├── types/                # TypeScript types
└── utils/                # Utility functions

Part of the Makaio AI framework