AWS Bedrock ExecModule

Overview

AwsBedrockModule brings Amazon Bedrock foundation models into ValkyrAI workflows without exposing AWS credentials or coupling a workflow to one model family. It combines the most useful ideas from n8n's Bedrock chat and embeddings nodes with native ValkyrAI model discovery, typed validation, deterministic attempt accounting, normalized output, and annotation-backed Workflow Studio discovery.

The connector implements five operations:

• list_models discovers foundation models and filters them by provider, output modality, and inference type.
• get_model returns normalized details for one foundation-model ID.
• converse sends portable alternating text messages through Bedrock's cross-model Converse API.
• invoke_model sends a bounded provider-specific JSON object to a selected model.
• embed_text normalizes Amazon Titan Text Embeddings and Cohere Embed vectors.

Inference can be probabilistic, costly, and sensitive. Treat generated text and vectors as evidence for a reviewed workflow—not authorization for legal, financial, employment, healthcare, security, or other high-impact decisions.

Usage

1. Enable the intended Bedrock model or inference profile in the selected AWS account and region.
2. Create a least-privilege IAM principal with only the Bedrock actions the workflow needs.
3. Store its access key ID and secret access key in an AWS IntegrationAccount, verify it, and keep it in READY status.
4. Add AwsBedrockModule to a workflow and bind the account through ExecModuleConfig.authConfig.integrationAccount.
5. Choose an exact AWS region and operation.
6. Use list_models to discover on-demand model IDs. Cross-region inference-profile IDs and model ARNs can be passed directly as modelId when already approved.
7. Route generated content through human or policy review before an external side effect.

Never put AWS credentials in module input, prompts, examples, logs, or output. Credential-like fields are rejected before provider access.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	list_models, get_model, converse, invoke_model, or embed_text.
region	string	Every execution	None	Exact AWS region syntax such as us-west-2; custom endpoint URLs are not accepted.
modelId	string	All except list_models	None	Foundation-model ID, inference-profile ID/ARN, provisioned-model ARN, or other Bedrock-supported model identifier; bounded to 2,048 safe characters.
provider	string	Optional for list_models	None	Exact case-insensitive provider name such as Anthropic, Amazon, or Cohere.
outputModality	string	Optional for list_models	None	TEXT, IMAGE, or EMBEDDING.
inferenceType	string	Optional for list_models	None	ON_DEMAND or PROVISIONED.
limit	integer	Optional for list_models	100	From 1 through 100.
messages	array	converse	None	1-20 {role, content} objects. Roles must alternate, start with user, and end with user. Each content value is at most 32,768 UTF-8 bytes; the conversation cap is 131,072 bytes.
systemPrompt	string	Optional for converse	None	Non-blank text up to 32,768 UTF-8 bytes.
maxTokens	integer	Optional for converse	1024	From 1 through 8,192. Provider and model limits may be lower.
temperature	number	Optional for converse	Provider default	From 0 through 1.
topP	number	Optional for converse	Provider default	From 0 through 1. Prefer tuning this or temperature, not both, unless the model's contract calls for it.
modelInput	object	invoke_model	None	Non-empty provider-specific JSON object, at most 262,144 encoded bytes. Arrays or scalar roots are rejected.
text	string	embed_text	None	Non-blank text up to 32,768 UTF-8 bytes. Newlines are normalized to spaces for embedding stability.
inputType	string	Optional for embed_text	search_document	search_document or search_query; used by Cohere and retained as workflow intent for Titan.
dimensions	integer	Optional for Titan embed_text	Model default	From 1 through 8,192; the selected Titan model determines supported values. Rejected for Cohere.
normalize	boolean	Optional for Titan embed_text	Model default	Requests a normalized Titan vector. Rejected for Cohere.

Operation-specific fields fail closed. For example, messages is rejected by catalog and embedding operations, and modelInput is accepted only by invoke_model.

Outputs

