Quickstart

List agents, inspect a service, and run a voice simulation. Your first Platform SDK calls.

This guide walks through your first three Platform SDK calls: listing agents, fetching a service, and running a voice simulation session step by step.

Prerequisites

Before You Begin

1. Installed the SDK in your project.

2. Configured your credentials with a valid API key and workspace ID.

Initialize the Client

import 'dotenv/config'
import { AmigoClient } from '@amigo-ai/platform-sdk'

const client = new AmigoClient({
  apiKey: process.env.AMIGO_API_KEY!,
  workspaceId: process.env.AMIGO_WORKSPACE_ID!,
})

Example 1: List Agents

Fetch all agents in your workspace:

const { agents } = await client.agents.list()

for (const agent of agents) {
  console.log(`Agent: ${agent.name} (ID: ${agent.id})`)
  console.log(`  Latest version: ${agent.latest_version ?? 'none'}`)
  console.log(`  Updated: ${agent.updated_at}`)
}

Retrieve a specific agent's version to see its full configuration:

const agentId = agents[0].id

const version = await client.agents.getVersion(agentId, 'latest')
console.log(`Persona: ${version.identity.persona}`)
console.log(`Background: ${version.background}`)

Example 2: Inspect a Service

List services and inspect the voice configuration of the first one:

const { services } = await client.services.list()
const service = services[0]

console.log(`Service: ${service.name}`)
console.log(`Channel: ${service.channel_type}`)
console.log(`Environment: ${service.environment}`)

// Check version sets
for (const [name, versionSet] of Object.entries(service.version_sets)) {
  console.log(`  Version set "${name}": agent v${versionSet.agent_version}`)
}

Example 3: Run a Voice Simulation

Simulate a caller conversation to test your service behavior without making a real call:

// Step 1: Start a simulation session
const { session_id, greeting } = await client.simulations.createSession({
  service_id: service.id,
  branch_name: 'release',
})

console.log(`Session started: ${session_id}`)
console.log(`Agent greeting: ${greeting}`)

// Step 2: Send a caller message and observe the agent response
const { observation, snapshot } = await client.simulations.step({
  session_id,
  caller_text: "Hi, I'd like to schedule an appointment",
})

console.log(`Agent response: ${observation.agent_response}`)
console.log(`Conversation state: ${snapshot.current_state}`)
console.log(`Is terminal: ${snapshot.is_terminal}`)

// Step 3: Continue the conversation
const { observation: obs2 } = await client.simulations.step({
  session_id,
  caller_text: 'Tomorrow at 2pm works for me',
})

console.log(`Agent: ${obs2.agent_response}`)

// Step 4: Delete the session when done
await client.simulations.deleteSession(session_id)
console.log('Session complete')

Example 4: Pull Analytics

Check dashboard metrics for the last 7 days:

const dashboard = await client.analytics.getDashboard({ days: 7 })

console.log(`Call volume: ${dashboard.call_volume.value}`)
console.log(`Avg quality: ${dashboard.avg_quality.value?.toFixed(1)}`)
console.log(`Escalation rate: ${(dashboard.escalation_rate.value! * 100).toFixed(1)}%`)

// Delta shows week-over-week change
if (dashboard.call_volume.delta_pct !== null) {
  const trend = dashboard.call_volume.delta_pct > 0 ? '▲' : '▼'
  console.log(`Volume trend: ${trend} ${Math.abs(dashboard.call_volume.delta_pct).toFixed(1)}%`)
}

Example 5: Stream a Text Conversation Turn

Send a turn to a text conversation and render the agent's response token by token. The SDK negotiates Accept: text/event-stream on the REST turns endpoint and returns a ReadableStream<Uint8Array> that you parse with eventsource-parser. Every event is typed under the TurnStreamEvent discriminated union.

import { EventSourceParserStream } from 'eventsource-parser/stream'
import type { TurnStreamEvent } from '@amigo-ai/platform-sdk'

const conversation = await client.conversations.create({ service_id: service.id })

const stream = await client.conversations.createTurnStream(conversation.id, {
  message: "I'd like to schedule a follow-up appointment",
})

const events = stream.pipeThrough(new TextDecoderStream()).pipeThrough(new EventSourceParserStream())

