[LinuxDevil]

What

createAgent now supports a five-line hello world:

import { createAgent } from '@loushy/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You are a helpful assistant.' });
const { text } = await agent.send('Hello!');
console.log(text);

• model: 'provider/model' is an alternative to provider. It is resolved with the existing resolveProvider, with the key read from the provider's env var.
• With both provider and model, provider is used and model becomes the per-agent model setting (agent.settings.model). This is documented.
• With neither, the model comes from LOUSHY_MODEL. Otherwise the first provider with a key set is used, in the order OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, OLLAMA_BASE_URL. If none is set, it throws an error listing every fix.
• instructions is the preferred system prompt and is optional (defaults to "You are a helpful assistant."). prompt remains a working alias, and passing both is an error that names both.
• The options type is a union of CreateAgentBase & CreateAgentInstructions & CreateAgentModelSource, so editors show model and provider as alternatives. No any.
• Error messages:
  • Missing key: createAgent: OPENAI_API_KEY is not set. Set it in your environment, or pass a provider instance: createAgent({ provider: ... }).
  • Unknown prefix: lists the supported prefixes and suggests the closest match by edit distance.
  • Missing optional peer: prints the exact npm install <pkg>@<range> command.
  • Nothing configured: lists every fix.
• agent.send() still returns ExecutionResult with a typed text. No run alias was added.

Why

Hello world previously needed two imports and the resolveProvider concept. Competitors need two files (eve) or about 10 lines (open-harness).

How verified

Run on the result of merging origin/main at 89d199f:

• npx tsc --noEmit: clean.
• npm run lint: 0 errors, 425 warnings, none from the changed files (pre-existing).
• npm run build and the create-loushy-agent build: both succeed.
• npm run test:coverage: Test Files 98 passed (98), Tests 1300 passed | 3 skipped (1303). Thresholds met.
• npm run fallow: exit 0.
• npm run docs:verify-snippets: all 35 snippet(s) type-check against src/; 6 also run cleanly.
• packages/create-loushy-agent, npx vitest run: Test Files 4 passed, Tests 8 passed.

Notes for reviewer

• New internal module src/providers/providerSpec.ts is not exported from the barrel. resolveProvider is now a thin wrapper, so the same messages are used with a caller prefix (resolveProvider: or createAgent:).
• Behaviour change in resolveProvider: a missing API key for openai, anthropic or openrouter now throws immediately instead of passing undefined through. Ollama still needs no env var.
• The first quick-start snippet needs a real key, so scripts/verify-docs-snippets.ts gains a no-run fence flag. It is type-checked in both stages but not executed.
• The existing test createAgent({ provider: undefined as any }) now stubs the provider env vars and drops the any, because provider is now optional by design.
• The create-loushy-agent template now generates model: '<provider>/<model>', instructions: ....
• Known limitation, not fixed here: providers statically import their optional peers, so a missing peer can still fail at SDK import time. The npm install hint covers the factory path only. A follow-up ticket is worth filing.

🤖 Generated with Claude Code