AnthropicAiQuery@1

Node AnthropicAiQuery@1 is used to query Claude (Anthropic AI) to extract or analyze information from data in the pipeline. This node sends data to Claude's API and can extract structured information, answer questions, or transform content based on AI analysis.

Adapter Prerequisites

• Mesh Adapter

API Key Configuration (recommended)

Instead of putting the API key into the pipeline definition (apiKey), reference a System.Communication/AiConfiguration entity via apiKeyConfigurationName. The configuration entity carries the credentials and model defaults:

Attribute	Description
ApiKey	The Anthropic API key
AiModel	The Claude model id (mandatory since System.Communication 3.24.0; prefer current ids like claude-sonnet-4-6 — pinned dated snapshots get retired)
MaxTokens	Default maximum response tokens
Temperature	Default temperature
McpServerUrl	Base URL of the OctoMesh MCP server (only needed when MCP tools are used)

The lookup requires both the apiKeyConfigurationName on the node and a System.Communication/Uses association from the pipeline to the AiConfiguration entity — without the association the node fails with AiConfiguration '<name>' not found or has no ApiKey:

- rtId: <pipelineRtId>
  ckTypeId: System.Communication/Pipeline
  associations:
    - roleId: System.Communication/Uses
      targetRtId: <aiConfigurationRtId>
      targetCkTypeId: System.Communication/AiConfiguration

Node Configuration

For fields path, targetPath, targetValueWriteMode, and targetValueKind, see Overview.

transformations:
  - type: AnthropicAiQuery@1
    path: $.ExtractedText # The path to the main content to analyze
    targetPath: $.AiExtractedData # The path where the AI response will be stored
    targetValueWriteMode: Overwrite # The target value write mode
    targetValueKind: Simple # The target value kind
    apiKeyConfigurationName: AnthropicAiConfig # rtWellKnownName of the AiConfiguration entity (recommended; requires the Uses association, see above)
    model: "claude-sonnet-4-6" # Optional override of the Claude model; defaults to the AiConfiguration's AiModel
    question: "Extract invoice details from this document" # The question/prompt to ask the AI about the data
    dataPaths: # Optional additional context data paths to include in the query
      - $.DocumentMetadata
      - $.AdditionalContext
    systemPrompt: "You are a helpful AI assistant that extracts specific information from documents. Always provide accurate, structured responses based only on the information provided." # System prompt to set the context for the AI
    maxTokens: 1000 # Maximum tokens for the response (default: 1000)
    temperature: 0.1 # Temperature for response generation (0.0 to 1.0, default: 0.1)
    responseFormat: "json" # Expected response format ("json" or "text", default: "json")
    includeRawResponse: false # Whether to include the raw AI response in the output (default: false)
    rawResponseOutputPath: $.RawAiResponse # Output path for the raw AI response if includeRawResponse is true
    continueOnError: false # Whether to continue processing if the AI query fails (default: false)
    jsonFormatSample: | # Sample JSON format for structured responses
      {
        "transactionDate": "2024-01-15",
        "companyAddress": "Main St, City, Country",
        "grossTotal": 1200.00,
        "netTotal": 1000.00,
        "taxAmount": 200.00
      }

Configuration Parameters

Parameter	Type	Required	Default	Description
apiKeyConfigurationName	string	No¹	-	rtWellKnownName of the AiConfiguration entity holding the API key and model defaults (recommended; the pipeline needs a Uses association to the entity)
apiKey	string	No¹	-	The Anthropic API key inline in the pipeline definition — prefer apiKeyConfigurationName to avoid exposing the key
model	string	No	AiConfiguration AiModel	Optional override of the Claude model
question	string	Yes	-	The question/prompt to ask the AI about the data
dataPaths	string[]	No	-	Additional context data paths to include in the query
systemPrompt	string	No	Default system prompt	System prompt to set the context for the AI
maxTokens	int	No	1000	Maximum tokens for the response
temperature	double	No	0.1	Temperature for response generation (0.0 to 1.0)
responseFormat	string	No	json	Expected response format (json or text)
includeRawResponse	bool	No	false	Whether to include the raw AI response
rawResponseOutputPath	string	No	$.RawAiResponse	Output path for the raw AI response
continueOnError	bool	No	false	Whether to continue processing if the query fails
jsonFormatSample	string	No	Sample JSON	Sample JSON format for structured responses
mcpServerUrl	string	No	AiConfiguration McpServerUrl	Base URL of the OctoMesh MCP server for tool use
mcpToolNames	string[]	No	-	MCP tools Claude may call (e.g. query_entities_simple, navigate_associations)
maxToolRounds	int	No	10	Maximum tool-call rounds before the model must answer
mcpServiceAccountConfigName	string	No	-	rtWellKnownName of a ServiceAccountConfiguration used to authenticate the MCP tool calls (required since the MCP server enforces authentication)
conversationHistoryPath	string	No	-	Path to a conversation history to continue a multi-turn exchange

¹ Exactly one of apiKeyConfigurationName (recommended) or apiKey must provide the key.

Response Processing

The node processes Claude's response based on the responseFormat parameter:

• JSON format: The node attempts to parse the response as JSON. If the response contains mixed content (explanatory text with embedded JSON), it will extract and parse the JSON portion.
• Text format: The response is returned as plain text.

Context Limitations

The total context (main content plus additional data paths) is limited to 3000 characters. If the combined context exceeds this limit, the node will throw an error.

Error Handling

• If continueOnError is set to false (default), the pipeline will stop if the AI query fails
• If continueOnError is set to true, errors will be logged but the pipeline will continue
• Common errors include: missing required fields, API authentication failures, context size exceeded, and invalid JSON parsing

Example: Extract Invoice Data

triggers:
  - type: FromHttpRequest@1
    path: /extract/invoice
    method: POST
transformations:
  - type: AnthropicAiQuery@1
    path: $.documentText
    targetPath: $.extractedInvoiceData
    apiKey: "sk-ant-api03-..."
    question: "Extract the following from this invoice: invoice number, date, total amount, vendor name, and all line items"
    responseFormat: "json"
    jsonFormatSample: |
      {
        "invoiceNumber": "INV-001",
        "date": "2024-01-15",
        "totalAmount": 1500.00,
        "vendorName": "ABC Company",
        "lineItems": [
          {
            "description": "Product A",
            "quantity": 2,
            "unitPrice": 500.00,
            "total": 1000.00
          }
        ]
      }

Example: Analyze Document with Additional Context

transformations:
  - type: AnthropicAiQuery@1
    path: $.mainDocument
    targetPath: $.analysis
    apiKey: "sk-ant-api03-..."
    question: "Analyze this document and identify any compliance issues based on the provided regulations"
    dataPaths:
      - $.regulatoryContext
      - $.previousAnalysis
    systemPrompt: "You are a compliance expert. Analyze documents for regulatory compliance issues."
    maxTokens: 2000
    responseFormat: "json"
    includeRawResponse: true
    rawResponseOutputPath: $.rawAnalysis

Available Models

Common Claude models include:

• claude-3-5-sonnet-20241022 - Most capable, balanced performance
• claude-3-haiku-20240307 - Fastest, most cost-effective
• claude-opus-4-1-20250805 - Most powerful for complex tasks
• claude-sonnet-4-20250514 - Latest Sonnet model (default)

Refer to Anthropic's documentation for the latest model information and capabilities.