React Hooks

React hook for connecting to agents with automatic state management

The useAgent hook provides a React-friendly way to connect to agents with automatic cleanup, state synchronization, and reconnection handling.

Installation

npm install agents partysocket

Basic Usage

import { useAgent } from "agents/react";

function ChatRoom() {
  const agent = useAgent({
    agent: "ChatAgent",
    name: "room-123",
    onStateUpdate: (state) => {
      console.log("New state:", state);
    }
  });

  const sendMessage = async () => {
    await agent.call("sendMessage", ["Hello!"]);
  };

  return (
    <button onClick={sendMessage}>
      Send Message
    </button>
  );
}

Hook Options

UseAgentOptions

agent · string · required

Name of the agent class to connect to. Automatically converted from camelCase to kebab-case for the URL.

name · string · default: "default"

Name of the specific agent instance.

host · string

Custom host for the WebSocket connection. Defaults to the current origin.

path · string

Custom path prefix for the connection URL.

query · Record<string, string | null> | (() => Promise<Record<string, string | null>>)

Query parameters to send with the connection. Can be a static object or an async function that returns query parameters.

queryDeps · unknown[]

Dependencies array for the async query function. When any dependency changes, the query function is re-executed.

cacheTtl · number · default: "300000"

Cache TTL in milliseconds for async query results. Default is 5 minutes (300000ms).

onStateUpdate · (state: State, source: 'server' | 'client') => void

Callback invoked when the agent’s state is updated. The source parameter indicates whether the update came from the server or was pushed by the client.

onStateUpdateError · (error: string) => void

Callback invoked when a state update fails (e.g., connection is readonly).

onMcpUpdate · (mcpServers: MCPServersState) => void

Callback invoked when MCP server state is updated.

onIdentity · (name: string, agent: string) => void

Callback invoked when the server sends the agent’s identity on connect. Useful when using basePath, as the actual instance name is determined server-side.

onIdentityChange · (oldName: string, newName: string, oldAgent: string, newAgent: string) => void

Callback invoked when identity changes on reconnect. If not provided and identity changes, a warning will be logged.

onOpen · () => void

Callback invoked when the WebSocket connection opens.

onClose · () => void

Callback invoked when the WebSocket connection closes.

onError · (error: Event) => void

Callback invoked when a WebSocket error occurs.

onMessage · (message: MessageEvent) => void

Callback invoked when a raw WebSocket message is received.

Return Value

The hook returns a PartySocket instance with additional agent-specific properties and methods:

agent · string

The kebab-case agent name.

name · string

The agent instance name.

identified · boolean

Whether the client has received identity from the server.

ready · Promise<void>

Promise that resolves when identity has been received from the server. Resets on connection close.

setState · (state: State) => void

Push state updates to the agent.

call · <T>(method: string, args?: unknown[], streamOptions?: StreamOptions) => Promise<T>

Call a method on the agent.

stub · Proxy

Proxy object for typed method calls.

send · (data: string | ArrayBuffer | Blob) => void

Send raw WebSocket message.

close · () => void

Close the WebSocket connection.

reconnect · () => void

Force reconnection.

Type Safety

Pass your agent class and state type as type parameters for full type safety:

import type { MyAgent, MyAgentState } from "./agents/my-agent";

function MyComponent() {
  const agent = useAgent<MyAgent, MyAgentState>({
    agent: "MyAgent",
    name: "instance-1",
    onStateUpdate: (state) => {
      // state is typed as MyAgentState
      console.log(state.count);
    }
  });

  // Method calls are fully typed
  const handleClick = async () => {
    const result = await agent.stub.processData({ input: "test" });
    // result type is inferred from MyAgent.processData return type
  };

  return <button onClick={handleClick}>Process</button>;
}

State Management

Receiving State Updates

The onStateUpdate callback receives both the new state and its source:

const agent = useAgent({
  agent: "CounterAgent",
  name: "counter-1",
  onStateUpdate: (state, source) => {
    if (source === "server") {
      console.log("Server pushed state:", state);
    } else {
      console.log("Client pushed state:", state);
    }
    setLocalState(state);
  }
});

Pushing State Updates

const incrementCounter = () => {
  agent.setState({ count: localState.count + 1 });
};

When you call setState(), your onStateUpdate callback will fire with source: "client" after the agent broadcasts the update.

Async Query Parameters

For authentication tokens or other async data, use an async query function:

function AuthenticatedChat({ userId }: { userId: string }) {
  const agent = useAgent({
    agent: "ChatAgent",
    name: "chat-room",
    query: async () => {
      const token = await getAuthToken();
      return { token, userId };
    },
    queryDeps: [userId],
    cacheTtl: 60 * 1000 // 1 minute
  });

  // ...
}

1. Query Execution

   The query function is called before establishing the WebSocket connection.

2. Caching

   The result is cached for the duration specified by cacheTtl (default: 5 minutes).

3. Re-execution

   The query is re-executed when:

   • Any value in queryDeps changes
   • The cacheTtl expires
   • The component remounts

Calling Agent Methods

Using call()

const handleSubmit = async () => {
  try {
    const result = await agent.call("createPost", [title, content]);
    console.log("Post created:", result);
  } catch (error) {
    console.error("Failed to create post:", error);
  }
};

Using the Stub Proxy