Every execution returns stable status, operation, and attempts fields.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
attempts	integer	Always	Provider calls. Catalog reads may retry; billable inference is one attempt.
resultType	string	Success	foundationModels, foundationModel, conversation, modelResponse, or embedding.
items	array	Model-list success	Bounded normalized foundation-model summaries.
count	integer	Model-list success	Returned summary count.
data	object	Model-detail or generic invocation success	Normalized model metadata or bounded provider JSON.
text	string	Converse success	Combined text content blocks, capped at 1 MiB.
embedding	array	Embedding success	Finite numeric vector with no source-text echo.
dimensions	integer	Embedding success	Returned vector length.
usage	object	Converse supplies usage	Input, output, and total token counts.
stopReason	string	Converse supplies one	Model stop reason such as end_turn or max_tokens.
latencyMs	integer	Converse supplies metrics	Provider-reported latency.
requestId	string	AWS supplies one	Bounded provider reference for reconciliation and support.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

Model summaries include safe IDs, names, ARNs, provider, input/output modalities, customization support, inference types, streaming support, and lifecycle status when AWS supplies them.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / Bedrock
status	Must be READY.
verified	Must be true.
apiKey SecureField	AWS access key ID.
password SecureField	AWS secret access key.

Grant only the actions selected by the workflow:

• bedrock:ListFoundationModels for list_models
• bedrock:GetFoundationModel for get_model
• bedrock:InvokeModel for converse, invoke_model, and embed_text

The Converse API is authorized by bedrock:InvokeModel; there is no separate bedrock:Converse IAM action. Scope model resources, regions, inference profiles, KMS keys, guardrails, network egress, and service control policies to the intended workflow.

The current connector supports a long-lived access-key pair. Temporary session credentials, role assumption, private/VPC endpoint overrides, prompt management, custom-model training/import, provisioned-throughput lifecycle, marketplace subscriptions, guardrail administration, knowledge-base retrieval, agents, batch inference, streaming, and model-invocation logging configuration are deferred.

Configuration

The awsAccount relationship is the only credential configuration. Region, model, messages, inference controls, and payloads belong in module parameters or mapped input.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-bedrock-production"
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"converse\",\"region\":\"us-west-2\",\"modelId\":\"us.anthropic.claude-3-5-sonnet-20241022-v2:0\",\"maxTokens\":600}"
  }
}

The relationship value is illustrative. Persisted workflows bind the generated IntegrationAccount relationship, never plaintext credentials.

Operations

Operation	Provider behavior	Side effect and retry behavior
list_models	Lists foundation models and applies optional provider/modality/inference filters.	Read-only; retryable throttles and transient failures use the workflow retry policy, capped at five attempts.
get_model	Returns normalized details for one foundation-model ID.	Read-only; bounded retries are allowed.
converse	Uses Bedrock's portable message API with bounded sampling controls.	Non-storage but billable external processing; exactly one provider attempt.
invoke_model	Passes a bounded provider-specific JSON object to Bedrock Runtime and returns bounded JSON.	Non-storage but billable external processing; exactly one provider attempt.
embed_text	Builds Titan or Cohere embedding payloads and returns one finite vector.	Non-storage but billable external processing; exactly one provider attempt.

No operation creates, changes, or deletes a Bedrock resource. Inference still sends approved content to AWS and can create billing, telemetry, and provider-side logging events under the AWS account's configuration.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing or malformed operation, region, model ID, message sequence, payload, sampling option, embedding model, or credential-like input.	No	Correct the named input; no provider request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_ERROR	Account missing, unverified, not READY, or missing key material.	No	Repair and bind the AWS account.
AWS_BEDROCK_HTTP_400	Unsupported model payload, inference setting, message shape, or region/model combination.	Usually no	Compare the selected model's current request schema and region support.
AWS_BEDROCK_HTTP_403	IAM, model-access, inference-profile, service-control-policy, or region policy denial.	No	Grant only the missing access on the intended account/model.
AWS_BEDROCK_HTTP_404	Model ID or ARN does not exist in the selected region/account.	No	Re-run approved discovery or correct the configured model identifier.
AWS_BEDROCK_HTTP_408 / 429 / 500 / 503	Timeout, throttle, or transient provider pressure.	Catalog reads only	Catalog reads retry within the configured cap. Inference reports ambiguity and never replays automatically.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Catalog reads only	For inference, inspect AWS evidence and billing before an orchestrated retry.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic replay	Preserve the operation, region, model ID, input hash, and request evidence.

