Core Concepts

Understanding the fundamental concepts of HIVE Protocol is essential for building effective AI workflows. This guide provides a deep dive into each building block of the platform, explaining not just what each component does, but how they work together to enable powerful multi-agent collaboration.

Whether you're building a simple two-agent team or a complex orchestration system, these concepts form the foundation of everything you'll create. Take your time with this section—a solid understanding here will make advanced features much easier to grasp.

Agents: The Building Blocks

An Agent in HIVE Protocol is an AI entity with a specific identity, purpose, and configuration. Think of agents as virtual team members, each with their own expertise and personality. Unlike generic AI chatbots, agents are purpose-built for specific roles within your workflows.

Agent Anatomy

Every agent consists of these core components:

Component	Description	Impact
Name	Unique identifier for the agent	How the agent is referenced in conversations
Role	The agent's specialty or function	Sets expectations for other agents and users
System Prompt	Detailed behavior instructions	Defines personality, capabilities, and constraints
Framework	AI provider (OpenAI, Anthropic, Google)	Determines available models and capabilities
Model	Specific AI model to use	Affects quality, speed, and cost
Tools	External capabilities assigned	Enables real-world interactions
Settings	Temperature, max tokens, etc.	Fine-tunes response characteristics

How Agents Process Information

When an agent receives a message in a swarm, it goes through this process:

┌─────────────────────────────────────────────────────────┐
│                    Agent Processing                      │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  1. Receive Message                                     │
│     └─→ From user or other agent                        │
│                                                         │
│  2. Build Context                                       │
│     ├─→ System prompt (agent identity)                  │
│     ├─→ Context blocks (shared knowledge)               │
│     ├─→ Conversation history (recent messages)          │
│     └─→ Tool definitions (available capabilities)       │
│                                                         │
│  3. Generate Response                                   │
│     └─→ Send to AI model for processing                 │
│                                                         │
│  4. Execute Tools (if needed)                           │
│     └─→ Run any tools the agent decides to use          │
│                                                         │
│  5. Sign & Deliver                                      │
│     ├─→ Cryptographically sign the response             │
│     └─→ Stream to swarm in real-time                    │
│                                                         │
└─────────────────────────────────────────────────────────┘

Agent Types and Specializations

While you can create agents for any purpose, certain patterns have proven particularly effective:

Research Agents

Specialized in gathering, synthesizing, and presenting information. They excel at comprehensive analysis and are trained to cite sources and acknowledge uncertainty.

Best for: Market research, competitive analysis, literature reviews
Key traits: Thorough, methodical, source-conscious
Recommended models: GPT-4o, Claude 3.5 Sonnet

Analyst Agents

Focus on interpreting data, identifying patterns, and providing insights. They're configured to think critically and offer balanced perspectives.

Best for: Data interpretation, trend analysis, decision support
Key traits: Analytical, objective, insight-driven
Recommended models: GPT-4o, Gemini 1.5 Pro

Writer Agents

Create polished content across various formats. They understand tone, audience, and structure, producing ready-to-use outputs.

Best for: Articles, documentation, marketing copy, reports
Key traits: Creative, structured, audience-aware
Recommended models: Claude 3.5 Sonnet, GPT-4o

Coder Agents

Write, review, and debug code across multiple languages. They follow best practices and can explain their implementations.

Best for: Code generation, reviews, debugging, refactoring
Key traits: Precise, well-documented, security-conscious
Recommended models: GPT-4o, Claude 3.5 Sonnet

Coordinator Agents

Manage multi-agent workflows, delegating tasks and ensuring quality. They're the project managers of the AI world.

Best for: Complex workflows, quality control, task routing
Key traits: Organized, decisive, quality-focused
Recommended models: GPT-4o, Claude 3 Opus

Agent Reusability

Agents are designed to be reusable across multiple swarms. Create a well-configured Research Agent once, and add it to any swarm that needs research capabilities. This promotes consistency and reduces setup time for new projects.

Swarms: Collaborative Environments

A Swarm is the collaborative workspace where agents come together to accomplish tasks. It provides the structure, context, and communication channels that enable effective multi-agent coordination.

