@anvia/studio API reference ​
All supported exports come from @anvia/studio. Runtime route handlers and UI modules are internal.
Studio ​
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.
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 ​
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 ​
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 ​
function createInMemoryStudioStore():
& StudioSessionStore
& StudioTraceStore
& StudioPipelineLogStore
& StudioPipelineRunStore
type SqliteSessionStoreOptions = { path?: string }
type SqliteSessionStoreHandle =
& StudioSessionStore
& StudioTraceStore
& StudioPipelineLogStore
& StudioPipelineRunStore
& { close(): void }
function createSqliteSessionStore(options?: SqliteSessionStoreOptions): SqliteSessionStoreHandleclose() releases the underlying SQLite handle. It is synchronous, safe to call more than once, and the store reopens lazily on its next operation. If schema setup fails after the database was opened (for example the legacy messages_json guard), the handle is closed before the error is rethrown.
Store contracts are intentionally public so applications can provide another backend:
| Contract | Responsibilities |
|---|---|
StudioMemoryStore | Append messages and record memory errors. |
StudioSessionStore | Create, list, load, update, and delete Studio sessions. |
StudioTraceStore | Save, get, and list traces. |
StudioPipelineLogStore | Append and list ordered pipeline log entries. |
StudioPipelineRunStore | Save, 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 ​
class StudioTraceObserver implements AgentObserver {
constructor(options: StudioTraceObserverOptions)
startRun(args: AgentRunStartArgs): AgentRunObserver
}
type StudioTraceObserverOptions = {
store: StudioTraceStore | (() => StudioTraceStore | undefined) | undefined
}
function traceSummary(trace: StudioTrace): StudioTraceSummaryTrace 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.
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 // AgentInteractionResponseStudioTeamRunRequest 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.
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.
| Surface | Public types |
|---|---|
| Team runs | StudioTeamConfig, StudioTeamRunRequest, StudioTeamRunEvent |
| Capabilities and status | StudioCapability, StudioCapabilityConfig, StudioStatusSummary, StudioStores, StudioConfig |
| Evaluations | StudioEvalSuite, StudioEvalSuiteConfig, StudioEvalCasePreview, StudioEvalMetricSummary, StudioEvalRunRequest, StudioEvalRunResponse |
| Tools and MCP | StudioAgentToolSource, StudioAgentToolApprovalMetadata, StudioAgentToolMetadata, StudioAgentToolsSummary, StudioToolRunRequest, StudioToolRunResponse, StudioAgentMcpToolMetadata, StudioAgentMcpServerMetadata, StudioAgentMcpsSummary |
| Approvals | StudioToolApproval, StudioToolApprovalDecision, StudioToolApprovalStatus, StudioToolApprovalTranscript, StudioToolApprovalRequestEvent, StudioToolApprovalResultEvent |
| Questions | StudioToolQuestion, StudioToolQuestionChoice, StudioToolQuestionPrompt, StudioToolQuestionAnswer, StudioToolQuestionStatus, StudioToolQuestionTranscript, StudioToolQuestionRequestEvent, StudioToolQuestionResultEvent |
| Sessions and transcripts | StudioSession, StudioSessionSummary, StudioSessionCreateInput, StudioSessionListOptions, StudioSessionRunStatus, StudioSessionRunTranscriptInput, StudioTranscriptEntry, StudioTranscriptChatEntry, StudioTranscriptReasoningEntry, StudioTranscriptToolEntry, StudioTranscriptAttachment, StudioTranscriptChildAgentEvent |
| Session logs | StudioSessionLogEntry, StudioSessionLogAppendInput, StudioSessionLogListOptions, StudioSessionLogLevel, StudioSessionLogCategory, StudioSessionLogEvent |
| Pipeline runs | StudioPipelineRunRequest, StudioPipelineReplayRequest, StudioPipelineRunResponse, StudioPipelineRunRecord, StudioPipelineRunSaveInput, StudioPipelineRunListOptions, StudioPipelineRunGetOptions, StudioPipelineRunStatus, StudioPipelineFinalEvent |
| Pipeline logs | StudioPipelineLogEntry, StudioPipelineLogAppendInput, StudioPipelineLogListOptions, StudioPipelineLogLevel, StudioPipelineLogCategory, StudioPipelineLogEvent |
| Knowledge | StudioAgentKnowledgeConfig, StudioKnowledgeSourceKind, StudioKnowledgeSourceSummary, StudioStaticKnowledgeDocument, StudioKnowledgeEvidence, StudioKnowledgeEvidenceDocument, StudioKnowledgeItem, StudioKnowledgeItemKind, StudioKnowledgeItemsPage, StudioKnowledgeSummary |
| Graphs | StudioGraphRegistration, StudioGraphConfig, StudioGraphExploreRequest |
| Memory inspection | StudioMemoryScope, StudioMemoryAppendOptions, StudioMemoryErrorOptions, StudioMemoryUserSummary, StudioMemoryConversationSummary, StudioMemoryConversationsPage, StudioMemoryUsersPage, StudioMemoryConversationMessages, StudioMemoryConversationSteps, StudioMemoryMessageRecord, StudioMemorySourceKind, StudioMemorySourceSummary, StudioMemorySourcesPage, StudioMemorySourceConversationSummary, StudioMemorySourceConversationsPage, StudioMemorySourceUsersPage, StudioMemorySourceConversationMessages, StudioMemorySourceConversationSteps |
| Sandboxes | StudioSandboxInspector, StudioSandboxRegistration, StudioSandboxCapabilities, StudioSandboxSummary, StudioSandboxesSummary, StudioSandboxFileType, StudioSandboxFileEntry, StudioSandboxFilesResponse, StudioSandboxPort, StudioSandboxPortsResponse, StudioSandboxProcessStatus, StudioSandboxProcess, StudioSandboxProcessesResponse, StudioSandboxProcessLogsResponse |
| Observability | StudioObservabilityEventType, 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.