ai-sdk-ragflow

Ragflow workflow transport for AI SDK UI.

Target:

• import path: ai-sdk-ragflow/024
• Ragflow line: 0.24.x
• internal workflow APIs under /v1
• ESM only

Not included:

• public /api/v1
• reconnect/resume stream
• workflow regenerate

Install

pnpm add ai @ai-sdk/vue ai-sdk-ragflow

Quick Start

<script setup lang="ts">
import type { UIMessage } from 'ai'
import { Chat } from '@ai-sdk/vue'
import {
  RagflowWorkflowChatTransport,
  type RagflowWorkflowDataParts,
  type RagflowWorkflowMessageMetadata,
} from 'ai-sdk-ragflow/024'
import { ref } from 'vue'

const transport = new RagflowWorkflowChatTransport({
  canvasId: 'canvas_123',
  apiBase: '/v1',
  credentials: 'same-origin',
})

const input = ref('')
const chat = new Chat<
  UIMessage<RagflowWorkflowMessageMetadata, RagflowWorkflowDataParts>
>({
  transport,
})

function handleSubmit(event: Event) {
  event.preventDefault()
  chat.sendMessage({ text: input.value })
  input.value = ''
}
</script>

<template>
  <form @submit="handleSubmit">
    <input v-model="input" placeholder="Ask Ragflow..." />
  </form>
</template>

Surface

• RagflowWorkflowChatTransport
• RagflowWorkflowChatTransportOptions
• RagflowWorkflowApiConfig
• RagflowWorkflowMessageMetadata
• RagflowWorkflowDataParts
• transport-facing citation, await-input, workflow-event, final-output, and attachment types

Data part names:

• data-ragflow-citations
• data-ragflow-workflow-events
• data-ragflow-await-inputs
• data-ragflow-final-output
• data-ragflow-audio

Endpoint

• POST /v1/canvas/completion
• transport always sends id: canvasId in the request body
• target is the internal Ragflow workflow endpoint that exposes the full workflow event stream

Await-Input Resume

When Ragflow pauses on user_inputs, the transport emits data-ragflow-await-inputs and marks the assistant metadata as awaiting structured input.

Resume is caller-managed. Send the next request with body.inputs:

chat.sendMessage(
  { text: 'Approve with note' },
  {
    body: {
      inputs: {
        approval: 'approved',
        note: 'ship it',
      },
    },
  },
)

The transport forwards body.inputs unchanged. Whether a fresh request can continue a paused workflow depends on your Ragflow setup and application flow.

Out Of Scope

This package does not ship helper/client APIs for:

• file upload
• server-side task cancel
• trace fetch
• TTS
• document download

Callers handle those endpoints directly.

Docs

• Overview
• API
• Integration
• Limitations

Fixture Script

Package includes workflow-fixture script:

pnpm fixtures:ragflow --dry-run
pnpm fixtures:ragflow --cookie "session=..."
pnpm fixtures:ragflow --mode all-agent

Purpose:

• create real Ragflow canvases from upstream templates
• build broad node coverage for transport testing
• write run manifest to tests/manifest.json

Modes:

• coverage
  • smallest broad set
  • good first run
• all-agent
  • all upstream agent/workflow templates
  • biggest real-world set
• names
  • exact templates from repeated --template

Manifest contains:

• Ragflow base URL and API base
• template source file and template id
• created canvas id
• graph node types
• nested tool types
• expected SSE feature hints

tests/manifest.json is gitignored. Generate locally when you want live integration coverage.

Tests

Default test run stays local-only:

pnpm test

Always-on tests:

• transport unit tests with mocked Ragflow SSE sequences
• manifest structure tests, but only if tests/manifest.json exists

Live Ragflow tests are opt-in. They run only when both conditions hold:

1. tests/manifest.json exists
2. auth env exists: RAGFLOW_COOKIE or RAGFLOW_BEARER_TOKEN / RAGFLOW_TOKEN

Example:

pnpm fixtures:ragflow --cookie "session=..."
RAGFLOW_COOKIE="session=..." pnpm test