Contextual AI icon

Contextual AI

Access Contextual AI tools for agents, parsing, querying, and reranking.
Join our community

Actions13

Overview

The node provides an interface to query a Contextual AI agent. It allows users to send natural language queries to an AI agent identified by an Agent ID and receive responses generated or retrieved based on the agent's knowledge and configuration.

Common scenarios include:

  • Integrating AI-powered question answering into workflows.
  • Fetching information from a custom-trained AI agent.
  • Continuing conversations with context by providing conversation history or IDs.
  • Customizing output formats and filtering documents used for retrieval.

Practical examples:

  • Asking "What is machine learning?" to a specialized AI agent trained on educational content.
  • Retrieving only relevant documents without generating new text by enabling "Retrievals Only".
  • Streaming partial responses as they are generated for real-time user feedback.
  • Using conversation history to maintain context in multi-turn dialogues.

Properties

Name Meaning
Agent ID The unique identifier of the AI agent to query. Required to specify which agent will process the query.
Query The natural language question or prompt to send to the agent.
Retrievals Only Boolean flag indicating whether to fetch only retrieved documents without generating a new response. Useful when you want just source material.
Include Retrieval Content Text Whether to include the full text content of retrieved documents in the response.
Stream Response Whether to receive the response as a stream, allowing partial results to be processed as they arrive.
Conversation ID Optional ID to continue an existing conversation. If provided, the node ignores any conversation history input and continues the dialogue thread identified by this ID.
LLM Model ID Identifier of a specific fine-tuned or aligned large language model to use for generation. Defaults to the base model if not specified.
Conversation History (JSON String) JSON string representing prior messages in the conversation. Format: array of objects with roles ("user" or "assistant") and message content. The last message must be from the user.
Structured Output (JSON String) JSON string defining a custom output format schema, e.g., specifying JSON structure for the response.
Document Filters (JSON String) JSON string defining metadata filters to apply when retrieving documents, e.g., filtering by status or other fields using logical operators like AND/OR.
Override Configuration (JSON String) JSON string to override certain agent configuration parameters during response generation, allowing dynamic customization per request.
Authentication Method of authentication to use; currently supports API key authentication.

Output

The node outputs an array of JSON objects corresponding to each input item queried. Each output object contains the response from the Contextual AI agent, which may include:

  • Generated answer text.
  • Retrieved documents or content snippets if retrieval was enabled.
  • Metadata about the response such as usage statistics or identifiers.
  • If streaming is enabled, partial responses may be emitted progressively.

If binary data is returned (not indicated explicitly here), it would typically represent media or files related to the response, but this node primarily deals with textual JSON output.

Dependencies

  • Requires an active API key credential for authenticating requests to the Contextual AI service.
  • Network access to the Contextual AI API endpoint.
  • Properly configured n8n credentials for the API key.

Troubleshooting

  • Missing or invalid Agent ID: The node requires a valid Agent ID; ensure it is correctly set and corresponds to an existing agent.
  • Malformed JSON strings: Properties like Conversation History, Structured Output, Document Filters, and Override Configuration expect valid JSON strings. Invalid JSON will cause errors.
  • Authentication failures: Verify that the API key credential is correctly configured and has necessary permissions.
  • Streaming issues: When enabling streaming, ensure your workflow can handle streamed partial responses properly.
  • Empty or unexpected responses: Check if the query is well-formed and the agent is properly trained or configured to handle the input.

Links and References

Discussion