`useAgentSession()` hook

useAgentSession() is the entry hook for the agents surface. It resolves the current agent session, returns the actor and the available agents for that session, and optionally exchanges a ticket before it loads the session.

Usage

The following example shows a basic usage of useAgentSession().

import { useAgentSession } from '@wacht/nextjs';export default function AgentShell({  ticket,}: {  ticket?: string | null;}) {  const {    hasSession,    sessionLoading,    sessionError,    actor,    agents,    ticketExchanged,  } = useAgentSession(ticket);  if (sessionLoading) {    return <div>Loading agent session...</div>;  }  if (!hasSession || sessionError) {    return <div>Access required</div>;  }  return (    <div>      <h1>{actor?.display_name ?? 'Actor'}</h1>      <p>{agents.length} agents available</p>      {ticket ? <p>Ticket exchanged: {String(ticketExchanged)}</p> : null}    </div>  );}

Return value

The hook returns the following fields and methods.

›

ticket?: string | null | undefined | undefined;

Optional session ticket. When present, the hook tries to exchange it once before it fetches the agent session.

›

hasSession?: boolean | undefined;

Whether the current user has a valid agent session.

›

sessionLoading?: boolean | undefined;

True while the ticket exchange or the session fetch is still in flight.

›

sessionError?: Error | null | undefined;

Transport or exchange failure. Missing-session responses are not exposed here.

›

sessionId?: string | null | undefined;

Session identifier from the loaded agent session.

›

actor?: Actor | null | undefined;

Current actor that owns the agent session.

›

id?: string | undefined;

Actor identifier.

›

subject_type?: string | undefined;

Actor subject type.

›

external_key?: string | undefined;

External actor key.

›

display_name?: string | undefined | undefined;

Display name for the actor when one is present.

›

deployment_id?: string | undefined | undefined;

Deployment identifier when attached to the actor.

›

agents?: Agent[] | undefined;

Agents available to the current session.

›

id?: string | undefined;

Agent identifier.

›

name?: string | undefined;

Human-readable agent name.

›

description?: string | undefined;

Optional agent description.

›

child_agents?: Agent[] | undefined | undefined;

Nested child agents when the deployment exposes them.

›

ticketExchanged?: boolean | undefined;

Whether the supplied ticket has already been exchanged successfully.

›

ticketLoading?: boolean | undefined;

Whether the hook is still exchanging the supplied ticket.

›

refetch?: () => Promise<void> | undefined;

Revalidates the loaded agent session.

Overview

The hook has two jobs. First, when a ticket is present, it exchanges that ticket once and waits for the exchange to finish. After that, it loads the current /ai/session state and keeps the resulting actor and agent list in memory through SWR.

When to use it

Use useAgentSession() at the boundary where your agents product becomes available, not deep inside every thread or project screen. It is the hook you use when you are building your own agent workspace and you want one place to resolve the session, the current actor, and the available agents before the rest of the UI mounts.

That is the right pattern when your app has a distinct agents area. Let this hook answer access, actor identity, and available-agent questions at the top of that area, then let the deeper hooks focus on projects, threads, tasks, and conversation state.

Integration pattern

A common pattern is to read the ticket from the URL at the layout boundary, pass it into useAgentSession(ticket), and then remove the query param after ticketExchanged becomes true. The rest of the agents UI can then read hasSession, actor, and agents from your own provider instead of calling the hook again in every page.

useAgentSession() hook