Anvia

@anvia/studio API reference ​

All supported exports come from @anvia/studio. Runtime route handlers and UI modules are internal.

Studio ​

ts
class Studio implements AnviaStudio {
  constructor(targets?: StudioTarget[], options?: StudioOptions)
  get app(): import('hono').Hono
  fetch(request: Request): Response | Promise<Response>
  config(): StudioConfig
  traceObserver(): StudioTraceObserver
  start(options?: StudioServeOptions): this
  serve(options?: StudioServeLifecycleOptions): Promise<void>
  shutdown(options?: { timeoutMs?: number }): Promise<void>
  close(): void
}

start() starts a server and returns immediately. serve() resolves after active runs drain and shutdown completes. shutdown() exposes the same asynchronous draining for an application-owned lifecycle. close() is synchronous, aborts active work, and does not wait for observers. fetch() makes the same application usable in runtimes or servers that accept a Fetch handler.

ts
type StudioServeOptions = {
  port?: number
  hostname?: string
  log?: boolean
  handleSignals?: boolean
  shutdownTimeoutMs?: number
}

type StudioServeLifecycleOptions = Omit<StudioServeOptions, 'handleSignals'> & {
  signal?: AbortSignal
  onShutdown?: () => void | Promise<void>
}

Targets and configuration ​

ts
type StudioTarget = Agent | Pipeline<any, any>

type StudioOptions = {
  evals?: StudioEvalSuite<any, any, any>[]
  quickPrompts?: Record<string, string[]>
  stores?: StudioStores
  ui?: boolean | StudioUiOptions
  models?: StudioModelConfig
  sandboxes?: readonly StudioSandboxRegistration[]
  graphs?: readonly StudioGraphRegistration[]
}

StudioUiOptions configures path, rootRoutes, title, redirectRoot, clientScript, and protectShell. StudioStores independently selects session, trace, pipeline-log, and pipeline-run stores; session and pipeline stores may be disabled with false where the type permits it.

The target configuration types are StudioAgent, StudioAgentConfig, StudioAgentRuntimeSummary, StudioPipeline, StudioPipelineConfig, StudioPipelineDetail, StudioGraphRegistration, StudioGraphConfig, and StudioConfig.

Models ​

ts
type StudioModelRef = { providerId: string; modelId: string }

type StudioModelProvider = {
  id: string
  name?: string
  defaultModelId?: string
  models?: StudioModelDefinition[]
  createCompletionModel(options: { modelId: string }):
    CompletionModel | StreamingCompletionModel
  listModels?: (options?: { abortSignal?: AbortSignal }) => Promise<ModelList>
  metadata?: JsonObject
}

type StudioAgentModelPolicy = {
  defaultModelRef?: StudioModelRef
  allowed?: Array<StudioModelRef | `${string}:*`>
}

type StudioModelConfig = {
  providers: StudioModelProvider[]
  defaultModelRef?: StudioModelRef
  agents?: Record<string, StudioAgentModelPolicy>
}

Supporting public types include StudioModelDefinition, StudioModelModality, StudioModelModalities, StudioAgentModelPolicy, StudioModelSummary, StudioModelProviderConfig, StudioAgentModelPolicyConfig, StudioModelsConfig, and StudioAgentModelsSummary.

Stores ​

ts
function createInMemoryStudioStore():
  & StudioSessionStore
  & StudioTraceStore
  & StudioPipelineLogStore
  & StudioPipelineRunStore

type SqliteSessionStoreOptions = { path?: string }

function createSqliteSessionStore(options?: SqliteSessionStoreOptions):
  & StudioSessionStore
  & StudioTraceStore
  & StudioPipelineLogStore
  & StudioPipelineRunStore

Store contracts are intentionally public so applications can provide another backend:

ContractResponsibilities
StudioMemoryStoreAppend messages and record memory errors.
StudioSessionStoreCreate, list, load, update, and delete Studio sessions.
StudioTraceStoreSave, get, and list traces.
StudioPipelineLogStoreAppend and list ordered pipeline log entries.
StudioPipelineRunStoreSave, get, and list replayable pipeline runs.

Their related input, list-options, record, status, summary, paging, and event types are public and listed by family below.

Trace observer ​

ts
class StudioTraceObserver implements AgentObserver {
  constructor(options: StudioTraceObserverOptions)
  startRun(args: AgentRunStartArgs): AgentRunObserver
}

type StudioTraceObserverOptions = {
  store: StudioTraceStore | (() => StudioTraceStore | undefined) | undefined
}

function traceSummary(trace: StudioTrace): StudioTraceSummary

Trace records use StudioTrace, StudioTraceSummary, StudioTraceObservation, StudioTraceStatus, StudioTraceObservationKind, StudioTraceListOptions, and StudioSessionTraceListOptions.

Requests, events, and errors ​

AgentRunRequest accepts a normalized messages array plus optional session ID, streaming, max-turn, tool-concurrency, model, metadata, and trace controls. AgentRunResponse aliases Core AgentResponse.

AgentRunStreamEvent combines core agent events with Studio approval, question, session-log, pipeline-log, and pipeline-final events.

Team runs ​

Registered AgentTeam targets gain live run routes. Team IDs occupy a separate namespace from agent IDs.

ts
const studio = new Studio([agent, team])

// Config exposure
GET /teams                    // -> StudioTeamConfig[]
GET /teams/:teamId            // -> StudioTeamConfig

