First Verified Conversation

Run a pinned TypeScript starter, verify a durable text response, exercise a failure, and close the conversation with explicit test-service prerequisites.

Build a trusted Node.js client that creates a web conversation, asks a synthetic scheduling question, reads the answer back from durable history, and closes the conversation. The result is an evidence file you can inspect. This first project does not book an appointment or contact a patient.

Choose how to run the same client:

Start here	What you need	What the result verifies
Local walkthrough	Node.js and npm; no Concurrence account or credentials	The real Platform SDK works with the supplied synthetic HTTP fixtures. No model or Concurrence service is called.
Provisioned test service	A configured test workspace, service, and credential	Your service returns an answer that the client can read back from history, and the conversation closes.

Both paths start with the download below. If you want to test a service in your browser, follow First Console Conversation.

Before You Start

You need Node.js 22 or later, npm, and a tool to extract ZIP files. The starter pins @amigo-ai/platform-sdk to 0.108.1 and commits its dependency lockfile. Use npm ci to reproduce the checked version.

You can run the Local walkthrough immediately. The Provisioned test service tab in step 2 lists the additional setup required before contacting Concurrence.

1. Get the Starter

Download and extract the starter ZIP. It contains only the example source, pinned dependencies, fixtures, tests, and the documentation snapshots used by its checks. No GitHub organization access is required.

amigo-first-conversation.zip

archive · 42KB

Open

Download the runnable Platform conversation starter.

In the extracted directory:

cd amigo-first-conversation
npm ci
npm test

Tests use fixture responses and do not contact Concurrence. npm run check:docs also compiles the included SDK quickstart snapshots and checks this tutorial's client block against its executable source.

2. Run a Conversation

Local walkthrough

npm run demo

No credentials or provisioning are needed. The SDK's injected transport accepts only the example host and never sends a network request. The fixture asks which information a scheduling team needs before considering an appointment change. Its answer explains the prerequisites and says that no appointment changed.

Provisioned test service

Before running this path, your workspace administrator or Concurrence implementation contact must supply:

Prerequisite	Ready when
Regional Platform API base and workspace ID	Both identify the same test deployment; see Regions and Endpoints
Workspace API key	It can create, read, submit turns to, and close conversations in that workspace; see Authentication
Configured test service ID	Its selected agent and Context Graph answer ordinary text questions without requiring a patient entity or production data
Reviewed tool and data access	The service has no production write tools, outbound channel actions, or private patient context; a prompt asking for a test is not an authorization boundary
Configuration record	The implementation owner records the service and selected configuration used for the test

This tutorial does not provision the workspace or author the service. Resolve those dependencies before continuing; use the Local walkthrough while arranging access.

Keep credentials in a trusted terminal or server process. Supply the key through your normal secret-injection mechanism, then set the non-secret deployment values:

export AMIGO_BASE_URL='https://platform.api-us.concurrence.com'
export AMIGO_WORKSPACE_ID='your-test-workspace-id'
export AMIGO_SERVICE_ID='your-configured-test-service-id'
export AMIGO_TEST_SERVICE_CONFIRMED='yes'
# AMIGO_API_KEY must already be supplied by your secret mechanism.
npm start

Use the regional base supplied for your deployment; the US base above is an example. Confirm the prerequisites before setting the test-service flag. The program sends one synthetic user message. Agent wording varies with your configuration and runtime.

3. Inspect the Evidence

Read artifacts/result.json. A successful local run includes:

{
  "mode": "local-fixture",
  "conversation_id": "33333333-3333-4333-8333-333333333333",
  "answer": "Confirm the appointment, the requested change, available alternatives, and the authority to make the change. No appointment has been changed.",
  "durable_answer_verified": true,
  "closed": true,
  "external_action_verified": false
}

For a provisioned run, mode is provisioned-platform, and the ID and answer come from your service. The program verifies that every returned agent answer is present in conversation history and that closure is visible on a subsequent read. A completed text answer establishes neither booking success nor the quality of a clinical decision.

The program writes artifacts/progress.json as soon as creation succeeds, before submitting a turn. If a later request fails, keep that ID and inspect the conversation before retrying. Only a zero exit status and the result from this run establish success; an older result file is not new evidence.

You have completed the conversation when:

• The command exits successfully and writes a new artifacts/result.json.
• mode matches the path you chose.
• answer contains the response and durable_answer_verified is true.
• closed is true. external_action_verified remains false because this exercise does not verify an external action.

Keep this result if you want to compare it with the rejection exercise, which writes its own result to the same file.

