agent-lattice 0.9.23 → 0.9.25

package/README.md

@@ -230,9 +230,13 @@ const tracer = createLangSmithContextTracer({
 });
 ```
 
-LangSmith receives one root `chain` run per SDK query, child `llm` runs for
-model turns, child `tool` runs for SDK tool calls, and run events for auxiliary
-trace events.
+LangSmith receives one root `chain` run per SDK query. For an `Agent` query,
+model turns and SDK tool calls appear as child `llm` and `tool` runs. For a
+`Team` query, the root represents the complete Team invocation; the initial
+Lead run, delegated Member runs, and later Lead runs all appear beneath that
+root and share one trace session. Each Agent keeps its own SDK session identity,
+recorded as `agent_session_id` metadata, so tracing does not change Agent state
+or returned SDK messages.
 
 Custom sinks can implement the same interface for SQLite, OpenTelemetry, object
 storage, or host-specific observability. The functions below are application
@@ -283,6 +287,88 @@ const result = await agent.prompt("What is 2+2?");
 console.log(result.result);
 ```
 
+## Concurrent Tool Calls
+
+The model requests concurrency by returning multiple `tool_use` blocks in one
+assistant message. The SDK makes the final safety decision. By default, only
+tools whose parsed input passes `isConcurrencySafe(input)` run together:
+
+```ts
+const search = tool(
+  "search",
+  "Search documents",
+  z.object({ query: z.string() }),
+  async ({ query }) => {
+    // App code: replace with your database or search client.
+    return { content: await documentIndex.search(query) };
+  },
+  { isConcurrencySafe: () => true },
+);
+
+const agent = createAgent({
+  model: "claude-sonnet-4-6",
+  tools: [search],
+  toolConcurrency: { mode: "safe", maxConcurrency: 8 },
+});
+```
+
+`safe` is the default mode, `maxConcurrency` defaults to `10`, and tools without
+an `isConcurrencySafe` declaration stay sequential. Use `mode: "all"` only when
+every tool in the Agent is safe to overlap. Use `mode: "sequential"` to disable
+tool concurrency even for tools marked safe.
+
+When concurrency is available, the SDK tells the model to batch independent
+calls and to use separate assistant responses when a later call needs an earlier
+result. Runtime safety checks and `toolBatchPolicy` remain authoritative.
+
+The SDK waits for the complete batch before requesting the model again. Tools
+may finish in any order, while the `tool_result` blocks sent to the model remain
+in the original `tool_use` order. One tool failure does not discard the other
+results. On abort, running handlers receive the shared `AbortSignal`, queued
+handlers do not start, and the SDK waits for handlers that already started to
+settle.
+
+## Tool Batch Policy
+
+Use `toolBatchPolicy` when some tools must not run in the same model response.
+The policy sees the complete batch before any tool executes. If it rejects the
+batch, no tool runs and every tool call receives a structured `is_error: true`
+result.
+
+```ts
+const lead = createAgent({
+  model: "claude-sonnet-4-6",
+  tools: [incrementRevision],
+  toolBatchPolicy: {
+    validate({ toolCalls }) {
+      const incrementsRevision = toolCalls.find(
+        call => call.name === "incrementRevision",
+      );
+      const handoff = toolCalls.find(
+        call => call.kind === "agent_tool" &&
+          (call.input as { mode?: string }).mode === "handoff",
+      );
+      if (incrementsRevision && handoff) {
+        return {
+          allowed: false,
+          code: "invalid_tool_batch",
+          message: "Update the revision before delegating dependent work.",
+          conflictingToolCallIds: [incrementsRevision.id, handoff.id],
+          suggestedNextStep: "Run incrementRevision first, then hand off the new revision.",
+        };
+      }
+      return { allowed: true };
+    },
+  },
+});
+```
+
+The policy may be synchronous or asynchronous. If it throws, the SDK rejects
+the whole batch with `tool_batch_policy_error`; no tool has executed. Without a
+policy, tool execution is unchanged. A policy prevents known bad combinations
+inside one model response, but it does not replace database transactions or
+revision checks against concurrent external updates.
+
 ## Business Context For Tools
 
 Pass host application data through `context`. The SDK gives that context to

package/dist/index.d.ts

