> ## Documentation Index
> Fetch the complete documentation index at: https://vibes-sdk.a7ul.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Why Vibes exists, its design philosophy, and the projects that inspired it.

Vibes is a TypeScript agent framework that brings [Pydantic AI](https://ai.pydantic.dev/)'s proven patterns to the TypeScript ecosystem, using [Vercel AI SDK](https://sdk.vercel.ai/) for LLM calls. It is designed for developers who want type safety, testability, and production-readiness without sacrificing simplicity.

## 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, and `any` 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 with `TestModel`, `FunctionModel`, `agent.override()`, and `setAllowModelRequests(false)` - no real API calls required, from the first line. Then go further with the full [evaluation framework](/concepts/evals): 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

<Info>
  **Pydantic AI** - by Samuel Colvin and the [Pydantic team](https://pydantic.dev/) - 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](https://ai.pydantic.dev/).
</Info>

Vibes is, in a real sense, Pydantic AI for TypeScript. The `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

<Info>
  **Vercel AI SDK** - maintained by the [Vercel team](https://vercel.com/) - 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](https://sdk.vercel.ai/).
</Info>

Vibes uses Vercel AI SDK as its model layer. Every `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                 |

See [Feature Parity](/reference/features) for the full comparison.

## Next steps

<CardGroup cols={2}>
  <Card title="Install" href="/getting-started/install" icon="download">
    Set up Vibes in your project in under 2 minutes
  </Card>

  <Card title="Hello World Tutorial" href="/getting-started/hello-world" icon="rocket">
    Build a complete weather agent step by step
  </Card>
</CardGroup>