agent-lattice 0.9.24 → 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,47 @@ 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.

package/dist/index.d.ts

@@ -211,6 +211,9 @@ 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;
@@ -219,6 +222,12 @@ export type ToolDefinition<TInput = unknown, TContext = 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;
@@ -414,6 +423,7 @@ export type AgentOptions<TContext = unknown> = {
     thinkingConfig?: ThinkingConfig;
     tools?: Array<ToolDefinition<any, TContext>>;
     toolBatchPolicy?: ToolBatchPolicy<TContext>;
+    toolConcurrency?: ToolConcurrencyOptions;
     skills?: SkillDefinition[];
     workspace?: AgentWorkspaceOptions;
     permission?: (request: PermissionRequest) => Promise<PermissionDecision> | PermissionDecision;
@@ -526,8 +536,8 @@ 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;
@@ -591,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>;
@@ -601,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;