Oryx provides a set of React hooks for managing chat state, message metadata, retrieval information, and streaming status. All hooks are exported from @contextualai/oryx-react.

useOryx

The primary hook for managing Oryx chat state and streaming lifecycle. Returns control functions and a probe object to pass into Oryx.Root.

const { probe, start, stop, states } = useOryx({ fetcher });

return <Oryx.Root probe={probe}>{/* ... */}</Oryx.Root>;

Parameters:

• fetcher — The fetcher function that handles SSE streaming to your backend.
  

  OryxChatFetcher

• extras — Optional extra data passed to the fetcher (e.g., agentId, auth tokens).
  

  TExtras

Returns:

• probe — The payload object to pass into Oryx.Root.
  

  OryxContextPayload

• start — Start a new chat request with the given prompt.
  

  (prompt: string) => void

• stop — Abort any in-flight streaming immediately.
  

  () => void

• states — A map of message IDs to their respective Oryx states.
  

  Record<string, OryxState>

useOryxStatus

Exposes the streaming status and error state for the current message.

This hook must be used within Oryx.Message.Agent to read the status of the current message properly.

const { isStreaming, error } = useOryxStatus();

• isStreaming — Whether the current message is actively streaming.
  

  boolean

• error — Error object if the streaming pipeline failed.
  

  OryxStreamingError | null

useOryxMessage

Returns identifiers and state for the current message.

This hook must be used within Oryx.Message.Agent to read the metadata of the current message properly.

const { messageId, requestId, conversationId, state } = useOryxMessage();

return (
  <ul>
    <li>Message ID: {messageId}</li>
    <li>Request ID: {requestId}</li>
    <li>Conversation ID: {conversationId}</li>
  </ul>
);

• messageId — Unique identifier for this message turn.
  

  string

• requestId — Upstream request ID from the API.
  

  string | null

• conversationId — Conversation thread ID, persisted across turns.
  

  string | null

• state — Full state object with message, status, and retrieval information.
  

  OryxState

useOryxRetrievals

Returns the list of retrievals for the current message.

This hook must be used within Oryx.Message.Agent to access retrievals properly.

const { retrievals } = useOryxRetrievals();

• retrievals — Array of retrieval items for the current message.
  

  OryxRetrieval[]

useOryxRetrievalItem

Returns the retrieval data for the current item.

This hook must be used within Oryx.Retrievals.List or Oryx.Retrievals.RawList.

const { retrieval } = useOryxRetrievalItem();

• retrieval — The retrieval item data including contentId, number, type, name, and snippet.
  

  OryxRetrieval

useOryxContext

Low-level hook to access the root Oryx context directly. Useful for building custom integrations outside the standard component tree.

Prefer using useOryx for standard use cases. This hook is for advanced scenarios only, where you want to avoid passing helper functions deeply into the component tree, or want to access all states directly.

const { states, start, stop } = useOryxContext();

• states — A map of message IDs to their respective Oryx states.
  

  Record<string, OryxState>

• start — Start a new chat request with the given prompt.
  

  (prompt: string) => void

• stop — Stop all ongoing streaming requests.
  

  () => void

useOryxCurrentStage

Returns the current workflow stage for the message being processed.

This hook must be used within Oryx.Message.Agent to read the current stage properly.

const { currentStage } = useOryxCurrentStage();

• currentStage — Current workflow stage: 'retrieval', 'generation', 'attribution', 'post_processing', or 'finalization'.
  

  OryxSteppingStage | null

useOryxToolCalls

Returns tool call information for the current message, including filtering helpers.

This hook must be used within Oryx.Message.Agent to access tool calls properly.

const { toolCalls, hasToolCalls, activeToolCalls, completedToolCalls, failedToolCalls } = useOryxToolCalls();

• toolCalls — Array of all tool calls for the current message.
  

  OryxToolCall[]

• hasToolCalls — Whether there are any tool calls.
  

  boolean

• activeToolCalls — Tool calls currently executing.
  

  OryxToolCall[]

• completedToolCalls — Tool calls that completed successfully.
  

  OryxToolCall[]

• failedToolCalls — Tool calls that failed.
  

  OryxToolCall[]

useOryxToolCallItem

Returns the tool call data for the current item.

This hook must be used within Oryx.ToolCalls.List.

const { toolCall } = useOryxToolCallItem();

• toolCall — The tool call item data including id, name, arguments, output, status, and error.
  

  OryxToolCall

useOryxThinking

Returns thinking/reasoning step information for the current message.

This hook must be used within Oryx.Message.Agent to access thinking steps properly.

const { thinkingSteps, hasThinking, activeThinking, completedThinking, currentThinking } = useOryxThinking();

• thinkingSteps — Array of all thinking steps for the current message.
  

  OryxThinkingStep[]

• hasThinking — Whether there are any thinking steps.
  

  boolean

• activeThinking — Thinking steps still in progress.
  

  OryxThinkingStep[]

• completedThinking — Thinking steps that have completed.
  

  OryxThinkingStep[]

• currentThinking — The most recent thinking step (useful for showing current thinking).
  

  OryxThinkingStep | null

useOryxThinkingStepItem

Returns the thinking step data for the current item.

This hook must be used within Oryx.Thinking.List.

const { thinkingStep } = useOryxThinkingStepItem();

• thinkingStep — The thinking step item data including id, content, summary, and isCompleted.
  

  OryxThinkingStep

useOryxWorkflowSteps

Returns workflow step information for the current message.

This hook must be used within Oryx.Message.Agent to access workflow steps properly.

const { workflowSteps, hasWorkflowSteps, activeSteps, completedSteps, failedSteps, currentStep } = useOryxWorkflowSteps();

• workflowSteps — Array of all workflow steps for the current message.
  

  OryxWorkflowStep[]

• hasWorkflowSteps — Whether there are any workflow steps.
  

  boolean

• activeSteps — Workflow steps currently running.
  

  OryxWorkflowStep[]

• completedSteps — Workflow steps that completed successfully.
  

  OryxWorkflowStep[]

• failedSteps — Workflow steps that failed.
  

  OryxWorkflowStep[]

• currentStep — The most recent workflow step.
  

  OryxWorkflowStep | null

useOryxWorkflowStepItem

Returns the workflow step data for the current item.

This hook must be used within Oryx.WorkflowSteps.List.

const { workflowStep } = useOryxWorkflowStepItem();

• workflowStep — The workflow step item data including id, name, type, and status.
  

  OryxWorkflowStep

useOryxIntermediateSteps

Returns all intermediate steps (tool calls, thinking, workflow) in chronological order. Useful for building a unified activity log or trajectory view.

This hook must be used within Oryx.Message.Agent to access intermediate steps properly.

const { steps, hasSteps, currentStage } = useOryxIntermediateSteps();

• steps — Array of all intermediate steps sorted by timestamp. Each step has a type ('tool_call', 'thinking', or 'workflow'), data, and timestamp.
  

  OryxIntermediateStep[]

• hasSteps — Whether there are any intermediate steps.
  

  boolean

• currentStage — Current workflow stage.
  

  OryxSteppingStage | null