@agent-ledger/sdk-ts 0.0.1 → 0.0.3
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 +85 -0
- package/dist/index.js +3 -10
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/src/index.ts +3 -10
package/README.md
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# @agent-ledger/sdk-ts
|
|
2
|
+
|
|
3
|
+
Official TypeScript client for Agent Ledger. The SDK instruments your agents so you can stream sessions, log LLM/tool activity, and enforce budget guardrails against the Agent Ledger API.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
pnpm add @agent-ledger/sdk-ts
|
|
9
|
+
# or
|
|
10
|
+
npm install @agent-ledger/sdk-ts
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Quick start
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { AgentLedgerClient } from "@agent-ledger/sdk-ts";
|
|
17
|
+
|
|
18
|
+
const ledger = new AgentLedgerClient({
|
|
19
|
+
apiKey: process.env.AGENT_LEDGER_API_KEY!,
|
|
20
|
+
// baseUrl is optional. Defaults to the production Agent Ledger API.
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
async function runAgent() {
|
|
24
|
+
const sessionId = await ledger.startSession("support-bot");
|
|
25
|
+
try {
|
|
26
|
+
await ledger.logLLMCall(sessionId, {
|
|
27
|
+
stepIndex: 0,
|
|
28
|
+
model: "gpt-4o",
|
|
29
|
+
provider: "openai",
|
|
30
|
+
prompt: "Draft a welcome email",
|
|
31
|
+
response: "Hello ...",
|
|
32
|
+
tokensIn: 120,
|
|
33
|
+
tokensOut: 98,
|
|
34
|
+
latencyMs: 2300,
|
|
35
|
+
});
|
|
36
|
+
|
|
37
|
+
// ...additional tool calls/events...
|
|
38
|
+
|
|
39
|
+
await ledger.endSession(sessionId, "success");
|
|
40
|
+
} catch (err) {
|
|
41
|
+
await ledger.endSession(sessionId, "error", { errorMessage: (err as Error).message });
|
|
42
|
+
throw err;
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## API surface
|
|
48
|
+
|
|
49
|
+
- `new AgentLedgerClient({ apiKey, baseUrl? })`
|
|
50
|
+
- `startSession(agentName)` → session ID
|
|
51
|
+
- `endSession(sessionId, status, { errorMessage? })`
|
|
52
|
+
- `logEvents(sessionId, events)` (low-level entry point)
|
|
53
|
+
- `logLLMCall`, `logToolCall`, `logToolResult` (typed helpers)
|
|
54
|
+
|
|
55
|
+
All helpers eventually POST to the Agent Ledger REST API using the API key supplied in the constructor.
|
|
56
|
+
|
|
57
|
+
### Budget guardrail errors
|
|
58
|
+
|
|
59
|
+
If Agent Ledger blocks an event because of a per-agent budget limit, the SDK throws `BudgetGuardrailError`. Catch it to inspect the `details` payload and react accordingly:
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
import { BudgetGuardrailError } from "@agent-ledger/sdk-ts";
|
|
63
|
+
|
|
64
|
+
try {
|
|
65
|
+
await ledger.logEvents(sessionId, events);
|
|
66
|
+
} catch (err) {
|
|
67
|
+
if (err instanceof BudgetGuardrailError) {
|
|
68
|
+
console.warn("Budget exceeded", err.details);
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### Environment overrides
|
|
74
|
+
|
|
75
|
+
- `baseUrl` option overrides the API host per client.
|
|
76
|
+
- When omitted, the SDK looks for `process.env.AGENT_LEDGER_BASE_URL` and falls back to `https://agent-ledger-api.azurewebsites.net`.
|
|
77
|
+
- For local testing, set `AGENT_LEDGER_BASE_URL=http://localhost:3000` (or your tunnel URL) before instantiating the client.
|
|
78
|
+
|
|
79
|
+
## TypeScript support
|
|
80
|
+
|
|
81
|
+
This package ships its own `.d.ts` files (generated from `src/index.ts`). No additional typings are required.
|
|
82
|
+
|
|
83
|
+
## License
|
|
84
|
+
|
|
85
|
+
MIT
|
package/dist/index.js
CHANGED
|
@@ -1,20 +1,13 @@
|
|
|
1
1
|
const PROD_BASE_URL = "https://agent-ledger-api.azurewebsites.net";
|
|
2
|
-
const DEV_BASE_URL = "http://localhost:3000";
|
|
3
2
|
const nodeProcess = typeof globalThis !== "undefined" && globalThis.process ? globalThis.process : undefined;
|
|
4
3
|
function resolveBaseUrl(explicit) {
|
|
5
4
|
if (explicit)
|
|
6
5
|
return explicit;
|
|
7
6
|
const envVars = nodeProcess?.env;
|
|
8
|
-
if (envVars) {
|
|
9
|
-
|
|
10
|
-
return envVars.AGENT_LEDGER_BASE_URL;
|
|
11
|
-
}
|
|
12
|
-
const env = envVars.NODE_ENV;
|
|
13
|
-
if (env && env !== "development") {
|
|
14
|
-
return PROD_BASE_URL;
|
|
15
|
-
}
|
|
7
|
+
if (envVars?.AGENT_LEDGER_BASE_URL) {
|
|
8
|
+
return envVars.AGENT_LEDGER_BASE_URL;
|
|
16
9
|
}
|
|
17
|
-
return
|
|
10
|
+
return PROD_BASE_URL;
|
|
18
11
|
}
|
|
19
12
|
export class BudgetGuardrailError extends Error {
|
|
20
13
|
constructor(message, details) {
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,MAAM,aAAa,GAAG,4CAA4C,CAAC;AACnE,MAAM,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
package/src/index.ts
CHANGED
|
@@ -11,23 +11,16 @@ export interface AgentLedgerClientOptions {
|
|
|
11
11
|
}
|
|
12
12
|
|
|
13
13
|
const PROD_BASE_URL = "https://agent-ledger-api.azurewebsites.net";
|
|
14
|
-
const DEV_BASE_URL = "http://localhost:3000";
|
|
15
14
|
const nodeProcess: { env?: Record<string, string | undefined>; } | undefined =
|
|
16
15
|
typeof globalThis !== "undefined" && (globalThis as any).process ? (globalThis as any).process : undefined;
|
|
17
16
|
|
|
18
17
|
function resolveBaseUrl(explicit?: string) {
|
|
19
18
|
if (explicit) return explicit;
|
|
20
19
|
const envVars = nodeProcess?.env;
|
|
21
|
-
if (envVars) {
|
|
22
|
-
|
|
23
|
-
return envVars.AGENT_LEDGER_BASE_URL;
|
|
24
|
-
}
|
|
25
|
-
const env = envVars.NODE_ENV;
|
|
26
|
-
if (env && env !== "development") {
|
|
27
|
-
return PROD_BASE_URL;
|
|
28
|
-
}
|
|
20
|
+
if (envVars?.AGENT_LEDGER_BASE_URL) {
|
|
21
|
+
return envVars.AGENT_LEDGER_BASE_URL;
|
|
29
22
|
}
|
|
30
|
-
return
|
|
23
|
+
return PROD_BASE_URL;
|
|
31
24
|
}
|
|
32
25
|
|
|
33
26
|
export type BudgetGuardrailDetails = {
|