Agent Integrator

Quick Start — Vanilla JS/TS

import { BuildShipAgent, z } from "bs-agent/core";

const agent = new BuildShipAgent({
  agentId: "YOUR_AGENT_ID",
  accessKey: "YOUR_ACCESS_KEY", // optional
  baseUrl: "https://your-project.buildship.run",
});

// Simple one-shot
const session = await agent.execute("Hello!", {
  onText: (text) => process.stdout.write(text),
  onComplete: (fullText) => console.log("\nDone:", fullText),
  onError: (err) => console.error(err),
});

Quick Start — React

import { AgentContextProvider, useAgent } from "bs-agent/react";

function App() {
  return (
    <AgentContextProvider>
      <ChatPage />
    </AgentContextProvider>
  );
}

function ChatPage() {
  const {
    messages,
    inProgress,
    handleSend,
    abort,
    sessionId,
    sessions,
    switchSession,
  } = useAgent(
    "agent-id",
    "https://your-project.buildship.run/executeAgent/AGENT_ID",
    "access-key",
  );

  return (
    <div>
      {messages.map((msg, i) => (
        <div key={i} className={msg.role}>
          {msg.content}
        </div>
      ))}
      <button onClick={() => handleSend("Hello!")} disabled={inProgress}>
        Send
      </button>
    </div>
  );
}

Multi-Turn Conversations

// First message returns a session
const session = await agent.execute("What is 2 + 2?", {
  onText: (t) => process.stdout.write(t),
  onComplete: () => console.log(),
});

// Continue with the same session ID
const continued = agent.session(session.getSessionId());
await continued.execute("Now multiply that by 3", {
  onText: (t) => process.stdout.write(t),
  onComplete: () => console.log(),
});

Multimodal Input

The execute() method accepts either a plain string or an array of content parts for sending text alongside images and files:

// Image + text
await agent.execute(
  [
    { type: "text", text: "What's in this image?" },
    { type: "image", data: "https://example.com/photo.jpg", mimeType: "image/jpeg" },
  ],
  callbacks,
);

// File attachment
await agent.execute(
  [
    { type: "text", text: "Summarize this CSV" },
    { type: "file", data: "https://storage.example.com/report.csv", mimeType: "text/csv", filename: "report.csv" },
  ],
  callbacks,
);

Data field accepts: HTTP URLs (https://...), Data URLs (data:image/png;base64,...), or raw base64 strings.

Client Tools

Register tools the agent can invoke on the client side. See Client Tools Reference for full details.

import { BuildShipAgent, z } from "bs-agent/core";

const agent = new BuildShipAgent({ agentId: "..." });

// Fire-and-forget tool
agent.registerClientTool({
  name: "show_notification",
  description: "Display a notification to the user",
  parameters: z.object({
    title: z.string().describe("Notification title"),
    message: z.string().describe("Notification body"),
  }),
  handler: (args) => {
    showNotification(args.title, args.message);
  },
});

// Blocking tool — agent pauses until result is returned
agent.registerClientTool({
  name: "get_location",
  description: "Get the user's current location",
  parameters: z.object({}),
  await: true,
  handler: async () => {
    const pos = await navigator.geolocation.getCurrentPosition();
    return { lat: pos.coords.latitude, lng: pos.coords.longitude };
  },
});

Reference Documentation

• Core API Reference — BuildShipAgent, AgentSession, stream callbacks, events, multimodal input types
• React API Reference — useAgent, useAgentContext, AgentContextProvider, sessions, messages & parts, text modifiers
• Client Tools Reference — headless tools, widget tools, combo tools, pause/resume, useClientTool, ToolRenderer

License

MIT