Provider exception text is never copied into output, preventing credential echoes and unbounded provider payloads. Generic invoke_model output is intentionally provider JSON; downstream workflows must classify and validate its fields before use.

Example

Draft an incident update from reviewed facts:

{
  "operation": "converse",
  "region": "us-west-2",
  "modelId": "us.anthropic.claude-3-5-sonnet-20241022-v2:0",
  "systemPrompt": "Use only supplied incident facts. Do not invent causes or recovery times.",
  "messages": [
    {
      "role": "user",
      "content": "Facts: checkout errors began at 14:05 UTC; mitigation deployed at 14:21 UTC; monitoring is stable. Draft a two-sentence customer update."
    }
  ],
  "maxTokens": 160,
  "temperature": 0.2
}

Expected result shape:

{
  "status": "success",
  "operation": "converse",
  "attempts": 1,
  "resultType": "conversation",
  "text": "We observed elevated checkout errors beginning at 14:05 UTC and deployed mitigation at 14:21 UTC. Monitoring is currently stable, and we will share another update if conditions change.",
  "usage": {
    "inputTokens": 61,
    "outputTokens": 43,
    "totalTokens": 104
  },
  "stopReason": "end_turn",
  "latencyMs": 812,
  "requestId": "aws-request-reference"
}

The expected workflow presents this draft and its approved source facts to a human owner before publication.

Notes

• Pagination: ListFoundationModels is not paginated. list_models applies ValkyrAI's limit after provider results and returns at most 100 summaries. Inference-profile listing is deferred; approved profile IDs and ARNs remain valid modelId values.
• Rate limits: quotas vary by account, model, region, inference profile, token count, and provisioned throughput. Catalog reads use bounded retry/backoff. Runtime inference disables SDK replay and executes once.
• API limits: ValkyrAI enforces its own message, conversation, JSON, response, text, and embedding bounds even when a model permits more. The selected model's lower limit still applies.
• Idempotency: model discovery is safe to repeat. Converse, generic invocation, and embeddings can be billed again and may produce different results even for identical input.
• Billable ambiguity: each inference request is sent once. If transport fails after AWS accepts it, reconcile CloudTrail, model-invocation logs, request ID, input hash, and billing evidence before replay.
• Destructive behavior: the connector never changes or deletes models, profiles, prompts, agents, guardrails, knowledge bases, throughput, or policies. It does send approved content to AWS and initiate billable processing.
• Model access: account access, region availability, cross-region inference rules, and marketplace subscriptions change independently of source code. Use the live AWS account and list_models where applicable.
• Inference profiles: newer models may require a cross-region inference-profile ID. The connector accepts profile IDs/ARNs for converse and invoke_model even though version 1.0 lists foundation models only.
• Embeddings: Titan requests use inputText and optional dimensions/normalize. Cohere requests use texts, input_type, and bounded truncation behavior. The source text is not echoed in normalized output.
• Generic invocation: invoke_model is intentionally model-family aware only through caller-supplied JSON. Prefer converse for portable text generation and embed_text for supported vectors.
• External verification boundary: deterministic tests cover validation, regional routing, account isolation, alternating messages, inference controls, generic JSON, embedding normalization, catalog retry, inference single-attempt behavior, redaction, registration, and metadata. Live AWS execution remains unverified until an authorized Bedrock account and reviewed payload are supplied.
• Functional reference: n8n exposes separate AWS Bedrock Chat Model and Embeddings AWS Bedrock nodes. ValkyrAI combines their core capabilities with model discovery, a generic bounded invocation escape hatch, strict IntegrationAccount enforcement, normalized envelopes, and explicit billable-replay controls.
• Runtime boundary: merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsBedrockModule through /v1/modules/metadata.

Related Documentation

• ExecModule catalog
• AWS Lambda ExecModule
• AWS DynamoDB ExecModule
• AWS Comprehend ExecModule
• n8n AWS Bedrock Chat Model
• n8n AWS Bedrock Embeddings
• Amazon Bedrock Converse API
• Amazon Bedrock InvokeModel API
• Integration Account Console