Needle provides retrieval-augmented generation (RAG) tools that enable semantic search across your data, facilitating the development of AI agents and applications.
Needle provides retrieval-augmented generation (RAG) tools that enable semantic search across your data, facilitating the development of AI agents and applications. On Nagent, Needle is exposed as a fully-configurable artificial intelligence integration that any agent can call — 16 actions, and API key authentication. No code is required to wire Needle into your workflow — connect it once via the External Integrations panel and reuse it across every agent you build.
Agent builders use Needle to automate the kinds of tasks artificial intelligence teams previously handled manually. Concrete examples — each one is a single agent step in Nagent — include:
Every action and trigger is paired with a structured input/output schema (visible in the sections below), so when you wire Needle into Helix — our agentic agent builder — the editor knows exactly what each step expects and produces. Configure once, deploy anywhere across your Nagent agents.
Every operation an agent can call against Needle, with input parameters and output schema. Drop these into any step of an agent built in Helix.
NEEDLE_ADD_FILES_TO_COLLECTIONTool to add files to a collection by providing file URLs. Use when you need to add one or more files to an existing collection. URLs can be public or private (generated via the Files API).
Input parameters
List of files to add to the collection. Each file must have a name and URL.
The unique identifier of the collection to add files to
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_ADD_FILES_TO_LOCAL_CONNECTORTool to add files to a local connector by providing file metadata. Use when you need to add external files to a connector using their URLs.
Input parameters
List of files to add to the local connector
The unique identifier of the local connector to add files to
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_CREATE_COLLECTIONTool to create a new collection. Use after confirming the collection name.
Input parameters
Name of the collection. Must be unique within your account.
Optional arbitrary JSON metadata associated with the collection.
Optional human-readable description of the collection.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_CREATE_LOCAL_CONNECTORTool to create a local connector that monitors specified folders on a device. Use when setting up file indexing from a local machine into Needle collections.
Input parameters
Operating system of the device (e.g., macOS, Windows, Linux)
CPU model/architecture of the device
Name for the local connector. Should be descriptive of the device or purpose.
List of folders to monitor for file indexing
Name of the device running the connector
Model identifier of the device
Serial number or unique identifier for the device
List of collection IDs to associate with this local connector. Files from the monitored folders will be indexed into these collections.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_DELETE_FILES_FROM_COLLECTIONTool to delete files from a specific collection by providing file IDs. Use after confirming valid file IDs to remove from the collection.
Input parameters
List of file IDs to delete from the collection
The unique identifier of the collection from which to delete files
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_DELETE_FILES_FROM_LOCAL_CONNECTORTool to delete files from a local connector by filename or file IDs. Use when you need to remove files from a connector's local storage.
Input parameters
Method to identify files for deletion: 'name' to delete by filename, 'file_ids' to delete by file IDs
Name of the file to delete. Required when 'by' is 'name'
List of file IDs to delete. Required when 'by' is 'file_ids'
The unique identifier of the connector from which to delete files
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_GET_COLLECTIONTool to retrieve details for a specific collection by its ID. Use when you need to get collection metadata including name, creation date, and search query count.
Input parameters
The unique identifier of the collection to retrieve.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_GET_COLLECTION_STATSTool to retrieve statistics for a specific collection by its ID. Use when you need document count, index size, and timestamps after confirming the collection exists. Zero document count is a valid response for empty collections, not an error.
Input parameters
The unique identifier of the collection. Verify the exact ID when collections have similar names to avoid retrieving stats for the wrong collection.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_GET_FILE_DOWNLOAD_URLTool to get a short-lived signed private download URL for a Needle file. Use when you need to retrieve file content but the public storage URL requires authentication. The returned URL should be used immediately as it expires quickly.
Input parameters
The unique identifier of the file to download
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_GET_FILE_UPLOAD_URLTool to get signed URLs for uploading local files to Needle. Use when you need to upload files to a collection. The upload URLs are valid for a short time, so upload files immediately after receiving the URLs. Multiple content types can be specified to generate multiple upload URLs in a single request.
Input parameters
MIME types for files to upload (e.g., application/pdf, text/plain, image/jpeg). Multiple content types can be provided to generate multiple upload URLs at once.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_GET_LOCAL_CONNECTORTool to retrieve details of a local connector by its ID. Use when you need information about a specific local connector's configuration, device details, and associated folders.
Input parameters
The unique identifier of the local connector.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_LIST_COLLECTION_FILESTool to list all files within a specific collection by its ID. Returns file metadata (including file URLs) only — not document text content; fetch file URLs separately to access content. Use when you have a collection ID and need to retrieve its files. Supports pagination.
Input parameters
Number of files to return per page, must be >=1
Number of items to skip for pagination, must be >=0
Unique identifier of the collection Multiple collections can share similar names; verify the correct collection_id before operating on returned files.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_LIST_COLLECTIONSTool to list collections. Use after authenticating with your API key to page through collections. Similar collection names can exist; always verify the correct `collection_id` from results before performing subsequent operations.
Input parameters
Maximum number of collections to return (if supported by API)
Number of collections to skip before collecting results (if supported by API)
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_LIST_CONNECTORSTool to list connectors. Use to retrieve all configured connectors in your account.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_LIST_LOCAL_CONNECTORSTool to list local connectors. Use to retrieve all local connectors configured in your Needle account.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_SEARCH_COLLECTIONTool to perform semantic search within a specific Needle collection and return ranked results with source references. Use when you need to retrieve relevant content from a known collection using natural language queries.
Input parameters
The natural-language search query to find relevant content in the collection.
Maximum number of search results to return. Default is 10 (maximum).
Offset for pagination to skip a number of results.
Optional pass-through object for additional retrieval parameters supported by the API (e.g., filters, future knobs).
Maximum similarity distance threshold for results, between 0 and 1. Lower values mean stricter relevance. Example: '0.65'.
The unique identifier of the collection to search in.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
No publicly available marketplace agent is found using this tool yet. There are 75 agents privately built on Nagent that already use Needle.
Build on Nagent
Connect Needle to any Nagent agent in minutes — no API key management, no boilerplate. Just configure and deploy.
The five questions agent builders ask before adopting a new integration.
Open the External Integrations panel inside Nagent (app.nagent.ai/externalIntegration), find Needle, and click "Connect Now." You'll authenticate with an API key — Nagent handles credential storage and refresh automatically. Once connected, Needle is available to any agent in your workspace.
No. Nagent provides no-code integration for every tool. Once Needle is connected, you configure its 16 actions directly in the agent builder UI — no API calls, no boilerplate, no schema management.
Helix — Nagent's agentic agent builder — lets you drop Needle steps into any workflow visually. Pick an action (e.g., one of those listed above), fill in the inputs (Helix knows the required vs. optional schema for each parameter), and connect it to upstream/downstream steps. Triggers run as the entry point of an agent, so when a Needle event fires, the agent kicks off automatically.
Every Needle action and trigger ships with a fully-typed schema — input parameters with name, type, required flag, and description, plus the output payload shape. The schemas are documented in the sections above. Helix uses these schemas to validate your configuration at build time and to type-check the data flowing between steps.
Yes. While Needle ships with 16 pre-built artificial intelligence actions, you can layer custom logic around them inside Helix — pre/post-processing steps, conditional branches, retries, or stitching Needle together with other connected tools. For deeper customization, talk to our team about Nagent's Agentic AI Lab — forward-deployed engineers who build Needle-based workflows tailored to your business.