HAX

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",
});

Website Terms of Use Privacy PolicyTrademarks

Overview

Installation

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",
});

Website Terms of Use Privacy PolicyTrademarks

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: "",

}

};

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>

);

}

// 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"

};

}

// 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",

});

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: "",

}

};

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>

);

}

// 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"

};

}

// 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",

});