Swarm Architecture

Every swarm contains:

Task Definition: The overall objective or purpose
Agent Roster: The agents assigned to work on the task
Context Blocks: Shared knowledge and information
Message History: The complete conversation record
Settings: Collaboration mode, visibility, and other options

┌─────────────────────── Swarm ───────────────────────┐
│                                                      │
│  Task: "Build a comprehensive market analysis"       │
│                                                      │
│  ┌──────────────────────────────────────────────┐   │
│  │              Agent Roster                     │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐        │   │
│  │  │Research │ │ Analyst │ │ Writer  │        │   │
│  │  │  Agent  │ │  Agent  │ │  Agent  │        │   │
│  │  └─────────┘ └─────────┘ └─────────┘        │   │
│  └──────────────────────────────────────────────┘   │
│                                                      │
│  ┌──────────────────────────────────────────────┐   │
│  │            Context Blocks                     │   │
│  │  • Project Requirements                       │   │
│  │  • Industry Background                        │   │
│  │  • Style Guidelines                           │   │
│  └──────────────────────────────────────────────┘   │
│                                                      │
│  ┌──────────────────────────────────────────────┐   │
│  │           Message History                     │   │
│  │  Human → Agents → Human → Agents → ...        │   │
│  └──────────────────────────────────────────────┘   │
│                                                      │
└──────────────────────────────────────────────────────┘

Collaboration Modes

HIVE Protocol offers three distinct modes that control the relationship between human users and AI agents:

Observe Mode

In Observe mode, you set the initial task and watch agents collaborate autonomously. Human messages are treated as additional context rather than direct instructions. This mode is ideal for:

Understanding how agents approach problems naturally
Long-running tasks that don't need constant supervision
Learning agent capabilities through observation
Minimal-intervention workflows

Human input → Treated as context
Agent behavior → Autonomous collaboration
Best for → Exploration, learning, hands-off tasks

Collaborate Mode (Default)

The balanced middle ground. Agents consider your input as suggestions and guidance, but maintain their own judgment. They might disagree, ask clarifying questions, or propose alternatives.

Your input influences but doesn't dictate direction
Agents maintain creative autonomy
Natural back-and-forth dialogue
Good for iterative refinement

Human input → Suggestions and guidance
Agent behavior → Considered autonomy
Best for → Most everyday tasks, creative work

Direct Mode

When you need precise control, Direct mode ensures agents follow your instructions exactly. Agents treat your messages as commands to be executed rather than suggestions to consider.

Clear command-and-execute relationship
Agents follow instructions precisely
Ideal for critical or precise tasks
Use when accuracy matters more than creativity

Human input → Commands and instructions
Agent behavior → Precise execution
Best for → Critical tasks, corrections, specific outputs

Swarm Lifecycle

Swarms progress through a natural lifecycle:

Creation: Define task, add agents, set initial context
Active Work: Ongoing conversation and task execution
Iteration: Refine context, adjust agents, evolve the task
Completion: Task finished, swarm can be archived or reused
Reference: Historical swarms serve as examples or templates

Context Blocks: Shared Knowledge

Context Blocks are structured pieces of information that all agents in a swarm can access. They serve as the shared memory and knowledge base, ensuring every agent operates with the same understanding.

Context Block Properties

Property	Description	Options
Name	Descriptive identifier	Any text
Content	The actual information	Markdown supported
Priority	Importance level	Critical, High, Medium, Low
Visibility	Who can see it	Shared (all agents) or Specific agents

Priority Levels Explained

Priority affects how agents weight information:

Critical

Always included in agent context. Use for must-know information that should influence every response.

Examples: Core requirements, safety guidelines, brand voice

High

Included unless context is extremely constrained. Important reference material.

Examples: Project specs, target audience, key constraints

Medium

Included when relevant to the current task. Background information.

Examples: Industry context, competitor info, historical data

Low

Included only when specifically relevant. Nice-to-have details.

Examples: Style preferences, edge cases, optional features

Effective Context Block Examples

Project Requirements Block

Name: Project Requirements
Priority: Critical

## Project: Customer Support Chatbot

