@open-hive/sdk

The official TypeScript/JavaScript SDK for the OpenHive Platform. It provides a lightweight, powerful toolkit for developers to interact with the OpenHive agent registry.

This SDK is designed to complement any A2A (Agent-to-Agent) compliant agent. While you can use any A2A SDK (like @a2a-js/sdk) to build your agent's core logic, the OpenHive SDK provides the necessary tools for agent discovery and management within the OpenHive ecosystem.

✨ Core Features

• Simplified Registry: A robust OpenHive class for discovering and managing A2A-compliant agents.
• Flexible Backends: Easily configure for different storage backends:
  • In-Memory (Default): Perfect for local development and testing.
  • Remote: Connect to a shared OpenHive registry endpoint.
• Powerful Query Engine: A flexible query parser to find agents based on their name, description, or skills.

🚀 Getting Started

Installation

npm install @open-hive/sdk

Basic Usage

The OpenHive class is the main entry point for all registry operations. By default, it uses a volatile in-memory registry.

import { OpenHive } from '@open-hive/sdk';
import { AgentCard } from '@open-hive/sdk';

async function main() {
  // 1. Initialize the registry.
  // By default, it uses an in-memory store.
  const hive = new OpenHive();

  // 2. Define an agent card
  const myAgent: AgentCard = {
    name: 'MyAwesomeAgent',
    protocolVersion: '0.3.0',
    version: '1.0.0',
    url: 'http://localhost:8080',
    skills: [{ id: 'chat', name: 'Chat' }],
  };

  // 3. Add the agent to the registry
  const registeredAgent = await hive.add(myAgent);
  console.log('Agent added:', registeredAgent);

  // 4. Search for agents with the 'chat' skill
  const results = await hive.search('skill:chat');
  console.log('Search results:', results);
}

main();

Registry Configurations

Remote Registry

To connect to a remote registry, provide the registryUrl in the constructor. This is the standard choice for multi-agent clusters where a dedicated agent or service acts as a discovery hub.

import { OpenHive } from '@open-hive/sdk';

const hive = new OpenHive({
  registryUrl: 'http://localhost:11100', // URL of the remote registry
  headers: { Authorization: 'Bearer your-optional-auth-token' },
});

// You can also authenticate using an API key or specific Access Token:
// const hive = new OpenHive({
//   registryUrl: 'http://localhost:11100',
//   apiKey: 'your-api-key',
// });
//
// const hive = new OpenHive({
//   registryUrl: 'http://localhost:11100',
//   accessToken: 'your-access-token',
// });

// All operations will now be performed against the remote registry.
const agentList = await hive.list();
console.log(agentList);

Pagination

The list and search methods now support pagination options when using the RemoteRegistry.

// Get the first 10 agents
const agents = await hive.list({ page: 1, limit: 10 });

// Search with pagination
const results = await hive.search('skill:chat', { page: 1, limit: 5 });

Platform Integration

The SDK includes extended methods for interacting with the OpenHive Platform. These methods are available when using a compatible RemoteRegistry.

// Complete an agent upload
await hive.completeUpload(agentData);

// Trigger a deployment
await hive.deployAgent('agent-name');

// Get a download URL for an agent
const downloadInfo = await hive.getAgentDownload('agent-name', '1.0.0');

// Get current user information
const user = await hive.getCurrentUser();

// Request an upload URL
const uploadInfo = await hive.requestUploadUrl(agentData, false);

// Revoke an API key
await hive.revokeApiKey('your-api-key');

SQLite Registry

For persistence across restarts without a dedicated registry server, you can use a SqliteRegistry. The OpenHive class can be configured to use any compliant registry adapter.

Note: The SqliteRegistry is no longer included in the main OpenHive bundle to keep the SDK lightweight. You can implement your own using the AgentRegistry interface.

import { OpenHive, AgentRegistry, AgentCard } from '@open-hive/sdk';

// 1. Implement your own SqliteRegistry class
class MySqliteRegistry implements AgentRegistry {
  // ... implementation using 'better-sqlite3' or similar
}

// 2. Pass the custom registry to the OpenHive constructor.
const hive = new OpenHive({
  registry: new MySqliteRegistry('local', './agents.db'),
});

// The agent will now use the SQLite database for all registry operations.
await hive.add({
  name: 'PersistentAgent',
  // ... other agent card properties
});

🔎 Advanced Search

The query engine allows you to find agents with specific skills or attributes using a simple yet powerful syntax.

Search by General Term

Provide a single term to search across an agent's name and description.

// Finds agents where 'Awesome' is in the name or description
const results = await hive.search('Awesome');

Search by Specific Fields

Target specific fields using field:value syntax. You can also wrap values with spaces in quotes.

// Finds agents with the name "My Awesome Agent"
const results = await hive.search('name:"My Awesome Agent"');

Search by Skill

You can find agents that possess a specific skill.

// Finds agents with the 'chat' skill
const results = await hive.search('skill:chat');

Combining Filters

Combine multiple filters to create more specific queries.

// Finds agents named "MyAwesomeAgent" that also have the 'chat' skill
const results = await hive.search('name:MyAwesomeAgent skill:chat');

🔧 Extensibility

All registry methods (add, get, list, search, update, delete, clear) now accept additional arguments (...args), allowing you to pass custom options or context to your registry implementation.

// Example: Passing a transaction ID to a custom registry
await hive.add(myAgent, { transactionId: 'tx-123' });

The OpenHive class and AgentRegistry interface now also support a generic return type. This is useful if you are implementing a custom registry that returns an object extending AgentCard or a completely different type.

// Initialize with a custom return type
const hive = new OpenHive<MyCustomAgentType>({ registry: myCustomRegistry });

// The add method will now return Promise<MyCustomAgentType>
const result = await hive.add(myAgent);

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines to get started.

⚖️ Licensing

This project is licensed under the Apache 2.0 License. See the LICENSE.md file for full details.