Outshift Logo

Installation

Complete setup guide for installing and configuring HAX in your project, from initial setup to adding components and connecting external agents.

Overview

Installation

HAX (Human-Agent eXperience) is a modular system that enhances chat interfaces with structured commands, behavioral rules, and external agent integration. This guide walks you through the complete installation process, from setting up the base system to configuring advanced features.

Prerequisites

  • Node.js 18+ and npm
  • An existing React/Next.js project
  • CopilotKit already installed in your project

First, install the HAX core package and CLI tools:

Installation

npm install @outshift-open/hax
npm install -g @outshift-open/hax-cli

Initialize HAX in your project:

Initialize

hax init

This creates:

  • hax/ directory in your project root
  • Base configuration files
  • TypeScript definitions
  • Initial project structure

Configure HAX

The `hax init` command creates a base configuration file at hax/config.ts:

Configuration

export const haxConfig = {
  // Core settings
  version: "1.0.0",
  components: [],

  // Chat interface settings
  chat: {
    enableCommands: false,
    enableFileUpload: false,
    enableRules: false,
  },

  // Adapter settings
  adapter: {
    enabled: false,
    protocol: "REST",
    baseURL: "",
  }
};

Add Components

Use the HAX CLI to add specific components to your project:

Setup

# Add artifacts (UI components that agents can create)
hax add artifact timeline

# Add composers (chat interface enhancements)
hax add composer chat-commands

Integration with Your Chat Interface

After adding components, integrate them into your existing chat interface:

Setup

import { HAXTimeline, useTimelineAction } from "@/hax/artifacts/timeline";

export function ChatWithArtifacts() {
  const [artifacts, setArtifacts] = useState([]);

  // Register timeline actions for AI agents
  useTimelineAction({
    addOrUpdateArtifact: (type, data) => {
      setArtifacts(prev => [...prev, { type, data }]);
    },
    artifacts: artifacts.filter(a => a.type === "timeline")
  });

  return (
    {/* HAX artifacts panel */}
    <div>
      {artifacts.map(artifact => (
        artifact.type === "timeline" && (
          <HAXTimeline
            key={artifact.id}
            title={artifact.data.title}
            items={artifact.data.items}
          />
        )
      ))}
    </div>
  );
}

Set Up With External Agent Adapter

This creates the adapter foundation in hax/adapter/.

Setup

hax add adapter

Set Up With External Agent Adapter

Create your agent-specific adapter by extending the base class:

Agent Specific Adapter setup

 // hax/adapter/my-agent-adapter.ts
import { HAXAdapter } from "@/hax/adapter";
import { CopilotRuntimeChatCompletionRequest } from "@copilotkit/runtime";

export class MyAgentAdapter extends HAXAdapter {
  constructor() {
    super(process.env.AGENT_BASE_URL!, {
      protocol: "REST",
      streamWordDelayMs: 30,
      interMessageDelayMs: 100
    });
  }

  protected buildRestRequest(
    request: CopilotRuntimeChatCompletionRequest,
    threadId: string
  ) {
    return {
      endpoint: "/chat/completions",
      body: {
        messages: request.messages.map(m => ({
          role: m.role,
          content: m.content
        })),
        thread_id: threadId,
        tools: request.actions?.map(action => ({
          name: action.name,
          description: action.description,
          parameters: action.parameters
        })) || []
      }
    };
  }

  protected buildRequestHeaders() {
    return {
      ...super.buildRequestHeaders(),
      "Authorization": `Bearer ${process.env.AGENT_API_KEY}`,
      "Content-Type": "application/json"
    };
  }
}

Configure Runtime

Update your CopilotKit runtime configuration to use the HAX adapter:

Setup

 // app/api/copilotkit/route.ts
import { CopilotRuntime, copilotRuntimeNextJSAppRouterEndpoint } from "@copilotkit/runtime";
import { MyAgentAdapter } from "@/hax/adapter/my-agent-adapter";

const runtime = new CopilotRuntime({
  serviceAdapter: new MyAgentAdapter(),
});

export const POST = copilotRuntimeNextJSAppRouterEndpoint({
  runtime,
  endpoint: "/api/copilotkit",
});

© 2025 Outshift. All Rights Reserved.