Improve optional/conditional agent connection pattern in useAgent

[threepointone]

(via cursor/opus, not sure we should do it yet)

Summary

The current useAgent hook requires awkward workarounds when you need a conditional connection (e.g., connect to a room agent only when the user has selected a room). Developers must provide placeholder names and add redundant null checks throughout their code.

Current Behavior

When you want to conditionally connect to an agent, the current pattern looks like this:

const [currentRoom, setCurrentRoom] = useState<string | null>(null);

const room = useAgent<RoomAgent, RoomState>({
  agent: "room-agent",
  name: currentRoom || "unused",  // ← Must provide a name even when disabled
  enabled: !!currentRoom,          // ← Controls whether to actually connect
  onOpen: async () => {
    if (currentRoom) {             // ← Must check again inside callback
      addLog("info", "room_connected", currentRoom);
      await room.call("join", [username]);
    }
  },
  onClose: () => {
    if (currentRoom) {             // ← Must check again
      addLog("info", "room_disconnected");
    }
  },
  onMessage: (message) => {
    if (currentRoom) {             // ← Must check again
      // handle message
    }
  }
});

Problems

1. Fake/placeholder name required

Even when enabled: false, you must provide a valid name prop. This leads to patterns like:

name: currentRoom || "unused"
name: selectedAgent ?? "placeholder"
name: roomId || "no-room"

These placeholder strings are confusing and could accidentally be used if there's a bug in the enabled logic.

2. Repeated null checks in callbacks

Every callback (onOpen, onClose, onMessage, onStateUpdate) needs to re-check the condition because TypeScript doesn't know the callbacks won't fire when disabled:

onOpen: () => {
  if (currentRoom) {  // Redundant but necessary
    // ...
  }
}

3. Confusing return type

The hook always returns an agent object with methods like call(), setState(), etc. When enabled: false:

• What happens if you call room.call("someMethod")?
• Is it a no-op? Does it throw? Does it queue?

This ambiguity leads to defensive coding.

4. No TypeScript help

TypeScript can't narrow the type based on enabled. You get the same return type whether the agent is connected or not.

Real-world use case

From the playground's ChatRoomsDemo.tsx:

// User browses a list of rooms (connected to lobby agent)
// User clicks a room → now need to connect to that specific room agent
// User leaves room → disconnect from room agent

const [currentRoom, setCurrentRoom] = useState<string | null>(null);

// This connection should only exist when currentRoom is set
const room = useAgent({
  agent: "room-agent",
  name: currentRoom || "unused",  // Awkward
  enabled: !!currentRoom,
  // ...
});

Proposed Solutions

Option A: Allow name to be undefined

const room = useAgent({
  agent: "room-agent",
  name: currentRoom,  // undefined = don't connect, no placeholder needed
});

// Hook returns null or a "disconnected" state when name is undefined
if (!room.connected) {
  return <div>Select a room</div>;
}

// TypeScript now knows room is connected
await room.call("join", [username]);

Option B: Separate useOptionalAgent hook

const room = useOptionalAgent({
  agent: "room-agent",
  name: currentRoom,  // null/undefined = returns null
});

if (!room) {
  return <div>Select a room</div>;
}

// TypeScript knows room is non-null and connected
await room.call("join", [username]);

Option C: Discriminated union return type

const room = useAgent({
  agent: "room-agent",
  name: currentRoom || "unused",
  enabled: !!currentRoom,
});

if (room.status === "disabled") {
  // room.call, room.setState are not available in this branch
  return <div>Select a room</div>;
}

// room.status === "connected" | "connecting" | "disconnected"
// room.call is available

Option D: Remove enabled, infer from name

// If name is nullish, don't connect
const room = useAgent({
  agent: "room-agent",
  name: currentRoom,  // null = disabled
});

Recommendation

Option B (separate hook) or Option D (infer from name) seem cleanest:

• No placeholder names
• Clear semantics
• TypeScript can narrow the type
• Existing useAgent behavior unchanged (backward compatible)

Additional Context

This pattern appears in any multi-agent scenario where connections are dynamic:

• Chat applications (join/leave rooms)
• Collaborative editing (connect to document when opened)
• Gaming (join/leave game sessions)
• Support tickets (agent per ticket, connect when viewing)

Related Files

• packages/agents/src/react.tsx - useAgent hook implementation
• examples/playground/src/demos/multi-agent/ChatRoomsDemo.tsx - Real example of the awkward pattern

Backward Compatibility

Any solution should be backward compatible. Existing code using enabled should continue to work.

[threepointone]

some recommendations after analysis:

