Add useWorkflow hook for consuming llama-deploy workflows #19

New Issue

2026-02-16T02:17:43-05:00

yindo commented

2026-02-16 02:17:43 -05:00

Originally created by @marcusschiesser on GitHub (Jun 10, 2025).

Originally assigned to: @thucpn on GitHub.

Spec

/** The Hook! */
function useWorkflow<
  I extends WorkflowEvent = AnyWorkflowEvent,
  O extends WorkflowEvent = AnyWorkflowEvent
>(params: WorkflowHookParams<O>): WorkflowHookHandler<I, O> {
  // ???
}

/** This is the input argument to the hook */
interface WorkflowHookParams<O extends WorkflowEvent = AnyWorkflowEvent> {
  /** the name of the registered workflow on the llama_deploy server */
  workflow: string;
  /** An already instantiated workflow, for resumption */
  taskId?: string;
  /** 
    * callback triggered on receipt of the StopEvent, signalling completion.
    * this event will also be the last event in the list
    */
  onStopEvent?: (event: O) => void;
  /**
    * callback triggered when the workflow has a fatal error.
    * Not sure if llama_deploy communicates errors yet?
    */
  onError?: (tbd: any) => void;
  // an optional base url for the workflow API
  baseUrl?: string;
}


/** This is the return value from the hook */
interface WorkflowHookHandler<
  I extends WorkflowEvent = AnyWorkflowEvent,
  O extends WorkflowEvent = AnyWorkflowEvent,
> {
  /** The task ID, once the workflow session is started */
  taskId?: string
  /** List of all events fired so far. Includes input events sent by the client
    * streamed and result events from the workflow. 
    * Concatenated when new events.
    * Oldest event is at the start (time ascending order)
    */
  events: (I | O)[];
  /** all events before this index were backfilled from a workflow resumption. */
  backfillIndex: number;
  /** 
    * true after the workflow is currently completed. The workflow can be started
    * again after completing by sending a start event. This will return back to
    * false when restarted.
    */
  isComplete: boolean;
  /** true if the workflow had a fatal error */
  isError: boolean;
  /** Manually trigger an event, promise resolves after the event is acked by the server */
  sendEvent(event: I): Promise<void>;
}

/** A generic interface for WorkflowEvents. define sub instances to get more specific fields */
interface WorkflowEvent {
  name: string; // the python class name of the event, for switching on
} 

// Default workflow event, so you can get or send events without specifying a sub-type
interface AnyWorkflowEvent extends WorkflowEvent {
  [key: string]: any // any json value
}

Example

/** A component that starts with a file, the assistant thinks about it and gives a summary. Then normal chat after that */
function AnnotatedChatTriggeredByFileUpload(props: ) {
   
   const taskId = useMemo(() => /* check local storage for existing chat */)
   const handler = useWorkflow({
     workflow: "ChatWithFile",
     taskId,
   })
   const [file, setFile] = useState();
   
   useEffect(() => {
     if (handler.taskId && file) {
        // send a file whenever a one one is set.
        handler.sendEvent({name: "AnalyzeFile", file: file })
     }
     
   }, [handler.taskId, taskId, file])
   
   if (!handler.taskId) return <Loading />
   if (!file && !handler.events.length)
        return <FilePicker onFile={setFile} ]>
   
   return (<>
     <ShowEvents events={handler.events} />
     {handler.complete && <ChatInput onSubmit={(text) => handler.sendEvent({name: "Chat", content: text })} />}
   </>)
  
}

function ShowEvents({events: AnyWorkflowEvent[]}) {
   
   return events.map(x => <ShowEvent event={x} />)
}

function ShowEvent({event: AnyWorkflowEvent}) {
  if (event.name === "AnalyzeFile") {
    return <FileIcon name={event.file.name} />
  }
  if (event.name === "Thinking") {
     return <ThinkingBubble message={event} />
  }
  if (event.name === "FileReport") {
     return <FileReport data={event.data} />
  }
  // ...
  return null;

}

