Skip to main content

prompt

Call AI/LLM services from workflow scripts.

The prompt module routes all LLM traffic through the universal model configuration system. Credentials, provider, model identity, and request defaults live in Settings → Models and are resolved server-side into a modelConfiguration object that is injected into V8 when a Prompt (or other entity step that runs the model pipeline) executes. Scripts call promptCallUniversal(modelConfiguration, promptText) with that resolved object plus the prompt string. Responses are stored automatically and can be read with latestPromptResponse() and getPromptResponse(index).

AWS Bedrock Support​

When your modelConfiguration targets AWS Bedrock, the host uses the Bedrock runtime with IAM role-based authentication from the task environment (no bearer token in script). Request and response shapes are handled by the universal adapter for Claude, Nova, Titan, and other supported Bedrock models.

Environment Requirements​

For Bedrock-backed model configurations:

  • AWS_REGION environment variable is set as needed (defaults to us-east-2 in many deployments)
  • The ECS task role or IAM credentials have bedrock:InvokeModel (and related) permissions for the configured model

promptCallUniversal​

Call an LLM using a resolved universal model configuration object (the same shape injected as the global modelConfiguration before executePromptWithModel() runs).

Signature​

await promptCallUniversal(modelConfiguration, promptText)
await promptCallUniversal(modelConfiguration, promptText, imageUrlsJson)

The optional third argument imageUrlsJson is a JSON string of an image URL array for vision-capable models (the built-in executePromptWithModel() path uses __promptImageUrls__ automatically when image mode is enabled).

Description​

Invokes the LLM through the universal adapter (callLLMWithConfig). The adapter picks the correct HTTP or Bedrock flow from modelConfiguration (provider, model, credential, overrides).

The call increments the prompt counter and stores the model’s primary text (or structured) output for latestPromptResponse() / getPromptResponse(index), consistent with executePromptWithModel().

Parameters​

ParameterTypeDescription
modelConfigurationobjectResolved universal config: provider, model, credential, config (injected global on Prompt entities; must be in scope for manual calls)
promptTextstringUser/system prompt text to send
imageUrlsJsonstring (optional)JSON array string of image URLs for vision, e.g. '["https://..."]'

Returns​

Promise<object> — Adapter result object (includes at least result with the model output string or object, plus usage/cost metadata when available). Many scripts only need:

const { result } = await promptCallUniversal(modelConfiguration, promptText);

Example (Prompt entity — modelConfiguration injected)​

const { result: response } = await promptCallUniversal(
  modelConfiguration,
  'Summarize this touchdown play: ' + description
);

print('AI says:', response);

Example (vision — optional third argument)​

const urls = JSON.stringify(['https://example.com/image.jpg']);
const { result } = await promptCallUniversal(
  modelConfiguration,
  'Describe this image in one sentence.',
  urls
);
print(result);

Supported providers and formats​

Response extraction is handled inside the universal adapter for OpenAI-compatible APIs, Anthropic, Google, Bedrock, and other configured providers. You do not pass raw URLs or auth headers from script for manual calls—modelConfiguration carries that data.

latestPromptResponse​

Get the most recent AI response.

Signature​

await latestPromptResponse()

Description​

Returns the response from the most recent promptCallUniversal or executePromptWithModel() completion (the stored result value). Useful for chaining, for example posting the model output to Mastodon.

Parameters​

None.

Returns​

Promise<string | object | undefined> — The latest response content, or undefined if no prompts have been run.

Example​

await promptCallUniversal(
  modelConfiguration,
  'Write a tweet about this play: ' + description
);

const tweet = await latestPromptResponse();
print('Generated tweet:', tweet);

await postToMastodon(MASTODON_URL, MASTODON_ACCESS_TOKEN, tweet);

getPromptResponse​

Get a specific AI response by its index.

Signature​

await getPromptResponse(index)

Description​

Returns a specific prompt response by its 1-based index. Use this when multiple promptCallUniversal / executePromptWithModel() calls run in one workflow execution.

Parameters​

ParameterTypeDescription
indexnumber1-based index of the prompt response

Returns​

Promise<string | object | undefined> — The response at the specified index, or undefined if the index is out of range.

Example​

await promptCallUniversal(modelConfiguration, 'Summarize: ' + play);
await promptCallUniversal(modelConfiguration, 'Generate hashtags for: ' + play);
await promptCallUniversal(modelConfiguration, 'Rate excitement 1-10: ' + play);

const summary = await getPromptResponse(1);
const hashtags = await getPromptResponse(2);
const rating = await getPromptResponse(3);

print('Summary:', summary);
print('Hashtags:', hashtags);
print('Excitement:', rating);

Complete Example​

print('Processing play:', type);

const prompt = `
You are a sports commentator. Generate an exciting social media post about this NFL play.

Play details:
- Type: ${type}
- Team: ${team}
- Player: ${player}
- Description: ${description}

Keep it under 280 characters. Include relevant emojis.
`;

try {
  await promptCallUniversal(modelConfiguration, prompt);
  print('Generated content:', await latestPromptResponse());
  await postLatestPromptToMastodon();
  print('Posted successfully!');
} catch (error) {
  print('Error:', error.message);
}

Configuration​

Model configuration in Admin​

Define models under Settings → Models. The consumer resolves the record into modelConfiguration (provider slug, model id, credential type, base URL overrides, defaults). Prompt entities (and the prompt portion of the unified pipeline) receive that object in V8; manual promptCallUniversal calls must use the same resolved object—typically the injected modelConfiguration global—not ad-hoc URL/token pairs.

Environment variables​

Org-level variables may still be referenced in arguments or handlebars (for example Mastodon tokens). LLM auth for universal models is stored on the Model / credential record, not as a separate “prompt URL + API key” pair in script.

createEmbedding​

Generate text embeddings using AWS Bedrock Titan.

Signature​

await createEmbedding(text)

Description​

Generates a vector embedding for the given text using AWS Bedrock's Titan embedding model. This is useful for semantic search, similarity comparisons, and RAG (Retrieval Augmented Generation) applications.

Parameters​

ParameterTypeDescription
textstringThe text to generate an embedding for

Returns​

Promise<number[]> — A float array representing the embedding vector (typically 1536 dimensions for Titan).

Example​

const embedding = await createEmbedding(content);
print('Embedding dimensions:', embedding.length);

await pineconeUpsert([{ id: id, values: embedding, metadata: { content, timestamp } }]);

Configuration​

The embedding model can be configured in three ways (in order of precedence):

  1. Entity argument: Set embeddingModelId as an argument on the entity
  2. Environment variable: Set EMBEDDING_MODEL_ID in the environment
  3. Default: Uses amazon.titan-embed-text-v2:0

Environment requirements​

  • AWS_REGION must be set (defaults to us-east-2 in many deployments)
  • The ECS task role must have bedrock:InvokeModel permission for the embedding model

Error handling​

promptCallUniversal throws when the adapter cannot complete the call (for example invalid configuration, HTTP errors from the provider, Bedrock IAM errors, or network failures).

Always wrap prompt calls in try/catch:

try {
  const { result } = await promptCallUniversal(modelConfiguration, prompt);
} catch (error) {
  print('AI call failed:', error.message);
}

Bedrock-specific errors​

Typical messages include AccessDeniedException (IAM), ValidationException (model or body), or ModelNotReadyException. Fix the model configuration or IAM policy on the deployment side.