useAgent getHttpUrl() returns empty string before WebSocket connects, causing ai-chat to crash

[IsraelHuentecura]

Bug

useAgent() from agents/react returns an agent object where getHttpUrl() returns "" before the WebSocket connection is established. @cloudflare/ai-chat's useAgentChat() then does new URL(agent.getHttpUrl()) (line 516 of react.js) which throws TypeError: Failed to construct 'URL': Invalid URL.

This crashes the component on first render before the WebSocket has time to connect.

Reproduction

import { useAgent } from 'agents/react'
import { useAgentChat } from '@cloudflare/ai-chat/react'

function Chat() {
  const agent = useAgent({ agent: 'my-agent', name: 'test' })
  
  // This crashes immediately because agent.getHttpUrl() returns ""
  // and ai-chat does new URL("") internally
  const chat = useAgentChat({ agent })
  
  return <div>{/* ... */}</div>
}

Root cause

In agents@0.11.4, react.js line 264:

agent.getHttpUrl = () => {
  return (agent._url || agent._pkurl || "").replace("ws://", "http://").replace("wss://", "https://");
};

When neither _url nor _pkurl is set (before WebSocket connects), this returns "".

In @cloudflare/ai-chat@0.4.6, react.js line 516:

const agentUrl = new URL(agent.getHttpUrl());

new URL("") throws TypeError: Invalid URL.

Versions

• agents@0.11.4
• @cloudflare/ai-chat@0.4.6
• @ai-sdk/react@3.0.170

Current workaround

We patch getHttpUrl in our useAgent wrapper to return a placeholder URL:

const nativeGetHttpUrlRef = useRef(theAgent.getHttpUrl)
theAgent.getHttpUrl = () => {
  const url = nativeGetHttpUrlRef.current?.() ?? ''
  return url || 'http://localhost'
}

Suggested fix

Either in agents:

agent.getHttpUrl = () => {
  const raw = (agent._url || agent._pkurl || "");
  if (!raw) return "about:blank"; // or throw a descriptive error
  return raw.replace("ws://", "http://").replace("wss://", "https://");
};

Or in ai-chat:

const rawUrl = agent.getHttpUrl();
const agentUrl = rawUrl ? new URL(rawUrl) : null;
// guard against null agentUrl downstream

[IsraelHuentecura]

We implemented a fix for this in packages/ai-chat/src/react.tsx: IsraelHuentecura@33ce5a0

The fix guards against empty string before calling new URL():

const rawHttpUrl = agent.getHttpUrl();
const agentUrl = rawHttpUrl ? new URL(rawHttpUrl) : null;

We couldn't open a PR because the repo restricts PRs to collaborators. Happy to help if you'd like us to contribute the fix another way.

[threepointone]

oops good catch, will fix. are you doing async queries or something?

[IsraelHuentecura]

Not async queries specifically, the crash happens on the very first React render.

Our setup: the API worker proxies WebSocket connections to the agents worker (app.all('agents/*', (c) => c.env.AGENTS_SERVICE.fetch(c.req.raw))). This adds a small delay to the WebSocket handshake compared to a direct connection.

During that delay, useAgent has already returned an agent object but _url/_pkurl are still undefined. Since useAgentChat runs in the same render and calls new URL(agent.getHttpUrl()) synchronously, it crashes before the WebSocket connects.

In simpler setups (agent on the same worker, no proxy), the WebSocket likely connects fast enough that _url is populated before the first render completes, which is why this hasn't been reported before.

[threepointone]

looking into it right now

[IsraelHuentecura]

Thanks for the quick fix! 🙏 We'll update once the new version is published and remove our workaround.