Using Tools

Requires:

• non-empty vector store

Schema:

{
    "type": "file_search",
    "vector_store_ids": "array of strings",
    "max_num_results": "integer",
    "filters": "object",
    "ranking_options": "object"
}

where:

• vector_store_ids – list of vector store IDs allowed to be accessed
• max_num_results – maximum number of returned results
• filters – additional filters
• ranking_options – reranker options for choosing the final search results

Compatible with OpenAI file search tool.

Example:

curl -X POST \
  'https://your-deepfellow-server.com/toolboxes/69b2c38a606170264e30f7c0/tools' \
  -H 'Authorization: Bearer dfproj_f7a0c4ba-70ae-4129-a4b4-b2da9324634b' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -d '{
    "type": "file_search",
    "vector_store_ids": [
      "69b2c436606170264e30f7c2"
    ],
    "filters": {
          "key": "document_type",
          "type": "eq",
          "value": "blogpost"
    },
    "max_num_results": 5,
    "ranking_options": {
      "ranker": "auto",
      "score_threshold": 0.8
    }
  }'

Requires:

• Stable Diffusion model installed on DeepFellow Infra

Schema:

{
    "type": "image_generation",
    "background": "string",
    "model": "string",
    "output_compression": "integer",
    "output_format": "string",
    "partial_image": "integer",
    "quality": "string",
    "size": "string",
    "moderation": "string",
    "input_image_mask": "object"
}

where:

• background – "transparent" or "opaque" (default)
• model – model installed in DeepFellow Infra's stable diffusion service
• output_compression – image quality as a percentage (0–100). Lower values reduce both file size and quality. Applies to "jpeg" and "webp" formats only
• output_format – image format: "png", "webp", "jpeg"
• partial_image – describes how many images are generated per call
• quality – image quality: "low", "medium", "high"
• size – image size: "width x height" for example, "1024x1024"
• moderation – text describing what content is not allowed in the image (currently not supported)
• input_image_mask – mask for changing parts of the image (currently not supported)

Compatible with OpenAI image generation tool.

Example:

curl -X POST \
  'https://your-deepfellow-server.com/toolboxes/69b2c38a606170264e30f7c0/tools' \
  -H 'Authorization: Bearer dfproj_f7a0c4ba-70ae-4129-a4b4-b2da9324634b' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -d '{
    "type": "image_generation",
    "background": "opaque",
    "model": "sdxl2",
    "output_compression": 99,
    "output_format": "jpeg",
    "partial_image": 2,
    "quality": "high",
    "size": "1024x1024",
    "moderation": null,
    "input_image_mask": null,
  }'

Schema:

{
    "type": "mcp",
    "server_label": "string",
    "server_url": "string",
    "allowed_tools": "array of strings",
    "headers": "object",
    "require_approval": "string",
    "server_description": "string"
}

where:

• server_label – name of the MCP server (used by LLM)
• server_url – URL of the external MCP server
• allowed_tools – list of tools allowed for LLM to use. If empty, all tools are allowed
• headers – additional HTTP headers useful for tool authorization
• require_approval – whether tool call needs user approval. Possible values: "always", "never". You can also set approval per-tool basis, for example: {"always": {"tool_names": ["remove_db", "git push"]}, "never": {"tool_names": ["check_date", "get_utc"]}}
• server_description – server description (used by LLM)

Example:

curl -X POST \
  'https://your-deepfellow-server.com/toolboxes/69b2c38a606170264e30f7c0/tools' \
  -H 'Authorization: Bearer dfproj_f7a0c4ba-70ae-4129-a4b4-b2da9324634b' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -d '{
    "type": "mcp",
    "server_label": "Deepwiki",
    "server_url": "https://mcp.deepwiki.com/mcp"
  }'

Requires:

• mcp service installed on DeepFellow Infra with at least one MCP server

Schema:

{
    "type": "df-mcp",
    "server_label": "string",
    "server_prefix": "string",
    "server_transport": "string",
    "server_description": "string",
    "allowed_tools": "array of strings",
    "headers": "object",
    "require_approval": "string"
}

