RAGFlow

Configure Future AGI trace export in a self-hosted, Future AGI-enabled RAGFlow deployment.

Send RAGFlow chat turns, retrieved documents and model calls to Future AGI Observe from RAGFlow’s settings. You do not need to add instrumentation code to your chats.

Upstream status: We have proposed Future AGI tracing in infiniflow/ragflow#22183, which is under review. Until it is merged and released, use the Future AGI-enabled build below. If the contribution ships in a RAGFlow release, stock images of that release will include the Future AGI settings card.

Prerequisites

  • A Linux x86-64 self-hosted deployment using RAGFlow’s Go backend, MySQL, Infinity, MinIO, Kvrocks and NATS.
  • Docker with Buildx to build the application image below, and Docker Compose for the deployment.
  • A chat model and an embedding model configured in RAGFlow, with your own provider credentials.
  • Your Future AGI API key and secret key, available in Settings → API keys, and an Observe project name.

Stock RAGFlow v1.0.0 images do not include this exporter. Installing a traceAI package in a stock image does not add the Future AGI settings card.

Build the Future AGI-enabled image

Build this pinned commit from the Future AGI fork’s contrib/futureagi-tracing branch. It is based on upstream development after v1.0.0. The commands use the public npm registry instead of the checkout’s npm mirror, without changing locked package versions or integrity hashes. Build the Go and web targets in sequence to reduce peak memory use, then assemble the production image:

git init ragflow-futureagi
git -C ragflow-futureagi remote add origin https://github.com/future-agi/ragflow.git
git -C ragflow-futureagi fetch --depth 200 origin 9b2bcb1d1864c75e35ed7d06d3e750725547290e
git -C ragflow-futureagi fetch --depth 200 https://github.com/infiniflow/ragflow.git tag v1.0.0
git -C ragflow-futureagi checkout --detach 9b2bcb1d1864c75e35ed7d06d3e750725547290e
sed -i 's#https://registry\.npmmirror\.com#https://registry.npmjs.org#g' ragflow-futureagi/web/.npmrc ragflow-futureagi/web/package-lock.json
docker buildx build --network host --build-arg GOPROXY=https://proxy.golang.org,direct --target go-builder --file ragflow-futureagi/Dockerfile ragflow-futureagi
docker buildx build --network host --target web-builder --file ragflow-futureagi/Dockerfile ragflow-futureagi
docker buildx build --load --network host --build-arg GOPROXY=https://proxy.golang.org,direct --target production --tag ragflow-futureagi:9b2bcb1d --file ragflow-futureagi/Dockerfile ragflow-futureagi

Use the pinned checkout’s deployment configuration, not configuration from an older release:

  1. In ragflow-futureagi/docker/.env, set RAGFLOW_IMAGE=ragflow-futureagi:9b2bcb1d and DOC_ENGINE=infinity. Keep the matching dependency versions: this checkout uses Infinity v0.7.5 (infiniflow/infinity:v0.7.5-x64-v3).
  2. Set deployment-specific service passwords, including ADMIN_DEFAULT_PASSWORD, before first startup. Restrict the Admin port to trusted administrators.
  3. Start the services with docker compose -f ragflow-futureagi/docker/docker-compose.yml up -d. Keep this checkout pinned; do not follow a release-checkout step that replaces it with stock v1.0.0.

The image applies database migrations before starting the Go services. Evaluate this unreleased build in a separate deployment and database before migrating an existing installation, and back up its metadata and document stores. Do not downgrade a database migrated by a newer build. Keep the release tag and Git history when building so the image’s version can be compared with the database version. Do not disable the database version guard to make a mismatched deployment start.

Configure trace export

  1. In RAGFlow, open your avatar menu → API and scroll to Future AGI.

  2. On the Future AGI card, select Configuration.

  3. Fill in the following fields:

    FieldValue
    API keyYour Future AGI API key
    SECRET KEYThe matching Future AGI secret key
    Observe projectThe project name to use for these traces
    EndpointLeave blank for https://api.futureagi.com, or enter your self-hosted collector origin
    Redact contentEnable to omit question, answer, prompt and retrieved text, document names and web URLs
  4. Select Save. RAGFlow checks the collector connection and credentials before saving.

Enter a collector endpoint you trust, not a Langfuse URL. RAGFlow sends OTLP/HTTP to /tracer/v1/traces and manages the authentication headers itself. The Future AGI and Langfuse configurations are independent. Use HTTPS outside a trusted local network; the exporter rejects redirects and does not use environment HTTP proxies.

Configuration is per tenant. Saved keys are masked when you reopen the dialog. Leave the key fields blank to keep the saved keys when editing the project or redaction setting; enter both keys again when changing the endpoint.

Use a private collector

Private, loopback and link-local collector addresses are blocked by default, both when saving settings and on every export. For a private collector, the operator must set ALLOW_ANY_HOST=true in the RAGFlow server container’s environment and recreate the container. With the Compose deployment above, add it to ragflow-futureagi/docker/.env and run docker compose -f ragflow-futureagi/docker/docker-compose.yml up -d --force-recreate ragflow-cpu.

This is a deployment-wide opt-in that also relaxes the shared host policy for other guarded outbound integrations. It is not a tenant setting or a collector-specific allowlist. Enable it only when your deployment’s network and egress controls permit those destinations. Future AGI Cloud does not require this opt-in. A loopback address refers to the RAGFlow container itself, not the Docker host.

Choose what to capture

Content capture is on by default: questions, answers, model prompts, retrieved text, document names and web URLs can be sent to Future AGI. Enable Redact content before sending sensitive data. Redaction keeps identifiers, retrieval scores, model names, token counts, status and timing while removing those content fields.

Provider error bodies are never exported, even with content capture on. Failed turns use a fixed failure message instead of provider error details, which can contain credentials.

RAGFlow stores these credentials in plaintext database columns. Restrict database access and protect its backups; masked fields in the settings dialog do not encrypt stored credentials.

Send a chat and inspect its trace

Open a RAGFlow chat connected to a dataset with an ingested document, and ask a question answered by that document. Then open Observe in Future AGI and select the project name you saved.

Expand the chat trace:

  • ragflow.chat — the chat turn and its result.
  • ragflow.retrieval — retrieved text, document identifiers and similarity scores when the turn performs retrieval.
  • ragflow.llm — the model call, messages, answer and token counts.

Token counts are RAGFlow’s tokenizer estimates, not provider billing totals. This setup traces the Go chat pipeline, including streaming. Agentic chat has a turn-level trace; internal agent tools, individual reasoning calls, ingestion and standalone retrieval are not instrumented.

Troubleshooting

The Future AGI card is missing

Check the deployed application image and the upstream status above. Use the Future AGI-enabled build until a RAGFlow release includes the contribution. An SDK installation alone cannot enable it.

Saving the configuration fails

Check the API key/secret key pair and the collector origin. The RAGFlow server must be able to reach the collector over the network, and private destinations require the operator opt-in above. When changing the endpoint, re-enter both keys rather than copying the masked values from a previous save.

Chats work but traces are missing

Check the Observe project name and the collector connection, then send a new chat. Export is asynchronous: an unreachable collector or a full queue can drop traces without interrupting chat. Shutdown attempts a bounded flush, but a hard shutdown can lose queued traces; this exporter is not a durable audit log.

Was this page helpful?

Questions & Discussion