@healthcloudai/hc-ams 0.0.1 → 3.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +204 -7
- package/dist/index.cjs +719 -3
- package/dist/index.d.cts +927 -2
- package/dist/index.d.ts +927 -2
- package/dist/index.js +705 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# HealthCloud AMS SDK for NodeJS / TypeScript
|
|
2
2
|
|
|
3
|
-
Typed access to AMS Services
|
|
3
|
+
Typed access to AMS Services: agent/department/team/skill/policy/guardrail
|
|
4
|
+
CRUD, the data-source and tool catalogs, synthetic test-patient personas,
|
|
5
|
+
conversation history, and the real-time WebSocket agent-chat runtime.
|
|
4
6
|
|
|
5
7
|
## Installation
|
|
6
8
|
|
|
@@ -23,16 +25,211 @@ const agents = await sdk.ams.getAgentsForTenant("<TENANT_ID>");
|
|
|
23
25
|
|
|
24
26
|
`ams.getAgentsForTenant` is public and requires no access token.
|
|
25
27
|
|
|
28
|
+
Every other REST client (`agents`, `departments`, `teams`, `skills`,
|
|
29
|
+
`policies`, `guardrails`, `dataSources`, `tools`, `testPersonas`) requires a
|
|
30
|
+
**Tenant Admin** Bearer token, set via `accessToken` in the constructor or
|
|
31
|
+
`sdk.setAccessToken(token)`. This SDK does not obtain that token itself —
|
|
32
|
+
get one from AMS's own `sdk.auth.login(...)` or from
|
|
33
|
+
`@healthcloudai/hc-tenantadmin`, and pass it in.
|
|
34
|
+
|
|
35
|
+
The WebSocket runtime (`sdk.connectAgentChat(...)` / `WssClient`) is
|
|
36
|
+
authenticated with a **patient** Health Cloud access token instead — obtain
|
|
37
|
+
one via `sdk.testPersonas.login(credentialId)` for testing, or from your
|
|
38
|
+
own patient auth flow in production.
|
|
39
|
+
|
|
40
|
+
## REST clients
|
|
41
|
+
|
|
42
|
+
| Client | Resource | Notes |
|
|
43
|
+
| --- | --- | --- |
|
|
44
|
+
| `sdk.ams` | Public application-agent discovery | No auth required |
|
|
45
|
+
| `sdk.agents` | Agent CRUD, transfer candidates, conversation history | `create`/`update`/`delete` may 405 if the tenant has `disable_direct_agent_mutations` enabled (see below) |
|
|
46
|
+
| `sdk.departments` | Department CRUD + activate/deactivate | |
|
|
47
|
+
| `sdk.teams` | Team CRUD | |
|
|
48
|
+
| `sdk.skills` | Skill CRUD | |
|
|
49
|
+
| `sdk.policies` | Policy CRUD | |
|
|
50
|
+
| `sdk.guardrails` | Guardrail CRUD | |
|
|
51
|
+
| `sdk.dataSources` | Data source catalog | Read-only — AMS exposes no create/update/delete |
|
|
52
|
+
| `sdk.tools` | Tool catalog | Read-only — AMS exposes no create/update/delete |
|
|
53
|
+
| `sdk.testPersonas` | Synthetic QA patient persona CRUD + login | `login()` mints a real Health Cloud patient token |
|
|
54
|
+
| `sdk.auth` | AMS's own Tenant Admin auth proxy (`/api/auth/*`) | Resolves against a different base path than every other client |
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
const sdk = new HCAmsSDK({ environment: "dev", accessToken: tenantAdminToken });
|
|
58
|
+
|
|
59
|
+
const department = await sdk.departments.create({ name: "Cardiology", created_by_user_id: "admin-1" });
|
|
60
|
+
const agent = await sdk.agents.create({ name: "Cardiology Intake", department_id: department.id });
|
|
61
|
+
const history = await sdk.agents.getConversation(agent.id, `${tenantId}/${patientId}`);
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Direct agent mutation
|
|
65
|
+
|
|
66
|
+
Some tenants run with `disable_direct_agent_mutations` enabled, in which
|
|
67
|
+
case AMS's plain `POST/PUT/DELETE /agents` routes respond 405 and real agent
|
|
68
|
+
authoring happens through the Vibe Coder plan/apply flow instead. That flow
|
|
69
|
+
is intentionally out of scope for this SDK — `sdk.agents.create/update/delete`
|
|
70
|
+
only cover the plain-CRUD path.
|
|
71
|
+
|
|
72
|
+
## WebSocket agent-chat runtime
|
|
73
|
+
|
|
74
|
+
> **Since 3.5.1**: the patient token is sent as the first WebSocket frame
|
|
75
|
+
> (`{"type":"auth","token":"..."}`) right after the socket opens, never in
|
|
76
|
+
> the connect URL or as a WS subprotocol — `chat.connect()` doesn't resolve
|
|
77
|
+
> until the server replies `auth_ok`. This is handled internally; you don't
|
|
78
|
+
> need to change any calling code that already passes `healthcloudToken` or
|
|
79
|
+
> `getAccessToken`. It **does require the AMS backend to be on the matching
|
|
80
|
+
> version** (the corresponding server-side change is
|
|
81
|
+
> [healthcloudservices/healthcloud-ams-services#280](https://github.com/healthcloudservices/healthcloud-ams-services/issues/280),
|
|
82
|
+
> merged via #288) — against an older backend, `connect()` will reject with
|
|
83
|
+
> an auth timeout instead of connecting. `WssClientOptions.tokenTransport`
|
|
84
|
+
> (0.0.1) is removed; if your code set it explicitly, delete that line.
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
const sdk = new HCAmsSDK({ environment: "dev", tenantId: "<TENANT_ID>", accessToken: tenantAdminToken });
|
|
88
|
+
|
|
89
|
+
// Mint a patient token for a synthetic test persona.
|
|
90
|
+
const session = await sdk.testPersonas.login(personaCredentialId);
|
|
91
|
+
|
|
92
|
+
// Connect and hold a multi-turn conversation with one agent.
|
|
93
|
+
const chat = sdk.connectAgentChat({
|
|
94
|
+
patientId: session.patient_id,
|
|
95
|
+
healthcloudToken: session.access_token,
|
|
96
|
+
agentId: "<AGENT_ID>", // omit to use the tenant's default agent
|
|
97
|
+
});
|
|
98
|
+
await chat.connect();
|
|
99
|
+
|
|
100
|
+
const turn = await chat.sendAndAwaitTurn("Hi, I'd like to schedule a check-up.");
|
|
101
|
+
console.log(turn.message, turn.transfers, turn.artifacts, turn.notifications, turn.activity);
|
|
102
|
+
|
|
103
|
+
chat.close();
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
**Note:** the `HCAmsSDK` instance's own `accessToken` (Tenant Admin) above
|
|
107
|
+
is only needed because this example uses `testPersonas.login` to mint a
|
|
108
|
+
*synthetic* test patient — a testing convenience, not a production
|
|
109
|
+
pattern. `connectAgentChat`/`WssClient` never read that `accessToken`;
|
|
110
|
+
they only ever use the `healthcloudToken` you pass them explicitly. A real
|
|
111
|
+
patient-facing app needs **no Tenant Admin token at all** — get the
|
|
112
|
+
patient token from your own patient auth (`@healthcloudai/hc-sdk`), e.g.:
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
import { HCSDK } from "@healthcloudai/hc-sdk";
|
|
116
|
+
import { HCAmsSDK } from "@healthcloudai/hc-ams";
|
|
117
|
+
|
|
118
|
+
const patientSdk = new HCSDK({ environment: "dev", tenantId: "<TENANT_ID>" });
|
|
119
|
+
const login = await patientSdk.auth.login({ email, password }); // real patient credentials
|
|
120
|
+
|
|
121
|
+
const amsSdk = new HCAmsSDK({ environment: "dev", tenantId: "<TENANT_ID>" }); // no accessToken needed
|
|
122
|
+
const chat = amsSdk.connectAgentChat({
|
|
123
|
+
patientId: login.fhir_patient_id,
|
|
124
|
+
healthcloudToken: login.access_token,
|
|
125
|
+
agentId: "<AGENT_ID>",
|
|
126
|
+
});
|
|
127
|
+
await chat.connect();
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
`WssClient` also exposes raw typed event subscription for finer-grained
|
|
131
|
+
control:
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
chat.on("turn_started", (e) => console.log("turn started", e.turn_id));
|
|
135
|
+
chat.on("chat", (e) => process.stdout.write(e.content));
|
|
136
|
+
chat.on("transfer", (e) => console.log("agent switched", e.to_agent_id));
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
The entire multi-agent conversation (orchestrator plus any number of
|
|
140
|
+
downstream specialist agents) lives on this **one** WebSocket connection —
|
|
141
|
+
agent switches arrive as `transfer` events, not reconnects.
|
|
142
|
+
|
|
143
|
+
For a **reconnect** (network drop, or your own periodic re-auth), pass
|
|
144
|
+
`getAccessToken` instead of a static `healthcloudToken` so a fresh token is
|
|
145
|
+
resolved on every `connect()` call rather than replaying a captured,
|
|
146
|
+
possibly-expired one:
|
|
147
|
+
|
|
148
|
+
```ts
|
|
149
|
+
const chat = sdk.connectAgentChat({
|
|
150
|
+
patientId,
|
|
151
|
+
getAccessToken: () => myAuthStore.getCurrentPatientToken(), // called on every connect()
|
|
152
|
+
agentId,
|
|
153
|
+
});
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### Guest chat before sign-in, then handoff to an authenticated conversation
|
|
157
|
+
|
|
158
|
+
For an agent configured with `requires_auth: false` (a public, pre-login
|
|
159
|
+
agent), no patient login or access token is needed. The connection still
|
|
160
|
+
requires a `patientId` to form its session ID; generate a random guest ID
|
|
161
|
+
for that — it is **not** a real FHIR patient ID, and the server never
|
|
162
|
+
resolves it against a real patient record for a `requires_auth: false`
|
|
163
|
+
agent.
|
|
164
|
+
|
|
165
|
+
```ts
|
|
166
|
+
const { public: publicAgents, orchestrator } = await amsSdk.ams.getAgentsForTenant(tenantId);
|
|
167
|
+
|
|
168
|
+
const guestId = crypto.randomUUID();
|
|
169
|
+
const guestChat = amsSdk.connectAgentChat({
|
|
170
|
+
patientId: guestId,
|
|
171
|
+
healthcloudToken: "", // no token needed for a requires_auth: false agent
|
|
172
|
+
agentId: publicAgents[0],
|
|
173
|
+
});
|
|
174
|
+
await guestChat.connect();
|
|
175
|
+
|
|
176
|
+
const guestTurn = await guestChat.sendAndAwaitTurn("What services are available?");
|
|
177
|
+
console.log(guestTurn.message);
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Once the patient signs in, start a **new** connection with the real
|
|
181
|
+
`patientId`/`healthcloudToken` — and pass `handoff` with the guest
|
|
182
|
+
transcript so the orchestrator's first greeting can acknowledge it,
|
|
183
|
+
instead of the conversation starting as if nothing was said:
|
|
184
|
+
|
|
185
|
+
```ts
|
|
186
|
+
guestChat.close();
|
|
187
|
+
|
|
188
|
+
const login = await patientSdk.auth.login({ email, password });
|
|
189
|
+
|
|
190
|
+
const chat = amsSdk.connectAgentChat({
|
|
191
|
+
patientId: login.fhir_patient_id,
|
|
192
|
+
healthcloudToken: login.access_token,
|
|
193
|
+
agentId: orchestrator[0],
|
|
194
|
+
handoff: [
|
|
195
|
+
{ role: "user", content: "What services are available?" },
|
|
196
|
+
{ role: "assistant", content: guestTurn.message },
|
|
197
|
+
],
|
|
198
|
+
});
|
|
199
|
+
await chat.connect();
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
`handoff` is sent once, at connect time — the server reads it before
|
|
203
|
+
generating the first greeting, so the greeting itself can reference the
|
|
204
|
+
handed-off content (e.g. "I see you were asking about X — let's continue
|
|
205
|
+
from there"). It is **not** the same as `sendHandoff(messages)` (a
|
|
206
|
+
post-connect frame kept only for callers on the older contract): that one
|
|
207
|
+
can only silently append to history after the greeting has already gone
|
|
208
|
+
out.
|
|
209
|
+
|
|
210
|
+
On Node < 21 (no global `WebSocket`), pass a compatible implementation:
|
|
211
|
+
|
|
212
|
+
```ts
|
|
213
|
+
import WebSocket from "ws";
|
|
214
|
+
|
|
215
|
+
const chat = sdk.connectAgentChat({
|
|
216
|
+
patientId,
|
|
217
|
+
healthcloudToken,
|
|
218
|
+
WebSocketImpl: WebSocket as any,
|
|
219
|
+
});
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
See [`TEST_LIST.md`](./TEST_LIST.md) for a full end-to-end flow: creating a
|
|
223
|
+
department/team/agents/test-persona, logging in as the persona, and
|
|
224
|
+
validating a multi-turn conversation's turns, transfers, artifacts,
|
|
225
|
+
notifications, and activity.
|
|
226
|
+
|
|
26
227
|
## Configuration
|
|
27
228
|
|
|
28
229
|
| Option | Description |
|
|
29
230
|
| --- | --- |
|
|
30
231
|
| `environment` | `"dev"` \| `"uat"` \| `"prod"` — resolves the AMS base URL (`{env-}amsservices.health.cloud/api/ams`, no prefix for `prod`). |
|
|
31
|
-
| `tenantId` | Optional default tenant ID
|
|
32
|
-
| `accessToken` | Optional bearer token for
|
|
232
|
+
| `tenantId` | Optional default tenant ID, used by `connectAgentChat` when no `tenantId` is passed per-call. |
|
|
233
|
+
| `accessToken` | Optional Tenant Admin bearer token for authenticated REST methods. |
|
|
33
234
|
| `baseUrlOverride` | Overrides the resolved AMS base URL (e.g. for local/staging testing). |
|
|
34
235
|
| `timeout` | Request timeout in milliseconds. Defaults to 30000. |
|
|
35
|
-
|
|
36
|
-
## Scope
|
|
37
|
-
|
|
38
|
-
This is an initial, minimal package: it currently ships only `AmsClient.getAgentsForTenant`. Real-time (WebSocket) agent endpoints are intentionally out of scope for this release.
|