Trodo

Every prompt-management method in the Node and Python SDKs — signatures, options, return shapes, and errors — plus the ManagedPrompt and CompiledPrompt fields.

The prompt API lives on the singleton (trodo.prompts.* / trodo.get_prompt) after init. All methods are read-only — prompts are authored in the dashboard.

get

Fetch and resolve a prompt by name. Follows the production label by default, falling back to the latest version if no production label exists.

trodo.prompts.get(name: string, options?: GetPromptOptions): Promise<ManagedPrompt>

Option	Type	Default
`label`	`string`	`production`	Resolve via a deploy label.
`version`	`string`	—	Pin an exact version by its hash (full, or an unambiguous short prefix like `a3f9c2`) — copy it from the activity timeline. Mutually exclusive with `label`.
`cacheTtlSeconds`	`number`	`60`	Cache lifetime; `0` disables caching. Caches per selector.
`fallback`	`object`	—	`{ messages, model?, variables? }` used when the API is unreachable and nothing is cached.
`maxRetries`	`number`	`2`	Network retries (max 4), exponential backoff.
`fetchTimeoutMs`	`number`	`5000`	Per-request timeout.

Throws if the prompt can't be fetched and nothing is cached and no fallback was given. Throws if both label and version are passed.

trodo.get_prompt(
    name: str,
    label: str | None = None,
    version: int | str | None = None,
    cache_ttl_seconds: float | None = None,
    fallback: dict | None = None,
    max_retries: int = 2,
) -> ManagedPrompt

Argument	Default
`label`	`production`	Resolve via a deploy label.
`version`	—	Pin an exact version by its hash (full, or an unambiguous short prefix like `"a3f9c2"`) — copy it from the activity timeline. Mutually exclusive with `label`.
`cache_ttl_seconds`	`60`	Cache lifetime; `0` disables caching. Caches per selector.
`fallback`	—	`{"messages": ..., "model"?: ..., "variables"?: ...}` used when the API is unreachable and nothing is cached.
`max_retries`	`2`	Network retries (max 4), exponential backoff.

Raises LookupError if the prompt can't be fetched, nothing is cached, and no fallback was given. Raises ValueError if name is empty or both label and version are passed.

Resolution precedence: explicit version → else label → else the production label, falling back to the latest version only if no production label exists. See Version control and Caching & availability.

compile

Fill variables and return a ready-to-send payload. Runs locally — no network. Renders only the messages; model, tools, and response_format pass through unchanged.

prompt.compile(variables?: Record<string, unknown>): CompiledPrompt

Returns:

interface CompiledPrompt {
  messages: PromptMessage[];              // ready for your provider
  model: ModelConfig;                     // { provider?, model?, temperature?, max_tokens?, ... }
  tools: PromptTool[];                    // attached tool references
  response_format: ResponseFormat | null;
}

Throws CompileError (with .details: string[] listing every problem) when you pass a value for a variable the prompt doesn't declare. A missing value is not an error — it renders the variable's default, or empty.

prompt.compile(variables: dict | None = None, **kwargs) -> CompiledPrompt

Returns a CompiledPrompt dataclass:

@dataclass
class CompiledPrompt:
    messages: list          # ready for your provider
    model: dict             # {"provider": ..., "model": ..., "temperature": ..., ...}
    tools: list             # attached tool references
    response_format: dict | None

Raises CompileError (with .details) when you pass a value for a variable the prompt doesn't declare. A missing value is not an error — it renders the variable's default, or empty. Values can be passed as a dict or as keyword arguments — prompt.compile(company="Acme").

list

List the prompts available to your site's team — summaries only, no message content.

trodo.prompts.list(): Promise<ManagedPromptSummary[]>
// [{ name, description, version, labels, updatedAt }]

trodo.list_prompts() -> list[PromptSummary]
# [PromptSummary(name=..., description=..., version=..., labels=[...], updated_at=...)]

Returns [] on error rather than throwing.

renderTemplate

Render a template string directly, without a managed prompt. Strict by default.

import { renderTemplate } from 'trodo-node';

renderTemplate(template: string, variables?: Record<string, unknown>, options?: { strict?: boolean }): string

from trodo import render_template

render_template(template: str, variables: dict | None = None, strict: bool = True, **kwargs) -> str

Throws / raises on an unknown variable unless strict is false / False, in which case unknown variables render empty. See the template syntax.

The ManagedPrompt object

What get resolves to:

Field	Description
`name`	The prompt's name.
`versionHash` / `version_hash`	The resolved version's hash — its stable id. Copy it from the timeline, or read it here to pin this exact version elsewhere via `get(name, { version })`.
`labels`	Deploy labels on this version.
`tags`	The prompt's tags.
`messages`	Raw structured messages — still hold `{{variables}}` and any placeholders.
`model`	The saved model configuration.
`tools`	Attached tool references.
`response_format`	JSON-object / JSON-schema config, or `null`.
`variables`	Declared variables (name + optional default).
`isFallback` / `is_fallback`	`true` when this came from `fallback` because the API was unreachable.
`compile(...)`	Bound method — fill variables and get a `CompiledPrompt`.

Three more fields exist for tooling and internal bookkeeping, not everyday use: version (an internal sequence number — use versionHash to reference a version, not this), contentHash / content_hash (a hash of just the content, used to detect byte-identical versions), and parentHash / parent_hash (the previous version's hash, forming the history chain). You won't need any of them to fetch or pin a prompt.

The wire shape returned by GET /api/sdk/prompts/:name matches these fields (snake_case on the wire). Both SDKs are thin mappers over it, so anything you can do in one you can do by calling the endpoint directly.

Span attributes

When you compile() a prompt inside a tracked agent run, the SDK stamps the exact version onto the emitted spans, keyed by immutable hash. You don't set these — they're recorded for you:

Attribute	Meaning
`trodo.prompt.name`	The prompt's name.
`trodo.prompt.version_hash`	The immutable version id that actually ran.
`trodo.prompt.label`	The deploy label the fetch followed (omitted when pinned by hash).
`trodo.prompt.content_hash`	sha256 of the content (internal).

The run also carries trodo.prompts — the full set of versions it used. See Prompt traceability for the mechanics and the edge cases.

SDK reference

get

compile

list

renderTemplate

The ManagedPrompt object

Span attributes

On this page