// Run lifecycle (JSONL event stream)
POST /teams/:teamId/runs                                          // { prompt } | { messages }
POST /teams/:teamId/runs/:runId/steer                             // { prompt } | user-only { messages }
POST /teams/:teamId/runs/:runId/cancel                            // {}
POST /teams/:teamId/runs/:runId/interactions/:interactionId       // AgentInteractionResponse

StudioTeamRunRequest is { prompt } or { messages } (at most 256 messages, last must be a user message). StudioTeamRunEvent is { type: 'team_run_started', teamId, runId }, then core AgentTeamEvents, then a terminal outcome or { type: 'error', error }. The Studio control ID also arrives in the x-anvia-team-run-id response header. Disconnecting or shutting down cancels the run; completed runs return 404 on later control requests.

ts
type StudioErrorCode =
  | 'bad_request'
  | 'conflict'
  | 'not_found'
  | 'payload_too_large'
  | 'unsupported_capability'
  | 'internal_error'

StudioErrorResponse wraps the code, message, and optional JSON details.

Public type inventory ​

The remaining public types are grouped by the Studio surface that produces or consumes them.

SurfacePublic types
Team runsStudioTeamConfig, StudioTeamRunRequest, StudioTeamRunEvent
Capabilities and statusStudioCapability, StudioCapabilityConfig, StudioStatusSummary, StudioStores, StudioConfig
EvaluationsStudioEvalSuite, StudioEvalSuiteConfig, StudioEvalCasePreview, StudioEvalMetricSummary, StudioEvalRunRequest, StudioEvalRunResponse
Tools and MCPStudioAgentToolSource, StudioAgentToolApprovalMetadata, StudioAgentToolMetadata, StudioAgentToolsSummary, StudioToolRunRequest, StudioToolRunResponse, StudioAgentMcpToolMetadata, StudioAgentMcpServerMetadata, StudioAgentMcpsSummary
ApprovalsStudioToolApproval, StudioToolApprovalDecision, StudioToolApprovalStatus, StudioToolApprovalTranscript, StudioToolApprovalRequestEvent, StudioToolApprovalResultEvent
QuestionsStudioToolQuestion, StudioToolQuestionChoice, StudioToolQuestionPrompt, StudioToolQuestionAnswer, StudioToolQuestionStatus, StudioToolQuestionTranscript, StudioToolQuestionRequestEvent, StudioToolQuestionResultEvent
Sessions and transcriptsStudioSession, StudioSessionSummary, StudioSessionCreateInput, StudioSessionListOptions, StudioSessionRunStatus, StudioSessionRunTranscriptInput, StudioTranscriptEntry, StudioTranscriptChatEntry, StudioTranscriptReasoningEntry, StudioTranscriptToolEntry, StudioTranscriptAttachment, StudioTranscriptChildAgentEvent
Session logsStudioSessionLogEntry, StudioSessionLogAppendInput, StudioSessionLogListOptions, StudioSessionLogLevel, StudioSessionLogCategory, StudioSessionLogEvent
Pipeline runsStudioPipelineRunRequest, StudioPipelineReplayRequest, StudioPipelineRunResponse, StudioPipelineRunRecord, StudioPipelineRunSaveInput, StudioPipelineRunListOptions, StudioPipelineRunGetOptions, StudioPipelineRunStatus, StudioPipelineFinalEvent
Pipeline logsStudioPipelineLogEntry, StudioPipelineLogAppendInput, StudioPipelineLogListOptions, StudioPipelineLogLevel, StudioPipelineLogCategory, StudioPipelineLogEvent
KnowledgeStudioAgentKnowledgeConfig, StudioKnowledgeSourceKind, StudioKnowledgeSourceSummary, StudioStaticKnowledgeDocument, StudioKnowledgeEvidence, StudioKnowledgeEvidenceDocument, StudioKnowledgeItem, StudioKnowledgeItemKind, StudioKnowledgeItemsPage, StudioKnowledgeSummary
GraphsStudioGraphRegistration, StudioGraphConfig, StudioGraphExploreRequest
Memory inspectionStudioMemoryScope, StudioMemoryAppendOptions, StudioMemoryErrorOptions, StudioMemoryUserSummary, StudioMemoryConversationSummary, StudioMemoryConversationsPage, StudioMemoryUsersPage, StudioMemoryConversationMessages, StudioMemoryConversationSteps, StudioMemoryMessageRecord, StudioMemorySourceKind, StudioMemorySourceSummary, StudioMemorySourcesPage, StudioMemorySourceConversationSummary, StudioMemorySourceConversationsPage, StudioMemorySourceUsersPage, StudioMemorySourceConversationMessages, StudioMemorySourceConversationSteps
SandboxesStudioSandboxInspector, StudioSandboxRegistration, StudioSandboxCapabilities, StudioSandboxSummary, StudioSandboxesSummary, StudioSandboxFileType, StudioSandboxFileEntry, StudioSandboxFilesResponse, StudioSandboxPort, StudioSandboxPortsResponse, StudioSandboxProcessStatus, StudioSandboxProcess, StudioSandboxProcessesResponse, StudioSandboxProcessLogsResponse
ObservabilityStudioObservabilityEventType, StudioObservabilityEvent, AgentTraceInfo, AgentTraceOptions

The exact fields for these transport and storage types are part of the published declarations. Prefer consuming the types directly instead of reproducing request shapes locally.

Built for Anvia.