Kagenti ADK Client SDK

TypeScript/JavaScript client SDK for building applications that interact with Kagenti ADK agents.

Overview

The @kagenti/adk provides TypeScript and JavaScript tools for building client applications that communicate with agents deployed on Kagenti ADK. It includes utilities for handling the A2A (Agent2Agent) protocol, working with extensions, and calling the Kagenti ADK platform API.

Key Features

• A2A Protocol Support - Parse agent cards and task status updates with typed utilities
• Extension System - Resolve service demands and UI metadata with typed helpers
• Platform API Client - Typed access to core platform resources
• Type Safe Responses - Zod validated payloads with structured API error helpers

Installation

npm install @kagenti/adk @a2a-js/sdk

Quickstart

import {
  buildApiClient,
  createAuthenticatedFetch,
  unwrapResult,
  getAgentCardPath,
  handleAgentCard,
  handleTaskStatusUpdate,
  resolveUserMetadata,
  type TaskStatusUpdateType,
  type Fulfillments,
} from '@kagenti/adk';
import {
  ClientFactory,
  ClientFactoryOptions,
  DefaultAgentCardResolver,
  JsonRpcTransportFactory,
} from '@a2a-js/sdk/client';

const baseUrl = 'https://your-adk-instance.com'; // or http://localhost:8333 for local development
const accessToken = '<user-access-token>';

const api = buildApiClient({
  baseUrl,
  fetch: createAuthenticatedFetch(accessToken),
});

const providers = unwrapResult(await api.listProviders());
const providerId = providers[0]?.id;

const context = unwrapResult(await api.createContext({ provider_id: providerId }));
const contextToken = unwrapResult(
  await api.createContextToken({
    context_id: context.id,
    grant_global_permissions: {
      llm: ['*'],
      embeddings: ['*'],
      a2a_proxy: ['*'],
    },
    grant_context_permissions: {
      files: ['*'],
      vector_stores: ['*'],
      context_data: ['*'],
    },
  }),
);

const fetchImpl = createAuthenticatedFetch(contextToken.token);
const factory = new ClientFactory(
  ClientFactoryOptions.createFrom(ClientFactoryOptions.default, {
    transports: [new JsonRpcTransportFactory({ fetchImpl })],
    cardResolver: new DefaultAgentCardResolver({ fetchImpl }),
  }),
);

const agentCardPath = getAgentCardPath(providerId);
const client = await factory.createFromUrl(baseUrl, agentCardPath);

const card = await client.getAgentCard();
const { resolveMetadata, demands } = handleAgentCard(card);

const selectedLlmModels: Record<string, string> = { default: 'gpt-4o' };

const fulfillments: Fulfillments = {
  llm: demands.llmDemands
    ? async ({ llm_demands }) => ({
        llm_fulfillments: Object.fromEntries(
          Object.keys(llm_demands).map((key) => [
            key,
            {
              identifier: 'llm_proxy',
              api_base: `${baseUrl}/api/v1/openai/`,
              api_key: contextToken.token,
              api_model: selectedLlmModels[key],
            },
          ]),
        ),
      })
    : undefined,
};

const agentMetadata = await resolveMetadata(fulfillments);

const stream = client.sendMessageStream({
  message: {
    kind: 'message',
    role: 'user',
    messageId: crypto.randomUUID(),
    contextId: context.id,
    parts: [{ kind: 'text', text: 'Hello' }],
    metadata: agentMetadata,
  },
});

let taskId: string | undefined;

for await (const event of stream) {
  switch (event.kind) {
    case 'task':
      taskId = event.id;
    case 'status-update':
      taskId = event.taskId;

      for (const update of handleTaskStatusUpdate(event)) {
        switch (update.type) {
          case TaskStatusUpdateType.FormRequired:
          // Render form
          case TaskStatusUpdateType.OAuthRequired:
          // Redirect to update.url
          case TaskStatusUpdateType.SecretRequired:
          // Prompt for secrets
          case TaskStatusUpdateType.ApprovalRequired:
          // Request approval
          case TaskStatusUpdateType.TextInputRequired:
          // Prompt for text input
        }
      }
    case 'message':
    // Render message parts and metadata
    case 'artifact-update':
    // Render artifacts
  }
}

Core APIs

• buildApiClient returns a typed API client for platform endpoints.
• handleAgentCard extracts extension demands and returns resolveMetadata.
• handleTaskStatusUpdate parses A2A status updates into UI actions.
• resolveUserMetadata builds metadata when the user submits forms, canvas edits, or approvals.
• createAuthenticatedFetch helps add bearer auth headers to API calls.
• buildLLMExtensionFulfillmentResolver matches LLM providers and returns fulfillments.
• unwrapResult returns the response data on success, throws an ApiErrorException on error

Extensions

Service extensions (client fulfillments):

• Embedding - Provide embedding access (api_base, api_key, api_model) for RAG or search.
• Form - Request structured user input via forms.
• LLM - Resolve model access and credentials for text generation.
• MCP - Connect Model Context Protocol services and tools.
• OAuth - Provide OAuth credentials or redirect URIs.
• Platform API - Inject context token metadata for platform access.
• Secrets - Supply or request secret values securely.

UI extensions (message metadata your UI can render):

• Agent Detail - Show agent specific metadata and context.
• Approval - Ask the user to approve actions or tool calls.
• Canvas - Provide canvas edit requests and updates.
• Citation - Display inline source references.
• Error - Render structured error messages.
• Form Request - Render interactive forms in the UI.
• Settings - Read or update runtime configuration values.
• Trajectory - Render execution traces or reasoning steps.

Documentation

• Kagenti ADK Documentation
• Getting Started
• A2A Client Integration
• Agent Requirements
• Platform API Client

Resources

• GitHub Repository
• npm Package

Contributing

Contributions are welcome! Please see the Contributing Guide for details.

Support

• GitHub Issues
• GitHub Discussions

Developed by contributors to the Kagenti project, this initiative is part of the Linux Foundation AI & Data program. Its development follows open, collaborative, and community-driven practices.