where:

• server_label – name of the MCP server (used by LLM)
• server_prefix – prefix set up during MCP server installation on DeepFellow Infra
• server_transport – MCP transport type: "mcp" (streamable HTTP; default), "sse"
• server_description – server description (used by LLM)
• allowed_tools – list of tools allowed for LLM to use. If empty, all tools are allowed
• headers – additional HTTP headers, useful for tool authorization
• require_approval – whether tool call needs user approval. Possible values: "always", "never". You can also set approval per-tool basis, for example: {"always": {"tool_names": ["remove_db", "git push"]}, "never": {"tool_names": ["check_date", "get_utc"]}}

Example:

curl -X POST \
  'https://your-deepfellow-server.com/toolboxes/69b2c38a606170264e30f7c0/tools' \
  -H 'Authorization: Bearer dfproj_f7a0c4ba-70ae-4129-a4b4-b2da9324634b' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -d '{
    "type": "df-mcp",
    "server_label": "ML example",
    "server_prefix": "ml-example",
    "server_description": "Allows to use machine learning model."
  }
'

Requires:

• mcp service installed on DeepFellow Infra with at least one MCP server providing web search and/or fetch capabilities

The Websearch tool composes two independently configured operations:

• search (find pages via a web search engine)
• fetch (scrape a webpage by URL)

Schema:

{
    "type": "websearch",
    "search": {
        "prefix": "string",
        "tool": "string",
        "transport": "string",
        "headers": "object"
    },
    "fetch": {
        "prefix": "string",
        "tool": "string",
        "transport": "string",
        "headers": "object"
    },
    "require_approval": "string"
}

where:

• search – configuration for the web search operation
  • prefix – prefix of the MCP server on DeepFellow Infra providing the search tool
  • tool – name of the search tool on that MCP server
  • transport – MCP transport type: "mcp" (streamable HTTP; default), "sse"
  • headers – additional HTTP headers for this operation
• fetch – configuration for the webpage fetch operation
  • prefix – prefix of the MCP server on DeepFellow Infra providing the fetch tool
  • tool – name of the fetch tool on that MCP server
  • transport – MCP transport type: "mcp" (streamable HTTP; default), "sse"
  • headers – additional HTTP headers for this operation
• require_approval – whether tool call needs user approval. Possible values: "always", "never". You can also set approval per-tool basis, for example: {"always": {"tool_names": ["web_fetch"]}, "never": {"tool_names": ["web_search"]}}

Example:

curl -X POST \
  'https://your-deepfellow-server.com/toolboxes/69948d90e255466771a4500f/tools' \
  -H 'Authorization: Bearer dfproj_e1dd1742-e57d-4e87-ba54-5971374bc700' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -d '{
    "type": "websearch",
    "search": {
      "prefix": "open-websearch",
      "tool": "web_search"
    },
    "fetch": {
      "prefix": "open-websearch",
      "tool": "web_fetch"
    }
  }'

A Custom tool wraps an HTTP request, mapping tool input fields to HTTP request fields and response data to tool output. The request can be sent to any endpoint.

Requires:

• custom service on Infra with at least one custom model

Schema:

{
    "type": "custom-mcp",
    "server_label": "string",
    "server_description": "string",
    "server_prefix": "string",
    "headers": "object",
    "require_approval": "string",
    "tools": [
        {
            "name": "string",
            "title": "string",
            "description": "string",
            "request": {
                "method": "string",
                "path": "string",
                "query": "object",
                "headers": "object",
                "body": "object"
            },
            "inputs": [
                {
                    "name": "string",
                    "type": "string",
                    "description": "string",
                    "required": "boolean",
                    "to_param": "string",
                    "to_type": "string"
                }
            ],
            "outputs": [
                {
                    "name": "string",
                    "type": "string",
                    "description": "string",
                    "required": "boolean",
                    "content_type": "string",
                    "mime_type": "string",
                    "from_b64": "boolean",
                    "from_param": "string",
                    "from_param_to_mimetype": "string"
                }
            ]
        }
    ]
}

