Upgrading to 1.0

​

Who needs this page

npm install @lousho/build-ai-agent@^1.0.0-rc.0

​

Import paths that moved

import { AgentExecutor, AgentBuilder, ToolRegistry } from '@lousho/build-ai-agent/executor';
import { FlowBuilder, validateFlow } from '@lousho/build-ai-agent/flows';
import { createSlackTool } from '@lousho/build-ai-agent/integrations';
import { EncryptionUtils, validateWithSchema } from '@lousho/build-ai-agent/utils';

​

Removed APIs and their replacements

• AgentType, AgentTypeDescriptor, AgentConfig.agentType, AgentBuilder.setType() and the agent-type registry (agentTypesRegistry, getAgentTypeDescriptor, getAllAgentTypeDescriptors, isValidAgentType, validateAgentConfig, validateAgentTools). They had no runtime effect: delete the setType(...) call and the agentType field. A checkpoint saved with agentType still loads; the field is ignored.
• ExecuteOptions.onEvent and the ExecutionEvent / ExecutionEventType types. Pass onAgentEvent to AgentExecutor.execute() / stream() / resumeAfterApproval() instead; the events you now receive are AgentEvents. The event-name mapping is in Streaming. With createAgent(), onEvent already receives AgentEvents and is unchanged.
• createDelegateTool(), DelegateAgentOptions, DelegateAgentResult and DelegationDepthExceededError. Use the subagents option on createAgent() or AgentExecutor.execute(): the model gets one task tool per sub-agent, with a depth limit (maxSubagentDepth, default 1) instead of the thrown error. See Sub-agents.
• Types nothing implemented or used: the repository interfaces (IRepository, IAgentRepository, ISessionRepository, IResultRepository, SessionData, ResultData, SDKRepositories), DataLoadingStatus, PaginationParams, PaginatedResponse, DeepPartial, Timestamped, IdEntity, AgentExecutionOptions, AgentExecutionResult, AgentDefinition and ToolSetting. If your code used one, copy its declaration into your project.

// Before (alpha):
import { createDelegateTool } from '@lousho/build-ai-agent';
const delegate = createDelegateTool({ agent: billing, name: 'billing' });

// After (1.0): the lead gets a `task` tool per sub-agent.
import { createAgent } from '@lousho/build-ai-agent';

const billing = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You answer billing questions.' });
const lead = createAgent({
  model: 'openai/gpt-4o-mini',
  instructions: 'Route questions to the right specialist.',
  subagents: { billing },
});

​

Renamed APIs

​

Deprecated, still working in 1.x

​

Other behavior changes since alpha.8

• The moves, removals and renames above are the ### Breaking section; the notes below are the ### Changed entries that alter behavior.
• A tool whose execute returns an async generator is now iterated - its last yielded value is the result - and AgentEvent gains tool.partial (ToolPartialEvent); wrap a generator you mean to return as a value ({ items: generator }). See Tools and Stream events.
• AgentEvent gains the handoff event and ExecutionResult the optional agentName: an exhaustive switch over event.type needs a handoff case. See Handoffs.
• McpServerStatus gains 'needs-auth' and AgentOAuth gains mcpSignInUrl(server): an exhaustive switch over connectMcp().status() needs the new case. See MCP and OAuth.
• ToolExecutionContext gains getToken(provider) and requireAuth(provider), and ApprovalKind gains 'sign-in': a hand-built tool context in a test needs the two methods (or a cast). See OAuth.
• With a listener (createAgent({ onEvent }), onAgentEvent), send() and execute() now stream model calls: a step’s text arrives as several text.delta events instead of one. execute({ streamModelCalls: false }) restores the old shape. See Stream events.
• MockLLMProvider / createMockProvider(): stream() now streams the same step generate() returns - the same tool calls, finish reason and usage - so a streamed mock run calls tools as send() does. See Testing.
• Agent Forge runs stream their model calls; the chat, logs and trace views are unchanged. See Agent Forge.
• lousho init --provider ollama now scaffolds ai@^7 with ollama-ai-provider-v2@^4 and zod@^4 (it was ai@^4 with ollama-ai-provider@^1 and zod 3). Existing projects are untouched. See Installation.
• A run paused inside a sub-agent compares the sub-agent with its current definition on resume, under the lead’s onAgentDrift - with 'error' a changed sub-agent now rejects agent.approvals.resolve() too. See Durable execution.
• lousho add enforces the registry permission manifest at install, and a loaded agent directory runs each item’s tools inside its accepted manifest (approval always on for exec/needsApproval/unattested items, fetch and process.env scoped to the declaration); mismatched code is refused with LOUSHO_REGISTRY_MANIFEST_MISMATCH, and --yes needs --allow for elevated permissions. See Registry.
• Continuing an unfinished checkpointed run with a principal other than the one it was saved with now throws LOUSHO_CONFIG_INVALID; checkpoints and approval snapshots store the run’s principal. See Route auth and principals.
• The published package is smaller: test-only files no longer ship, and source maps no longer embed sourcesContent (their sources still resolve to the shipped src/). No API change.

​

What 1.0 promises

• Public: every entry point exports declares - the root @lousho/build-ai-agent and the /executor, /tools, /flows, /integrations, /utils, /mcp, /types, /testing, /otel, /hooks, /sqlite, /auth, /kv, /worker, /traces, /triggers, /react, /vue and /svelte subpaths - and every name in the checked-in API reports (api/index.api.md, api/executor.api.md, … in the repository). Removing or renaming one, or changing a signature, needs a major version.
• Internal: everything else, including deep imports into dist/ or src/ (any path exports does not list) and names a public signature uses but does not export (the ae-forgotten-export entries in the reports). These can change in any release.
• Deprecated: names marked @deprecated keep working through 1.x and are removed in 2.0.