Skip to content

Upgrade: createHelixChatTransport removed; agent-server's chat routes take a stock client (CP-07) ​

@helix-agents/ai-sdk no longer ships createHelixChatTransport, the browser client for agent-server's native /start, /resume, /sse, /status and /submit-tool-result routes. An app hosted with @helix-agents/agent-server serves its chat from the server's chat routes instead, with ai's own DefaultChatTransport (or useHelixChat over it), as every other host does. Client and server deploy together.

What changed ​

@helix-agents/ai-sdk (major) ​

Removed:

  • createHelixChatTransport, HelixChatTransport, HelixChatTransportOptions;
  • extractToolOutputs (its only user was the transport);
  • HelixPayloadTooLargeError (only the transport threw it).

The transport re-sent the previous user message after a client-tool answer or an approval, sent no approvals, sent no stream cursor, and dropped file parts (CP-07). The chat routes do none of that.

@helix-agents/agent-server (minor) ​

  • POST /chat takes ai's own request body: the session is its id, or a Helix sessionId. A Helix sessionId wins over ai's chat id: the documented prepareHelixChatRequest({ body: { sessionId } }) shape sends both. The session is resolved before the authenticate hook, which sees it as body.sessionId.
  • Both chat routes (POST /chat, GET /chat/{id}/stream) pass the route's request to the chat handler as a web Request (ChatStreamHandler params gain request?: Request). With the documented wiring, handleChatStream gets the client's resume headers (a reconnect resumes from its cursor) and its disconnect.
  • AgentHttpRequest gains an optional signal (the client's disconnect). createExpressAdapter sets it from the response's close; a custom adapter passes its host request's signal (a web Request's signal).

Migrate ​

Server: wire the chat routes to handleChatStream.

ts
import type { UIMessage } from 'ai';
import { handleChatStream } from '@helix-agents/ai-sdk';

const server = new AgentServer({
  agents: { 'my-agent': myAgent },
  stateStore,
  streamManager,
  executor,
  authenticate,
  chatHandler: (params) =>
    handleChatStream(
      { executor, stateStore, streamManager, agent: myAgent },
      { ...params, messages: params.messages as UIMessage[] }
    ),
});

A custom HTTP adapter (for example a Next.js route over createHttpAdapter) passes signal: req.signal on the AgentHttpRequest.

Client: before, then after.

tsx
// Before
const transport = createHelixChatTransport({
  endpoint: '/api/agent',
  sessionId,
  agentType: 'my-agent',
});
const chat = useHelixChat({ transport, toolHandlers });

// After: the chat id is the session id; the route's `chatHandler` names the agent.
const transport = new DefaultChatTransport({ api: '/api/agent/chat' });
const chat = useHelixChat({ id: sessionId, transport, toolHandlers });

Client tools with a plain useChat: auto-send with createHelixSendAutomaticallyWhen() (from @helix-agents/ai-sdk), or with ai's own predicates (lastAssistantMessageIsCompleteWithToolCalls for client-tool answers, OR-ed with lastAssistantMessageIsCompleteWithApprovalResponses when the agent has approval-gated tools; CP-340: the stock tool-calls predicate sends an answer once). Or use useHelixChat.

transport.submitToolResult(...) (submitting an answer while a stream is open) has two replacements:

  • answer through the chat: addToolOutput (or addToolApprovalResponse), which goes back in the next POST /chat;
  • or POST <mount>/chat/{sessionId}/submit-tool-result with the submit body ({ kind: 'client-tool-result', sessionId, toolCallId, result | error }), the same validation and answers as /submit-tool-result.

HelixPayloadTooLargeError: read the typed 413 body instead: parseHelixChatError(chat.error) gives code: 'validation_payload_too_large' with cause, limitBytes and sizeBytes (or state_size_exceeded for the store's limit), and a direct submit's 413 carries the same JSON body.

Request keys stay as they were: useHelixChat keys every send, and agent-server reads X-Helix-Request-Key on /chat.

Unchanged ​

agent-server's native routes (/start, /resume, /sse, /status, /submit-tool-result) and the remote-agent transports (HttpRemoteAgentTransport) are unchanged.

Released under the MIT License.