const handleSubmit = async () => {
  try {
    const result = await agent.stub.createPost(title, content);
    console.log("Post created:", result);
  } catch (error) {
    console.error("Failed to create post:", error);
  }
};

The stub proxy provides better TypeScript inference and a more natural calling syntax.

Streaming Responses

Handle streaming responses with the onChunk, onDone, and onError callbacks:

function AIChat() {
  const [output, setOutput] = useState("");
  const [isStreaming, setIsStreaming] = useState(false);
  const agent = useAgent({ agent: "AIAgent", name: "chat" });

  const handleGenerate = async () => {
    setIsStreaming(true);
    setOutput("");

    await agent.call("generateText", [prompt], {
      onChunk: (chunk) => {
        setOutput((prev) => prev + chunk);
      },
      onDone: () => {
        setIsStreaming(false);
      },
      onError: (error) => {
        setIsStreaming(false);
        console.error("Stream error:", error);
      }
    });
  };

  return (
    <div>
      <button onClick={handleGenerate} disabled={isStreaming}>
        {isStreaming ? "Generating..." : "Generate"}
      </button>
      <pre>{output}</pre>
    </div>
  );
}

Lifecycle Management

Automatic Cleanup

The hook automatically closes the WebSocket connection when the component unmounts:

function TemporaryConnection() {
  const agent = useAgent({
    agent: "MyAgent",
    name: "temp",
    onClose: () => {
      console.log("Connection closed");
    }
  });

  // Connection is automatically closed when component unmounts
  return <div>Connected to {agent.name}</div>;
}

Manual Reconnection

Force a reconnection with the reconnect() method:

const handleReconnect = () => {
  agent.reconnect();
};

Waiting for Identity

Use the ready promise to wait for the agent to send its identity:

const agent = useAgent({
  agent: "MyAgent",
  name: "instance-1"
});

useEffect(() => {
  agent.ready.then(() => {
    console.log(`Connected to ${agent.name}`);
  });
}, [agent]);

Connection Events

Handle connection lifecycle events with callbacks:

const agent = useAgent({
  agent: "MyAgent",
  name: "my-instance",
  onOpen: () => {
    console.log("Connection opened");
  },
  onClose: () => {
    console.log("Connection closed, will auto-reconnect");
  },
  onError: (error) => {
    console.error("Connection error:", error);
  }
});

The client automatically reconnects on connection loss. You do not need to manually handle reconnection logic.

MCP Server Updates

Receive updates about MCP server state:

function MCPStatus() {
  const [mcpServers, setMcpServers] = useState<MCPServersState>({});

  const agent = useAgent({
    agent: "AssistantAgent",
    name: "session",
    onMcpUpdate: (servers) => {
      setMcpServers(servers);
    }
  });

  return (
    <div>
      {Object.entries(mcpServers).map(([id, server]) => (
        <div key={id}>
          <h3>{id}</h3>
          <p>Status: {server.connectionState}</p>
          <p>Tools: {server.tools?.map((t) => t.name).join(", ")}</p>
        </div>
      ))}
    </div>
  );
}

Examples

Real-time Counter

import { useAgent } from "agents/react";
import { useState } from "react";

function Counter() {
  const [count, setCount] = useState(0);

  const agent = useAgent({
    agent: "CounterAgent",
    name: "shared-counter",
    onStateUpdate: (state) => {
      setCount(state.count);
    }
  });

  const increment = () => {
    agent.setState({ count: count + 1 });
  };

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={increment}>Increment</button>
    </div>
  );
}

Authenticated Connection

import { useAgent } from "agents/react";
import { useAuth } from "./hooks/use-auth";

function PrivateChat() {
  const { user } = useAuth();

  const agent = useAgent({
    agent: "PrivateChatAgent",
    name: "private-room",
    query: async () => {
      const token = await getAuthToken();
      return { token, userId: user.id };
    },
    queryDeps: [user.id],
    cacheTtl: 55 * 60 * 1000 // Refresh 5 min before 1 hour expiry
  });

  // ...
}

Streaming AI Response

import { useAgent } from "agents/react";
import { useState } from "react";

function AIAssistant() {
  const [response, setResponse] = useState("");
  const [isGenerating, setIsGenerating] = useState(false);

  const agent = useAgent({
    agent: "AIAgent",
    name: "assistant"
  });

  const handleGenerate = async (prompt: string) => {
    setIsGenerating(true);
    setResponse("");

    await agent.call("generateResponse", [prompt], {
      onChunk: (chunk) => {
        setResponse((prev) => prev + chunk);
      },
      onDone: () => {
        setIsGenerating(false);
      },
      onError: (error) => {
        setIsGenerating(false);
        console.error(error);
      }
    });
  };

  return (
    <div>
      <button
        onClick={() => handleGenerate("Hello!")}
        disabled={isGenerating}
      >
        {isGenerating ? "Generating..." : "Generate"}
      </button>
      <pre>{response}</pre>
    </div>
  );
}

Best Practices

Use Type Parameters

Pass your agent and state types for full type safety and autocomplete.

Handle Reconnection

The hook automatically reconnects. Your onStateUpdate will fire with the latest state on reconnect.

Cache Auth Tokens

Use cacheTtl and queryDeps to optimize auth token fetching.

Clean Up Side Effects

Use useEffect cleanup functions for any side effects triggered by state updates.

See Also

Client SDK Overview

Learn about the full client SDK capabilities

Vanilla JS Client

Use AgentClient in non-React environments