@healthcloudai/hc-ams 0.0.1 → 3.5.1
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 +101 -7
- package/dist/index.cjs +711 -3
- package/dist/index.d.cts +907 -2
- package/dist/index.d.ts +907 -2
- package/dist/index.js +697 -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,108 @@ 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
|
+
```ts
|
|
75
|
+
const sdk = new HCAmsSDK({ environment: "dev", tenantId: "<TENANT_ID>", accessToken: tenantAdminToken });
|
|
76
|
+
|
|
77
|
+
// Mint a patient token for a synthetic test persona.
|
|
78
|
+
const session = await sdk.testPersonas.login(personaCredentialId);
|
|
79
|
+
|
|
80
|
+
// Connect and hold a multi-turn conversation with one agent.
|
|
81
|
+
const chat = sdk.connectAgentChat({
|
|
82
|
+
patientId: session.patient_id,
|
|
83
|
+
healthcloudToken: session.access_token,
|
|
84
|
+
agentId: "<AGENT_ID>", // omit to use the tenant's default agent
|
|
85
|
+
});
|
|
86
|
+
await chat.connect();
|
|
87
|
+
|
|
88
|
+
const turn = await chat.sendAndAwaitTurn("Hi, I'd like to schedule a check-up.");
|
|
89
|
+
console.log(turn.message, turn.transfers, turn.artifacts, turn.notifications, turn.activity);
|
|
90
|
+
|
|
91
|
+
chat.close();
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`WssClient` also exposes raw typed event subscription for finer-grained
|
|
95
|
+
control:
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
chat.on("turn_started", (e) => console.log("turn started", e.turn_id));
|
|
99
|
+
chat.on("chat", (e) => process.stdout.write(e.content));
|
|
100
|
+
chat.on("transfer", (e) => console.log("agent switched", e.to_agent_id));
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
The entire multi-agent conversation (orchestrator plus any number of
|
|
104
|
+
downstream specialist agents) lives on this **one** WebSocket connection —
|
|
105
|
+
agent switches arrive as `transfer` events, not reconnects.
|
|
106
|
+
|
|
107
|
+
On Node < 21 (no global `WebSocket`), pass a compatible implementation:
|
|
108
|
+
|
|
109
|
+
```ts
|
|
110
|
+
import WebSocket from "ws";
|
|
111
|
+
|
|
112
|
+
const chat = sdk.connectAgentChat({
|
|
113
|
+
patientId,
|
|
114
|
+
healthcloudToken,
|
|
115
|
+
WebSocketImpl: WebSocket as any,
|
|
116
|
+
});
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
See [`TEST_LIST.md`](./TEST_LIST.md) for a full end-to-end flow: creating a
|
|
120
|
+
department/team/agents/test-persona, logging in as the persona, and
|
|
121
|
+
validating a multi-turn conversation's turns, transfers, artifacts,
|
|
122
|
+
notifications, and activity.
|
|
123
|
+
|
|
26
124
|
## Configuration
|
|
27
125
|
|
|
28
126
|
| Option | Description |
|
|
29
127
|
| --- | --- |
|
|
30
128
|
| `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
|
|
129
|
+
| `tenantId` | Optional default tenant ID, used by `connectAgentChat` when no `tenantId` is passed per-call. |
|
|
130
|
+
| `accessToken` | Optional Tenant Admin bearer token for authenticated REST methods. |
|
|
33
131
|
| `baseUrlOverride` | Overrides the resolved AMS base URL (e.g. for local/staging testing). |
|
|
34
132
|
| `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.
|