@@ -177,6 +177,32 @@ export interface ModelClient {
 export type ToolResult = {
     content: string | ContentBlock[];
 };
+export type ToolKind = "tool" | "agent_tool";
+export type ToolBatchCall = {
+    id: string;
+    name: string;
+    input: unknown;
+    kind: ToolKind;
+};
+export type ToolBatchPolicyContext<TContext = unknown> = {
+    source?: AgentRuntimeSource;
+    toolCalls: ToolBatchCall[];
+    context?: TContext;
+    signal?: AbortSignal;
+};
+export type ToolBatchPolicyRejection = {
+    allowed: false;
+    code: string;
+    message: string;
+    conflictingToolCallIds?: string[];
+    suggestedNextStep?: string;
+};
+export type ToolBatchPolicyResult = {
+    allowed: true;
+} | ToolBatchPolicyRejection;
+export type ToolBatchPolicy<TContext = unknown> = {
+    validate(context: ToolBatchPolicyContext<TContext>): ToolBatchPolicyResult | Promise<ToolBatchPolicyResult>;
+};
 export type ToolExecutionContext<TContext = unknown> = {
     signal?: AbortSignal;
     toolUseId: string;
@@ -185,13 +211,23 @@ export type ToolExecutionContext<TContext = unknown> = {
     permissions?: RuntimePermissions;
 };
 export type ToolHandler<TInput = unknown, TContext = unknown> = (input: TInput, context: ToolExecutionContext<TContext>) => Promise<ToolResult> | ToolResult;
+export type ToolOptions<TInput = unknown> = {
+    isConcurrencySafe?: (input: TInput) => boolean;
+};
 export type ToolDefinition<TInput = unknown, TContext = unknown> = {
     name: string;
     description: string;
+    kind?: ToolKind;
     inputSchema: unknown;
     jsonSchema: Record<string, unknown>;
     parse(input: unknown): TInput;
     handler: ToolHandler<TInput, TContext>;
+    isConcurrencySafe?: (input: TInput) => boolean;
+};
+export type ToolConcurrencyMode = "safe" | "all" | "sequential";
+export type ToolConcurrencyOptions = {
+    mode?: ToolConcurrencyMode;
+    maxConcurrency?: number;
 };
 export type SkillDefinition = {
     name: string;
@@ -386,6 +422,8 @@ export type AgentOptions<TContext = unknown> = {
     maxTurns?: number;
     thinkingConfig?: ThinkingConfig;
     tools?: Array<ToolDefinition<any, TContext>>;
+    toolBatchPolicy?: ToolBatchPolicy<TContext>;
+    toolConcurrency?: ToolConcurrencyOptions;
     skills?: SkillDefinition[];
     workspace?: AgentWorkspaceOptions;
     permission?: (request: PermissionRequest) => Promise<PermissionDecision> | PermissionDecision;
@@ -490,12 +528,16 @@ export declare class MaxTurnsError extends AgentSDKError {
 }
 export declare class AbortError extends AgentSDKError {
 }
+export declare class ToolBatchRejectedError extends AgentSDKError {
+    readonly rejection: ToolBatchPolicyRejection;
+    constructor(rejection: ToolBatchPolicyRejection);
+}
 export declare class ToolPermissionDeniedError extends AgentSDKError {
     readonly denial: PermissionDenial;
     constructor(denial: PermissionDenial);
 }
-export declare function tool<TContext = unknown>(): <TSchema>(name: string, description: string, inputSchema: TSchema, handler: ToolHandler<InferInput<TSchema>, TContext>) => ToolDefinition<InferInput<TSchema>, TContext>;
-export declare function tool<TSchema, TContext = unknown>(name: string, description: string, inputSchema: TSchema, handler: ToolHandler<InferInput<TSchema>, TContext>): ToolDefinition<InferInput<TSchema>, TContext>;
+export declare function tool<TContext = unknown>(): <TSchema>(name: string, description: string, inputSchema: TSchema, handler: ToolHandler<InferInput<TSchema>, TContext>, options?: ToolOptions<InferInput<TSchema>>) => ToolDefinition<InferInput<TSchema>, TContext>;
+export declare function tool<TSchema, TContext = unknown>(name: string, description: string, inputSchema: TSchema, handler: ToolHandler<InferInput<TSchema>, TContext>, options?: ToolOptions<InferInput<TSchema>>): ToolDefinition<InferInput<TSchema>, TContext>;
 export type DelegateToolOptions = {
     wait?: DelegateWaitMode;
     targetMailboxId?: string;
@@ -559,6 +601,7 @@ export declare class Agent<TContext = unknown> {
     private readonly modelClient;
     private readonly messages;
     private readonly sessionId;
+    private readonly toolConcurrency;
     constructor(options: AgentOptions<TContext>);
     query(prompt: string | ContentBlock[], options?: QueryOptions<TContext>): AsyncGenerator<SDKMessage>;
     prompt(prompt: string | ContentBlock[], options?: QueryOptions<TContext>): Promise<SDKResultMessage>;
@@ -569,6 +612,8 @@ export declare class Agent<TContext = unknown> {
     private messagesForModel;
     private selectSkills;
     private runTool;
+    private executeToolBatch;
+    private isToolCallConcurrencySafe;
 }
 type InferInput<TSchema> = TSchema extends {
     parse(input: unknown): infer TInput;