for await (const event of events) {
  const parsed = JSON.parse(event.data) as TurnStreamEvent
  switch (parsed.event) {
    case 'token':
      process.stdout.write(parsed.text)
      break
    case 'tool_call_started':
      console.log(`\n[tool: ${parsed.tool_name} started]`)
      break
    case 'tool_call_completed':
      console.log(`[tool: ${parsed.tool_name} ${parsed.succeeded ? 'ok' : 'failed'}]`)
      break
    case 'message':
      console.log(`\n[final: ${parsed.text}]`)
      break
    case 'done':
      console.log(`\n[done — ${parsed.turn_count} turns total]`)
      break
    case 'error':
      console.error(`\n[stream error: ${parsed.message}]`)
      break
  }
}

If the client disconnects mid-stream, the server still finishes the turn and persists the partial agent response. Resuming with client.conversations.get(conversation.id) returns the completed turn.

Example 6: Open a Public Text-Session WebSocket

For interactive UIs, connect a bidirectional WebSocket to the workspace-scoped session-connect endpoint. The SDK builds the URL and provides the auth subprotocol; the API key is delivered via the Sec-WebSocket-Protocol header so it never appears in URLs or proxy logs.

import { sessionConnectAuthProtocols } from '@amigo-ai/platform-sdk'

const url = client.conversations.sessionConnectUrl({
  serviceId: service.id,
  entityId: ENTITY_ID,
  // conversationId is optional — omit for a fresh session
})

const ws = new WebSocket(url, sessionConnectAuthProtocols(process.env.AMIGO_API_KEY!))

ws.addEventListener('message', (event) => {
  const frame = JSON.parse(event.data as string)
  switch (frame.type) {
    case 'session_started':
      console.log(`session ${frame.session_id} (conv ${frame.conversation_id})`)
      break
    case 'message':
      console.log(`agent: ${frame.text}`)
      break
    case 'tool_call_started':
      console.log(`[tool ${frame.tool_name} started]`)
      break
    case 'session_ended':
      console.log(`session ended: ${frame.reason}`)
      break
  }
})

ws.addEventListener('open', () => {
  ws.send(JSON.stringify({ type: 'message', text: 'Hello' }))
})

Available since @amigo-ai/[email protected]. Earlier versions expose only the legacy textStreamUrl() helper that targets /agent/text-stream with the same wire protocol.

Example 7: Look Up an Entity

Retrieve a patient or caller entity from the world model:

const { entities } = await client.world.listEntities({ limit: 10 })

if (entities.length > 0) {
  const entity = entities[0]
  console.log(`Entity: ${entity.display_name ?? entity.entity_type}`)
  console.log(`Type: ${entity.entity_type}`)
  console.log(`Last seen: ${entity.last_event_at}`)
  console.log(`Event count: ${entity.event_count}`)
}

Full Quickstart Script

Here is a complete runnable script combining all examples above:

import 'dotenv/config'
import { AmigoClient } from '@amigo-ai/platform-sdk'

async function main() {
  const client = new AmigoClient({
    apiKey: process.env.AMIGO_API_KEY!,
    workspaceId: process.env.AMIGO_WORKSPACE_ID!,
  })

  // 1. List agents
  const { agents } = await client.agents.list()
  console.log(`\n=== Agents (${agents.length}) ===`)
  for (const agent of agents) {
    console.log(`  ${agent.name} (v${agent.latest_version ?? '?'})`)
  }

  // 2. Inspect first service
  const { services } = await client.services.list()
  if (services.length > 0) {
    const svc = services[0]
    console.log(`\n=== Service: ${svc.name} ===`)
    console.log(`  Channel: ${svc.channel_type}`)
    console.log(`  Agent: ${svc.agent_name}`)
  }

  // 3. Analytics dashboard
  const dashboard = await client.analytics.getDashboard({ days: 7 })
  console.log('\n=== Analytics (7d) ===')
  console.log(`  Calls: ${dashboard.call_volume.value ?? 0}`)
  console.log(`  Avg quality: ${dashboard.avg_quality.value?.toFixed(1) ?? 'N/A'}`)

  console.log('\nDone!')
}

main().catch(console.error)

Next Steps

• Error Handling. Handle errors and edge cases.

• Agents. Deep dive into agent management.

• Voice Simulation. Full simulation coverage reference.

• Analytics & Observability. Call analytics and quality metrics.