@agent-ledger/sdk-ts 0.0.1 → 0.0.2
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 +87 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
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 production unless NODE_ENV === "development".
|
|
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 uses:
|
|
77
|
+
- `process.env.AGENT_LEDGER_BASE_URL` if set
|
|
78
|
+
- Production API if `NODE_ENV !== "development"`
|
|
79
|
+
- `http://localhost:3000` otherwise
|
|
80
|
+
|
|
81
|
+
## TypeScript support
|
|
82
|
+
|
|
83
|
+
This package ships its own `.d.ts` files (generated from `src/index.ts`). No additional typings are required.
|
|
84
|
+
|
|
85
|
+
## License
|
|
86
|
+
|
|
87
|
+
MIT
|