agentkit

module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 24, 2026 License: Apache-2.0

README

AgentKit

Reusable Go packages for building AI agent swarms.

Quick Start

Get an agent running in 5 minutes:

go get github.com/vinayprograms/agentkit

package main

import (
    "context"
    "log"
    "time"

    "github.com/vinayprograms/agentkit/bus"
    "github.com/vinayprograms/agentkit/heartbeat"
    "github.com/vinayprograms/agentkit/registry"
)

func main() {
    ctx := context.Background()

    // Connect to message bus — the backbone of agent communication
    msgBus, _ := bus.NewNATSBus(bus.NATSConfig{URL: "nats://localhost:4222"})
    defer msgBus.Close()

    // Register this agent — so other agents can discover us
    reg, _ := registry.NewNATSRegistry(msgBus.Conn(), registry.NATSRegistryConfig{
        BucketName: "my-swarm",
        TTL:        30 * time.Second,
    })
    defer reg.Close()

    agentID := "worker-1"
    reg.Register(registry.AgentInfo{
        ID:           agentID,
        Name:         "Example Worker",
        Capabilities: []string{"process-tasks"},
        Status:       registry.StatusIdle,
    })

    // Start heartbeat — proves we're alive to coordinators
    sender, _ := heartbeat.NewBusSender(heartbeat.SenderConfig{
        Bus:      msgBus,
        AgentID:  agentID,
        Interval: 5 * time.Second,
    })
    sender.Start(ctx)
    defer sender.Stop()

    // Subscribe to work via queue group — load balanced across workers
    sub, _ := msgBus.QueueSubscribe("tasks.process", "workers")

    log.Printf("Agent %s ready", agentID)

    for msg := range sub.Messages() {
        sender.SetStatus("busy")
        log.Printf("Processing: %s", msg.Data)
        // ... your logic here ...
        sender.SetStatus("idle")
    }
}

Architecture

graph TB
    subgraph Agent["Your Agent"]
        LLM["LLM<br/>(Claude, GPT, Gemini)"]
        Tools["Tools<br/>(builtin + MCP)"]
        Memory["Memory<br/>(FIL + search)"]
    end

    subgraph Coordination["Swarm Coordination"]
        Registry["Registry<br/>who exists"]
        Heartbeat["Heartbeat<br/>who's alive"]
        State["State<br/>shared data"]
        Tasks["Tasks<br/>work items"]
        Results["Results<br/>outputs"]
        Ratelimit["Ratelimit<br/>quotas"]
    end

    subgraph Infrastructure["Infrastructure"]
        Bus["Message Bus<br/>pub/sub, queues, RPC"]
        Backend["Backend<br/>NATS / Memory"]
    end

    Agent --> Coordination
    Coordination --> Bus
    Bus --> Backend

Message Bus is the foundation — all agent communication flows through it.

Swarm Coordination builds on the bus — registry tracks agents, heartbeat detects failures, state shares data, tasks manage work.

Your Agent uses coordination primitives plus LLM/tools/memory for actual work.

Learning Path

Start with the fundamentals, then add capabilities as needed:

1. Core (Read First)
Package What It Does Doc
llm Call LLMs (Claude, GPT, Gemini) with unified interface llm-design.md
bus Message passing between agents (pub/sub, queues, RPC) bus-design.md
errors Structured errors with retry semantics errors-design.md
2. Swarm Basics (Multi-Agent)
Package What It Does Doc
registry Agent registration and capability-based discovery registry-design.md
heartbeat Detect dead agents, trigger failover heartbeat-design.md
state Shared key-value store with distributed locks state-design.md
3. Task Coordination
Package What It Does Doc
tasks Idempotent task handling with deduplication tasks-design.md
results Publish/subscribe for task results results-design.md
ratelimit Coordinate rate limits across swarm ratelimit-design.md
4. Operations
Package What It Does Doc
shutdown Graceful shutdown with phases shutdown-design.md
logging Structured real-time logging logging-design.md
telemetry OpenTelemetry tracing telemetry-design.md
5. Specialized
Package What It Does Doc
transport JSON-RPC transports (stdio, WebSocket, SSE) transport-design.md
mcp Connect to external tool servers mcp-design.md
acp Editor integration (VS Code, Cursor) acp-design.md
memory Semantic memory with BM25 search memory-design.md

Examples

Working code you can run:

Example What It Shows
chat-transport Basic transport setup
task-queue Work distribution via bus
swarm-heartbeat Agent liveness detection
graceful-shutdown Multi-phase shutdown
idempotent-tasks Safe task retries
rate-limiting Coordinated rate limits
result-publication Pub/sub for results
structured-errors Error handling patterns

