@lleverage-ai/agent-sdk 0.0.2 → 0.0.4

package/README.md

@@ -160,6 +160,59 @@ const agent = createAgent({ model, skills });
 
 See [Skills Documentation](./docs/skills.md) for complete details on the skills system and Agent Skills spec compliance.
 
+### Prompt Builder
+
+Create dynamic, context-aware system prompts from composable components. Instead of static strings, prompts automatically include tools, skills, backend capabilities, and more.
+
+**Using the default builder:**
+```typescript
+const agent = createAgent({
+  model,
+  // No systemPrompt = uses default prompt builder
+  tools: { read, write, bash },
+});
+// Automatically generates:
+// "You are a helpful AI assistant.
+//
+// # Available Tools
+// - **read**: Read files
+// - **write**: Write files
+// - **bash**: Execute commands
+//
+// # Capabilities
+// - Execute shell commands (bash)
+// - Read and write files to the filesystem"
+```
+
+**Customizing the prompt:**
+```typescript
+import { createDefaultPromptBuilder } from "@lleverage-ai/agent-sdk";
+
+const builder = createDefaultPromptBuilder()
+  .register({
+    name: "project-context",
+    priority: 95,
+    render: () => "You are working on a TypeScript project.",
+  });
+
+const agent = createAgent({
+  model,
+  promptBuilder: builder,
+  tools,
+});
+```
+
+**Static prompts still work:**
+```typescript
+const agent = createAgent({
+  model,
+  systemPrompt: "You are a helpful assistant.",
+  tools,
+});
+```
+
+See [Prompt Builder Documentation](./docs/prompt-builder.md) for complete details on dynamic prompts, components, and customization.
+
 ### Hooks
 
 Hooks allow you to observe and react to agent lifecycle events:
@@ -189,9 +242,96 @@ const agent = createAgent({
 - `PreGenerate`, `PostGenerate`, `PostGenerateFailure` — Generation lifecycle
 - `PreToolUse`, `PostToolUse`, `PostToolUseFailure` — Tool execution lifecycle
 - `MCPConnectionFailed`, `MCPConnectionRestored` — MCP server connection lifecycle
+- `Custom` — Plugin-defined custom events (see below)
 
 **Hook utilities:** `createRetryHooks`, `createRateLimitHooks`, `createLoggingHooks`, `createGuardrailsHooks`, `createSecretsFilterHooks`, `createToolHook`
 
+**Plugin hooks:** Plugins can define hooks in their configuration, which are automatically merged into the agent's hook registration:
+
+```typescript
+const myPlugin = definePlugin({
+  name: "my-plugin",
+  tools: { /* ... */ },
+  hooks: {
+    PostToolUse: [async ({ tool_name }) => {
+      console.log("Tool used:", tool_name);
+    }],
+  },
+});
+```
+
+**Custom hooks:** Plugins can define their own lifecycle events via `Custom` hooks and `invokeCustomHook()`:
+
+```typescript
+import { invokeCustomHook, TEAM_HOOKS } from "@lleverage-ai/agent-sdk";
+
+// Subscribe to custom events
+const agent = createAgent({
+  model,
+  hooks: {
+    Custom: {
+      [TEAM_HOOKS.TeammateSpawned]: [async (input) => {
+        console.log("Teammate spawned:", input.payload);
+      }],
+    },
+  },
+});
+```
+
+### Background Tasks
+
+Background tasks (bash commands and subagents) are automatically handled. When `generate()`, `stream()`, `streamResponse()`, or `streamDataResponse()` spawns a background task, the agent waits for completion and triggers follow-up generations to process results.
+
+```typescript
+const agent = createAgent({
+  model,
+  subagents: [researcherSubagent],
+
+  // These are the defaults:
+  waitForBackgroundTasks: true,
+
+  // Customize follow-up prompt formatting
+  formatTaskCompletion: (task) => `Task ${task.id} done: ${task.result}`,
+  formatTaskFailure: (task) => `Task ${task.id} failed: ${task.error}`,
+});
+
+// generate() returns only after all background tasks are processed
+const result = await agent.generate({ prompt: "Research this in the background" });
+```
+
+### Agent Teams
+
+Multi-agent coordination where the primary agent becomes a team lead:
+
+```typescript
+import {
+  createAgent,
+  createAgentTeamsPlugin,
+  InMemoryTeamCoordinator,
+} from "@lleverage-ai/agent-sdk";
+
+const teamsPlugin = createAgentTeamsPlugin({
+  teammates: [
+    {
+      id: "researcher",
+      name: "Researcher",
+      description: "Researches topics",
+      create: ({ model }) => createAgent({ model, systemPrompt: "You research topics." }),
+    },
+  ],
+  coordinator: new InMemoryTeamCoordinator(),
+});
+
+const agent = createAgent({
+  model,
+  plugins: [teamsPlugin],
+});
+```
+
+The agent gets a `start_team` tool. When called, it gains team management tools (`team_spawn`, `team_message`, `team_task_create`, etc.) at runtime. Teammates run in background sessions and communicate via mailboxes.
+
+See [Subagents & Teams](./docs/subagents.md) for full details.
+
 ### Streaming
 
 Agents support streaming responses for real-time output:
@@ -212,6 +352,7 @@ export async function POST(req: Request) {
 
 ## Documentation
 
+- [Prompt Builder](./docs/prompt-builder.md) — Dynamic, context-aware system prompts
 - [Skills System](./docs/skills.md) — Progressive disclosure with Agent Skills spec compliance
 - [Tool Loading Strategies](./docs/tool-loading.md) — Eager, lazy, and dynamic tool loading
 - [Security & Production](./docs/security.md) — Security policies, guardrails, and secrets filtering

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAwDH,OAAO,KAAK,EACV,KAAK,EACL,YAAY,EAyBb,MAAM,YAAY,CAAC;AA8lBpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK,CAshExD"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA2DH,OAAO,KAAK,EACV,KAAK,EACL,YAAY,EAyBb,MAAM,YAAY,CAAC;AA6pBpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK,CA2jFxD"}