import type { Model } from "../types.js"; import { Conversation } from "./conversation.js"; import { AgentStream } from "./stream.js"; import type { AgentConfig, AgentTool, Hooks, InferAgentOutput, ORInputItem, RetryPolicy, RunOptions, RunResult, SchemaLike, ToolConfig } from "./types.js"; /** * Define a tool for use with an Agent. * * `parameters` accepts plain JSON Schema or a Standard Schema V1 object * (Zod v4, Valibot, ArkType, etc.). Standard Schemas are resolved to * JSON Schema at tool creation time. * * @example * ```typescript * // With plain JSON Schema * const getMetric = tool({ * name: 'get_metric', * description: 'Fetch a product metric by name', * parameters: { * type: 'object', * properties: { * metric: { type: 'string' }, * period: { type: 'string', enum: ['7d', '30d', '90d'] }, * }, * required: ['metric'], * }, * execute: async ({ metric, period }) => { * return { metric, value: 42 }; * }, * }); * * // With Zod schema * import { z } from 'zod'; * const getMetric = tool({ * name: 'get_metric', * description: 'Fetch a product metric by name', * parameters: z.object({ metric: z.string(), period: z.string().optional() }), * execute: async ({ metric, period }) => { * return { metric, value: 42 }; * }, * }); * ``` */ export declare function tool(config: ToolConfig): AgentTool; /** * Resolve an AgentTool's parameters to plain JSON Schema. * If parameters is a Standard Schema, it is converted; otherwise passed through. * Returns a new AgentTool with resolved parameters (does not mutate the original). */ export declare function resolveToolSchema(t: AgentTool): Promise; /** * An agent that can run tools and interact with an LLM via the OpenResponses endpoint. * * The type parameter `S` is inferred from `outputSchema` — when you pass a * Standard Schema (Zod, Valibot, etc.), `result.output` is automatically typed. * * @example * ```typescript * // Untyped output (string) * const agent = new Agent({ name: 'bot', instructions: '...' }); * const result = await agent.run('hello'); * result.output; // unknown * * // Typed output via Zod schema * const agent = new Agent({ * name: 'summarizer', * instructions: '...', * outputSchema: z.object({ title: z.string(), points: z.array(z.string()) }), * }); * const result = await agent.run('Summarize...'); * result.output.title; // string — inferred! * ``` */ export declare class Agent { readonly name: string; readonly instructions: string; readonly tools: AgentTool[]; readonly model?: Model; readonly outputSchema?: S; readonly temperature?: number; readonly maxTokens?: number; readonly maxIterations: number; readonly reasoningEffort?: "low" | "medium" | "high"; readonly reasoningSummary?: string; readonly parallelToolExecution: boolean; readonly hooks?: Hooks; readonly traceName: string; readonly tracing: boolean; readonly retry?: RetryPolicy; readonly onMaxIterations?: "throw" | "return_partial"; readonly structuredOutputMode?: "auto" | "native" | "tool"; private readonly providers; private readonly client; private readonly spansClient?; private resolvedOutputSchema?; private _pendingSpanUpdates; constructor(config: AgentConfig); /** * Run the agent to completion, returning the final result. * * @param input - A string prompt or an array of OpenResponses input items. * @param options - Per-run overrides for model, temperature, etc. */ run(input: string | ORInputItem[], options?: RunOptions): Promise>>; /** Internal: drain the streaming loop into a RunResult (no tracing wrapper). */ private executeRun; /** * Stream the agent's execution, yielding events as they happen. * * Returns an AgentStream that can be iterated for events and also * provides a `.result()` method for the final RunResult. * * @param input - A string prompt or an array of OpenResponses input items. * @param options - Per-run overrides for model, temperature, etc. */ stream(input: string | ORInputItem[], options?: RunOptions): AgentStream>; private createTracedStreamGenerator; /** Internal: execute the stream loop without tracing wrapper. */ private executeStream; /** * Create a stateful multi-turn conversation with this agent. * * The conversation tracks the full items history across `.send()` calls * so the agent sees prior turns as context. * * @example * ```typescript * const conv = agent.conversation(); * await conv.send('My name is Alice.'); * const r = await conv.send('What is my name?'); * // Agent remembers "Alice" from the prior turn * ``` */ conversation(): Conversation; /** * Wrap this agent as a tool that another agent can call. * * The returned tool accepts a string `input` and runs this agent to completion, * returning an object with the agent's output and metadata (usage, iterations, tool calls). * * @example * ```typescript * const researcher = new Agent({ name: 'researcher', instructions: '...' }); * const coordinator = new Agent({ * name: 'coordinator', * instructions: 'Delegate research tasks to the researcher tool.', * tools: [researcher.asTool({ name: 'research', description: 'Research a topic' })], * }); * ``` */ asTool(config: { name: string; description: string; }): AgentTool; /** Activate all tool providers, returning discovered tools. */ private activateProviders; /** Deactivate all tool providers (disconnect MCP servers, etc.). */ private deactivateProviders; /** Create a platform span for the synthetic `final_answer` tool call. * * Mirrors {@link wrapToolWithTracing}: type `"tool"` plus tags * `{tool: true, final_answer: true, call_id}` so the platform can render * the structured-output delivery alongside real tool calls while still * being filterable. End-time is set immediately — the synthetic call has * no real duration. Tracing must never break a run, so each step is * best-effort. */ private recordFinalAnswerSpan; /** Lazily resolve outputSchema from Standard Schema to JSON Schema. */ private resolveOutputSchema; } export { Conversation } from "./conversation.js"; export { AbortError, AgentError, MaxIterationsError } from "./errors.js"; export type { MCPServerConfig, MCPSSEConfig, MCPStdioConfig, MCPStreamableHTTPConfig, } from "./mcp/index.js"; export { MCPToolProvider, mcp } from "./mcp/index.js"; export { AgentStream } from "./stream.js"; export { createToolTracingHooks, mergeHooks } from "./tracing.js"; export type { AgentConfig, AgentEndHookContext, AgentStartHookContext, AgentStreamEvent, AgentTool, AggregatedUsage, ErrorHookContext, Hooks, InferAgentOutput, IterationEndEvent, IterationEndHookContext, IterationStartEvent, IterationStartHookContext, LLMCallHookContext, LLMResponseHookContext, ORContentPart, ORError, ORFunctionCallArgsDeltaEvent, ORFunctionCallArgsDoneEvent, ORFunctionCallInputItem, ORFunctionCallOutputItem, ORFunctionCallOutputItemResponse, ORInputItem, ORMessageInputItem, ORMessageOutputItem, OROutputItem, OROutputTextDeltaEvent, OROutputTextDoneEvent, ORReasoning, ORReasoningOutputItem, ORRequest, ORResponse, ORResponseCompletedEvent, ORResponseCreatedEvent, ORStreamEvent, ORTextFormat, ORTool, ORUsage, ReasoningDeltaEvent, ResultEvent, RetryPolicy, RunMeta, RunOptions, RunResult, SchemaLike, StreamErrorEvent, TextDeltaEvent, ToolCallRecord, ToolConfig, ToolEndEvent, ToolEndHookContext, ToolProvider, ToolStartEvent, ToolStartHookContext, } from "./types.js";