4. Exercise a Rejection

npm run demo:failure

This sends an invalid web-create request with force_new: true. The fixture returns a validation rejection, and the program records expected_rejection: 422. The current web contract rejects this combination because every web create already starts a new conversation. To exercise the same rejection in your provisioned test environment, use npm start -- --invalid with the prerequisites above.

An authentication error or transport failure does not count as the expected rejection. See the canonical Conversation operations for the request and response contracts.

5. Understand the Client

Save the conversation ID before the turn; only verified history and closure complete the starter.

The following block is checked against the executable src/starter.ts on every PR. The CLI supplies either the fixture transport or your provisioned client.

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

export const message = 'This is a synthetic documentation exercise. What information would a scheduling team need before considering an appointment change? Do not book or change anything.'

export async function firstConversation(
  client: AmigoClient,
  serviceId: string,
  onCreated: (id: string) => Promise<void> = async () => {},
) {
  const conversation = await client.conversations.create({ service_id: serviceId, channel: 'web' })
  // Persist the ID before sending a turn, so an ambiguous failure can be investigated.
  await onCreated(conversation.id)
  const turn = await client.conversations.createTurn(conversation.id, { message })
  if (turn.background_pending) {
    throw new Error(`Background work remains for ${conversation.id}. Keep this conversation open and follow the web integration delivery guide.`)
  }
  const answers = turn.output.filter(item => item.role === 'agent' && item.text.trim())
  if (!answers.length) throw new Error(`No completed agent answer for ${conversation.id}`)
  const durable = await client.conversations.get(conversation.id)
  if (!answers.every(answer => durable.turns?.some(item => item.role === 'agent' && item.text === answer.text))) {
    throw new Error(`Answer not found in durable history for ${conversation.id}; investigate before retrying`)
  }
  await client.conversations.close(conversation.id)
  const closed = await client.conversations.get(conversation.id)
  if (closed.lifecycle !== 'closed') throw new Error(`Close was not confirmed for ${conversation.id}`)
  return {
    conversation_id: conversation.id,
    answer: answers.map(item => item.text).join('\n'),
    durable_answer_verified: true,
    closed: true,
    external_action_verified: false,
  }
}

export async function demonstrateRejection(client: AmigoClient, serviceId: string) {
  try {
    await client.conversations.create({ service_id: serviceId, channel: 'web', force_new: true })
  } catch (error) {
    if (error && typeof error === 'object' && 'statusCode' in error && error.statusCode === 422) {
      return { expected_rejection: 422, reason: 'force_new does not apply to web conversations' }
    }
    throw error
  }
  throw new Error('Expected a validation rejection but the request succeeded; stop and investigate the contract')
}

If background_pending is true, the starter stops without claiming a completed answer or automatically closing the conversation. Implement the receipt-based delivery flow in Serve an Agent From a Web App before choosing a service with background tools.

6. Clean Up and Continue

A successful conversation run closes its created conversation and verifies closure. Closing ends the conversation lifecycle; it does not erase retained records. After an incomplete run, inspect the saved ID, reconcile pending work, and use the close operation when appropriate. Follow your workspace's retention and deletion process for test records.

Local artifacts and fixture state are disposable. Remove artifacts/ when you no longer need the evidence, and revoke a temporary test key through your normal credential process. The starter does not create a service, entity, sender, or external appointment.

For production, add scoped browser access, request correlation, background delivery and acknowledgement, retry reconciliation, operational monitoring, and workflow-specific authorization. Continue with Verify an Integration Action, Test a Managed SMS Workflow, or Troubleshoot an Integration. Use the SDK Quickstart for additional operations.

Troubleshooting

What you see	What to do next
npm ci or compilation fails	Check node --version is 22 or later and that you are in the extracted starter directory. Keep the supplied lockfile and capture the first installation or compiler error.
A Set AMIGO_... message during a local attempt	Run npm run demo. npm start selects the provisioned path and requires its environment variables.
Authentication or service lookup fails	Check the API family, assigned regional base, workspace, key permissions, and configured service. Start with Choose Credentials.
Background work remains, the answer is missing from history, or the connection fails	Inspect the conversation identified by this attempt's artifacts/progress.json before resending. Follow web delivery for a service that uses background tools.
The result file contains an older success or only expected_rejection	Check the most recent command's exit status. The failure exercise replaces the result file; a previous success does not establish a new successful conversation.
Closure was not confirmed	Inspect the saved conversation's lifecycle and pending work, then follow the documented close operation.