@cuylabs/agent-http

HTTP streaming adapter for the CuyLabs agent stack.

It maps the UI-facing streaming events (text-*, reasoning-*, tool-*, error) and intentionally skips advanced agent-core events that do not have a direct UIMessageStream equivalent (turn-boundary, turn-summary, approvals, interventions, retries, etc.).

This package is intentionally narrow:

• It is a good way to expose an agent over HTTP when your client already speaks the AI SDK v6 chat stream protocol.
• It is not a full generic agent hosting layer, REST API surface, or control plane.
• For broader host/runtime concerns, keep those in your app, use @cuylabs/agent-server, or use the runtime packages.

Installation

npm install @cuylabs/agent-http @cuylabs/agent-core ai
# or
pnpm add @cuylabs/agent-http @cuylabs/agent-core ai

You'll also need at least one AI SDK provider:

npm install @ai-sdk/openai
# or @ai-sdk/anthropic, @ai-sdk/google

Quick Start

// app/api/chat/route.ts (Next.js)
import { createAgent } from "@cuylabs/agent-core";
import { createAgentStreamResponse } from "@cuylabs/agent-http";
import { anthropic } from "@ai-sdk/anthropic";

const agent = createAgent({
  model: anthropic("claude-sonnet-4-20250514"),
  systemPrompt: "You are a helpful assistant.",
});

export async function POST(req: Request) {
  const { messages, id } = await req.json();
  const lastMessage = messages[messages.length - 1];

  if (typeof lastMessage?.content !== "string") {
    return new Response("agent-http expects a plain text user message", {
      status: 400,
    });
  }

  return createAgentStreamResponse(agent, {
    sessionId: id,
    message: lastMessage.content,
  });
}

Then use with AI SDK's useChat():

"use client";
import { useChat } from "@ai-sdk/react";

export function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    api: "/api/chat",
  });

  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>
          {m.role}: {m.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
        <button type="submit">Send</button>
      </form>
    </div>
  );
}

API

createAgentStreamResponse

Creates an HTTP Response with streaming agent events.

function createAgentStreamResponse(
  agent: Agent,
  options: AgentStreamOptions
): Response;

interface AgentStreamOptions {
  sessionId: string;
  message: string;
  abortSignal?: AbortSignal;
  system?: string;
  onFinish?: (result: { response: string; messageId?: string }) => void | Promise<void>;
}

message is plain text. If your HTTP route accepts richer UI message parts, convert or validate them before calling createAgentStreamResponse(...).

createAgentStream

Lower-level API that returns a ReadableStream.

function createAgentStream(
  agent: Agent,
  options: AgentStreamOptions
): ReturnType<typeof createUIMessageStream>;

Use createAgentStream(...) when you need to compose the stream yourself before turning it into a Response.

Boundary

agent-http is best thought of as:

• agent-core -> AI SDK chat stream adapter

It does not own:

• request parsing
• auth
• session storage policy
• non-AI-SDK wire formats
• approval or intervention HTTP APIs

If you need a generic HTTP interface for agents, build that at the app layer and treat createAgentStream(...) as one rendering option.

License

Apache-2.0