DOCSEARCHbyAlgolia
Submit Docs

Refly Documentation

repository·main·Indexed 25 days ago

https://github.com/refly-ai/refly

Refly is an open-source agent skills builder that transforms business logic (SOPs) into stable, versioned, and executable agent skills. It provides a deterministic runtime and a central skill registry to bridge the gap between raw APIs and intelligent agents. The system includes a VectorSearchService supporting Qdrant and LanceDB backends, a comprehensive VectorFilter union type for complex metadata filtering, and a local observability Trace Stack for distributed tracing, metrics, and log aggregation.

Tokens
56.6K
Snippets
108
Records
345
Agent score
92%

What's inside Refly

  1. Explore Refly Skills Registry

    main
    Refly Skills is an official executable skill registry containing versioned, reusable agent capabilities. Unlike one-off prompts, these are durable infrastructure that can be executed instantly, exported to platforms like Claude Code, or deployed as APIs. You can explore the registry in the official GitHub repository.

  2. Integrate tools and protocols with Refly

    main

    Refly acts as a bridge between your existing enterprise toolchain and agent runtimes. You can ingest data and logic using several methods:

    • Native Tools: Seamless integration with over 3,000 industrial-grade APIs including Stripe, Slack, Salesforce, and GitHub. A full list of supported providers is available in config/provider-catalog.json.
    • MCP Support: Native compatibility with any Model Context Protocol (MCP) server to extend agent capabilities beyond standard APIs.
    • Private Skills Connectors: Securely connect to enterprise databases, custom scripts, and internal systems.

  3. Understand the Credit-Based Usage System

    main

    In the Cloud version of Refly (v0.9.0+), model usage is managed via a unified credit system instead of manual API key configuration:

    • All model types (text, image, audio, and video) consume credits.
    • Manual API key setup is no longer required for standard usage.
    • Early unlimited members retain free access to major models including Kimi, GPT-4.1, and Gemini Pro.

  4. Understand Auto Model Smart Routing

    main

    Auto Model is a virtual model layer that decouples the user's selection from the actual LLM execution. When a user selects "Auto", the system silently routes the request to the best available model based on rules, scene, toolset, and user context.

    Key Characteristics

    • UI Stability: The user always sees "Auto" in the UI, even if the backend model changes.
    • Cost Optimization: Refly can optimize costs without user reconfiguration.
    • Billing: When using Auto routing, billing is calculated using the Auto model's specific credit rates (80 credits/1M input tokens, 400 credits/1M output tokens), regardless of which real model is used for execution.
    • Identification: The utility isAutoModel() (from packages/utils/src/auto-model.ts) identifies this mode by checking if config.modelId === 'auto'.

  5. Export Refly Skills to agent runtimes and platforms

    main

    Once Skills are defined, they can be exported to various environments:

    • AI Coding Tools: Export natively to Claude Code and Cursor, allowing agents to use your versioned Skills as standardized tools.
    • App Builders: Provide logic support for Lovable or custom frontend applications via stateful, authenticated APIs.
    • Automation Hubs: Deploy as intelligent webhooks triggered by platforms like Slack or Microsoft Teams to execute complex SOPs.
    • Agent Frameworks: Direct compatibility with AutoGen, Manus, and custom LangChain/Python stacks.

  6. Understand Programmatic Tool Calling (PTC) Architecture

    main

    PTC (Programmatic Tool Calling) is a design pattern in Refly that replaces standard JSON-schema tool calling with Python code execution in a sandbox. Instead of the model calling tools via function-calling, the model writes Python code that imports a generated SDK and calls tools as class methods.

    Key Advantages:

    • Enables complex multi-step orchestration in a single model turn.
    • Supports batch processing, conditional logic, loops, and in-flight data transformation.
    • Provides programmatic control like error handling and retries.

    Execution Flow:

    1. The Agent decides to use PTC by writing execute_code with Python.
    2. The Sandbox receives the code, an injected SDK, and environment variables.
    3. The Python code executes: result = ToolsetClass.method_name(param=value).
    4. The SDK makes an HTTP POST request to /v1/tool/execute on the Refly API.
    5. The Refly API executes the tool and returns the result to the Python sandbox.
    6. Results are polled and streamed to the frontend via SSE.

  11. Enable type-aware linting in ESLint

    main

    For production applications, it is recommended to enable type-aware lint rules in your ESLint configuration.

    1. Update the parserOptions in your ESLint config file to include project and tsconfigRootDir.
    2. Update your extends list to use type-checked TypeScript rules instead of standard recommended rules.
    3. Add React-specific linting plugins for better coverage.
    export default {
  // other rules...
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
    project: ['./tsconfig.json', './tsconfig.node.json'],
    tsconfigRootDir: __dirname,
  },
}