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)
`mcpDelegateToCaller`	bool	No	false	Run the MCP tool calls under the calling user's delegated identity instead of the service account's, so the AI only sees the data that user is allowed to see. Requires a token-carrying trigger such as `FromHttpRequest@2`. See Delegation
`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.

Running the AI lookups as the calling user (delegation)

When the AI uses MCP tools to look up data, those lookups run under an identity. By default that is the pipeline's service account (configured via mcpServiceAccountConfigName). For user-facing flows — such as an application chat where each user must only see their own data — set mcpDelegateToCaller: true. The MCP lookups then run under the calling user's delegated identity, limited to the intersection of the user's roles and the service account's roles.

This requires the pipeline to be triggered with the caller's token, using FromHttpRequest@2. Delegation is fail-closed: if the flag is set but no caller token is present, the node refuses rather than falling back to the service account. See Delegation for the full picture.

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.

Adapter Prerequisites​

API Key Configuration (recommended)​

Node Configuration​

Configuration Parameters​

Running the AI lookups as the calling user (delegation)​

Response Processing​

Context Limitations​

Error Handling​

Example: Extract Invoice Data​

Example: Analyze Document with Additional Context​

Available Models​