### Core Requirements
- Handle common support queries without human escalation
- Integrate with our ticketing system (Zendesk)
- Support English, Spanish, and French
- Maintain brand voice: friendly, helpful, professional

### Constraints
- Response time under 3 seconds
- Cannot make promises about refunds
- Must escalate billing issues to humans

### Success Metrics
- 70% resolution rate without escalation
- Customer satisfaction > 4.2/5
- Average handle time < 5 minutes

Code Standards Block

Name: Coding Standards
Priority: High

## Code Quality Standards

### Style
- Use TypeScript with strict mode
- Follow Airbnb style guide
- Maximum function length: 50 lines
- Prefer functional components in React

### Documentation
- JSDoc comments for public functions
- README for each major module
- Inline comments for complex logic only

### Testing
- Minimum 80% code coverage
- Unit tests for all utilities
- Integration tests for API endpoints

Context Block Best Practices

Keep blocks focused: One topic per block for easier management
Use clear names: Names should indicate content at a glance
Set appropriate priority: Don't make everything critical
Update regularly: Context should evolve with your project
Structure with markdown: Use headings, lists, and formatting

Messages: The Communication Layer

Messages are the lifeblood of swarm communication. They flow between humans and agents in real-time, creating a collaborative dialogue that drives task completion.

Message Types

Human Messages

Messages from users directing, questioning, or providing information to the swarm. These are the primary way you interact with your agents.

Agent Messages

Responses from AI agents, containing analysis, content, questions, or tool execution results. Each agent message is cryptographically signed.

System Messages

Platform-generated notifications about events like agent joining/leaving, tool execution status, or swarm settings changes.

Message Anatomy

Every message in HIVE Protocol contains:

interface Message {
  id: string;              // Unique identifier
  swarm_id: string;        // Which swarm this belongs to
  sender_type: 'human' | 'agent' | 'system';
  sender_id: string;       // User ID or Agent ID
  content: string;         // The message text
  created_at: timestamp;   // When it was sent
  metadata: {
    model?: string;        // AI model used (for agents)
    tokens?: number;       // Token count
    tools_used?: string[]; // Any tools invoked
  };
  signature?: string;      // Cryptographic signature
  verified?: boolean;      // Signature verification status
}

Cryptographic Message Signing

Every agent message is cryptographically signed using HMAC-SHA256. This provides:

Authenticity: Proves the message came from the claimed agent

Integrity: Verifies the content hasn't been modified

Non-repudiation: Creates an audit trail of agent outputs

Message Creation:
┌─────────────────────────────────────────────────┐
│  1. Agent generates response content             │
│  2. System creates signature payload:            │
│     payload = agent_id + content + timestamp     │
│  3. Sign with swarm's secret key:                │
│     signature = HMAC-SHA256(payload, secret)     │
│  4. Attach signature to message                  │
│  5. Deliver to swarm                             │
└─────────────────────────────────────────────────┘

Message Verification:
┌─────────────────────────────────────────────────┐
│  1. Extract signature from message               │
│  2. Recreate payload from message data           │
│  3. Compute expected signature                   │
│  4. Compare: signature == expected?              │
│  5. Mark as verified (✓) or unverified (!)       │
└─────────────────────────────────────────────────┘

Verified messages display a checkmark badge in the interface, giving you confidence in the authenticity of agent outputs.

Real-Time Streaming

Messages stream to the interface in real-time as agents generate responses. You'll see:

Typing indicators: Which agent is currently thinking
Progressive rendering: Content appears as it's generated
Instant delivery: No waiting for complete responses
Live collaboration: Multiple agents can respond in sequence

Tools: Extending Agent Capabilities

Tools give agents the ability to interact with the world beyond conversation. They can search the web, execute code, call APIs, and integrate with external services.

Built-in Tools

HIVE Protocol provides several ready-to-use tools:

Tool	Capability	Example Use
Web Search	Query search engines	Find current information
Code Execution	Run code snippets	Calculate, transform data
API Caller	Make HTTP requests	Integrate external services
File Reader	Access file content	Process documents

Tool Definition Structure

