Runtime Downstream Invocation

Purpose

This functional area performs the governed downstream call to the target system after tool input has been prepared.

By the time execution reaches this step, the Runtime has already translated the caller payload from ExposedFieldName to SourceFieldName. The downstream invocation layer therefore operates on the source-shaped request and returns the raw downstream source-shaped response to the response transformation step.

Main Capabilities

• target-system based REST and SOAP execution
• endpoint-specific authentication binding
• outbound host restriction enforcement
• guarded redirect handling
• SOAP envelope generation and normalized SOAP response handling
• multipart/form-data request construction for binary inputs
• absolute endpoint execution when a tool already carries a full target URL
• configurable correlation identifier propagation with custom header names
• mutual TLS (client certificate) execution for both REST and SOAP tools bound to a client-certificate auth profile
• hard, bounded response-body handling for both REST and SOAP

REST And SOAP Execution Details

For REST-style execution, the Runtime can:

• compose a target URL from the target-system base URL and mapped source path
• merge mapped request bodies with credential-provided headers, query parameters, and cookies
• omit request bodies for methods and schemas that do not require one

For SOAP-style execution, the Runtime can:

• build SOAP 1.1 or SOAP 1.2 envelopes
• inject SOAPAction in the protocol-appropriate location
• include SOAP security material such as UsernameToken, UsernameTokenDigest, and custom SOAP headers
• normalize SOAP body or fault payloads back into structured JSON for downstream response transformation

Correlation Propagation

The Runtime sends a correlation identifier to the downstream API so the downstream system's own logs can be joined to the platform trace. Which identifier it sends, and under which header name, is configured per toolset.

Two identifiers are available for a call:

• the execution ID, which the platform generates for every runtime call
• the external correlation ID, which the caller supplied on X-Correlation-Id, when it did

Strategies

Choose ExternalCorrelationId or ExternalCorrelationIdOrExecutionId when the downstream system is part of the same trace as the calling application and should see that application's identifier. Choose Both when the downstream needs to distinguish the two. Choose None for downstream systems that reject unrecognised headers.

Custom Header Names

Both header names are configurable per toolset:

• the primary header defaults to X-Correlation-Id
• the secondary header, used only by Both, defaults to X-External-Correlation-Id

A configured name must be a valid HTTP header field name — at most 128 characters, and letters, digits, and ! # $ % & ' * + - . ^ _ \ | ~` only. An invalid name is refused when the toolset is saved rather than at call time, so a malformed value can never reach the outbound request. Under Both, the two names must differ, otherwise the second identifier would overwrite the first.

The policy applies to REST and SOAP execution alike, and the same primary header name is used when reading a correlation identifier back off the downstream response.

Downstream Response Limit

The Runtime enforces a configurable maximum body size accepted from a downstream HTTP or SOAP endpoint. It defaults to 16 MiB and can be set between 1 KiB and 64 MiB. This limit is separate from the audit logging capture limit, which controls only how much content an audit record retains for review.

The Runtime rejects a response above the configured limit before reading the full body when the size is known up front. For chunked or unknown-length responses, it streams at most the limit plus a small margin and rejects the response if that margin is exceeded. SOAP normalization begins only after the bounded read succeeds.

An oversized response produces the stable code downstream_response_too_large. Runtime HTTP callers receive a 502 Bad Gateway problem response; MCP callers receive the same code and safe message in the tool error content.

Functional Value

This is the point where AI requests become actual business-system calls, so it must remain controlled, predictable, and observable across both REST and SOAP integrations.