Design Philosophy

  • Composition over frameworks — Use what you need, ignore the rest
  • Backend agnostic — Memory implementations for testing, NATS for production
  • Go idiomatic — Channels, interfaces, context propagation
  • Explicit over magic — No hidden state, no auto-discovery

Used By

License

Apache-2.0

Directories

Path Synopsis
Package acp provides Agent Client Protocol support.
 Package acp provides Agent Client Protocol support.
Package auth provides OAuth2 authentication flows for LLM providers.
 Package auth provides OAuth2 authentication flows for LLM providers.
Package bus provides message bus clients for agent-to-agent communication.
 Package bus provides message bus clients for agent-to-agent communication.
Claude CLI credential discovery.
 Claude CLI credential discovery.
Package errors provides a structured error taxonomy for swarm coordination in agentkit.
 Package errors provides a structured error taxonomy for swarm coordination in agentkit.
examples
chat-transport/client command
Package main demonstrates a WebSocket JSON-RPC chat client.
 Package main demonstrates a WebSocket JSON-RPC chat client.
chat-transport/server command
Package main demonstrates a WebSocket JSON-RPC chat server using agentkit transport.
 Package main demonstrates a WebSocket JSON-RPC chat server using agentkit transport.
graceful-shutdown command
Package main demonstrates graceful shutdown coordination using agentkit's shutdown package.
 Package main demonstrates graceful shutdown coordination using agentkit's shutdown package.
idempotent-tasks/producer command
Package main demonstrates submitting idempotent tasks using agentkit's tasks package.
 Package main demonstrates submitting idempotent tasks using agentkit's tasks package.
idempotent-tasks/worker command
Package main demonstrates a task worker using agentkit's tasks package.
 Package main demonstrates a task worker using agentkit's tasks package.
rate-limiting command
Package main demonstrates rate limiting using agentkit's ratelimit package.
 Package main demonstrates rate limiting using agentkit's ratelimit package.
result-publication command
Package main demonstrates the results package for task result publication.
 Package main demonstrates the results package for task result publication.
structured-errors command
Package main demonstrates the agentkit/errors package for structured error handling.
 Package main demonstrates the agentkit/errors package for structured error handling.
swarm-heartbeat/agent command
Package main demonstrates a self-registering agent with heartbeat using agentkit's registry.
 Package main demonstrates a self-registering agent with heartbeat using agentkit's registry.
swarm-heartbeat/monitor command
Package main demonstrates a swarm monitor that watches for agent registration events and detects dead agents based on missed heartbeats.
 Package main demonstrates a swarm monitor that watches for agent registration events and detects dead agents based on missed heartbeats.
task-queue/coordinator command
Package main demonstrates a distributed task coordinator using agentkit's bus and registry.
 Package main demonstrates a distributed task coordinator using agentkit's bus and registry.
task-queue/worker command
Package main demonstrates a task worker using agentkit's bus and registry.
 Package main demonstrates a task worker using agentkit's bus and registry.
Package heartbeat provides agent liveness detection for distributed swarms.
 Package heartbeat provides agent liveness detection for distributed swarms.
Package llm provides LLM provider interfaces and implementations.
 Package llm provides LLM provider interfaces and implementations.
Package logging provides real-time log output derived from session events.
 Package logging provides real-time log output derived from session events.
Package mcp provides MCP (Model Context Protocol) client support.
 Package mcp provides MCP (Model Context Protocol) client support.
Package memory provides persistent knowledge storage with BM25 text search.
 Package memory provides persistent knowledge storage with BM25 text search.
Package policy provides bash command security checking.
 Package policy provides bash command security checking.
Package ratelimit provides rate limit coordination for agent swarms.
 Package ratelimit provides rate limit coordination for agent swarms.
Package registry provides agent registration and discovery for swarm coordination.
 Package registry provides agent registration and discovery for swarm coordination.
Package results provides task result publication and retrieval for agent coordination.
 Package results provides task result publication and retrieval for agent coordination.
Package security provides prompt injection defense through trust-tagged content blocks, tiered verification, and cryptographic audit trails.
 Package security provides prompt injection defense through trust-tagged content blocks, tiered verification, and cryptographic audit trails.
Package shutdown provides graceful shutdown coordination for distributed agents.
 Package shutdown provides graceful shutdown coordination for distributed agents.
Package state provides shared state management for distributed agent coordination.
 Package state provides shared state management for distributed agent coordination.
Package tasks provides idempotent task handling with deduplication.
 Package tasks provides idempotent task handling with deduplication.
OpenTelemetry provider initialization and configuration.
 OpenTelemetry provider initialization and configuration.
Package tools provides the tool registry and built-in tools.
 Package tools provides the tool registry and built-in tools.
Package transport provides pluggable transports for JSON-RPC 2.0 communication.
 Package transport provides pluggable transports for JSON-RPC 2.0 communication.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.