TypeScript SDK

@helmr/sdk declares Agents, Computers, images and triggers, configures the build, and provides an explicitly authenticated HelmrClient. Agent context exposes ctx.mcp.getConnectionOptions(policy?) for the runtime MCP tools. Template outbound networking and Agent MCP maxima are described in Execution policies.

import { agent, template, image, triggers, defineConfig, HelmrClient } from "@helmr/sdk"

Reference pages

Page Covers
Agent agent(), AgentDefinition, Turn, InitContext/AgentContext, RuntimeMcpConnectionOptions, RuntimeMcpPolicy, RuntimeMcpRule, RuntimeMcpTargetOperation, MessageRejected, and the client’s Session and Turn methods.
Computer template(), image(), source, Secret bindings, and the client’s Computer, Template definition and Command methods.
Client HelmrClient options and properties, Agent and definition reads, Deployments and Secrets.
Triggers triggers.cron() and the client’s read-only Trigger methods.
Questions turn.ask(), answer controls, answer shapes and limits, and the client’s ask methods.
Runtime MCP ctx.mcp.getConnectionOptions() and every runtime MCP tool, with inputs and results.

Build configuration (defineConfig, builder) is documented in Configuration.

Exports

Values exported from @helmr/sdk:

Export Kind Reference
agent function Agent
template function Computer
triggers object with cron() Triggers
image, source function, object Computer
builder function Configuration
defineConfig function Configuration
HelmrClient class Client
MessageRejected error class Agent

Types exported from @helmr/sdk, grouped by area:

Area Types
Definitions AgentDefinition, TemplateDefinition, CronTrigger, ComputerIdentity, PrepareContext, SecretBinding, AllowedDomain, NetworkPolicy, Duration, JsonValue, MaybePromise
Turn handler Turn, InitContext, AgentContext, RuntimeMcpConnectionOptions, RuntimeMcpPolicy, RuntimeMcpRule, RuntimeMcpTargetOperation, InputSource, Message, MessageSource, SlackInputSource, OutputReceipt, TurnOutcome
Content ContentPart, Content, HumanContent, InputPart, InputContent
Questions ChoiceOption, TextQuestion, ChoiceQuestion, AnswerSubmission, Question, ChoiceAnswer, AnswerFor, AskAnswer, AskState, AskAnswerReceipt, AskQuery, AskPage, TurnAsks
Client HelmrClientOptions, RequestOptions, CursorPage, HelmrError, APIError
Agents ClientAgentsApi, SessionCreateRequest, SessionCreateReceipt, ClientAgentsApi, AgentGetQuery, AgentListQuery, AgentListItem, AgentInfo, AgentPage
Sessions and Turns ClientSessionsApi, SessionRef, SessionListQuery, Session, SessionStatus, SessionHold, SessionOperationOptions, SessionCreateReceipt, SessionMessageReceipt, SessionCloseReceipt, SessionCancelReceipt, SessionInterruptReceipt, SessionResumeRequest, SessionResumeReceipt, SessionEvent, SessionEventKind, SessionEventPage, SessionEventQuery, MessageReceipt, TurnRef, TurnState, TurnStatus, TurnListQuery, TurnWaitOptions, TimedTurnWaitResult
Computers ClientComputersApi, ComputerRef, ComputerRef, Computer, ComputerStatus, ComputerResidency, ComputerListItem, ComputerListQuery, ComputerSecretExposure, ComputerCreateRequest, ComputerDeleteRequest, ComputerDeleteReceipt, ComputerCommandRequest, ComputerUsageQuery, ComputerUsage, ClientTemplatesApi, TemplateInfo, TemplateListItem, TemplateListQuery, TemplatePage, TemplateGetQuery, ImageBuilder, SourceDirectory, SourceFile
Commands CommandRef, CommandInfo, CommandOutcome, CommandWaitOptions, TimedCommandWaitResult, CommandCancelReceipt, CommandLogQuery, CommandLogStreamQuery, CommandLogRecord, CommandLogReadPage
Deployments ClientDeploymentsApi, Deployment, DeploymentListItem, DeploymentListQuery
Triggers ClientTriggersApi, Trigger, TriggerListQuery
Secrets ClientSecretsApi, SecretRef, Secret, SecretStatus, SecretCreateRequest, SecretListQuery, SecretRotateRequest, SecretRevokeRequest
Configuration HelmrConfig, HelmrConfigInput, HelmrBuildConfig, HelmrBuildInput, Builder, BuilderStep

Shared conventions

  • Definition IDs match ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$.
  • Duration is a positive safe integer number of milliseconds, or a string of a positive integer followed by ms, s, m, h or d (for example "30s", "7d"). Compound and fractional strings are rejected. Retention options (closeAfterIdle, hibernateAfterIdle, deleteAfterUnused) also accept "never".
  • Input is always an array of text parts (InputContent); omit initial input to create a Session with zero Turns; explicit empty initial input is rejected. Output, responses and question prompts use Content, which also allows JSON parts. Machine results and answers are JSON.
  • Client methods accept an optional final RequestOptions argument, { signal?: AbortSignal }.
  • Client list methods return CursorPage<T>: { items, nextCursor? }. Treat cursors as opaque. See Pagination.
  • Operations inside a Turn handler (turn.output, turn.respond, turn.ask, turn.onMessage) and runtime MCP tools act with the current Session’s runtime authority. A HelmrClient always acts with its own API key, including when it is constructed inside Agent code.