-+### Build AI agents that actually *do things*. -[](https://www.npmjs.com/package/general-agent-sdk) - -[](https://www.typescriptlang.org/) - -[](./LICENSE) - -[](./tests) - -[](https://nodejs.org/) +**Stream responses. Call tools. Manage sessions. Ship to production.** -
+[](https://www.npmjs.com/package/general-agent-sdk) +[](./LICENSE) +[](https://www.typescriptlang.org/) +[](https://nodejs.org/) +[](./tests) -**The TypeScript SDK for building AI agents that call tools, manage sessions, and ship to production.** +
-[Quick Start](#-get-started-in-60-seconds) Β· [Architecture](#-architecture) Β· [API Reference](./SDK%20DOCS/API-REFERENCE.md) Β· [Examples](./SDK%20DOCS/) +``` +npm install general-agent-sdk +```
+[Quick Start](#-quick-start) Β· [Examples](./SDK%20DOCS/) Β· [API Reference](./SDK%20DOCS/API-REFERENCE.md) Β· [Documentation](#-documentation) +
-
-
+- **Autonomous tool loops** β agent calls tools and continues thinking until done
+- **8 built-in tools** β `read`, `write`, `edit`, `exec`, `web_search`, `web_fetch`, `apply_patch`, `subagents`
+- **Hosted tools** β define your own tools, SDK suspends & resumes
+- **Multi-turn memory** β sessions remember across turns automatically
+- **Real-time streaming** β every token, tool call, and result as events
+- **MCP integration** β plug in any MCP server (stdio or HTTP)
+- **26 lifecycle hooks** β intercept anything from model selection to tool execution
+- **Subagent delegation** β spawn child agents with scoped instructions
-
+---
-
+## β‘ Quick Start
-### Step 1 β Install
+### 1. Install
```bash
npm install general-agent-sdk
```
-### Step 2 β Set your API key
+### 2. Set your API key
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
-# Optional: use a custom endpoint
+# Optional: use a proxy
# export ANTHROPIC_BASE_URL="https://your-proxy.example.com"
```
-### Step 3 β Run your first agent
+### 3. Build your first agent
```typescript
import { createGeneralAgentSdk } from "general-agent-sdk";
@@ -87,14 +110,16 @@ import { randomUUID } from "node:crypto";
import path from "node:path";
import os from "node:os";
-// 1. Initialize
+// Initialize the SDK
const sdk = await createGeneralAgentSdk({
workspaceDir: process.cwd(),
- stateDir: path.join(process.cwd(), ".agent-state"),
- agentDir: path.join(process.cwd(), ".agent"),
- profileId: "default",
- pluginMode: "disabled",
- logger: { onDebug() {}, onInfo() {}, onWarn() {}, onError() {} },
+ stateDir: path.join(process.cwd(), ".agent-state"),
+ agentDir: path.join(process.cwd(), ".agent"),
+ profileId: "default",
+ pluginMode: "disabled",
+ logger: {
+ onDebug() {}, onInfo() {}, onWarn() {}, onError() {},
+ },
sessionStore: {
async load() { return null; },
async save() {},
@@ -104,225 +129,198 @@ const sdk = await createGeneralAgentSdk({
},
});
-// 2. Create a session
+// Create a session
const session = sdk.createSession({
- identity: { mode: "general", sessionId: randomUUID(), sessionKey: "demo" },
- systemPrompt: "You are a helpful assistant. Use tools when needed.",
- modelRef: "claude-sonnet-4-20250514",
- sessionFile: path.join(os.tmpdir(), "demo-session.jsonl"),
+ identity: { mode: "general", sessionId: randomUUID(), sessionKey: "my-app:default" },
+ systemPrompt: "You are a helpful assistant.",
+ modelRef: "claude-sonnet-4-20250514",
+ sessionFile: path.join(os.tmpdir(), "session.jsonl"),
});
-// 3. Stream a turn β the agent calls tools autonomously
+// Stream a conversation
for await (const event of session.streamTurn({
role: "user",
- content: [{ type: "text", text: "List the files in the current directory" }],
+ content: [{ type: "text", text: "What files are in the current directory?" }],
})) {
switch (event.kind) {
- case "assistant_delta": process.stdout.write(event.text); break;
- case "tool_call": console.log(`\nπ§ ${event.toolName}`); break;
- case "tool_result": console.log(` β
done`); break;
- case "turn_complete": console.log(`\n\nπ Turn complete (${event.stopReason})`); break;
+ case "assistant_delta":
+ process.stdout.write(event.text);
+ break;
+ case "tool_call":
+ console.log(`\nπ§ ${event.toolName}(${JSON.stringify(event.input)})`);
+ break;
+ case "tool_result":
+ console.log(`β
Done`);
+ break;
+ case "turn_complete":
+ console.log(`\n\nβ
Finished (${event.stopReason})`);
+ break;
}
}
await sdk.shutdown();
```
-> **That's it.** The agent autonomously reads the directory, reasons about the output, and streams a formatted answer β all in one `for await` loop.
-
-
-
-
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+npx tsx "SDK DOCS/01-hello-world.ts"
+```
-