agent-lattice 0.14.0 → 0.15.0

package/README.md

@@ -700,6 +700,44 @@ type AgentLike<TContext = unknown> = {
 That means a team can be used anywhere a callable agent is expected. From the
 outside, a team is an agent; inside, it can contain a whole organization.
 
+## Agent Specs (Templates) And Sessions
+
+*Requires 0.15.0 or later.*
+
+`createAgent()` returns a live session: one conversation, one history, one
+workspace. `defineAgent()` returns an `AgentSpec` — a template carrying the
+same options but no state. `spawn()` creates an independent session from it:
+
+```ts
+import { agentTool, defineAgent } from "agent-lattice";
+
+const reviewerSpec = defineAgent({
+  name: "reviewer",
+  model: "claude-sonnet-4-5",
+  systemPrompt: "You are a senior code reviewer...",
+});
+
+// Register the spec: every tool call spawns a fresh session with no memory
+// of previous calls. This is the safe default for reuse.
+const lead = createAgent({
+  model: "claude-sonnet-4-5",
+  tools: [
+    agentTool("review", reviewerSpec, {
+      description: "Ask the reviewer to audit a change.",
+    }),
+  ],
+});
+
+// Register a spawned session instead when the target should remember earlier
+// tasks across calls — continuity is an explicit opt-in.
+const reviewSession = reviewerSpec.spawn();
+```
+
+The same union applies to `delegateTool()`. The generated tool description
+states which semantics a target has, so the calling agent knows whether each
+task must be self-contained. Existing code that passes an `AgentLike` keeps
+its current behavior: a long-lived session with history.
+
 ## Team Mailbox Collaboration
 
 Use `createTeam()` when you want to talk to one `AgentLike` while it coordinates

package/dist/index.d.ts

@@ -692,12 +692,33 @@ export type AgentToolOptions = {
     description: string;
     targetMailboxId?: string;
 };
-export declare function agentTool(name: string, agent: AgentLike<any>, options: AgentToolOptions): ToolDefinition<AgentToolInput>;
-export declare function delegateTool(name: string, description: string, agent: AgentLike<any>, options?: DelegateToolOptions): ToolDefinition<{
+/**
+ * An AgentLike is a live session: it keeps its conversation history across
+ * calls. An AgentSpec is a template: each call spawns a fresh session with no
+ * memory of previous calls. Prefer a spec unless the parent explicitly wants
+ * continuity.
+ */
+export type AgentToolTarget = AgentLike<any> | AgentSpec<any>;
+export declare function agentTool(name: string, agent: AgentToolTarget, options: AgentToolOptions): ToolDefinition<AgentToolInput>;
+export declare function delegateTool(name: string, description: string, agent: AgentToolTarget, options?: DelegateToolOptions): ToolDefinition<{
     task: string;
 }>;
 export declare function createAgent<TContext = unknown>(options: AgentOptions<TContext>): Agent<TContext>;
 export declare function createBareAgent<TContext = unknown>(options: BareAgentOptions<TContext>): Agent<TContext>;
+/**
+ * A template describing an agent's identity: model, prompt, tools, skills,
+ * and workspace policy. A spec carries no conversation state; `spawn()`
+ * creates an independent session (an Agent) that owns its own history and
+ * workspace. Register a spec wherever a capability should be reused without
+ * leaking memory between tasks; spawn a session when continuity is wanted.
+ */
+export type AgentSpec<TContext = unknown> = {
+    readonly name?: string;
+    readonly options: AgentOptions<TContext>;
+    spawn(overrides?: Partial<AgentOptions<TContext>>): Agent<TContext>;
+};
+export declare function defineAgent<TContext = unknown>(options: AgentOptions<TContext>): AgentSpec<TContext>;
+export declare function isAgentSpec(target: AgentLike<any> | AgentSpec<any>): target is AgentSpec<any>;
 export declare function createBuiltinTools(options?: AgentWorkspaceToolsOptions): Array<ToolDefinition<any, any>>;
 export declare function createJsonlContextTracer(options: JsonlContextTracerOptions): ContextTracer;
 /**