For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Skip to content

1. Create a Test Service

Create a synthetic Platform text service with a versioned agent and Context Graph, verify its selected versions, and recover from an incomplete setup.

Create the service needed by First Verified Conversation. The downloadable starter creates an agent, an agent version, a Context Graph, a graph version, and a text service that pins those versions. It reads the service back and records the IDs before you run a conversation.

This is a synthetic configuration exercise. The agent explains which information a scheduling team needs before considering an appointment change. It does not implement scheduling or a clinical guideline. The graph's instructions guide model behavior. Access controls and test-system isolation establish the permission boundary.

Before You Start

You can rehearse setup locally with Node.js 22 and npm, without credentials. To create real resources, first arrange the following:

Prerequisite
Ready when

Assigned test workspace

Your administrator supplies its ID and regional Platform base URL. This guide starts with an existing workspace.

Authoring access

Your workspace credential can create and read agents, Context Graphs, versions, and services. Conversation access is also required for the next guide.

Isolated data and actions

The implementation owner confirms this workspace contains only permitted test data and has no production integration credentials, patient records, or outbound channel bindings available to this exercise.

Cleanup owner

Someone with the required deletion permissions can remove these test resources after the conversation is closed.

1. Download and Rehearse

Download the same starter used for the conversation tutorial. It includes both setup and conversation commands, configuration, fixtures, and tests.

archive ยท 56KB
Open
Download the runnable Platform setup and conversation starter.

After extracting it:

cd amigo-first-conversation
npm ci
npm test
npm run setup:demo

Read artifacts/setup-local.json. It should contain mode: "local-fixture" and stage: "verified", along with synthetic resource IDs and selected version numbers. The SDK uses an injected fixture transport and does not contact Concurrence or run a model. The fixture's version numbers deliberately differ from one to check that the sample uses returned values.

The setup command refuses to overwrite an existing setup record. Keep the record until you have inspected the outcome. To repeat a local rehearsal, archive or remove only artifacts/setup-local.json.

2. Understand the Configuration

Review setup-config.json before using a deployment. It contains the complete agent and graph requests, including two graph states: answer_question and finish. The authored exit condition asks the graph to move to finish when the user explicitly says they are finished. The conversation tutorial separately closes the conversation through its lifecycle API.

Order
Resource
What the starter records or verifies

1

The new agent ID. In Console terminology, this is a Persona.

2

Agent version

The returned version number and the synthetic assistant instructions.

3

The new graph ID.

4

Graph version

The returned version number and the initial/terminal states.

5

The agent and graph IDs, explicit release version pins, and channel_type: "text". In Console terminology, this is an Agent.

src/setup.ts executes this sequence. src/setup-cli.ts records the regional base, workspace, unique resource name, current step, acknowledged IDs, and version numbers. It writes a checkpoint before each mutation and reads back the service's active state, channel type, component IDs, and release pins before reporting success.

Configuration verification does not prove that a model can answer, a tool is authorized, or an external action succeeds. Those require the next workflow checks.

3. Create the Test Service

Complete the prerequisites, then supply the API key through your normal secret-injection mechanism in a trusted terminal or server process. Set the non-secret values:

Use your assigned regional base. The US base is an example. This command makes five create requests and one read. It creates real configuration resources and does not start a conversation. The test-workspace flag records your prerequisite check. It does not configure a sandbox or change permissions.

Inspect artifacts/setup-live.json and the command's exit status. Continue only when:

  • The command exits successfully and the record says mode: "provisioned-platform", stage: "verified".

  • The saved regional base and workspace match your test deployment.

  • agent_id, context_graph_id, and service_id are present, with numeric agent and graph versions.

  • You retain this record as the configuration evidence for the conversation test.

4. Run and Verify a Conversation

Copy the service_id from the verified live record into the existing terminal environment:

Follow First Verified Conversation to inspect the answer in durable history, verify closure, and exercise the rejected-request path. Keep the setup record beside the conversation result. A fixture service ID is not a usable deployment resource.

Recover an Incomplete Setup

Setup is a sequence of independent writes, not one transaction. The starter disables automatic retries and does not automatically roll back after failure. A failed command can leave resources behind. Its last saved stage identifies the operation to inspect.

Last recorded stage or symptom
Next action

not_started, authentication failure, or permission rejection

Check the API family, region, workspace, and credential permissions. Inspect any acknowledged IDs before starting another setup.

creating_agent or creating_graph

Search the corresponding resource list for the unique recorded name. A lost response can mean creation succeeded without a locally saved ID.

creating_agent_version or creating_graph_version

Read the recorded parent and list its versions. Compare the intended configuration before creating another version.

creating_service

Search services for the recorded name and inspect its agent/graph IDs and release pins. Do not blindly repeat the create request.

verifying_service

Read the saved service ID. Investigate a read failure or mismatched configuration. Do not treat the create response alone as verification.

Local file-write failure

Stop. Inspect the operation named in the last checkpoint and recover acknowledged or potentially created resources through the API before continuing.

Setup record already exists

Inspect and reconcile that attempt. Archive it only after deciding whether to keep or remove its resources. Removing the file does not remove remote resources.

Use the list, version, read, and deletion operations in Agents, Context Graphs, and Services. If the outcome remains uncertain, keep the record and follow Troubleshooting. Do not include keys or patient data in escalation material.

Clean Up and Continue

After a successful exercise, close the conversation and confirm its lifecycle as described in the conversation guide. Then have the cleanup owner inspect the recorded resources and confirm they are not being reused:

  1. Delete the test service by its recorded ID using client.services.delete(serviceId).

  2. Delete the test graph using client.contextGraphs.delete(graphId).

  3. Delete the test agent using client.agents.delete(agentId).

  4. Confirm each deleted resource returns a not-found response from its read operation. If a deletion response is lost, read the same ID before retrying. Resolve references or permission failures rather than deleting shared resources.

  5. Apply your retention process to test evidence and retained records, then revoke a temporary credential if one was issued. Deleting configuration is not a promise to erase conversation history or all retained versions.

An incomplete attempt needs the reconciliation above before cleanup, including resources whose create response was lost. The setup command does not perform deletion.

For a real workflow, continue with Build and Prove: review the patient arc, data contract, tool permissions, channel configuration, evaluations, and promotion/recovery plan. A pinned agent and graph do not freeze model output, workspace data, runtime defaults, or external-system behavior.


You are here: step 1 of 10 in Learn by Building, Create a Test Service.

Last updated

Was this helpful?