Originally created by @marcusschiesser on GitHub (Jun 10, 2025). Originally assigned to: @thucpn on GitHub. ## Spec ```ts /** The Hook! */ function useWorkflow< I extends WorkflowEvent = AnyWorkflowEvent, O extends WorkflowEvent = AnyWorkflowEvent >(params: WorkflowHookParams<O>): WorkflowHookHandler<I, O> { // ??? } /** This is the input argument to the hook */ interface WorkflowHookParams<O extends WorkflowEvent = AnyWorkflowEvent> { /** the name of the registered workflow on the llama_deploy server */ workflow: string; /** An already instantiated workflow, for resumption */ taskId?: string; /** * callback triggered on receipt of the StopEvent, signalling completion. * this event will also be the last event in the list */ onStopEvent?: (event: O) => void; /** * callback triggered when the workflow has a fatal error. * Not sure if llama_deploy communicates errors yet? */ onError?: (tbd: any) => void; // an optional base url for the workflow API baseUrl?: string; } /** This is the return value from the hook */ interface WorkflowHookHandler< I extends WorkflowEvent = AnyWorkflowEvent, O extends WorkflowEvent = AnyWorkflowEvent, > { /** The task ID, once the workflow session is started */ taskId?: string /** List of all events fired so far. Includes input events sent by the client * streamed and result events from the workflow. * Concatenated when new events. * Oldest event is at the start (time ascending order) */ events: (I | O)[]; /** all events before this index were backfilled from a workflow resumption. */ backfillIndex: number; /** * true after the workflow is currently completed. The workflow can be started * again after completing by sending a start event. This will return back to * false when restarted. */ isComplete: boolean; /** true if the workflow had a fatal error */ isError: boolean; /** Manually trigger an event, promise resolves after the event is acked by the server */ sendEvent(event: I): Promise<void>; } /** A generic interface for WorkflowEvents. define sub instances to get more specific fields */ interface WorkflowEvent { name: string; // the python class name of the event, for switching on } // Default workflow event, so you can get or send events without specifying a sub-type interface AnyWorkflowEvent extends WorkflowEvent { [key: string]: any // any json value } ``` ## Example ``` /** A component that starts with a file, the assistant thinks about it and gives a summary. Then normal chat after that */ function AnnotatedChatTriggeredByFileUpload(props: ) { const taskId = useMemo(() => /* check local storage for existing chat */) const handler = useWorkflow({ workflow: "ChatWithFile", taskId, }) const [file, setFile] = useState(); useEffect(() => { if (handler.taskId && file) { // send a file whenever a one one is set. handler.sendEvent({name: "AnalyzeFile", file: file }) } }, [handler.taskId, taskId, file]) if (!handler.taskId) return <Loading /> if (!file && !handler.events.length) return <FilePicker onFile={setFile} ]> return (<> <ShowEvents events={handler.events} /> {handler.complete && <ChatInput onSubmit={(text) => handler.sendEvent({name: "Chat", content: text })} />} </>) } function ShowEvents({events: AnyWorkflowEvent[]}) { return events.map(x => <ShowEvent event={x} />) } function ShowEvent({event: AnyWorkflowEvent}) { if (event.name === "AnalyzeFile") { return <FileIcon name={event.file.name} /> } if (event.name === "Thinking") { return <ThinkingBubble message={event} /> } if (event.name === "FileReport") { return <FileReport data={event.data} /> } // ... return null; } ```

yindo closed this issue

2026-02-16 02:17:43 -05:00

yindo commented

2026-02-16 02:17:43 -05:00

@marcusschiesser commented on GitHub (Jun 10, 2025):

updated llama-deploy backend: https://github.com/run-llama/llama_deploy/pull/536 - run it locally and use baseUrl in useWorkflow to point to the local development

@marcusschiesser commented on GitHub (Jun 10, 2025): updated llama-deploy backend: https://github.com/run-llama/llama_deploy/pull/536 - run it locally and use `baseUrl` in `useWorkflow` to point to the local development

yindo referenced this issue

2026-02-16 02:17:56 -05:00

[PR #19] [MERGED] feat: use DocumentInfo for displaying uploaded file #51

Sign in to join this conversation.

Branches Tags

main

vercel/react-server-components-cve-vu-grfhrf

changeset-release/main

tp/add-custom-markdown-example

tp/eject-bin-make-release-changeset-fail

tp/fix-missing-doc

tp/update-doc

tp/auto-open-chat-canvas

tp/fix-examples

tp/add-more-rechart-examples

ms/use-theme-color

tp/handle-fail-to-parse-chunk

tp/allow-markdown-under-custom-renderer

tp/fix-display-image-in-document-editor

fix/ime-composition-race-condition

tp/fix-warning

ms/workflow-hook-tasks

tp/fix-document-citaion-regex

lee/remove-limit-file-extension

tp/source-nodes-should-from-artifact

tp/document-editor-overflow

tp/fix-document-editor-ui

tp/use-edge-for-demo-chat-api

tp/use-mdxeditor-for-document-editor

tp/document-editor-using-platejs

tp/make-wiki-example-better

tp/fix-release-0.5.0

tp/style-in-example-pages

tp/annotation-custom-render

tp/fix-for-release

tp/render-markdown-in-document-editor

tp/use-multiple-sources-per-message

tp/send-request-data-when-submitting-suggested-questions

tp/using-language-props-to-add-language-extension

tp/latest-tailwindcss-postcss-caused-absolute-paths-for-fontfaces

tp/code-editor

tp/support-canvas

tp/enhance-style-of-chat-ui

tp/fix-document

fix/display-all-sources-from-annotations

fix/css-style

feat/remove-use-client-decorative-in-widgets

ms/use-reflex

feat/implement-llamaindex-chat-ui-components

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: run-llama/chat-ui#19