Design philosophy
Type safety everywhere
Every tool parameter is defined with a Zod schema. Every structured output is defined with a Zod schema. Validation happens at runtime, errors surface early, andany types never leak into your application logic. If the LLM returns something that doesn’t match the schema, Vibes retries automatically.
Dependency injection, not globals
RunContext carries your dependencies - database connections, HTTP clients, feature flags, configuration - through the entire agent call chain. To test an agent, you swap its dependencies; you don’t mock modules. This makes agents composable and testable in isolation.
Testing + Evals - the only way to ship AI to production
Shipping an agent is easy. Knowing whether it got better or worse after a change is hard. Vibes treats testing and evals as a single discipline, not two separate afterthoughts. Unit-test every agent in CI withTestModel, FunctionModel, agent.override(), and setAllowModelRequests(false) - no real API calls required, from the first line. Then go further with the full evaluation framework: define typed datasets, score outputs with built-in scorers or an LLM-as-judge, and run experiments with configurable concurrency and retries. Evals are code - they live in your repo, run in CI, and give you a quantitative signal every time you change a prompt, swap a model, or refactor a tool.
Model-agnostic by default
Vibes uses Vercel AI SDK as its model layer. Switching from Anthropic to OpenAI to a local Ollama instance is a one-line change. You never write provider-specific code in your agent logic.Progressive complexity
Start with 5 lines. Add tools. Add structured output. Add dependency injection. Add streaming. Each layer is opt-in. You only pay - in code complexity - for what you use.Standing on the shoulders of giants
Pydantic AI
Pydantic AI - by Samuel Colvin and the Pydantic team - is a Python agent framework built with the same philosophy as Pydantic itself: type safety, validation, and developer experience first. Learn more at ai.pydantic.dev.
Agent class API, the dependency injection pattern using a typed context object, the tool registration approach, the structured output model, and the testing utilities (TestModel, FunctionModel, agent.override()) all originate with Pydantic AI. Samuel Colvin and the Pydantic team showed that agent frameworks can be type-safe and testable without sacrificing the simplicity that makes them worth using.
If you’re familiar with Pydantic AI, you’ll feel at home in Vibes immediately. Most concepts transfer directly - see the comparison table below.
Vercel AI SDK
Vercel AI SDK - maintained by the Vercel team - provides a unified TypeScript interface to 50+ LLM providers with streaming, structured output, and tool-calling support built in. Learn more at sdk.vercel.ai.
Agent accepts a LanguageModel from the AI SDK, which means you get access to Anthropic, OpenAI, Google, Groq, Mistral, Ollama, and dozens more providers through a single unified interface. Vibes does not maintain its own provider integrations - the AI SDK does that work, and does it well.
How Vibes compares
Vibes mirrors Pydantic AI closely. If you’re porting a Python agent, most concepts transfer directly.| Concept | Pydantic AI | @vibesjs/sdk |
|---|---|---|
| Core class | Agent | Agent |
| Run | agent.run_sync() | agent.run() |
| Streaming | agent.run_stream() | agent.stream() |
| Tools | @agent.tool decorator | tool() factory |
| Dependencies | deps: TDeps | deps: TDeps |
| Typed output | result_type: MyModel | outputSchema: z.object(...) |
| Type validation | Pydantic | Zod |
| Result validators | @agent.result_validator | resultValidators: [...] |
| Testing | TestModel / FunctionModel | TestModel / FunctionModel |
| Language | Python | TypeScript |
| Model layer | Pydantic AI providers | Vercel AI SDK |