RAGfly — AGENTS.md

Place this file in the root of the agent's workspace.

What is RAGfly

Multi-tenant RAG (Retrieval-Augmented Generation) infrastructure accessible via MCP and REST. It indexes an organization's documents and exposes them to AI agents with full tenant (group) isolation and area-based access control.

Base URL: $RAGFLY_API_URL
MCP server: https://api.ragfly.ai/mcp-http/
OpenAPI docs: $RAGFLY_API_URL/docs

MCP (recommended for Codex)

If the MCP server is configured, always use MCP tools instead of direct REST:

# Configure (once)
codex mcp add ragfly \
  --url https://api.ragfly.ai/mcp-http/ \
  --bearer-token-env-var RAGFLY_API_KEY

Always call first:

mcp__ragfly__estado_sesion()

Confirms the connection and returns the active tenant context.

Main tools:

• mcp__ragfly__estado_sesion() — verify connection
• mcp__ragfly__buscar_chunks(q, limite) — semantic search
• mcp__ragfly__listar_documentos(estado, limite) — list documents
• mcp__ragfly__preguntar(texto) — full RAG question with citations

If MCP is not available, use the REST endpoints documented below.

Required environment variables

RAGFLY_API_URL=https://api.ragfly.ai
RAGFLY_API_KEY=slm_live_...

Authentication

Include in every request:

Authorization: Bearer <RAGFLY_API_KEY>

Alternative (short-lived JWT):

Authorization: Bearer <JWT obtained from POST /auth/login>

Main endpoints

Verify session

GET /auth/me

Returns grupo_activo, entidad_activa, rol_principal, tipo_acceso. Always call first to confirm the API Key is valid.

List documents

GET /documentos/paginado
  ?codigo_estado_doc=VECTORIZADO   # only docs with embeddings (ready for RAG)
  &limit=20
  &page=1
  &q=<text>                        # search by name (optional)

Semantic search (central endpoint)

POST /documentos/buscar-semantico
Content-Type: application/json

{
  "q": "<natural language question>",  # required
  "limit": 5,                          # chunks to return
  "min_similitud": 0.0,                # threshold 0–1 (optional)
  "id_espacio": null,                  # filter by Workspace (optional)
  "ids_documento": null                # filter by specific IDs (optional)
}

View a document

GET /documentos/{codigo_documento}

List workspaces

GET /espacios-trabajo/paginado?limit=10

Pipeline state

GET /cola-estados-docs/paginado?limit=10

Python usage pattern

import os, httpx

BASE    = os.environ["RAGFLY_API_URL"]
HEADERS = {"Authorization": f"Bearer {os.environ['RAGFLY_API_KEY']}"}

def me():
    return httpx.get(f"{BASE}/auth/me", headers=HEADERS).raise_for_status().json()

def search(q: str, limit: int = 5) -> list:
    return httpx.post(
        f"{BASE}/documentos/buscar-semantico",
        headers=HEADERS,
        json={"q": q, "limit": limit},
    ).raise_for_status().json().get("resultados", [])

def list_docs(limit: int = 20) -> list:
    return httpx.get(
        f"{BASE}/documentos/paginado",
        headers=HEADERS,
        params={"codigo_estado_doc": "VECTORIZADO", "limit": limit},
    ).raise_for_status().json().get("items", [])

Security invariants

• The API Key operates exclusively on the corpus of the tenant that issued it.
• RBAC (group, entity, area) is resolved from the key — not sent in the body.
• A key can never access data from another group, even with specifically crafted queries.

Document state reference

VECTORIZADO → ready for RAG
CHUNKEADO → processed but no embeddings yet
ESCANEADO → text extracted, pending chunking
METADATA → metadata only
CARGADO → just uploaded
NO_ESCANEABLE → format not processable