Skip to content

HugAI Protocol v2

Introduction

The HugAI Protocol is an open specification designed to enable interoperability, orchestration, and governance of artificial intelligence agents in software development. Inspired by the Language Server Protocol (LSP), HugAI aims to standardize communication between tools, agents, and humans, allowing multiple AI systems to collaborate securely, audibly, and under human control.

The protocol defines how AI agents register, negotiate capabilities, exchange messages, and integrate into workflows governed by humans. Its goal is to enable scalable AI adoption in development environments, reduce vendor lock-in, and create an open ecosystem where agents, tools, and humans can collaborate transparently and efficiently.

HugAI is designed to be extensible, adaptable to different domains, and compatible with multiple transport technologies (HTTP, WebSocket, STDIO), following principles of modularity, security, and traceability.

Protocol Objectives

The main objectives of the HugAI protocol technical specification are:

  1. Standardize communication between AI agents, tools, and humans
  2. Define a common language and interoperable message formats to facilitate integration of multiple systems and vendors.
  3. Enable multi-agent orchestration and collaboration
  4. Allow specialized agents to work together, share context, and coordinate tasks within human-governed workflows.
  5. Ensure governance and human control
  6. Include mechanisms for approval, auditing, and traceability to ensure that critical decisions are supervised and validated by people.
  7. Promote extensibility and adaptability
  8. Design the protocol to evolve, incorporate new capabilities, and adapt to different domains and technologies.
  9. Ensure security and integrity of interactions
  10. Provide authentication, authorization, and protection against malicious or accidental actions.
  11. Reduce vendor lock-in and foster an open ecosystem
  12. Enable interoperability between agents and tools from different vendors, facilitating adoption and collaborative innovation.

General Architecture

The HugAI protocol is based on a modular, layered architecture inspired by the Language Server Protocol (LSP) and the JSON-RPC 2.0 standard. This architecture separates responsibilities, facilitates extensibility, and ensures interoperability between different agents, tools, and platforms.

Main Components:

  • AI Agents: Specialized entities that perform tasks, process messages, and collaborate in workflows.
  • Coordinator/Gateway: Central node (optional) that orchestrates communication, routes messages, and enforces governance rules.
  • Clients/Tools: User interfaces, IDEs, CI/CD systems, or other applications that interact with agents via the protocol.
  • Human Stakeholders: People who supervise, validate, and make decisions at defined control points.

Architecture Layers:

  1. Transport Layer: Defines the physical communication mechanisms (HTTP, WebSocket, STDIO, etc.).
  2. Messaging Layer (JSON-RPC 2.0): Standardizes the format of messages, requests, responses, and notifications.
  3. Agent Communication Layer: Manages registration, discovery, and capability negotiation between agents.
  4. Governance and Approvals Layer: Implements human control flows, auditing, and validation checkpoints.
  5. Tool Integration Layer: Enables connection with external systems (IDEs, CI/CD, monitoring, etc.).
  6. Multi-Agent Orchestration Layer: Coordinates collaboration and task flow between multiple agents and humans.

This architecture allows the protocol to evolve, incorporate new features, and adapt to different use cases, always maintaining traceability, security, and human control as fundamental principles.

Protocol Layers

The main layers of the HugAI protocol are described below:

  1. Transport Layer
  2. Provides the physical and logical channels for message transmission between agents, tools, and humans. Supports HTTP, WebSocket, STDIO, and other mechanisms depending on the environment and integration needs.
  3. Messaging Layer (JSON-RPC 2.0)
  4. Defines the standard format for messages (requests, responses, notifications) and ensures interoperability between different participants. Allows structured extension of methods and parameters.
  5. Agent Communication Layer
  6. Manages registration, discovery, capability negotiation, and direct communication between agents. Allows agents to announce themselves, describe their functions, and collaborate on complex tasks.
  7. Governance and Approvals Layer
  8. Implements mechanisms for human control, validation checkpoints, auditing, and traceability. Allows definition of approval, escalation, and review rules at each workflow phase.
  9. Tool Integration Layer
  10. Facilitates connection and communication with external systems such as IDEs, CI/CD pipelines, monitoring platforms, etc. Enables integration of events, commands, and results from third-party tools.
  11. Multi-Agent Orchestration Layer
  12. Coordinates collaboration between multiple agents and humans, managing task flow, responsibility assignment, and resolution of dependencies or conflicts.

Each layer can evolve independently, allowing the protocol to adapt to new scenarios, technologies, and requirements without compromising compatibility or security.

Message Types

The HugAI protocol defines several main message types, each with a specific purpose within workflows and governance:

  1. Initialization (initialize)
  2. Message to establish connection, negotiate capabilities, and share context information between agents, clients, and the coordinator.
  3. Agent Registration (agent/register)
  4. Allows agents to announce themselves, describe their capabilities, and become available for specific tasks.
  5. Requests (request)
  6. Messages to request task execution, obtain information, or initiate flows between agents and tools.
  7. Responses (response)
  8. Return messages with results, data, or states derived from a previous request.
  9. Events (event)
  10. Notifications about state changes, incidents, progress, or any relevant event in the system.
  11. Approvals and Checkpoints (governance/approval)
  12. Messages to manage human control points, approvals, reviews, and auditing of critical decisions.
  13. Tool Integration (tool/integration)
  14. Messages to interact with external systems, execute commands, receive results, or integrate events from third-party tools.
  15. Audit and Traceability (audit/log)
  16. Messages to record actions, decisions, and relevant events, ensuring traceability and regulatory compliance.

