agentsdk-agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shetan Mehra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,290 @@
+# @agentsdk/agent
+
+> Multi-step agent runtime for the AgentSDK — model + system prompt + tools + a step loop, with **agent-as-tool handoff** as a first-class primitive.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+`@agentsdk/agent` turns an `AgentConfig` (model + system prompt + tools +
+max steps) into a running agent. Each step the model may emit text or tool
+calls; tool calls are executed and their results fed back, until the model
+stops calling tools or `maxSteps` is reached.
+
+The standout feature is **agent-as-tool handoff**: an agent can be wrapped
+as a callable tool and handed to another agent. When the parent invokes the
+tool, the child agent runs to completion and its final text is returned as
+the tool result. This enables true multi-agent orchestration — a "router"
+agent can delegate to specialised researcher / writer / critic agents as if
+they were tools.
+
+> Built on top of [`@agentsdk/core`](https://github.com/shetanmehra/agentsdk/tree/main/packages/core#readme).
+
+---
+
+## Table of contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [AgentConfig](#agentconfig)
+- [Running an agent](#running-an-agent)
+- [Step events & hooks](#step-events--hooks)
+- [Memory strategies](#memory-strategies)
+- [Agent-as-tool handoff](#agent-as-tool-handoff)
+- [Multi-agent orchestration](#multi-agent-orchestration)
+- [Result shape](#result-shape)
+- [License](#license)
+
+---
+
+## Install
+
+```bash
+bun add @agentsdk/agent @agentsdk/core
+# or
+npm install @agentsdk/agent @agentsdk/core
+```
+
+---
+
+## Quick start
+
+```ts
+import '@agentsdk/core/bootstrap'  // auto-register available providers
+import { runAgent, type AgentConfig } from '@agentsdk/agent'
+
+const agent: AgentConfig = {
+  id: 'writer',
+  name: 'Writer',
+  model: 'gpt-4o-mini',           // or 'glm-4.6', 'claude-3-5-sonnet-20241022', ...
+  provider: 'openai',             // optional — auto-detected if omitted
+  systemPrompt: 'You are a concise technical writer.',
+  maxSteps: 5,
+  temperature: 0.7,
+}
+
+const result = await runAgent(agent, {
+  messages: [{ role: 'user', content: 'Explain async/await in 2 sentences.' }],
+  onStepFinish: (event) => console.log(`[step ${event.step}] ${event.kind}`),
+})
+
+console.log(result.text)
+console.log(result.steps.length)     // number of steps executed
+console.log(result.cost.total)       // aggregated USD cost
+```
+
+> **Note:** The example uses OpenAI (`gpt-4o-mini`) which works anywhere with
+> `OPENAI_API_KEY` set. To use GLM, set `ZAI_API_KEY`. See [`@agentsdk/core`](https://github.com/shetanmehra/agentsdk/tree/main/packages/core#readme)
+> for full provider configuration.
+
+---
+
+## AgentConfig
+
+```ts
+interface AgentConfig {
+  id: string                          // stable id within a graph
+  name: string                        // display name
+  provider?: string                   // optional — auto-detected (prefers glm, then openai, then anthropic)
+  model: string                       // e.g. "glm-4.6"
+  systemPrompt: string
+  tools?: ResolvedTool[]              // tools the agent may call
+  maxSteps?: number                   // default 10
+  temperature?: number
+  maxTokens?: number
+  thinking?: boolean                  // enable provider reasoning mode
+  memoryStrategy?: MemoryStrategy     // default "full"
+  memoryWindow?: number               // for "window" strategy, default 8
+  providerOptions?: Record<string, unknown>
+}
+
+type MemoryStrategy = 'none' | 'full' | 'summary' | 'window'
+```
+
+---
+
+## Running an agent
+
+```ts
+import { runAgent, type AgentRunOptions } from '@agentsdk/agent'
+
+interface AgentRunOptions {
+  messages: Message[]                 // seed input
+  onStepFinish?: StepHook             // called after each step
+  runId?: string                      // auto-generated if omitted
+  maxSteps?: number                   // override config.maxSteps for this run
+}
+
+const result = await runAgent(config, options)
+```
+
+The step loop:
+
+1. Seed history with the agent's system prompt + the input messages.
+2. Apply the memory strategy to bound history size.
+3. Call the provider's `generateText`.
+4. If the model emitted tool calls, execute them, append tool results, go to 2.
+5. If the model returned pure text, that's the final answer — stop.
+6. If `maxSteps` is hit mid-tool-call, mark `truncated: true` and synthesise
+   a final summary by running one more non-tool generation.
+
+---
+
+## Step events & hooks
+
+The `onStepFinish` hook fires after every step (text answer, tool call,
+tool result, or error). Use it for live UI updates, logging, or credit
+deduction per step.
+
+```ts
+interface StepEvent {
+  step: number                        // 1-indexed
+  kind: 'text' | 'tool_call' | 'tool_result' | 'error'
+  text?: string                       // assistant text (text/tool_call)
+  toolCalls?: ToolCall[]              // tool calls requested
+  toolResults?: ToolResult[]          // tool results produced
+  error?: string                      // when kind === 'error'
+  usage: Usage
+  cost: Cost
+  timestamp: string                   // ISO
+}
+
+type StepHook = (event: StepEvent) => void | Promise<void>
+```
+
+---
+
+## Memory strategies
+
+Control how conversation history is carried between steps:
+
+| Strategy   | Behaviour                                                                  |
+| ---------- | -------------------------------------------------------------------------- |
+| `none`     | Keep only system prompt + last user message                                |
+| `full`     | Keep the entire history (default)                                          |
+| `summary`  | Stub — currently behaves like `window`; a real summariser can be plugged in |
+| `window`   | Keep system prompt(s) + the last `memoryWindow` messages (default 8)       |
+
+```ts
+const agent: AgentConfig = {
+  // ...
+  memoryStrategy: 'window',
+  memoryWindow: 12,
+}
+```
+
+---
+
+## Agent-as-tool handoff
+
+> The core differentiator vs Vercel AI SDK.
+
+Wrap any agent as a callable tool, then hand it to a parent agent:
+
+```ts
+import { asTool } from '@agentsdk/agent'
+
+const researcher: AgentConfig = {
+  id: 'researcher',
+  name: 'Researcher',
+  model: 'glm-4.6',
+  systemPrompt: 'You research topics thoroughly. Always cite sources.',
+  maxSteps: 8,
+}
+
+const researcherTool = asTool(researcher, {
+  description: 'Hand off to the Researcher agent for in-depth research.',
+  inputKey: 'input',                  // arg name that becomes the user message
+  onChildStep: (event) => {           // forwarded child step events
+    console.log(`  [researcher step ${event.step}]`, event.kind)
+  },
+})
+
+const parent: AgentConfig = {
+  id: 'router',
+  name: 'Router',
+  model: 'glm-4.6',
+  systemPrompt: 'You are a router. Delegate research tasks to the researcher tool.',
+  tools: [researcherTool],
+  maxSteps: 6,
+}
+```
+
+When the parent calls `researcher({ input: '...' })`, the child agent runs to
+completion and the parent receives:
+
+```ts
+{
+  text: '<child final answer>',
+  agentId: 'researcher',
+  stepsExecuted: 3,
+  usage: { ... },
+  cost: { ... },
+  truncated: false,
+}
+```
+
+### `HandoffOptions`
+
+```ts
+interface HandoffOptions {
+  description?: string
+  parameters?: Record<string, unknown>  // JSON Schema; defaults to a single `input` string
+  inputKey?: string                     // default "input"
+  seedMessages?: Message[]              // extra prepended messages for the child
+  onChildStep?: StepHook                // live child step events
+}
+```
+
+---
+
+## Multi-agent orchestration
+
+The `withHandoffs` helper composes a parent's tool list from ordinary tools
+plus a set of child agents:
+
+```ts
+import { withHandoffs } from '@agentsdk/agent'
+
+const parent: AgentConfig = {
+  id: 'orchestrator',
+  name: 'Orchestrator',
+  model: 'glm-4.6',
+  systemPrompt: 'Coordinate the researcher and writer agents.',
+  tools: withHandoffs(
+    [searchTool, calcTool],            // ordinary tools
+    [
+      { agent: researcher, opts: { description: 'Research a topic' } },
+      { agent: writer,    opts: { description: 'Write a draft' } },
+    ],
+  ),
+  maxSteps: 12,
+}
+```
+
+This pattern scales — one orchestrator can fan out to any number of
+specialised child agents, each with their own model, prompt, and tool set.
+
+---
+
+## Result shape
+
+```ts
+interface AgentRunResult {
+  agentId: string
+  text: string                         // final answer
+  messages: Message[]                  // full post-run history
+  steps: StepEvent[]                   // every step, in order
+  usage: Usage                         // aggregated across steps
+  cost: Cost                           // aggregated across steps
+  stepsExecuted: number
+  truncated: boolean                   // true if maxSteps hit mid-tool
+}
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE). Copyright (c) 2026 Shetan Mehra.
+
+This package is part of the [AgentSDK](https://github.com/shetanmehra/agentsdk)
+monorepo.

package/dist/chunk-55J6XMHW.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=chunk-55J6XMHW.js.map
+//# sourceMappingURL=chunk-55J6XMHW.js.map

package/dist/chunk-55J6XMHW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-55J6XMHW.js"}

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+import { AgentConfig, AgentRunOptions, AgentRunResult, MemoryStrategy } from './types.js';
+export { StepEvent, StepHook, StepKind } from './types.js';
+import * as agentsdk_core from 'agentsdk-core';
+import { Message, ResolvedTool } from 'agentsdk-core';
+
+/**
+ * AgentSDK Agent Runtime — Step loop
+ * MIT License — see LICENSE. Copyright (c) 2026 Shetan Mehra.
+ *
+ * The core agent execution loop:
+ *   1. Seed history with the agent's system prompt + the input messages.
+ *   2. Call the provider's generateText (with automatic retry on transient errors).
+ *   3. If the model emitted tool calls, execute them in PARALLEL and append
+ *      tool results.
+ *   4. Otherwise, the agent is done — return the final text.
+ *   5. Apply the memory strategy before each step to bound history size.
+ *   6. Stop when maxSteps is hit or the model stops calling tools.
+ */
+
+declare function runAgent(config: AgentConfig, options: AgentRunOptions): Promise<AgentRunResult>;
+
+/**
+ * AgentSDK Agent Runtime — Memory strategies
+ * MIT License — see LICENSE. Copyright (c) 2026 Shetan Mehra.
+ *
+ * Reduces the message history between steps according to the agent's
+ * `memoryStrategy`. Each function returns the (possibly trimmed) history.
+ */
+
+/** Apply the memory strategy to a message history. */
+declare function applyMemory(messages: Message[], strategy: MemoryStrategy, windowSize?: number): Message[];
+
+interface HandoffOptions {
+    /** Description the parent agent sees for this "tool". */
+    description?: string;
+    /** Input schema describing what the parent should pass. Defaults to a single `input` string. */
+    parameters?: Record<string, unknown>;
+    /** The argument key that becomes the user message to the child agent. Default: "input". */
+    inputKey?: string;
+    /** Extra seed messages to prepend for the child agent (beyond the input). */
+    seedMessages?: agentsdk_core.Message[];
+    /** Hook fired for every child step (for live UI updates). */
+    onChildStep?: AgentRunOptions['onStepFinish'];
+    /** Maximum handoff depth before recursion is rejected. Default: 5. */
+    maxDepth?: number;
+}
+/**
+ * Wrap an agent as a tool that another agent can call. The resulting tool can
+ * be appended to a parent agent's `tools` array.
+ *
+ * Includes a recursion guard: if the same child agent appears more than
+ * `maxDepth` times in the call chain (e.g. A→B→A→B→...), the tool throws
+ * instead of looping forever.
+ */
+declare function asTool(child: AgentConfig, opts?: HandoffOptions): ResolvedTool;
+/**
+ * Convenience: build a parent agent's tool list by mixing ordinary tools with
+ * a set of child agents (each converted to a tool via `asTool`).
+ */
+declare function withHandoffs(baseTools: ResolvedTool[], children: Array<{
+    agent: AgentConfig;
+    opts?: HandoffOptions;
+}>): ResolvedTool[];
+
+export { AgentConfig, AgentRunOptions, AgentRunResult, type HandoffOptions, MemoryStrategy, applyMemory, asTool, runAgent, withHandoffs };

package/dist/index.js

@@ -0,0 +1,283 @@
+import './chunk-55J6XMHW.js';
+import { addUsage, addCost, normalizeError, generateText, AgentSDKError } from 'agentsdk-core';
+
+// src/memory.ts
+function applyMemory(messages, strategy, windowSize = 8) {
+  switch (strategy) {
+    case "none":
+      return keepHeadAndLastUser(messages);
+    case "full":
+      return messages;
+    case "summary":
+      warnSummaryDeprecated();
+      return applyWindow(messages, windowSize);
+    case "window":
+    default:
+      return applyWindow(messages, windowSize);
+  }
+}
+function applyWindow(messages, windowSize) {
+  const system = [];
+  const rest = [];
+  for (const m of messages) {
+    (m.role === "system" ? system : rest).push(m);
+  }
+  const tail = rest.slice(-Math.max(1, windowSize));
+  return [...system, ...tail];
+}
+function keepHeadAndLastUser(messages) {
+  const system = messages.filter((m) => m.role === "system");
+  const lastUser = [...messages].reverse().find((m) => m.role === "user");
+  return [...system, ...lastUser ? [lastUser] : []];
+}
+var summaryWarned = false;
+function warnSummaryDeprecated() {
+  if (summaryWarned) return;
+  summaryWarned = true;
+  console.warn(
+    '[agentsdk:agent] memoryStrategy "summary" is not yet implemented; falling back to "window" behaviour. Use "window" or "full" to silence this warning.'
+  );
+}
+
+// src/runtime.ts
+var DEFAULT_MAX_STEPS = 10;
+var DEFAULT_MAX_RETRIES = 2;
+var RETRYABLE_TYPES = /* @__PURE__ */ new Set(["rate_limit", "server", "timeout"]);
+var RETRY_BASE_DELAY_MS = 800;
+async function runAgent(config, options) {
+  const maxSteps = options.maxSteps ?? config.maxSteps ?? DEFAULT_MAX_STEPS;
+  const runId = options.runId ?? makeRunId();
+  const onStep = options.onStepFinish;
+  let history = [
+    { role: "system", content: config.systemPrompt },
+    ...options.messages
+  ];
+  const steps = [];
+  let totalUsage = {
+    promptTokens: 0,
+    completionTokens: 0,
+    totalTokens: 0
+  };
+  let totalCost = { input: 0, output: 0, total: 0, currency: "USD" };
+  let finalText = "";
+  let truncated = false;
+  for (let step = 1; step <= maxSteps; step++) {
+    const memStrategy = config.memoryStrategy ?? "full";
+    const windowSize = config.memoryWindow ?? 8;
+    const visible = applyMemory(history, memStrategy, windowSize);
+    let event;
+    try {
+      const result = await generateTextWithRetry(
+        {
+          model: config.model,
+          messages: visible,
+          tools: config.tools,
+          temperature: config.temperature,
+          maxTokens: config.maxTokens,
+          thinking: config.thinking,
+          providerOptions: config.providerOptions
+        },
+        { provider: config.provider }
+      );
+      totalUsage = addUsage(totalUsage, result.usage);
+      totalCost = addCost(totalCost, result.cost);
+      const assistantMsg = {
+        role: "assistant",
+        content: result.text,
+        toolCalls: result.toolCalls.length ? result.toolCalls : void 0
+      };
+      history.push(assistantMsg);
+      if (result.toolCalls.length === 0) {
+        finalText = result.text;
+        event = {
+          step,
+          kind: "text",
+          text: result.text,
+          usage: result.usage,
+          cost: result.cost,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        steps.push(event);
+        await onStep?.(event);
+        break;
+      }
+      const toolResults = await Promise.all(
+        result.toolCalls.map((tc) => executeToolCall(tc, config, step, runId))
+      );
+      for (const toolResult of toolResults) {
+        history.push({
+          role: "tool",
+          content: stringifyToolResult(toolResult.result),
+          name: toolResult.name,
+          toolCallId: toolResult.toolCallId
+        });
+      }
+      event = {
+        step,
+        kind: "tool_call",
+        text: result.text,
+        toolCalls: result.toolCalls,
+        toolResults,
+        usage: result.usage,
+        cost: result.cost,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      steps.push(event);
+      await onStep?.(event);
+      if (step === maxSteps) truncated = true;
+    } catch (err) {
+      const norm = normalizeError(err, config.provider);
+      event = {
+        step,
+        kind: "error",
+        error: norm.message,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      steps.push(event);
+      await onStep?.(event);
+      throw norm;
+    }
+  }
+  if (!finalText && steps.length > 0) {
+    const last = await generateTextWithRetry(
+      {
+        model: config.model,
+        messages: [
+          ...applyMemory(history, config.memoryStrategy ?? "full", config.memoryWindow ?? 8),
+          {
+            role: "system",
+            content: "Summarise the result of the previous tool calls in a concise final answer for the user."
+          }
+        ],
+        temperature: config.temperature,
+        maxTokens: config.maxTokens,
+        providerOptions: config.providerOptions
+      },
+      { provider: config.provider }
+    );
+    finalText = last.text;
+    totalUsage = addUsage(totalUsage, last.usage);
+    totalCost = addCost(totalCost, last.cost);
+  }
+  return {
+    agentId: config.id,
+    text: finalText,
+    messages: history,
+    steps,
+    usage: totalUsage,
+    cost: totalCost,
+    stepsExecuted: steps.length,
+    truncated
+  };
+}
+async function generateTextWithRetry(params, opts) {
+  const maxRetries = DEFAULT_MAX_RETRIES;
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await generateText(params, opts);
+    } catch (err) {
+      lastError = err;
+      const providerId = opts?.provider;
+      const norm = err instanceof AgentSDKError ? err : normalizeError(err, providerId);
+      if (attempt === maxRetries || !RETRYABLE_TYPES.has(norm.type)) {
+        throw norm;
+      }
+      const baseDelay = RETRY_BASE_DELAY_MS * Math.pow(2, attempt);
+      const jitter = baseDelay * (0.8 + Math.random() * 0.4);
+      await new Promise((resolve) => setTimeout(resolve, jitter));
+    }
+  }
+  throw lastError;
+}
+async function executeToolCall(call, config, step, runId) {
+  const tool = config.tools?.find((t) => t.name === call.name);
+  if (!tool || typeof tool.execute !== "function") {
+    return {
+      toolCallId: call.id,
+      name: call.name,
+      result: { error: `Tool "${call.name}" is not defined or has no executor.` },
+      isError: true
+    };
+  }
+  try {
+    const out = await tool.execute(call.arguments, { runId, step });
+    return { toolCallId: call.id, name: call.name, result: out };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      toolCallId: call.id,
+      name: call.name,
+      result: { error: msg },
+      isError: true
+    };
+  }
+}
+function stringifyToolResult(result) {
+  if (typeof result === "string") return result;
+  try {
+    return JSON.stringify(result);
+  } catch {
+    return String(result);
+  }
+}
+function makeRunId() {
+  return `run_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function asTool(child, opts = {}) {
+  const inputKey = opts.inputKey ?? "input";
+  const maxDepth = opts.maxDepth ?? 5;
+  return {
+    name: child.id,
+    description: opts.description ?? `Hand off to the "${child.name}" agent. Pass a natural-language ${inputKey} describing what the child agent should do.`,
+    parameters: opts.parameters ?? {
+      type: "object",
+      properties: {
+        [inputKey]: {
+          type: "string",
+          description: "The task or question to delegate to this agent."
+        }
+      },
+      required: [inputKey],
+      additionalProperties: false
+    },
+    async execute(args, ctx) {
+      const chain = ctx.runId.split(":");
+      const occurrences = chain.filter((x) => x === child.id).length;
+      if (occurrences > maxDepth) {
+        throw new AgentSDKError(
+          `Handoff recursion limit exceeded: agent "${child.id}" appears ${occurrences} times in the call chain (max ${maxDepth}). This usually means two agents are handing off to each other in a loop. Check your agent tool lists for cycles.`,
+          { type: "invalid_request" }
+        );
+      }
+      const input = String(args?.[inputKey] ?? "");
+      const messages = [
+        ...opts.seedMessages ?? [],
+        { role: "user", content: input }
+      ];
+      const result = await runAgent(child, {
+        messages,
+        runId: `${ctx.runId}:${child.id}`,
+        onStepFinish: opts.onChildStep
+      });
+      return {
+        text: result.text,
+        agentId: result.agentId,
+        stepsExecuted: result.stepsExecuted,
+        usage: result.usage,
+        cost: result.cost,
+        truncated: result.truncated
+      };
+    }
+  };
+}
+function withHandoffs(baseTools, children) {
+  return [
+    ...baseTools,
+    ...children.map(({ agent, opts }) => asTool(agent, opts))
+  ];
+}
+
+export { applyMemory, asTool, runAgent, withHandoffs };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map