Tools are defined using a JSON schema format:

interface ToolDefinition {
  name: string;           // Identifier (snake_case)
  description: string;    // What the tool does
  parameters: {           // Input schema
    type: 'object';
    properties: {
      [key: string]: {
        type: string;
        description: string;
        required?: boolean;
        enum?: string[];  // For fixed options
      }
    };
    required: string[];
  };
}

Custom Tool Example

Here's a complete custom tool definition:

{
  "name": "check_inventory",
  "description": "Check product inventory levels in the warehouse system",
  "parameters": {
    "type": "object",
    "properties": {
      "product_id": {
        "type": "string",
        "description": "The SKU or product identifier"
      },
      "warehouse": {
        "type": "string",
        "description": "Warehouse location code",
        "enum": ["NYC", "LAX", "ORD", "ALL"]
      }
    },
    "required": ["product_id"]
  }
}

How Agents Use Tools

When an agent determines it needs to use a tool:

Decision: Agent analyzes the task and decides a tool would help
Invocation: Agent constructs a tool call with appropriate parameters
Execution: HIVE Protocol executes the tool securely
Response: Tool results are returned to the agent
Integration: Agent incorporates results into its response

User: "What's the current stock price of Apple?"

Agent thinking: "I need current data. I'll use web_search."

Tool call: web_search({ query: "AAPL stock price today" })

Tool result: "AAPL: $178.72, +1.23 (+0.69%)"

Agent response: "Apple (AAPL) is currently trading at $178.72,
up $1.23 (0.69%) today..."

Putting It All Together

These concepts work together to create powerful AI workflows:

┌─────────────────────────────────────────────────────────┐
│                    Your Workflow                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  You create AGENTS with specific roles and capabilities │
│              ↓                                          │
│  You assemble agents into a SWARM for collaboration     │
│              ↓                                          │
│  You add CONTEXT BLOCKS with relevant information       │
│              ↓                                          │
│  You send MESSAGES to initiate and guide work           │
│              ↓                                          │
│  Agents use TOOLS to accomplish real-world tasks        │
│              ↓                                          │
│  Results flow back as verified, signed messages         │
│                                                         │
└─────────────────────────────────────────────────────────┘

Example Workflow: Content Creation

Create agents: Research Agent + Writer Agent + Editor Agent
Create swarm: "Blog Content Production"
Add context: Brand guidelines, target audience, topic list
Send message: "Write a blog post about AI in healthcare"
Research Agent: Gathers information and trends
Writer Agent: Creates first draft from research
Editor Agent: Reviews and polishes the content
Result: Publication-ready blog post

Next Steps

Now that you understand the core concepts, you're ready to dive deeper:

Immediate Next Steps

[Creating Agents](/docs/agents/creating-agents): Master agent configuration
[Creating Swarms](/docs/swarms/creating-swarms): Build effective teams
[Agent Tools](/docs/agents/agent-tools): Extend capabilities

Advanced Topics

[System Prompts](/docs/agents/system-prompts): Write effective prompts
[Agent Coordination](/docs/swarms/agent-coordination): Multi-agent patterns
[Human-in-the-Loop](/docs/swarms/human-in-loop): Control strategies

Reference Material

[API Reference](/docs/api/authentication): Build integrations
[Security](/docs/security/message-signing): Understand protections

Core Concepts

Core Concepts

Agents: The Building Blocks

Agent Anatomy

How Agents Process Information

Agent Types and Specializations

Agent Reusability

Swarms: Collaborative Environments

Swarm Architecture

Collaboration Modes

Swarm Lifecycle

Context Blocks: Shared Knowledge

Context Block Properties

Priority Levels Explained

Effective Context Block Examples

Context Block Best Practices

Messages: The Communication Layer

Message Types

Message Anatomy

Cryptographic Message Signing

Real-Time Streaming

Tools: Extending Agent Capabilities

Built-in Tools

Tool Definition Structure

Custom Tool Example

How Agents Use Tools

Putting It All Together

Example Workflow: Content Creation

Next Steps

Immediate Next Steps

Advanced Topics

Reference Material

Cookie Preferences