hub

README

AgentsHub - Agent Registry and Distribution System

AgentsHub is a lightweight registry system for managing and distributing AI agent definition(Agentfile), similar to how container registries works for container images(think of the popular Dockerfile). It provides a simple way to store, version, and retrieve agent definition through both an HTTP API and CLI tool.

Features

• Push and pull agent configuration files
• Version control for agents definitions
• Simple HTTP API for integration
• Command-line interface (CLI) for easy management
• In-memory storage (with extensible storage backend)

Usage

Starting the Server

The AgentsHub server is integrated into the main application:

go run main.go

This will start both the orchestrator and the AgentsHub server on port 8082.

Using the CLI

The a8shub CLI tool provides commands for interacting with the registry.

Basic Commands

# Push an agent definition
a8shub push       # Example: a8shub push myagent:1.0 agent.json
# Output: Successfully pushed myagent:1.0

# Pull an agent definition
a8shub pull             # Example: a8shub pull myagent:1.0
# Output: Successfully pulled myagent:1.0 to myagent-1.0.json

# Show agent documentation
a8shub show           # Example: a8shub show myagent:1.0
                                      # or: a8shub show myagent (shows latest version)

Version Format

The system uses semantic versioning (SemVer):

• Accepts versions like: "1.0", "v1.0", "1.0.0", "v1.0.0"
• When version is omitted in 'show' command, automatically uses latest version
• Latest version is determined by highest numerical value

CLI Options

# Use a different server with different port
a8shub --server http://other-server:8090 push myagent:1.0 config.md

# Get help
a8shub --help
a8shub push --help

API Endpoints

Push Agent Definition

POST /v1/push
Content-Type: multipart/form-data

Form fields:
- agentfile: The agent definition file
- name: Agent name
- version: Agent version

Pull Agent Definition

GET /v1/pull?name=<name>&version=<version>

Show Agent Documentation

GET /v1/show?name=&version=

Response: Markdown formatted documentation of the agent definition

Development

The system is designed to be extensible:

1. The Registry interface can be implemented for different storage backends
2. New API endpoints can be added to the server
3. CLI commands can be extended using Cobra

Configuration

Default configuration:

• Server port: 8082
• Server URL: http://localhost:8082
• Max file size: 10MB

Best Practices

1. Use semantic versioning for agent configurations
2. Include proper documentation in your agent files
3. Use meaningful names for your agents
4. Test configurations before pushing to production registries

Security

Current limitations:

• No authentication/authorization
• In-memory storage only
• No SSL/TLS support

For production use, consider implementing these security features.

Documentation

Overview

File: hub/server.go

Index

• type AgentFile
• type AgentVersions
• type Config
  • func DefaultConfig() Config
• type DefinationRegistry
• type InMemoryRegistry
  • func NewInMemoryRegistry() *InMemoryRegistry
  • func (r *InMemoryRegistry) Close() error
  • func (r *InMemoryRegistry) Get(name, version string) (*AgentFile, error)
  • func (r *InMemoryRegistry) GetJSON(name, version string) ([]byte, error)
  • func (r *InMemoryRegistry) Store(name, version string, agent *AgentFile) error
• type SQLiteRegistry
  • func GetSQLiteRegistry() (*SQLiteRegistry, error)
  • func (r *SQLiteRegistry) Close() error
  • func (r *SQLiteRegistry) Get(name, version string) (*AgentFile, error)
  • func (r *SQLiteRegistry) GetAgentDef(name, version string) (*types.AgentDefinition, error)
  • func (r *SQLiteRegistry) GetJSON(name, version string) ([]byte, error)
  • func (r *SQLiteRegistry) ListAgents() error
  • func (r *SQLiteRegistry) Store(name, version string, agent *AgentFile) error
• type Server
  • func NewServer(config Config) (*Server, error)
  • func (s *Server) Shutdown(ctx context.Context) error
  • func (s *Server) Start(ctx context.Context) error
• type Version
  • func ParseVersion(v string) (*Version, error)
  • func (v Version) Compare(other Version) int
  • func (v Version) String() string

Types

type AgentFile

type AgentFile struct {
	Name       string            `json:"name"`
	Version    string            `json:"version"`
	Content    string            `json:"content"`
	Metadata   map[string]string `json:"metadata"`
	CreateTime int64             `json:"create_time"`
}

AgentFile represents the metadata and content of an agent

type AgentVersions

type AgentVersions map[string]*AgentFile

type Config

type Config struct {
	Address string        // Server address (e.g., ":8080")
	BaseURL string        // Base URL for the server
	Timeout time.Duration // Operation timeout
}

Config holds configuration for the AgentsHub

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a default configuration

type DefinationRegistry

type DefinationRegistry interface {
	Store(name, version string, agent *AgentFile) error
	Get(name, version string) (*AgentFile, error)
	GetJSON(name, version string) ([]byte, error)
	GetAgentDef(name, version string) (*types.AgentDefinition, error)
	Close() error
}

DefinationRegistry defines the interface for agent defination registry

type InMemoryRegistry

type InMemoryRegistry struct {
	// contains filtered or unexported fields
}

func NewInMemoryRegistry

func NewInMemoryRegistry() *InMemoryRegistry

func (*InMemoryRegistry) Close

func (r *InMemoryRegistry) Close() error

func (*InMemoryRegistry) Get

func (r *InMemoryRegistry) Get(name, version string) (*AgentFile, error)

func (*InMemoryRegistry) GetJSON

func (r *InMemoryRegistry) GetJSON(name, version string) ([]byte, error)

func (*InMemoryRegistry) Store

func (r *InMemoryRegistry) Store(name, version string, agent *AgentFile) error

type SQLiteRegistry

type SQLiteRegistry struct {
	// contains filtered or unexported fields
}

func GetSQLiteRegistry

func GetSQLiteRegistry() (*SQLiteRegistry, error)

func (*SQLiteRegistry) Close

func (r *SQLiteRegistry) Close() error

func (*SQLiteRegistry) Get

func (r *SQLiteRegistry) Get(name, version string) (*AgentFile, error)

func (*SQLiteRegistry) GetAgentDef

func (r *SQLiteRegistry) GetAgentDef(name, version string) (*types.AgentDefinition, error)

func (*SQLiteRegistry) GetJSON

func (r *SQLiteRegistry) GetJSON(name, version string) ([]byte, error)

func (*SQLiteRegistry) ListAgents

func (r *SQLiteRegistry) ListAgents() error

func (*SQLiteRegistry) Store

func (r *SQLiteRegistry) Store(name, version string, agent *AgentFile) error

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server handles HTTP requests for the AgentsHub

func NewServer

func NewServer(config Config) (*Server, error)

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

func (*Server) Start

func (s *Server) Start(ctx context.Context) error

type Version

type Version struct {
	Major int
	Minor int
	Patch int
}

func ParseVersion

func ParseVersion(v string) (*Version, error)

func (Version) Compare

func (v Version) Compare(other Version) int

func (Version) String

func (v Version) String() string