where:

• server_label – MCP tool name
• server_description – server description (used by LLM)
• server_prefix – prefix set up during MCP server installation on DeepFellow Infra
• headers – additional HTTP headers, useful for tool authorization
• require_approval – whether tool call needs user approval. Possible values: "always", "never". You can also set approval per-tool basis, for example: {"always": {"tool_names": ["remove_db", "git push"]}, "never": {"tool_names": ["check_date", "get_utc"]}}
• tools – list of tools
  • name – tool name
  • title – tool pretty name (display name)
  • description – tool description
  • request – defines the default request
    • method – HTTP method
    • path – URL path after the server prefix
    • query – additional path parameters
    • headers – headers for a specific tool
    • body – HTTP request body
  • inputs – list of input fields
    • name – field name
    • type – field type in JSON standard
    • description – field description
    • required – determines whether the field is required or not
    • to_type – specifies which HTTP part type the value is sent to, for example: "query", "param", "body"
    • to_param – parameter name the value is sent to
  • outputs – output fields
    • name – field name
    • type – field type in JSON standard
    • description – field description
    • required – determines whether the field is guaranteed in the output
    • content_type – specifies the output type in an unstructured response
    • from_param – specifies which body parameter the response is taken from; an empty value means the entire content
    • mime_type – specifies a fixed MIME type; for content_type "image" or "audio", either "mime_type" or "from_param_to_mimetype" must be set
    • from_param_to_mimetype – specifies which body parameter corresponds to the MIME type; for content_type "image" or "audio", either "mime_type" or "from_param_to_mimetype" must be set
    • from_b64 – converts a base64 value to text before sending to MCP

Example:

curl -X 'POST' \
  'http://127.0.0.1:8000/toolboxes/69948d90e255466771a4500f/tools' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer dfproj_e1dd1742-e57d-4e87-ba54-5971374bc700' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "custom-mcp",
    "server_label": "iris-classifier",
    "server_description": "Machine Learning Classifier to classify iris petals",
    "server_prefix": "ml-model",
    "headers": null,
    "require_approval": "always",
    "tools": [
      {
        "name": "iris-classifier",
        "title": "Iris Species Predictor",
        "description": "Predicts iris species based on sepal and petal dimensions.",
        "request": {
          "method": "POST",
          "path": "/predict",
          "query": {},
          "headers": {
            "Content-Type": "application/json"
          },
          "body": {}
        },
        "inputs": [
          {
            "name": "features",
            "type": "array",
            "description": "List of four float values: sepal length, sepal width, petal length, petal width",
            "required": true,
            "to_param": "features",
            "to_type": "body"
          }
        ],
        "outputs": [
          {
            "name": "prediction",
            "type": "number",
            "description": "The predicted class or probability value",
            "required": true,
            "content_type": "text",
            "mime_type": "",
            "from_b64": false,
            "from_param": "prediction",
            "from_param_to_mimetype": ""
          }
        ]
      }
    ]
  }'

The Standard method functions like a typical streamable-http or SSE (Server-Sent Events) MCP connection.

• Setup: Requires a standard HTTP URL and an authorization token.

• Accessibility: External applications have direct access to the toolbox or tool MCP server.

• Configuration:

  • Server URL: http://your-deepfellow-server.com/toolboxes/[TOOLBOX_ID]/mcp

  • Header: Requires an Authorization bearer token.

    Authorization: Bearer dfproj_e1dd1742-e57d-4e87-ba54-5971374bc700

The Built-in method uses a custom internal protocol, prioritizing security and simplicity for native integrations.

• Setup: Uses the custom df:// protocol and does not require an authorization header.
• Privacy: External applications cannot access the MCP server directly. The response hides the tools used.
• Limitations:
  • Currently only compatible with the /v1/responses endpoint.
  • Will not work if an external application needs to explicitly list the MCP servers.
• Configuration:
  • Server URL: df://local/toolboxes/[TOOLBOX_ID]/mcp
  • Header: No authorization bearer is required.