AI agents and runtime sessions — Telemio Documentation

Start a runtime session

A Telemio runtime session can group one agent execution with its tool calls, logs, metrics and usage. Create sessions only in a trusted backend.

Before you begin: Create a Telemio workspace and a scoped ingest credential in the console. Keep server keys in deployment secrets. Set service.name and an environment on every service, and verify signals in the console after starting the process.

TypeScript

import { createTelemio } from "@telemio/sdk"

const telemio = createTelemio({
  apiKey: process.env.TELEMIO_API_KEY,
  workspaceId: process.env.TELEMIO_WORKSPACE_ID,
  serviceName: "support-agent",
  environment: "production"
})

const session = await telemio.runtime.start({
  kind: "agent",
  name: "ticket-triage"
})

const runTelemetry = createTelemio(session.clientOptions)

The session API requires a credential permitted to start runtime sessions in the selected workspace. The resulting ingest token is short-lived and should remain server-side.

Instrument model and tool work

Keep provider/model metadata, usage counts and tool outcomes. Default to metadata rather than recording prompt content.

TypeScript

let outcome: "completed" | "failed" = "completed"

try {
  await runTelemetry.tracer.withSpan("ticket.triage", async () => {
    const agentSpan = runTelemetry.agent.startAgent("ticket-triage")
    try {
      const toolSpan = runTelemetry.agent.startTool("lookup-account")
      try {
        await lookupAccount()
      } finally {
        await toolSpan.end()
      }
      await runTelemetry.agent.recordUsage({
        agentName: "ticket-triage",
        provider: "openai",
        model: "configured-model",
        inputTokens: 850,
        outputTokens: 120
      })
    } finally {
      await agentSpan.end()
    }
  })
} catch (error) {
  outcome = "failed"
  throw error
} finally {
  await session.end({ status: outcome })
}

lookupAccount() represents your application’s existing tool. Replace the sample token values with measured usage from your model provider.

Track context efficiency

Record context metadata without exporting raw documents, user prompts, or secrets.

TypeScript

await runTelemetry.context.loaded({
  id: "kb-billing-v3",
  kind: "documentation",
  source: "internal-knowledge-base",
  estimatedTokens: 2200,
  sensitivity: "internal"
})

Use context summaries and fingerprints when payload disclosure would be unsafe. See agentic runtime instrumentation.

Inspect a run

Find the session by agent name and environment. Review parent/child spans, model usage and tool failures.

If session creation returns 401/403, inspect workspace identity and credential scope. If events are missing, verify the temporary session ingest credential was used with session.clientOptions.