@aimform/agent-sdk

Aimform Agent SDK — React components and hooks for building AI chat interfaces. Drop-in <ChatWidget />, headless hooks, tool-calling, approval prompts, and more. Built on @aimform/identity-sdk.

Installation

npm install @aimform/agent-sdk @aimform/identity-sdk react react-dom

Quick Start

One-line Chat Widget

import { AgentProvider, ChatWidget } from "@aimform/agent-sdk";

function App() {
  return (
    <AgentProvider
      orgId="org_abc123"
      identityUrl="https://identity.aimform.com"
      token={userToken}
    >
      <div style={{ height: "100vh" }}>
        <ChatWidget />
      </div>
    </AgentProvider>
  );
}

Headless Hooks (build your own UI)

import { AgentProvider, useConversation, useMessages, useSendMessage } from "@aimform/agent-sdk";

function CustomChat() {
  const { conversations, createConversation, activeConversationId } = useConversation({
    orgId, identityUrl, token,
  });
  const { messages, loadMessages } = useMessages({
    orgId, conversationId: activeConversationId, identityUrl, token,
  });
  const { sendMessage, sending } = useSendMessage({
    orgId, conversationId: activeConversationId, identityUrl, token,
  });

  // Build your own chat UI
  return (
    <div>
      {messages.map(msg => (
        <div key={msg.id} className={msg.role}>{msg.content}</div>
      ))}
      <input onKeyDown={e => { if (e.key === "Enter") sendMessage(e.target.value); }} />
    </div>
  );
}

Tool Confirmation

import { useToolConfirmation } from "@aimform/agent-sdk";

function ApprovalPrompt() {
  const { pendingConfirmation, approve, deny } = useToolConfirmation();

  if (!pendingConfirmation) return null;

  return (
    <div className="approval-banner">
      <p>Aimform wants to: {pendingConfirmation.name}</p>
      <button onClick={() => approve()}>Approve</button>
      <button onClick={() => deny()}>Deny</button>
    </div>
  );
}

Components

| Component | Description | |-----------|-------------| | <AgentProvider> | Context provider — wraps your app with orgId, identityUrl, token | | <ChatWidget> | Full chat interface — conversation list + messages + input | | <MessageList> | Message list with role-based styling | | <ChatInput> | Chat input with send button |

Hooks

| Hook | Description | |------|-------------| | useConversation() | Create, list, and select conversations | | useMessages() | Load messages for the active conversation | | useSendMessage() | Send messages to the active conversation | | useTools() | Load available tool definitions | | useToolConfirmation() | Handle confirm-tier tool approvals | | useSearch() | Search across Spaces and Entities | | useAgentContext() | Show what the current conversation can see |

Types

import type {
  Message,
  MessageRole,
  ToolCall,
  Conversation,
  ToolDefinition,
} from "@aimform/agent-sdk";

Peer Dependencies

• react ^18.0.0 | ^19.0.0
• react-dom ^18.0.0 | ^19.0.0

License

MIT