Each message type can have subtypes, parameters, and extensions depending on the use case and protocol evolution. All messages follow the structured JSON-RPC 2.0 format to ensure interoperability and extensibility.

Agents and Capabilities

In the HugAI protocol, agents are autonomous or semi-autonomous entities that offer specialized capabilities (analysis, design, implementation, testing, operations, governance, etc.). Managing their capabilities is fundamental for efficient and secure workflow orchestration.

Agent Registration

  • Each agent must register in the system (directly or via a coordinator), announcing its identity, type, capabilities, and supported governance level.
  • Registration includes metadata such as name, version, author, description, supported tasks, inputs/outputs, and configuration requirements.

Capability Description and Negotiation

  • An agent's capabilities are described using a structured schema (e.g., list of tasks, supported data types, constraints, dependencies).
  • During initialization or at runtime, agents can negotiate capabilities with other agents or tools, allowing dynamic adaptation to different flows and contexts.
  • Negotiation may include: task assignment, delegation, escalation, or parameter adjustment based on system availability and context.

Dynamic Update and Discovery

  • The protocol supports dynamic capability updates (e.g., when an agent learns a new task or its model is updated).
  • Agents and tools can discover and query the capabilities of other registered agents at any time, facilitating collaboration and system resilience.

This structured and dynamic capability management enables building flexible, scalable, and secure ecosystems where each agent adds value in a controlled and auditable manner.

Communication Flows

The HugAI protocol defines structured communication flows to ensure coordination, traceability, and governance throughout the lifecycle:

  1. Initialization
  2. An agent or tool initiates the connection, negotiates capabilities, and establishes the working context.
  3. Task Orchestration
  4. Agents coordinate task assignment, execution, and tracking, sharing context and results according to governance rules.
  5. Governance Checkpoints
  6. At critical points, human intervention is required to approve, reject, or request reviews before proceeding.
  7. Escalation and Incident Resolution
  8. If an agent detects a problem beyond its scope, it escalates the incident to a human or governance agent for resolution.
  9. Closure and Audit
  10. At the end of a flow, results, decisions, and learnings are recorded for auditing and continuous improvement.

These flows ensure that automation is always under human control and that all actions are traceable and auditable.

Security and Governance

Security and governance are fundamental pillars of the HugAI protocol:

  • Authentication and Authorization: All agents and tools must authenticate and be authorized to participate in flows. The use of tokens, certificates, or equivalent mechanisms is recommended.
  • Traceability and Auditing: All actions, decisions, and relevant events must be recorded to enable auditing, regulatory compliance, and forensic analysis.
  • Human Control: Control points, approvals, and human reviews are mandatory for critical or sensitive tasks.
  • Permission and Role Management: The protocol allows defining granular roles and permissions to limit the scope of each agent or tool.
  • Protection against Bias and Errors: Cross-validation and human review are recommended to mitigate risks associated with AI model biases or errors.

Extensibility and Versioning

The HugAI protocol is designed to evolve and adapt:

  • Message Extension: New message types, methods, and parameters can be added without breaking compatibility with previous versions.
  • Version Negotiation: During initialization, participants negotiate the protocol version and supported extensions.
  • Custom Capabilities: Agents can announce and negotiate specific capabilities, enabling integration of new functions or domains.
  • Deprecation and Migration: Mechanisms are defined to deprecate messages or capabilities and migrate to new versions in a controlled manner.

Implementation Examples

Below are minimal examples of messages and flows:

  • Agent Initialization: 

    {
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "agentId": "test-agent-1",
    "capabilities": ["code-generation", "testing"],
    "governanceLevel": "supervised"
  }
}

  • Task Request: 

    {
  "jsonrpc": "2.0",
  "method": "agent/request",
  "params": {
    "sourceAgent": "test-agent-1",
    "targetAgent": "test-agent-2",
    "task": "generate-tests",
    "context": {"file": "main.ts"},
    "priority": "high"
  }
}

  • Human Approval: 

    {
  "jsonrpc": "2.0",
  "method": "governance/approval",
  "params": {
    "checkpoint": "code-review",
    "artifact": {"file": "main.ts", "diff": "..."},
    "approver": "user-123",
    "decision": "approved",
    "feedback": "Looks good."
  }
}

Roadmap and Future Extensions

  • Integration with advanced identity and permission systems.
  • Support for new types of agents and capabilities (e.g., compliance agents, explainability agents).
  • Extension to domains beyond software development (e.g., operations, security, data science).
  • Protocol validation, simulation, and testing tools.
  • Community and marketplace of certified agents.
  • Integration with emerging standards for responsible and ethical AI.

NOTE: This document is the starting point for version 2 of the HugAI protocol. Each section will be completed and improved iteratively.