The current useAgent hook requires awkward workarounds for conditional connections. This proposal allows name to be undefined and adds configurable behavior for method calls when disconnected.

Current Problem

const [currentRoom, setCurrentRoom] = useState<string | null>(null);

const room = useAgent({
  agent: "room-agent",
  name: currentRoom || "unused",  // ← Forced to provide placeholder
  enabled: !!currentRoom,
  onOpen: () => {
    if (currentRoom) { /* redundant check */ }
  }
});

Issues:

1. Must provide fake name when disabled
2. Repeated null checks in every callback
3. Unclear what happens if you call room.call() when disconnected

Proposed Solution

1. Allow name to be undefined

const room = useAgent({
  agent: "room-agent",
  name: currentRoom,  // undefined = not connected yet
});

2. Clear semantics for name + enabled interaction

name	enabled	Result
"foo"	true (default)	Connected
"foo"	false	Disconnected (explicit disable)
undefined	true	Disconnected (waiting for name)
undefined	false	Disconnected

• enabled = "should I try to connect?"
• name = "what should I connect to?"
• Both must be truthy to actually connect
• name: undefined, enabled: true is valid: "ready to connect when name is provided"

3. Configurable behavior for method calls when disconnected

Default: throw immediately

const room = useAgent({ agent: "room-agent", name: undefined });
await room.call("join", [username]);
// Error: "Cannot call method on disconnected agent"

Opt-in: queue with timeout

const room = useAgent({ 
  agent: "room-agent", 
  name: currentRoom,
  whenDisconnected: { 
    behavior: "queue", 
    timeout: 5000  // Reject queued calls after 5s if still disconnected
  }
});

// Call is queued, will execute when connected or reject after timeout
room.call("join", [username]);

whenDisconnected	Behavior
"throw" (default)	Immediately rejects with error
{ behavior: "queue", timeout: 5000 }	Queues, rejects after timeout
{ behavior: "queue", timeout: Infinity }	Queues forever (use carefully)

4. Return type (always returns object)

The hook always returns an agent object (not null) with a connected property:

const room = useAgent({ agent: "room-agent", name: currentRoom });

// Check connection status
if (!room.connected) {
  return <div>Select a room to join</div>;
}

// Safe to call methods
await room.call("join", [username]);

API Changes

interface UseAgentOptions<A, S> {
  agent: string;
  name: string | undefined;  // ← Allow undefined (currently required string)
  enabled?: boolean;  // Keep as-is
  
  // New option
  whenDisconnected?: "throw" | {
    behavior: "queue";
    timeout: number;  // ms, or Infinity
  };
  
  // Existing callbacks unchanged
  onOpen?: () => void;
  onClose?: () => void;
  onMessage?: (message: MessageEvent) => void;
  onStateUpdate?: (state: S) => void;
  onError?: () => void;
}

interface AgentConnection<A, S> {
  // Existing properties
  call: AgentMethodCall<A>;
  setState: (state: S) => void;
  readyState: number;
  // ...
  
  // New property
  connected: boolean;  // ← Easy check for connection status
}

Migration

Before

const room = useAgent({
  agent: "room-agent",
  name: currentRoom || "unused",
  enabled: !!currentRoom,
});

After

const room = useAgent({
  agent: "room-agent",
  name: currentRoom,  // No placeholder needed
});

Backward Compatibility

• Existing code with name: string (always defined) continues to work
• Existing code using enabled continues to work
• Default whenDisconnected: "throw" matches current implicit behavior
• No breaking changes for existing usage patterns

Use Cases

Chat rooms (connect when room selected)

const [roomId, setRoomId] = useState<string | undefined>();
const room = useAgent({ agent: "room-agent", name: roomId });

Toggle connection on/off

const [paused, setPaused] = useState(false);
const agent = useAgent({ 
  agent: "my-agent", 
  name: "instance-1",
  enabled: !paused 
});

Fire-and-forget with queueing

const agent = useAgent({ 
  agent: "analytics-agent", 
  name: sessionId,
  whenDisconnected: { behavior: "queue", timeout: 30000 }
});

// Safe to call immediately, will queue if not connected yet
agent.call("trackEvent", [eventData]);

Open Questions

1. Should connected be a boolean or an enum ("connected" | "connecting" | "disconnected" | "disabled")?

2. For queueing: should there be a max queue size to prevent memory issues?

3. Should we expose a way to manually flush/clear the queue?

4. Should callbacks (onOpen, etc.) still fire when name is undefined? (Probably no)

Related Files

• packages/agents/src/react.tsx - useAgent hook implementation
• examples/playground/src/demos/multi-agent/ChatRoomsDemo.tsx - Real example of the problem