> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/guides/create-a-test-service.md).

# 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](https://docs.concurrence.com/developer-guide/guides/first-verified-conversation.md). 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](https://docs.concurrence.com/developer-guide/getting-started/regions-and-endpoints.md). This guide starts with an existing workspace.                             |
| Authoring access          | Your [workspace credential](https://docs.concurrence.com/developer-guide/getting-started/credentials.md) 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.                                                                                                                      |

{% hint style="warning" %}
The sample has no graph tool bindings. Service and runtime configuration can expose additional tools, so an empty tool list or an instruction to avoid writes is not sufficient isolation. Review effective access before creating the service. The sample preserves the platform's caller-verification defaults.
{% endhint %}

## 1. Download and Rehearse

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

{% file src="/files/cgkESp5ztA2rhX4SRogb" %}
Download the runnable Platform setup and conversation starter.
{% endfile %}

After extracting it:

```bash
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     | [Agent](https://docs.concurrence.com/developer-guide/platform-api/workspaces/agents.md)                 | The new agent ID. In Console terminology, this is a Persona.                                                                    |
| 2     | Agent version                                                                                           | The returned version number and the synthetic assistant instructions.                                                           |
| 3     | [Context Graph](https://docs.concurrence.com/developer-guide/platform-api/workspaces/context-graphs.md) | The new graph ID.                                                                                                               |
| 4     | Graph version                                                                                           | The returned version number and the initial/terminal states.                                                                    |
| 5     | [Service](https://docs.concurrence.com/developer-guide/platform-api/workspaces/services.md)             | 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:

```bash
export AMIGO_BASE_URL='https://platform.api-us.concurrence.com'
export AMIGO_WORKSPACE_ID='your-test-workspace-id'
export AMIGO_TEST_WORKSPACE_CONFIRMED='yes'
# AMIGO_API_KEY must already be supplied by your secret mechanism.
npm run setup
```

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:

```bash
export AMIGO_SERVICE_ID='service-id-from-setup-live-json'
export AMIGO_TEST_SERVICE_CONFIRMED='yes'
npm start
```

Follow [First Verified Conversation](https://docs.concurrence.com/developer-guide/guides/first-verified-conversation.md) 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](https://docs.concurrence.com/developer-guide/platform-api/workspaces/agents.md), [Context Graphs](https://docs.concurrence.com/developer-guide/platform-api/workspaces/context-graphs.md), and [Services](https://docs.concurrence.com/developer-guide/platform-api/workspaces/services.md). If the outcome remains uncertain, keep the record and follow [Troubleshooting](https://docs.concurrence.com/developer-guide/guides/troubleshooting.md#prepare-an-escalation). 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](https://docs.concurrence.com/developer-guide/guides/build-and-prove.md): 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](https://docs.concurrence.com/developer-guide/guides.md#implementation-path), Create a Test Service.

**Previous:** [Guides](https://docs.concurrence.com/developer-guide/guides.md#implementation-path). **Next:** [Step 2: First Verified Conversation](https://docs.concurrence.com/developer-guide/guides/first-verified-conversation.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/developer-guide/guides/create-a-test-service.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
