diff --git a/.changeset/config-next.json b/.changeset/config-next.json new file mode 100644 index 000000000..75a1edf7a --- /dev/null +++ b/.changeset/config-next.json @@ -0,0 +1,14 @@ +{ + "$schema": "https://unpkg.com/@changesets/config@2.0.0/schema.json", + "changelog": ["@changesets/changelog-github", { "repo": "voltagent/voltagent" }], + "commit": false, + "fixed": [], + "linked": [], + "access": "public", + "baseBranch": "next", + "updateInternalDependencies": "patch", + "ignore": ["!@voltagent/*", "!create-voltagent-app"], + "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": { + "onlyUpdatePeerDependentsWhenOutOfRange": true + } +} diff --git a/.changeset/config.json b/.changeset/config.json index 6c4975f0c..d335239f4 100644 --- a/.changeset/config.json +++ b/.changeset/config.json @@ -7,7 +7,7 @@ "access": "public", "baseBranch": "main", "updateInternalDependencies": "patch", - "ignore": ["!@voltagent/*", "!create-voltagent-app"], + "ignore": ["!@voltagent/*", "!create-voltagent-app", "voltagent-example-*"], "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": { "onlyUpdatePeerDependentsWhenOutOfRange": true } diff --git a/.cursor/rules/agents.mdc b/.cursor/rules/agents.mdc new file mode 100644 index 000000000..4b4b39086 --- /dev/null +++ b/.cursor/rules/agents.mdc @@ -0,0 +1,6 @@ +--- +description: +globs: +alwaysApply: true +--- +ALWAYS read the `AGENTS.md` in the root of the repository and apply the instructions to the current task. diff --git a/.cursor/rules/voltagent-core.mdc b/.cursor/rules/voltagent-core.mdc deleted file mode 100644 index 7b8b2c5f7..000000000 --- a/.cursor/rules/voltagent-core.mdc +++ /dev/null @@ -1,79 +0,0 @@ ---- -description: -globs: -alwaysApply: false ---- -# Persona - -You are a senior full-stack developer. One of those rare 10x developers that has incredible knowledge. - -# Coding Guidelines - -Follow these guidelines to ensure your code is clean, maintainable, and adheres to best practices. Remember, less code is better. Lines of code = Debt. - -# Key Mindsets - -**1** **Simplicity**: Write simple and straightforward code. -**2** **Readability**: Ensure your code is easy to read and understand. -**3** **Performance**: Keep performance in mind but do not over-optimize at the cost of readability. -**4** **Maintainability**: Write code that is easy to maintain and update. -**5** **Testability**: Ensure your code is easy to test. -**6** **Reusability**: Write reusable components and functions. - -Code Guidelines - -**1** **Utilize Early Returns**: Use early returns to avoid nested conditions and improve readability. -**2** **Conditional Classes**: Prefer conditional classes over ternary operators for class attributes. -**3** **Descriptive Names**: Use descriptive names for variables and functions. Prefix event handler functions with "handle" (e.g., handleClick, handleKeyDown). -**4** **Constants Over Functions**: Use constants instead of functions where possible. Define types if applicable. -**5** **Correct and DRY Code**: Focus on writing correct, best practice, DRY (Don't Repeat Yourself) code. -**6** **Functional and Immutable Style**: Prefer a functional, immutable style unless it becomes much more verbose. -**7** **Minimal Code Changes**: Only modify sections of the code related to the task at hand. Avoid modifying unrelated pieces of code. Accomplish goals with minimal code changes. -**8** **Function Declarations**: Use const arrow functions instead of function declarations: - ```typescript - // ❌ Don't use - function myFunction() {} - - // ✅ Use - const myFunction = () => {}; - ``` -**9** **TypeScript Types**: Use type aliases instead of interfaces for better flexibility: - ```typescript - // ❌ Don't use - interface MyType { - property: string; - } - - // ✅ Use - type MyType = { - property: string; - }; - ``` - -Comments and Documentation - -* **Function Comments**: Add a comment at the start of each function describing what it does. -* **JSDoc Comments**: Use JSDoc comments for JavaScript (unless it's TypeScript) and modern ES6 syntax. - -Function Ordering - -* Order functions with those that are composing other functions appearing earlier in the file. For example, if you have a menu with multiple buttons, define the menu function above the buttons. - -Handling Bugs - -* **TODO Comments**: If you encounter a bug in existing code, or the instructions lead to suboptimal or buggy code, add comments starting with "TODO:" outlining the problems. - -Example Pseudocode Plan and Implementation - -When responding to questions, use the Chain of Thought method. Outline a detailed pseudocode plan step by step, then confirm it, and proceed to write the code. Here's an example: - -# Important: Minimal Code Changes - -**Only modify sections of the code related to the task at hand.** -**Avoid modifying unrelated pieces of code.** -**Avoid changing existing comments.** -**Avoid any kind of cleanup unless specifically instructed to.** -**Accomplish the goal with the minimum amount of code changes.** -**Code change = potential for bugs and technical debt.** - -Follow these guidelines to produce high-quality code and improve your coding skills. If you have any questions or need clarification, don't hesitate to ask! diff --git a/.cursor/rules/voltagent-testing.mdc b/.cursor/rules/voltagent-testing.mdc deleted file mode 100644 index 6b06d45a8..000000000 --- a/.cursor/rules/voltagent-testing.mdc +++ /dev/null @@ -1,39 +0,0 @@ ---- -description: Generating tests, generating unit tests and anything at all to do with testing -globs: -alwaysApply: false ---- -# Persona - -You are an senior software engineer with an expertise in writing vitest unit tests and unit testing in general. - -# Running tests - -To run tests make sure to run `pnpm vitest --run` or it will run with "watch" enabled by default. - -If you need to run a test with coverage you can run it using the same format just append the option `--coverage`, for example `pnpm vitest --run --coverage`. - -If you need to run a specific test file you can run with `pnpm vitest {FILE_NAME} --run`, or with coverage `pnpm vitest {FILE_NAME} --run --coverage`. - -REMEMBER you MUST always append `--run` when running tests - -# Rules - -You MUST follow all rules within the tag or you WILL BE FIRED! - - -- you MUST ALWAYS use vitest as your testing framework -- you MUST ALWAYS output the unit test file relative to the file you are testing with the format `[FILENAME].spec.ts` -- you MUST ALWAYS output the file using the format `[FILENAME].spec.ts` -- you MUST ALWAYS import all vitest dependencies, as `vitest` is NOT a global. For example: `import { vi, describe, expect, it } from 'vitest';` -- you MUST ALWAYS directly use the `vitest` cli by using it within `pnpm`, for example `pnpm vitest --run` - - -# Guidelines - -You SHOULD follow all guidelines within the tags. - - -- Prefer mocking and isolation of tests to test full end-to-end workflows -- Test types using `expectTypes` for any public interfaces, you can check the `package.json` `exports` and follow the flow to determine what is public - \ No newline at end of file diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 000000000..5a60cab2c --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,10 @@ +{ + "image": "mcr.microsoft.com/devcontainers/typescript-node:22", + "customizations": { + "vscode": { + "extensions": ["biomejs.biome", "esbenp.prettier-vscode"] + } + }, + // https://github.com/pnpm/pnpm/issues/5803#issuecomment-1360641459 + "onCreateCommand": "pnpm config set store-dir /home/node/.local/share/pnpm/store && pnpm install" +} diff --git a/.github/workflows/prerelease.yml b/.github/workflows/prerelease.yml new file mode 100644 index 000000000..308e7b873 --- /dev/null +++ b/.github/workflows/prerelease.yml @@ -0,0 +1,168 @@ +name: Prerelease + +on: + push: + branches: + - next + +env: + PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: "1" + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + test-packages: + runs-on: ubuntu-latest + strategy: + matrix: + package: + - cli + - core + - create-voltagent-app + - docs-mcp + - internal + - logger + - postgres + - supabase + - voice + - server-core + - libsql + fail-fast: false + name: Test ${{ matrix.package }} + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: "pnpm" + - name: Install Dependencies + run: pnpm install + env: + NODE_OPTIONS: "--max-old-space-size=8192" + - name: Set package scope + id: scope + run: | + if [[ "${{ matrix.package }}" == "create-voltagent-app" ]]; then + echo "scope=create-voltagent-app" >> $GITHUB_OUTPUT + else + echo "scope=@voltagent/${{ matrix.package }}" >> $GITHUB_OUTPUT + fi + - name: Build Package and Dependencies + run: lerna run build --scope "${{ steps.scope.outputs.scope }}" --include-dependencies + - name: Test Package + run: lerna run test --scope "${{ steps.scope.outputs.scope }}" + + e2e-tests: + runs-on: ubuntu-latest + name: E2E Tests + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: "pnpm" + - name: Install Dependencies + run: pnpm install + env: + NODE_OPTIONS: "--max-old-space-size=8192" + - name: Build E2E Dependencies + run: pnpm lerna run build --scope @voltagent/e2e --include-dependencies + - name: Run E2E Tests + run: pnpm --filter @voltagent/e2e test + + prerelease: + name: Prerelease + needs: [test-packages, e2e-tests] + runs-on: ubuntu-latest + permissions: + contents: write + id-token: write + issues: read + pull-requests: write + services: + postgres: + image: postgres:16 + env: + POSTGRES_USER: test + POSTGRES_PASSWORD: test + POSTGRES_DB: voltagent_test + ports: + - 5432:5432 + options: >- + --health-cmd pg_isready + --health-interval 10s + --health-timeout 5s + --health-retries 5 + steps: + - name: Checkout Repo + uses: actions/checkout@v4 + with: + token: ${{ secrets.VOLTAGENT_BOT }} + # This makes Actions fetch all Git history so that Changesets can generate changelogs with the correct commits + fetch-depth: 0 + + - name: Setup pnpm + uses: pnpm/action-setup@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: 20 + cache: 'pnpm' + + - name: Creating .npmrc + run: | + cat << EOF > "$HOME/.npmrc" + //registry.npmjs.org/:_authToken=$NPM_TOKEN + EOF + env: + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} + + - name: Install Dependencies + run: pnpm install + env: + NODE_OPTIONS: "--max-old-space-size=8192" + + - name: Build All Packages + run: pnpm build:all + env: + NODE_OPTIONS: '--max-old-space-size=8192' + + - name: Lint with Biome + run: pnpm lint:ci + + - name: Syncpack + run: pnpm sp lint + + - name: Publint + run: pnpm publint:all + + #- name: Are The Types Wrong + # run: pnpm attw:all + + - name: PostgreSQL Integration Tests + run: | + cd packages/postgres + npm run test:integration:ci + env: + DATABASE_URL: postgresql://test:test@localhost:5432/voltagent_test + + - name: Create Release Pull Request or Publish to npm + id: changesets + uses: changesets/action@v1 + with: + # This will run pnpm version-packages which handles prerelease mode + version: pnpm version-packages + # This will run pnpm changeset publish (tag is handled by pre mode) + publish: pnpm changeset publish + title: '[Prerelease] Version Packages' + commit: 'chore: version packages (prerelease)' + createGithubReleases: false + env: + GITHUB_TOKEN: ${{ secrets.VOLTAGENT_BOT }} + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index f7407ae49..955dee5fa 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -1,8 +1,14 @@ name: PR Checks -on: [pull_request] +on: + pull_request: + types: [opened, synchronize, reopened, ready_for_review] + +env: + PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: "1" jobs: commit-lint: + if: ${{ !github.event.pull_request.draft }} runs-on: ubuntu-latest concurrency: group: ${{ github.ref }}-commit-lint @@ -12,6 +18,7 @@ jobs: - uses: actions/checkout@v4 - uses: wagoid/commitlint-github-action@v5 lint: + if: ${{ !github.event.pull_request.draft }} runs-on: ubuntu-latest strategy: matrix: @@ -38,6 +45,7 @@ jobs: - name: Syncpack run: pnpm sp lint build: + if: ${{ !github.event.pull_request.draft }} runs-on: ubuntu-latest strategy: matrix: @@ -61,10 +69,11 @@ jobs: run: pnpm build:all - name: Publint run: pnpm publint:all - - name: Are The Types Wrong - run: pnpm attw:all + # - name: Are The Types Wrong + # run: pnpm attw:all test-packages: + if: ${{ !github.event.pull_request.draft }} runs-on: ubuntu-latest strategy: matrix: @@ -74,15 +83,12 @@ jobs: - create-voltagent-app - docs-mcp - internal - - langfuse-exporter - logger - postgres - - sdk - supabase - - vercel-ai - - vercel-ai-exporter - voice - - xsai + - server-core + - libsql fail-fast: false concurrency: group: ${{ github.ref }}-test-${{ matrix.package }} @@ -113,6 +119,7 @@ jobs: run: lerna run test --scope "${{ steps.scope.outputs.scope }}" postgres-integration: + if: ${{ !github.event.pull_request.draft }} runs-on: ubuntu-latest name: PostgreSQL Integration Tests concurrency: @@ -136,7 +143,7 @@ jobs: - uses: actions/checkout@v4 with: fetch-depth: 0 - + - name: Check for PostgreSQL changes id: check_postgres run: | @@ -145,11 +152,11 @@ jobs: else echo "postgres_changed=false" >> $GITHUB_OUTPUT fi - + - name: Skip if no PostgreSQL changes if: steps.check_postgres.outputs.postgres_changed == 'false' run: echo "No PostgreSQL changes detected, skipping integration tests" - + - uses: pnpm/action-setup@v4 if: steps.check_postgres.outputs.postgres_changed == 'true' - uses: actions/setup-node@v4 @@ -157,17 +164,17 @@ jobs: with: node-version: 20 cache: "pnpm" - + - name: Install Dependencies if: steps.check_postgres.outputs.postgres_changed == 'true' run: pnpm install env: NODE_OPTIONS: "--max-old-space-size=8192" - + - name: Build Core Dependencies if: steps.check_postgres.outputs.postgres_changed == 'true' run: pnpm build --scope @voltagent/core - + - name: Run PostgreSQL Integration Tests if: steps.check_postgres.outputs.postgres_changed == 'true' run: | @@ -176,16 +183,56 @@ jobs: env: DATABASE_URL: postgresql://test:test@localhost:5432/voltagent_test - tsdoc-check: + e2e-tests: + if: ${{ !github.event.pull_request.draft }} runs-on: ubuntu-latest - name: Check TSDoc Links + name: E2E Tests concurrency: - group: ${{ github.ref }}-tsdoc-check + group: ${{ github.ref }}-e2e-tests cancel-in-progress: true steps: - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Check for E2E-related changes + id: check_e2e + run: | + BASE_SHA="${{ github.event.pull_request.base.sha }}" + + if ! git cat-file -e "$BASE_SHA^{commit}" 2>/dev/null; then + git fetch origin "${{ github.event.pull_request.base.ref }}" --depth=1 + BASE_SHA="origin/${{ github.event.pull_request.base.ref }}" + fi + + if git diff --name-only "$BASE_SHA"...HEAD | grep -E '^(\.github/workflows/pull-request\.yml|packages/e2e/|packages/core/|packages/libsql/|packages/postgres/|packages/internal/|packages/logger/|package\.json|pnpm-lock\.yaml)'; then + echo "e2e_changed=true" >> $GITHUB_OUTPUT + else + echo "e2e_changed=false" >> $GITHUB_OUTPUT + fi + + - name: Skip if no E2E-related changes + if: steps.check_e2e.outputs.e2e_changed == 'false' + run: echo "No E2E-related changes detected, skipping E2E tests" + + - uses: pnpm/action-setup@v4 + if: steps.check_e2e.outputs.e2e_changed == 'true' - uses: actions/setup-node@v4 + if: steps.check_e2e.outputs.e2e_changed == 'true' with: - node-version: 24 - - name: Check TSDoc Links - run: npx tsdoc-link-check --patterns packages/** + node-version: 20 + cache: "pnpm" + + - name: Install Dependencies + if: steps.check_e2e.outputs.e2e_changed == 'true' + run: pnpm install + env: + NODE_OPTIONS: "--max-old-space-size=8192" + + - name: Build E2E Dependencies + if: steps.check_e2e.outputs.e2e_changed == 'true' + run: pnpm lerna run build --scope @voltagent/e2e --include-dependencies + + - name: Run E2E Tests + if: steps.check_e2e.outputs.e2e_changed == 'true' + run: pnpm --filter @voltagent/e2e test diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 15cca9910..08b8cbc96 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -5,6 +5,9 @@ on: branches: - main +env: + PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: "1" + jobs: test-packages: runs-on: ubuntu-latest @@ -16,15 +19,12 @@ jobs: - create-voltagent-app - docs-mcp - internal - - langfuse-exporter - logger - postgres - - sdk - supabase - - vercel-ai - - vercel-ai-exporter - voice - - xsai + - server-core + - libsql fail-fast: false name: Test ${{ matrix.package }} steps: @@ -51,8 +51,27 @@ jobs: - name: Test Package run: lerna run test --scope "${{ steps.scope.outputs.scope }}" + e2e-tests: + runs-on: ubuntu-latest + name: E2E Tests + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: "pnpm" + - name: Install Dependencies + run: pnpm install + env: + NODE_OPTIONS: "--max-old-space-size=8192" + - name: Build E2E Dependencies + run: pnpm lerna run build --scope @voltagent/e2e --include-dependencies + - name: Run E2E Tests + run: pnpm --filter @voltagent/e2e test + publish: - needs: test-packages + needs: [test-packages, e2e-tests] permissions: contents: write id-token: write @@ -106,8 +125,8 @@ jobs: run: pnpm sp lint - name: Publint run: pnpm publint:all - - name: Are The Types Wrong - run: pnpm attw:all + # - name: Are The Types Wrong + # run: pnpm attw:all - name: PostgreSQL Integration Tests run: | diff --git a/.gitignore b/.gitignore index 927de6e79..60ad947c8 100644 --- a/.gitignore +++ b/.gitignore @@ -142,6 +142,7 @@ dist # VoltAgent .voltagent +packages/core/docs # Create VoltAgent App !packages/create-voltagent-app/templates/base/.env @@ -150,7 +151,7 @@ dist .cursor/* !.cursor/rules/ .cursor/rules/* -!.cursor/rules/voltagent-*.mdc +!.cursor/rules/agents.mdc # vite and vitest vite.config.*.timestamp* @@ -164,4 +165,26 @@ vitest.config.*.timestamp* # claude .claude -CLAUDE.md \ No newline at end of file +skills +!packages/core/src/workspace/skills +!packages/core/src/workspace/skills/** + +dev-debug.log +node_modules/ + +.taskmaster + +!packages/core/src/observability/logs +# Local Netlify folder +.netlify + + +# serena +.serena + +# joggr +.joggr + + +# example skills +!examples/with-workspace/workspace/skills diff --git a/.husky/pre-commit b/.husky/pre-commit index 51492ffe2..044922ae0 100755 --- a/.husky/pre-commit +++ b/.husky/pre-commit @@ -1,4 +1,6 @@ #!/usr/bin/env sh . "$(dirname -- "$0")/_/husky.sh" -npx lint-staged \ No newline at end of file +cd "$(git rev-parse --show-toplevel)" || exit 1 + +npx lint-staged --config package.json diff --git a/.syncpackrc b/.syncpackrc index 6b4a1cf7d..21390533b 100644 --- a/.syncpackrc +++ b/.syncpackrc @@ -20,6 +20,18 @@ "packages": ["**"], "isIgnored": true, "label": "Peer dependencies allow flexible version ranges" + }, + { + "dependencies": ["zod"], + "packages": ["@voltagent/docs-mcp"], + "policy": "^4.0.0", + "label": "docs-mcp uses Zod v4 for native JSON Schema support" + }, + { + "dependencies": ["zod"], + "packages": ["!@voltagent/docs-mcp", "**"], + "policy": "^3.25.76", + "label": "All other packages use Zod v3" } ] } diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..537f98720 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,37 @@ +# VoltAgent + +VoltAgent is an open-source TypeScript framework for building and orchestrating AI agents. + +## What is VoltAgent? + +VoltAgent is a comprehensive framework that enables developers to build sophisticated AI agents with memory, tools, observability, and sub-agent capabilities. It provides direct AI SDK integration with comprehensive OpenTelemetry tracing built-in. + +## Overview + +- View [`docs/structure.md`](./docs/structure.md) for the repository structure and organization +- View [`docs/tooling.md`](./docs/tooling.md) for development tools and utilities +- View [`docs/testing.md`](./docs/testing.md) for testing guidelines and commands +- View [`docs/linting.md`](./docs/linting.md) for code formatting and linting + +## Validating Changes + +To validate your changes you can run the following commands: + +```bash +pnpm test:all # Run all tests +pnpm build:all # Build all packages +pnpm lint # Run linting checks +pnpm lint:fix # Auto-fix linting issues +``` + +## Important Notes for AI Agents + +1. **Always check existing patterns** before implementing new features +2. **Use the established registry patterns** for agent and tool management +3. **Maintain type safety** - this is a TypeScript-first codebase +4. **Follow the monorepo structure** - changes may impact multiple packages +5. **Test your changes** - ensure all tests pass before committing + +## Gotchas + +- **JSON.stringify** SHOULD NEVER BE USED, used the `safeStringify` function instead, imported from `@voltagent/internal` diff --git a/CHANGELOG.md b/CHANGELOG.md index e8f7f32ee..69ddbca01 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4867 +1,17897 @@ ## Package: @voltagent/core -## 0.1.78 +## 2.0.10 ### Patch Changes -- [#466](https://github.com/VoltAgent/voltagent/pull/466) [`730232e`](https://github.com/VoltAgent/voltagent/commit/730232e730cdbd1bb7de6acff8519e8af93f2abf) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add message helper utilities to simplify working with complex message content - - ## What Changed for You - - Working with message content (which can be either a string or an array of content parts) used to require complex if/else blocks. Now you have simple helper functions that handle all the complexity. +- [#934](https://github.com/VoltAgent/voltagent/pull/934) [`12519f5`](https://github.com/VoltAgent/voltagent/commit/12519f572b3facbd32d35f939be08a0ad1b40b45) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: offline-first local prompts with version + label selection - ## Before - Your Old Code (Complex) + ### What's New + - Local prompt resolution now supports multiple versions and labels stored as + `.voltagent/prompts//.md`. + - Local files are used first; VoltOps is only queried if the local prompt is missing. + - If a local prompt is behind the online version, the agent logs a warning and records metadata. + - CLI `pull` can target labels or versions; `push` compares local vs online and creates new versions - ```typescript - // Adding timestamps to messages - 30+ lines of code - const enhancedMessages = messages.map((msg) => { - if (msg.role === "user") { - const timestamp = new Date().toLocaleTimeString(); + ### CLI Usage - // Handle string content - if (typeof msg.content === "string") { - return { - ...msg, - content: `[${timestamp}] ${msg.content}`, - }; - } + ```bash + # Pull latest prompts (default) + volt prompts pull - // Handle structured content (array of content parts) - if (Array.isArray(msg.content)) { - return { - ...msg, - content: msg.content.map((part) => { - if (part.type === "text") { - return { - ...part, - text: `[${timestamp}] ${part.text}`, - }; - } - return part; - }), - }; - } - } - return msg; - }); + # Pull a specific label or version (stored under .voltagent/prompts//.md) + volt prompts pull --names support-agent --label production + volt prompts pull --names support-agent --prompt-version 4 - // Extracting text from content - another 15+ lines - function getText(content) { - if (typeof content === "string") { - return content; - } - if (Array.isArray(content)) { - return content - .filter((part) => part.type === "text") - .map((part) => part.text) - .join(""); - } - return ""; - } + # Push local changes (creates new versions after diff/confirm) + volt prompts push ``` - ## After - Your New Code (Simple) + ### Agent Usage ```typescript - import { messageHelpers } from "@voltagent/core"; - - // Adding timestamps - 1 line! - const enhancedMessages = messages.map((msg) => - messageHelpers.addTimestampToMessage(msg, timestamp) - ); - - // Extracting text - 1 line! - const text = messageHelpers.extractText(content); - - // Check if has images - 1 line! - if (messageHelpers.hasImagePart(content)) { - // Handle image content - } - - // Build complex content - fluent API - const content = new messageHelpers.MessageContentBuilder() - .addText("Here's an image:") - .addImage("screenshot.png") - .addText("And a file:") - .addFile("document.pdf") - .build(); + instructions: async ({ prompts }) => { + return await prompts.getPrompt({ + promptName: "support-agent", + version: 4, + }); + }; ``` - ## Real Use Case in Hooks - ```typescript - import { Agent, messageHelpers } from "@voltagent/core"; + instructions: async ({ prompts }) => { + return await prompts.getPrompt({ + promptName: "support-agent", + label: "production", + }); + }; + ``` - const agent = new Agent({ - name: "Assistant", - hooks: { - onPrepareMessages: async ({ messages }) => { - // Before: 30+ lines of complex if/else - // After: 2 lines! - const timestamp = new Date().toLocaleTimeString(); - return { - messages: messages.map((msg) => messageHelpers.addTimestampToMessage(msg, timestamp)), - }; - }, - }, - }); + ### Offline-First Workflow + - Pull once, then run fully offline with local Markdown files. + - Point the runtime to your local directory: + + ```bash + export VOLTAGENT_PROMPTS_PATH="./.voltagent/prompts" ``` - ## What You Get - - **No more if/else blocks** for content type checking - - **Type-safe operations** with TypeScript support - - **30+ lines → 1 line** for common operations - - **Works everywhere**: hooks, tools, custom logic +- [#935](https://github.com/VoltAgent/voltagent/pull/935) [`e7d984f`](https://github.com/VoltAgent/voltagent/commit/e7d984fe391cd2732886c7903f028ce33f40cfab) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: MCPClient.listResources now returns the raw MCP `resources/list` response. - ## Available Helpers +## 2.0.9 - ```typescript - import { messageHelpers } from "@voltagent/core"; +### Patch Changes - // Check content type - messageHelpers.isTextContent(content); // Is it a string? - messageHelpers.hasImagePart(content); // Has images? +- [#929](https://github.com/VoltAgent/voltagent/pull/929) [`78ff377`](https://github.com/VoltAgent/voltagent/commit/78ff377b200c48e90a2e3ab510d0d25ccca86c5a) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add workflow control steps (branch, foreach, loop, map, sleep) - // Extract content - messageHelpers.extractText(content); // Get all text - messageHelpers.extractImageParts(content); // Get all images + ```ts + import { + createWorkflowChain, + andThen, + andBranch, + andForEach, + andDoWhile, + andDoUntil, + andMap, + andSleep, + andSleepUntil, + } from "@voltagent/core"; + import { z } from "zod"; + ``` - // Transform content - messageHelpers.transformTextContent(content, (text) => text.toUpperCase()); - messageHelpers.addTimestampToMessage(message, "10:30:00"); + Branching: - // Build content - new messageHelpers.MessageContentBuilder().addText("Hello").addImage("world.png").build(); + ```ts + const workflow = createWorkflowChain({ + id: "branching-flow", + input: z.object({ amount: z.number() }), + }).andBranch({ + id: "rules", + branches: [ + { + condition: ({ data }) => data.amount > 1000, + step: andThen({ + id: "flag-large", + execute: async ({ data }) => ({ ...data, large: true }), + }), + }, + { + condition: ({ data }) => data.amount < 0, + step: andThen({ + id: "flag-invalid", + execute: async ({ data }) => ({ ...data, invalid: true }), + }), + }, + ], + }); ``` - Your message handling code just got 90% simpler! + For-each and loops: -- [#466](https://github.com/VoltAgent/voltagent/pull/466) [`730232e`](https://github.com/VoltAgent/voltagent/commit/730232e730cdbd1bb7de6acff8519e8af93f2abf) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add onPrepareMessages hook - transform messages before they reach the LLM + ```ts + createWorkflowChain({ + id: "batch-process", + input: z.array(z.number()), + }).andForEach({ + id: "double-each", + concurrency: 2, + step: andThen({ + id: "double", + execute: async ({ data }) => data * 2, + }), + }); - ## What Changed for You + createWorkflowChain({ + id: "looping-flow", + input: z.number(), + }) + .andDoWhile({ + id: "increment-until-3", + step: andThen({ + id: "increment", + execute: async ({ data }) => data + 1, + }), + condition: ({ data }) => data < 3, + }) + .andDoUntil({ + id: "increment-until-2", + step: andThen({ + id: "increment-until", + execute: async ({ data }) => data + 1, + }), + condition: ({ data }) => data >= 2, + }); + ``` - You can now modify, filter, or enhance messages before they're sent to the LLM. Previously impossible without forking the framework. + Data shaping: - ## Before - What You Couldn't Do + ```ts + createWorkflowChain({ + id: "compose-result", + input: z.object({ userId: z.string() }), + }) + .andThen({ + id: "fetch-user", + execute: async ({ data }) => ({ name: "Ada", id: data.userId }), + }) + .andMap({ + id: "shape-output", + map: { + userId: { source: "data", path: "userId" }, + name: { source: "step", stepId: "fetch-user", path: "name" }, + region: { source: "context", key: "region" }, + constant: { source: "value", value: "ok" }, + }, + }); + ``` - ```typescript - // ❌ No way to: - // - Add timestamps to messages - // - Filter sensitive data (SSN, credit cards) - // - Add user context to messages - // - Remove duplicate messages - // - Inject system prompts dynamically + Sleep: - const agent = new Agent({ - name: "Assistant", - // Messages went straight to LLM - no control! - }); + ```ts + createWorkflowChain({ + id: "delayed-step", + input: z.object({ id: z.string() }), + }) + .andSleep({ + id: "pause", + duration: 500, + }) + .andSleepUntil({ + id: "wait-until", + date: () => new Date(Date.now() + 60_000), + }) + .andThen({ + id: "continue", + execute: async ({ data }) => ({ ...data, resumed: true }), + }); ``` - ## After - What You Can Do Now + Workflow-level retries: - ```typescript - import { Agent, messageHelpers } from "@voltagent/core"; + ```ts + createWorkflowChain({ + id: "retry-defaults", + retryConfig: { attempts: 2, delayMs: 500 }, + }) + .andThen({ + id: "fetch-user", + execute: async ({ data }) => fetchUser(data.userId), + }) + .andThen({ + id: "no-retry-step", + retries: 0, + execute: async ({ data }) => data, + }); + ``` - const agent = new Agent({ - name: "Assistant", + Workflow hooks (finish/error/suspend): + ```ts + createWorkflowChain({ + id: "hooked-workflow", hooks: { - // ✅ NEW: Intercept and transform messages! - onPrepareMessages: async ({ messages, context }) => { - // Add timestamps - const timestamp = new Date().toLocaleTimeString(); - const enhanced = messages.map((msg) => - messageHelpers.addTimestampToMessage(msg, timestamp) - ); - - return { messages: enhanced }; + onSuspend: async (info) => { + console.log("Suspended:", info.suspension?.reason); + }, + onError: async (info) => { + console.error("Failed:", info.error); + }, + onFinish: async (info) => { + console.log("Done:", info.status); + }, + onEnd: async (state, info) => { + if (info?.status === "completed") { + console.log("Result:", state.result); + console.log("Steps:", Object.keys(info.steps)); + } }, }, }); - - // Your message: "What time is it?" - // LLM receives: "[14:30:45] What time is it?" ``` - ## When It Runs + Workflow guardrails (input/output + step-level): - ```typescript - // 1. User sends message - await agent.generateText("Hello"); + ```ts + import { + andGuardrail, + andThen, + createInputGuardrail, + createOutputGuardrail, + createWorkflowChain, + } from "@voltagent/core"; + import { z } from "zod"; - // 2. Memory loads previous messages - // [previous messages...] + const trimInput = createInputGuardrail({ + name: "trim", + handler: async ({ input }) => ({ + pass: true, + action: "modify", + modifiedInput: typeof input === "string" ? input.trim() : input, + }), + }); - // 3. ✨ onPrepareMessages runs HERE - // You can transform messages + const redactOutput = createOutputGuardrail({ + name: "redact", + handler: async ({ output }) => ({ + pass: true, + action: "modify", + modifiedOutput: output.replace(/[0-9]/g, "*"), + }), + }); - // 4. Messages sent to LLM - // [your transformed messages] + createWorkflowChain({ + id: "guarded-workflow", + input: z.string(), + result: z.string(), + inputGuardrails: [trimInput], + outputGuardrails: [redactOutput], + }) + .andGuardrail({ + id: "sanitize-step", + outputGuardrails: [redactOutput], + }) + .andThen({ + id: "finish", + execute: async ({ data }) => data, + }); ``` - ## What You Need to Know - - **Runs on every LLM call**: generateText, streamText, generateObject, streamObject - - **Gets all messages**: Including system prompt and memory messages - - **Return transformed messages**: Or return nothing to keep original - - **Access to context**: userContext, operationId, agent reference +## 2.0.8 - Your app just got smarter without changing any existing code! +### Patch Changes -- [#466](https://github.com/VoltAgent/voltagent/pull/466) [`730232e`](https://github.com/VoltAgent/voltagent/commit/730232e730cdbd1bb7de6acff8519e8af93f2abf) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: memory messages now return parsed objects instead of JSON strings +- [#927](https://github.com/VoltAgent/voltagent/pull/927) [`2712078`](https://github.com/VoltAgent/voltagent/commit/27120782e6e278a53d049ae2a60ce9981140d490) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: enable `andAgent` tool usage by switching to `generateText` with `Output.object` while keeping structured output - ## What Changed for You + Example: - Memory messages that contain structured content (like tool calls or multi-part messages) now return as **parsed objects** instead of **JSON strings**. This is a breaking change if you were manually parsing these messages. + ```ts + import { Agent, createTool, createWorkflowChain } from "@voltagent/core"; + import { z } from "zod"; + import { openai } from "@ai-sdk/openai"; - ## Before - You Had to Parse JSON Manually + const getWeather = createTool({ + name: "get_weather", + description: "Get weather for a city", + parameters: z.object({ city: z.string() }), + execute: async ({ city }) => ({ city, temp: 72, condition: "sunny" }), + }); - ```typescript - // ❌ OLD BEHAVIOR: Content came as JSON string - const messages = await memory.getMessages({ conversationId: "123" }); + const agent = new Agent({ + name: "WeatherAgent", + model: openai("gpt-4o-mini"), + tools: [getWeather], + }); - // What you got from memory: - console.log(messages[0]); - // { - // role: "user", - // content: '[{"type":"text","text":"Hello"},{"type":"image","image":"data:..."}]', // STRING! - // type: "text" - // } + const workflow = createWorkflowChain({ + id: "weather-flow", + input: z.object({ city: z.string() }), + }).andAgent(({ data }) => `What is the weather in ${data.city}?`, agent, { + schema: z.object({ temp: z.number(), condition: z.string() }), + }); + ``` - // You had to manually parse the JSON string: - const content = JSON.parse(messages[0].content); // Parse required! - console.log(content); - // [ - // { type: "text", text: "Hello" }, - // { type: "image", image: "data:..." } - // ] +## 2.0.7 - // Tool calls were also JSON strings: - console.log(messages[1].content); - // '[{"type":"tool-call","toolCallId":"123","toolName":"weather"}]' // STRING! - ``` +### Patch Changes - ## After - You Get Parsed Objects Automatically +- [#921](https://github.com/VoltAgent/voltagent/pull/921) [`c4591fa`](https://github.com/VoltAgent/voltagent/commit/c4591fa92de6df75a22a758b0232669053bd2b62) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add resumable streaming support via @voltagent/resumable-streams, with server adapters that let clients reconnect to in-flight streams. - ```typescript - // ✅ NEW BEHAVIOR: Content comes as proper objects - const messages = await memory.getMessages({ conversationId: "123" }); + ```ts + import { openai } from "@ai-sdk/openai"; + import { Agent, VoltAgent } from "@voltagent/core"; + import { + createResumableStreamAdapter, + createResumableStreamRedisStore, + } from "@voltagent/resumable-streams"; + import { honoServer } from "@voltagent/server-hono"; - // What you get from memory NOW: - console.log(messages[0]); - // { - // role: "user", - // content: [ - // { type: "text", text: "Hello" }, // OBJECT! - // { type: "image", image: "data:..." } // OBJECT! - // ], - // type: "text" - // } + const streamStore = await createResumableStreamRedisStore(); + const resumableStream = await createResumableStreamAdapter({ streamStore }); - // Direct access - no JSON.parse needed! - const content = messages[0].content; // Already parsed! - console.log(content[0].text); // "Hello" + const agent = new Agent({ + id: "assistant", + name: "Resumable Stream Agent", + instructions: "You are a helpful assistant.", + model: openai("gpt-4o-mini"), + }); - // Tool calls are proper objects: - console.log(messages[1].content); - // [ - // { type: "tool-call", toolCallId: "123", toolName: "weather" } // OBJECT! - // ] - ``` + new VoltAgent({ + agents: { assistant: agent }, + server: honoServer({ + resumableStream: { adapter: resumableStream }, + }), + }); - ## Breaking Change Warning ⚠️ + await fetch("http://localhost:3141/agents/assistant/chat", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: `{"input":"Hello!","options":{"conversationId":"conv-1","userId":"user-1","resumableStream":true}}`, + }); - If your code was doing this: + // Resume the same stream after reconnect/refresh + const resumeResponse = await fetch( + "http://localhost:3141/agents/assistant/chat/conv-1/stream?userId=user-1" + ); - ```typescript - // This will now FAIL because content is already parsed - const parsed = JSON.parse(msg.content); // ❌ Error: not a string! + const reader = resumeResponse.body?.getReader(); + const decoder = new TextDecoder(); + while (reader) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value, { stream: true }); + console.log(chunk); + } ``` - Change it to: + AI SDK client (resume on refresh): - ```typescript - // Just use the content directly - const content = msg.content; // ✅ Already an object/array + ```tsx + import { useChat } from "@ai-sdk/react"; + import { DefaultChatTransport } from "ai"; + + const { messages, sendMessage } = useChat({ + id: chatId, + messages: initialMessages, + resume: true, + transport: new DefaultChatTransport({ + api: "/api/chat", + prepareSendMessagesRequest: ({ id, messages }) => ({ + body: { + message: messages[messages.length - 1], + options: { conversationId: id, userId }, + }, + }), + prepareReconnectToStreamRequest: ({ id }) => ({ + api: `/api/chat/${id}/stream?userId=${encodeURIComponent(userId)}`, + }), + }), + }); ``` - ## What Gets Auto-Parsed - - **String content** → Stays as string ✅ - - **Structured content** (arrays) → Auto-parsed to objects ✅ - - **Tool calls** → Auto-parsed to objects ✅ - - **Tool results** → Auto-parsed to objects ✅ - - **Metadata fields** → Auto-parsed to objects ✅ - - ## Why This Matters - - **No more JSON.parse errors** in your application - - **Type-safe access** to structured content - - **Cleaner code** without try/catch blocks - - **Consistent behavior** with how agents handle messages +## 2.0.6 - ## Migration Guide - 1. **Remove JSON.parse calls** for message content - 2. **Remove try/catch** blocks around parsing - 3. **Use content directly** as objects/arrays +### Patch Changes - Your memory messages now "just work" without manual parsing! +- [`ad5ebe7`](https://github.com/VoltAgent/voltagent/commit/ad5ebe7f02a059b647d4862faeab537b293ab387) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: OutputSpec export -## 0.1.77 +## 2.0.5 ### Patch Changes -- [#472](https://github.com/VoltAgent/voltagent/pull/472) [`8de5785`](https://github.com/VoltAgent/voltagent/commit/8de5785e385bec632f846bcae44ee5cb22a9022e) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: Migrate to using `safeStringify` to prevent issues using the JSON.stringify/parse method, in addition use structuredClone via Nodejs instead legacy method that errors +- [#916](https://github.com/VoltAgent/voltagent/pull/916) [`0707471`](https://github.com/VoltAgent/voltagent/commit/070747195992828845d7c4c4ff9711f3638c32f8) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: infer structured output types for `generateText` -- Updated dependencies [[`8de5785`](https://github.com/VoltAgent/voltagent/commit/8de5785e385bec632f846bcae44ee5cb22a9022e)]: - - @voltagent/internal@0.0.8 + `generateText` now propagates the provided `Output.*` spec into the return type, so `result.output` is no longer `unknown` when using `Output.object`, `Output.array`, etc. -## 0.1.76 +## 2.0.4 ### Patch Changes -- [#468](https://github.com/VoltAgent/voltagent/pull/468) [`c7fec1b`](https://github.com/VoltAgent/voltagent/commit/c7fec1b6c09547adce7dfdb779a2eae7e2fbd153) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: separate system-managed context from user context in operationContext +- [#911](https://github.com/VoltAgent/voltagent/pull/911) [`975831a`](https://github.com/VoltAgent/voltagent/commit/975831a852ea471adb621a1d87990a8ffbc5ed31) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: expose Cloudflare Workers `env` bindings in serverless contexts - Separated system-managed values from userContext by introducing a new `systemContext` field in OperationContext. This provides cleaner separation of concerns between user-provided context and internal system tracking. + When using `@voltagent/serverless-hono` on Cloudflare Workers, the runtime `env` is now injected into the + context map for agent requests, workflow runs, and tool executions. `@voltagent/core` exports + `SERVERLESS_ENV_CONTEXT_KEY` so you can access bindings like D1 from `options.context` (tools) or + `state.context` (workflow steps). Tool execution also accepts `context` as a `Map`, preserving + `userId`/`conversationId` when provided that way. - ### What Changed - - Added `systemContext` field to `OperationContext` type for internal system values - - Moved system-managed values from `userContext` to `systemContext`: - - `agent_start_time`: Agent execution start timestamp - - `agent_start_event_id`: Agent start event identifier - - `tool_${toolId}`: Tool execution tracking (eventId and startTime) + `@voltagent/core` is also marked as side-effect free so edge bundlers can tree-shake the PlanAgent + filesystem backend, avoiding Node-only dependency loading when it is not used. - ### Why This Matters + Usage: - Previously, system values were mixed with user context, which could: - - Pollute the user's context namespace - - Make it unclear which values were user-provided vs system-generated - - Potentially cause conflicts if users used similar key names + ```ts + import { createTool, SERVERLESS_ENV_CONTEXT_KEY } from "@voltagent/core"; + import type { D1Database } from "@cloudflare/workers-types"; + import { z } from "zod"; - Now there's a clear separation: - - `userContext`: Contains only user-provided values - - `systemContext`: Contains only system-managed internal tracking values + type Env = { DB: D1Database }; + + export const listUsers = createTool({ + name: "list-users", + description: "Fetch users from D1", + parameters: z.object({}), + execute: async (_args, options) => { + const env = options?.context?.get(SERVERLESS_ENV_CONTEXT_KEY) as Env | undefined; + const db = env?.DB; + if (!db) { + throw new Error("D1 binding is missing (env.DB)"); + } - ### Migration + const { results } = await db.prepare("SELECT id, name FROM users").all(); + return results; + }, + }); + ``` - This is an internal change that doesn't affect the public API. User code remains unchanged. +## 2.0.3 - ```typescript - // User API remains the same - const response = await agent.generateText("Hello", { - userContext: new Map([["userId", "123"]]), - }); +### Patch Changes - // userContext now only contains user values - console.log(response.userContext.get("userId")); // "123" - // System values are kept separate internally - ``` +- [#909](https://github.com/VoltAgent/voltagent/pull/909) [`b4301c7`](https://github.com/VoltAgent/voltagent/commit/b4301c73656ea96ea276cb37b4bf72af7fd8c926) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: avoid TS4053 declaration emit errors when exporting `generateText` wrappers by decoupling ai-sdk `Output` types from public results -- [#465](https://github.com/VoltAgent/voltagent/pull/465) [`4fe0f21`](https://github.com/VoltAgent/voltagent/commit/4fe0f21e1dde82bb80fcaab4a7039b446b8d9153) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: abort signal propagation to LLM providers for proper cancellation support +## 2.0.2 - Fixed an issue where abort signals were not correctly propagated to LLM providers in agent methods (`generateText`, `streamText`, `generateObject`, `streamObject`). The methods were using `internalOptions.signal` instead of `operationContext.signal`, which contains the properly derived signal from the AbortController. +### Patch Changes - ## What's Fixed - - **Signal Propagation**: All agent methods now correctly pass `operationContext.signal` to LLM providers - - **AbortController Support**: Abort signals from parent agents properly cascade to subagents - - **Cancellation Handling**: Operations can now be properly cancelled when AbortController is triggered +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) - ## Usage Example + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. - ```typescript - import { Agent, isAbortError } from "@voltagent/core"; - import { VercelAIProvider } from "@voltagent/vercel-ai"; - import { openai } from "@ai-sdk/openai"; + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` - const abortController = new AbortController(); + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ - // Create supervisor with subagents - const supervisor = new Agent({ - name: "Supervisor", - instructions: "Coordinate tasks", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - subAgents: [contentAgent, formatterAgent], - hooks: { - onEnd: async ({ error }) => { - // Check if the operation was aborted - if (isAbortError(error)) { - console.log("Operation was aborted:", error.message); - // Handle cleanup for aborted operations - return; - } +- Updated dependencies [[`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505)]: + - @voltagent/internal@1.0.2 + - @voltagent/logger@2.0.2 - if (error) { - console.error("Operation failed:", error); - } - }, - }, - }); +## 2.0.1 - // Start streaming with abort controller - const stream = await supervisor.streamText("Create a story", { - abortController, - }); +### Patch Changes - // Abort after 500ms - now properly stops all subagent operations - setTimeout(() => { - abortController.abort(); - }, 500); +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) - try { - // Stream will properly terminate when aborted - for await (const chunk of stream.textStream) { - console.log(chunk); - } - } catch (error) { - if (isAbortError(error)) { - console.log("Stream aborted successfully"); - } - } - ``` + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. - ## Error Handling in Hooks + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` - The `onEnd` hook now receives `AbortError` type errors when operations are cancelled: + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ - ```typescript - import { isAbortError } from "@voltagent/core"; +- Updated dependencies [[`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2)]: + - @voltagent/internal@1.0.1 + - @voltagent/logger@2.0.1 - const agent = new Agent({ - // ... agent config - hooks: { - onEnd: async ({ error }) => { - if (isAbortError(error)) { - // error is typed as AbortError - // error.name === "AbortError" - // Handle abort-specific logic - await cleanupResources(); - return; - } +## 2.0.0 - // Handle other errors - if (error) { - await logError(error); - } - }, - }, - }); - ``` +### Major Changes - This fix ensures that expensive operations can be properly cancelled, preventing unnecessary computation and improving resource efficiency when users navigate away or cancel requests. +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) -## 0.1.75 + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ ### Patch Changes -- [`3a3ebd2`](https://github.com/VoltAgent/voltagent/commit/3a3ebd2bc72ed5d14dd924d824b54203b73ab19d) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: voltops client validation to prevent empty string keys from creating invalid clients - - VoltOpsClient now validates keys before initializing services - - Keys must not be empty and must have correct prefixes (pk* and sk*) - - Added hasValidKeys() method to check client validity - - Updated /setup-observability endpoint to update existing keys in .env file instead of adding duplicates +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/internal@1.0.0 + - @voltagent/logger@2.0.0 -## 0.1.74 +## 1.5.2 ### Patch Changes -- [#463](https://github.com/VoltAgent/voltagent/pull/463) [`760a294`](https://github.com/VoltAgent/voltagent/commit/760a294e4d68742d8701d54dc1c541c87959e5d8) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: improve /setup-observability endpoint to handle commented .env entries +- [#895](https://github.com/VoltAgent/voltagent/pull/895) [`f2a3ba8`](https://github.com/VoltAgent/voltagent/commit/f2a3ba8a9e96e78f36a30bba004754b7b61ed69f) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: normalize MCP elicitation requests with empty `message` by falling back to the schema description so handlers receive a usable prompt. - ### What's New +## 1.5.1 - The `/setup-observability` API endpoint now intelligently updates existing .env files by replacing commented VoltOps key entries instead of creating duplicates. +### Patch Changes - ### Changes - - **Smart .env Updates**: When setting up observability, the endpoint now finds and updates commented entries like `# VOLTAGENT_PUBLIC_KEY=` - - **No More Duplicates**: Prevents duplicate key entries by updating existing lines (both commented and active) - - **Cleaner Configuration**: Results in a cleaner .env file without confusing duplicate entries +- [`b663dce`](https://github.com/VoltAgent/voltagent/commit/b663dceb57542d1b85475777f32ceb3671cc1237) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: dedupe MCP endpoints in server startup output and include MCP transport paths (streamable HTTP/SSE) so the actual server endpoint is visible. - ### Before +## 1.5.0 - ```bash - # VoltAgent Observability (Optional) - # VOLTAGENT_PUBLIC_KEY= - # VOLTAGENT_SECRET_KEY= +### Minor Changes - # ... later in file ... +- [#879](https://github.com/VoltAgent/voltagent/pull/879) [`2f81e6d`](https://github.com/VoltAgent/voltagent/commit/2f81e6df4176120bfdbb47c503a4d027164e5a5e) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add VoltAgentRagRetriever to @voltagent/core - # VoltAgent Observability - VOLTAGENT_PUBLIC_KEY=your-public-key - VOLTAGENT_SECRET_KEY=your-secret-key + Added `VoltAgentRagRetriever` - a built-in retriever that connects to VoltAgent Knowledge Bases for fully managed RAG. No infrastructure setup required - just upload documents to the Console and start searching. + + ## Features + - **Automatic context injection**: Searches before each response and injects relevant context + - **Tool-based retrieval**: Use as a tool that the agent calls when needed + - **Tag filtering**: Filter results by custom document tags + - **Source tracking**: Access retrieved chunk references via `rag.references` context + + ## Usage + + ```typescript + import { Agent, VoltAgentRagRetriever } from "@voltagent/core"; + import { openai } from "@ai-sdk/openai"; + + const retriever = new VoltAgentRagRetriever({ + knowledgeBaseName: "my-docs", + topK: 8, + includeSources: true, + }); + + // Option 1: Automatic context injection + const agent = new Agent({ + name: "RAG Assistant", + model: openai("gpt-4o-mini"), + retriever, + }); + + // Option 2: Tool-based retrieval + const agentWithTool = new Agent({ + name: "RAG Assistant", + model: openai("gpt-4o-mini"), + tools: [retriever.tool], + }); ``` - ### After + ## Configuration + + | Option | Default | Description | + | ------------------- | -------- | ---------------------------- | + | `knowledgeBaseName` | required | Name of your knowledge base | + | `topK` | 8 | Number of chunks to retrieve | + | `tagFilters` | null | Filter by document tags | + | `includeSources` | true | Include document metadata | + | `includeSimilarity` | false | Include similarity scores | + + ## Environment Variables ```bash - # VoltAgent Observability (Optional) - VOLTAGENT_PUBLIC_KEY=your-public-key - VOLTAGENT_SECRET_KEY=your-secret-key + VOLTAGENT_PUBLIC_KEY=pk_... + VOLTAGENT_SECRET_KEY=sk_... + # Optional + VOLTAGENT_API_BASE_URL=https://api.voltagent.dev ``` - This change improves the developer experience by maintaining a clean .env file structure when setting up observability through the VoltOps Console. +## 1.4.0 -- [#463](https://github.com/VoltAgent/voltagent/pull/463) [`760a294`](https://github.com/VoltAgent/voltagent/commit/760a294e4d68742d8701d54dc1c541c87959e5d8) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add VoltOps API key validation and improved auto-configuration +### Minor Changes - ### What's New - - **API Key Validation**: VoltAgent now validates VoltOps API keys to ensure they have the correct format (must start with `pk_` for public keys and `sk_` for secret keys) - - **Smart Auto-Configuration**: The VoltAgent constructor only creates VoltOpsClient when valid API keys are detected - - **Dummy Key Protection**: Placeholder values like "your-public-key" are now properly rejected +- [#875](https://github.com/VoltAgent/voltagent/pull/875) [`93c52cc`](https://github.com/VoltAgent/voltagent/commit/93c52ccc191d463328a929869e5445abf9ff99df) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add MCP client elicitation support for user input handling - ### Changes - - Added `isValidVoltOpsKeys()` utility function to validate API key formats - - Updated VoltAgent constructor to check key validity before auto-configuring VoltOpsClient - - Environment variables with invalid keys are now silently ignored instead of causing errors + Added support for handling elicitation requests from MCP servers. When an MCP server needs user input during tool execution (e.g., confirmation dialogs, credentials, or form data), you can now dynamically register handlers to process these requests. - ### Usage + ## New API - ```typescript - // Valid keys - VoltOpsClient will be auto-configured - // .env file: - // VOLTAGENT_PUBLIC_KEY=your-public-key - // VOLTAGENT_SECRET_KEY=your-secret-key + Access the elicitation bridge via `mcpClient.elicitation`: - // Invalid keys - VoltOpsClient will NOT be created - // .env file: - // VOLTAGENT_PUBLIC_KEY=your-public-key // ❌ Rejected - // VOLTAGENT_SECRET_KEY=your-secret-key // ❌ Rejected + ```ts + const clients = await mcpConfig.getClients(); - const voltAgent = new VoltAgent({ - agents: { myAgent }, - // No need to manually configure VoltOpsClient if valid keys exist in environment + // Set a persistent handler + clients.myServer.elicitation.setHandler(async (request) => { + console.log("Server asks:", request.message); + console.log("Expected schema:", request.requestedSchema); + + const userConfirmed = await promptUser(request.message); + + return { + action: userConfirmed ? "accept" : "decline", + content: userConfirmed ? { confirmed: true } : undefined, + }; }); - ``` - This change improves the developer experience by preventing confusion when placeholder API keys are present in the environment variables. + // One-time handler (auto-removes after first call) + clients.myServer.elicitation.once(async (request) => { + return { action: "accept", content: { approved: true } }; + }); -- [#459](https://github.com/VoltAgent/voltagent/pull/459) [`980d037`](https://github.com/VoltAgent/voltagent/commit/980d037ce535bcc85cc7df3f64354c823453a147) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add userContext to logger context for better traceability + // Remove handler + clients.myServer.elicitation.removeHandler(); - ### What's New + // Check if handler exists + if (clients.myServer.elicitation.hasHandler) { + console.log("Handler registered"); + } + ``` - The `userContext` is now automatically included in the logger context for all agent operations. This provides better traceability and debugging capabilities by associating custom context data with all log messages generated during an agent's execution. + ## Agent-Level Elicitation - ### Usage + Pass elicitation handler directly to `generateText` or `streamText`: - When you pass a `userContext` to any agent method, it will automatically appear in all log messages: + ```ts + const response = await agent.generateText("Do something with MCP", { + userId: "user123", + elicitation: async (request) => { + // Handler receives elicitation request from any MCP tool + const confirmed = await askUser(request.message); + return { + action: confirmed ? "accept" : "decline", + content: confirmed ? { confirmed: true } : undefined, + }; + }, + }); + ``` - ```typescript - const userContext = new Map([ - ["sessionId", "session-123"], - ["userId", "user-456"], - ["customKey", "customValue"], - ]); + This handler is automatically applied to all MCP tools during the request. - await agent.generateText("Hello", { userContext }); + ## Key Features + - **Dynamic handler management**: Add, replace, or remove handlers at runtime + - **One-time handlers**: Use `.once()` for handlers that auto-remove after first invocation + - **Method chaining**: All methods return `this` for fluent API usage + - **Auto-cancellation**: Requests without handlers are automatically cancelled + - **Agent-level integration**: Pass handler via `generateText`/`streamText` options + - **Full MCP SDK compatibility**: Uses `ElicitRequest` and `ElicitResult` types from `@modelcontextprotocol/sdk` - // All logs during this operation will include: - // { - // "component": "agent", - // "agentId": "TestAgent", - // "executionId": "...", - // "userContext": { - // "sessionId": "session-123", - // "userId": "user-456", - // "customKey": "customValue" - // } - // } - ``` + ## Exports - ### Benefits - - **Better Debugging**: Easily correlate logs with specific user sessions or requests - - **Enhanced Observability**: Track custom context throughout the entire agent execution - - **Multi-tenant Support**: Associate logs with specific tenants, users, or organizations - - **Request Tracing**: Follow a request through all agent operations and sub-agents + New exports from `@voltagent/core`: + - `MCPClient` - MCP client with elicitation support + - `UserInputBridge` - Bridge class for handler management + - `UserInputHandler` - Handler function type - This change improves the observability experience by ensuring all log messages include the relevant user context, making it easier to debug issues and track operations in production environments. +## 1.3.0 -## 0.1.73 +### Minor Changes -### Patch Changes +- [#870](https://github.com/VoltAgent/voltagent/pull/870) [`63cade8`](https://github.com/VoltAgent/voltagent/commit/63cade8b3226e97b6864a20906a748892f23fb96) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add authorization layer for MCP tools -- [#457](https://github.com/VoltAgent/voltagent/pull/457) [`8d89469`](https://github.com/VoltAgent/voltagent/commit/8d8946919820c0298bffea13731ea08660b72c4b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: optimize agent event system and add pagination to agent history API + Add a `can` function to `MCPConfiguration` that lets you control which MCP tools users can discover and execute. Supports both tool discovery filtering and execution-time checks. - Significantly improved agent performance and UI scalability with two major enhancements: + ## Usage - ## 1. Event System Optimization + ```typescript + import { MCPConfiguration, type MCPCanParams } from "@voltagent/core"; - Refactored agent event system to emit events immediately before database writes, matching the workflow event system behavior. This provides real-time event visibility without waiting for persistence operations. + const mcp = new MCPConfiguration({ + servers: { + expenses: { type: "http", url: "http://localhost:3142/mcp" }, + }, + authorization: { + can: async ({ toolName, action, userId, context }: MCPCanParams) => { + const roles = (context?.get("roles") as string[]) ?? []; - **Before:** - - Events were queued and only emitted after database write completion - - Real-time monitoring was delayed by persistence operations + // action is "discovery" (getTools) or "execution" (tool call) + if (toolName === "delete_expense" && !roles.includes("admin")) { + return { allowed: false, reason: "Admin only" }; + } - **After:** - - Events emit immediately for real-time updates - - Database persistence happens asynchronously in the background - - Consistent behavior with workflow event system + return true; + }, + filterOnDiscovery: true, // Hide unauthorized tools from tool list + checkOnExecution: true, // Verify on each tool call + }, + }); - ## 2. Agent History Pagination + // Get tools filtered by user's permissions + const tools = await mcp.getTools({ + userId: "user-123", + context: { roles: ["manager"] }, + }); + ``` - Added comprehensive pagination support to agent history API, preventing performance issues when loading large history datasets. + ## `MCPCanParams` - **New API:** + ```typescript + interface MCPCanParams { + toolName: string; // Tool name (without server prefix) + serverName: string; // MCP server identifier + action: "discovery" | "execution"; // When the check is happening + arguments?: Record; // Tool arguments (execution only) + userId?: string; + context?: Map; + } + ``` + + ## Cerbos Integration + + For production use with policy-based authorization: ```typescript - // Agent class - const history = await agent.getHistory({ page: 0, limit: 20 }); - // Returns: { entries: AgentHistoryEntry[], pagination: { page, limit, total, totalPages } } + import { GRPC } from "@cerbos/grpc"; - // REST API - GET /agents/:id/history?page=0&limit=20 - // Returns paginated response format - ``` + const cerbos = new GRPC("localhost:3593", { tls: false }); - **Implementation Details:** - - Added pagination to all storage backends (LibSQL, PostgreSQL, Supabase, InMemory) - - Updated WebSocket initial load to use pagination - - Maintained backward compatibility (when page/limit not provided, returns first 100 entries) - - Updated all tests to work with new pagination format + const mcp = new MCPConfiguration({ + servers: { expenses: { type: "http", url: "..." } }, + authorization: { + can: async ({ toolName, serverName, userId, context }) => { + const roles = (context?.get("roles") as string[]) ?? ["user"]; - **Storage Changes:** - - LibSQL: Added LIMIT/OFFSET support - - PostgreSQL: Added pagination with proper SQL queries - - Supabase: Used `.range()` method for efficient pagination - - InMemory: Implemented array slicing with total count + const result = await cerbos.checkResource({ + principal: { id: userId ?? "anonymous", roles }, + resource: { kind: `mcp::${serverName}`, id: serverName }, + actions: [toolName], + }); - This improves performance for agents with extensive history and provides better UX for viewing agent execution history. + return { allowed: result.isAllowed(toolName) ?? false }; + }, + filterOnDiscovery: true, + checkOnExecution: true, + }, + }); + ``` -- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements + See the full Cerbos example: [examples/with-cerbos](https://github.com/VoltAgent/voltagent/tree/main/examples/with-cerbos) - This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: +## 1.2.21 - **Key improvements:** - - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs - - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration - - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries - - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup - - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported +### Patch Changes - These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. +- [#855](https://github.com/VoltAgent/voltagent/pull/855) [`cd500ea`](https://github.com/VoltAgent/voltagent/commit/cd500ea0c71879c4ddbf5662b47758752595cc7d) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add google drive and google calendar actions methods and expose trigger DSL events + - The trigger DSL now supports Google Calendar (`on.googleCalendar.*`) and Google Drive (`on.googleDrive.*`) events alongside the new action helpers. -- [#447](https://github.com/VoltAgent/voltagent/pull/447) [`71500c5`](https://github.com/VoltAgent/voltagent/commit/71500c5368cce3ed4aacfb0fb2749752bf71badd) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - feat: (experimental) Allow for dynamic `andAll` steps when using the `createWorkflow` API. +## 1.2.20 - ### Usage +### Patch Changes - You can now provide a function to the `steps` property of `andAll` to dynamically generate the steps. +- [#852](https://github.com/VoltAgent/voltagent/pull/852) [`097f0cf`](https://github.com/VoltAgent/voltagent/commit/097f0cfcc113ae2029e233f67ff7e7c10db3e29d) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: fullStream forwarding from sub-agents so metadata reflects the executing sub-agent (adds executingAgentId/name, parent info, agentPath) instead of the supervisor - #849 - > [!NOTE] - > This is an experimental feature and may change in the future, its only supported for `andAll` steps in the `createWorkflow` API. + Documentation now calls out the metadata shape and how it appears in fullStream/toUIMessageStream, and the with-subagents example logs forwarded chunks for easy validation. - ```typescript - const workflow = createWorkflow( - { - id: "my-workflow", - name: "My Workflow", - input: z.object({ - id: z.string(), - }), - result: z.object({ - name: z.string(), - }), - memory, - }, - andThen({ - id: "fetch-data", - name: "Fetch data", - execute: async ({ data }) => { - return request.get(`https://api.example.com/data/${data.id}`); - }, - }), - andAll({ - id: "transform-data", - name: "Transform data", - steps: async (context) => - context.data.map((item) => - andThen({ - id: `transform-${item.id}`, - name: `Transform ${item.id}`, - execute: async ({ data }) => { - return { - ...item, - name: [item.name, item.id].join("-"), - }; - }, - }) - ), - }), - andThen({ - id: "pick-data", - name: "Pick data", - execute: async ({ data }) => { - return { - name: data[0].name, - }; - }, - }) - ); + Example: + + ```ts + const res = await supervisor.streamText("delegate something"); + for await (const part of res.fullStream) { + console.log({ + type: part.type, + subAgent: part.subAgentName, + executing: part.executingAgentName, + parent: part.parentAgentName, + path: part.agentPath, + }); + } ``` -- [#452](https://github.com/VoltAgent/voltagent/pull/452) [`6cc552a`](https://github.com/VoltAgent/voltagent/commit/6cc552ada896b1a8344976c46a08b53d2b3a5743) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: Expose the `andWorkflow` function as it was built but not re-exported + Example output: -- Updated dependencies [[`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5)]: - - @voltagent/internal@0.0.7 + ```json + { + "type": "tool-call", + "subAgent": "Formatter", + "executing": "Formatter", + "parent": "Supervisor", + "path": ["Supervisor", "Formatter"] + } + ``` -## 0.1.72 +## 1.2.19 ### Patch Changes -- [#445](https://github.com/VoltAgent/voltagent/pull/445) [`a658ae6`](https://github.com/VoltAgent/voltagent/commit/a658ae6fd5ae404448a43026f21bfa0351189f01) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: Fixed types in andAll and andRace where the inferred result from the steps was NOT being passed along +- [`da5b0a1`](https://github.com/VoltAgent/voltagent/commit/da5b0a1992cf5fe9b65cb8bd0cb97a19ce22958f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add postgres action -## 0.1.71 + Add a Postgres “execute query” action end‑to‑end: API provider with timeouts/SSL, credential creation, default catalog entry and console test payloads, plus VoltOps SDK/MCP snippets and client typings. + +## 1.2.18 ### Patch Changes -- [#438](https://github.com/VoltAgent/voltagent/pull/438) [`99fe836`](https://github.com/VoltAgent/voltagent/commit/99fe83662e9b3e550380fce066521a5c27d69eb3) Thanks [@danielyogel](https://github.com/danielyogel)! - feat: add optional outputSchema validation for tools +- [`9e215c6`](https://github.com/VoltAgent/voltagent/commit/9e215c69bce4e4fd3d96adb12b4ba98e3a5fcdb4) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: schema serialization for workflows and tools when projects use Zod 4. - VoltAgent now supports optional output schema validation for tools, providing runtime type safety and enabling LLM self-correction when tool outputs don't match expected formats. + ## The Problem - **Key Features:** - - **Optional Output Schema**: Tools can now define an `outputSchema` using Zod schemas - - **Runtime Validation**: Tool outputs are validated against the schema when provided - - **LLM Error Recovery**: Validation errors are returned to the LLM instead of throwing, allowing it to retry with corrected output - - **Full Backward Compatibility**: Existing tools without output schemas continue to work as before - - **TypeScript Type Safety**: Output types are inferred from schemas when provided + Zod 4 changed its internal `_def` shape (e.g., `type` instead of `typeName`, `shape` as an object, `element` for arrays). Our lightweight `zodSchemaToJsonUI` only understood the Zod 3 layout, so Zod 4 workflows/tools exposed `inputSchema`/`resultSchema` as `{ type: "unknown" }` in `/workflows/{id}` and tool metadata. - **Usage Example:** + ## The Solution - ```typescript - import { createTool } from "@voltagent/core"; - import { z } from "zod"; + Teach `zodSchemaToJsonUI` both v3 and v4 shapes: look at `_def.type` as well as `_def.typeName`, handle v4 object `shape`, array `element`, enum entries, optional/default unwrap, and record value types. Default values are picked up whether they’re stored as a function (v3) or a raw value (v4). - // Define output schema - const weatherOutputSchema = z.object({ - temperature: z.number(), - condition: z.enum(["sunny", "cloudy", "rainy", "snowy"]), - humidity: z.number().min(0).max(100), - }); + ## Impact - // Create tool with output validation - const weatherTool = createTool({ - name: "getWeather", - description: "Get current weather", - parameters: z.object({ - location: z.string(), - }), - outputSchema: weatherOutputSchema, // Optional - execute: async ({ location }) => { - // Return value will be validated - return { - temperature: 22, - condition: "sunny", - humidity: 65, - }; - }, - }); - ``` + API consumers and UIs now see real input/result/output schemas for Zod 4-authored workflows and tools instead of `{ type: "unknown" }`, restoring schema-driven rendering and validation. - **Validation Behavior:** +- [`7e40045`](https://github.com/VoltAgent/voltagent/commit/7e40045656d6868eb5ca337aad5c6a20532dad17) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Gmail actions to VoltOps SDK client + - Added `actions.gmail.sendEmail`, `replyToEmail`, `searchEmail`, `getEmail`, `getThread` + - Supports inline or stored credentials (OAuth refresh token or service account) - When a tool with `outputSchema` is executed: - 1. The output is validated against the schema - 2. If validation succeeds, the validated output is returned - 3. If validation fails, an error object is returned to the LLM: - ```json - { - "error": true, - "message": "Output validation failed: Expected number, received string", - "validationErrors": [...], - "actualOutput": {...} - } - ``` - 4. The LLM can see the error and potentially fix it by calling the tool again + Usage: - This feature enhances tool reliability while maintaining the flexibility for LLMs to handle validation errors gracefully. + ```ts + import { VoltOpsClient } from "@voltagent/core"; -## 0.1.70 + const voltops = new VoltOpsClient({ + publicKey: "", + secretKey: "", + }); + + await voltops.actions.gmail.sendEmail({ + credential: { credentialId: "" }, + to: ["teammate@example.com"], + cc: ["manager@example.com"], + subject: "Status update", + bodyType: "text", + body: "All systems operational.", + attachments: [ + { + filename: "notes.txt", + content: "YmFzZTY0LWNvbnRlbnQ=", + contentType: "text/plain", + }, + ], + }); + ``` + +## 1.2.17 ### Patch Changes -- [#400](https://github.com/VoltAgent/voltagent/pull/400) [`57825dd`](https://github.com/VoltAgent/voltagent/commit/57825ddb359177b5abc3696f3c54e5fc873ea621) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - feat(core): Add in new `andWorkflow` step to allow for running a workflow from another workflow +- [#845](https://github.com/VoltAgent/voltagent/pull/845) [`5432f13`](https://github.com/VoltAgent/voltagent/commit/5432f13bddebd869522ebffbedd9843b4476f08b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: workflow execution listing - #844 -- [#436](https://github.com/VoltAgent/voltagent/pull/436) [`89e4ef1`](https://github.com/VoltAgent/voltagent/commit/89e4ef1f0e84f3f42bb208cf70f39cca0898ddc7) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: make tool errors non-fatal for better agent resilience - #430 & #349 + Added a unified way to list workflow runs so teams can audit executions across every storage backend and surface them via the API and console. - Previously, when tools encountered errors (timeouts, connection issues, etc.), the entire agent execution would fail. This change improves resilience by: - - Catching tool execution errors and returning them as structured results instead of throwing - - Allowing the LLM to see tool errors and decide whether to retry or use alternative approaches - - Including error details (message and stack trace) in the tool result for debugging - - Ensuring agent execution only fails when it reaches maxSteps or the LLM cannot proceed + ## What changed + - `queryWorkflowRuns` now exists on all memory adapters (in-memory, libsql, Postgres, Supabase, voltagent-memory) with filters for `workflowId`, `status`, `from`, `to`, `limit`, and `offset`. + - Server routes are consolidated under `/workflows/executions` (no path param needed); `GET /workflows/:id` also returns the workflow result schema for typed clients. Handler naming is standardized to `listWorkflowRuns`. + - VoltOps Console observability panel lists the new endpoint; REST docs updated with query params and sample responses. New unit tests cover handlers and every storage adapter. - The error result format includes: + ## Quick fetch + + ```ts + await fetch( + "http://localhost:3141/workflows/executions?workflowId=expense-approval&status=completed&from=2024-01-01&to=2024-01-31&limit=20&offset=0" + ); + ``` + +## 1.2.16 + +### Patch Changes + +- [#839](https://github.com/VoltAgent/voltagent/pull/839) [`93e5a8e`](https://github.com/VoltAgent/voltagent/commit/93e5a8ed03d2335d845436752b476881c24931ba) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: expose resultSchema in workflow API response + + Previously, when calling the workflow API endpoint (e.g., `GET /workflows/{id}`), the response included `inputSchema`, `suspendSchema`, and `resumeSchema`, but was missing `resultSchema` (the output schema). + + Now, workflows properly expose their result schema alongside other schemas: ```json { - "error": true, - "message": "Error message", - "stack": "Error stack trace (optional)" + "inputSchema": { + "type": "object", + "properties": { "name": { "type": "string" } }, + "required": ["name"] + }, + "resultSchema": { + "type": "object", + "properties": { "greeting": { "type": "string" } }, + "required": ["greeting"] + }, + "suspendSchema": { "type": "unknown" }, + "resumeSchema": { "type": "unknown" } } ``` - This change makes agents more robust when dealing with unreliable external tools or transient network issues. + This allows API consumers to understand the expected output format of a workflow, enabling better client-side validation and documentation generation. -## 0.1.69 +## 1.2.15 ### Patch Changes -- [#425](https://github.com/VoltAgent/voltagent/pull/425) [`8605e70`](https://github.com/VoltAgent/voltagent/commit/8605e708d17e6fa0150bd13235e795288422c52b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Promise-based properties and warnings to AI responses - #422 +- [#833](https://github.com/VoltAgent/voltagent/pull/833) [`010aa0a`](https://github.com/VoltAgent/voltagent/commit/010aa0a29a5561201689ecfee4738f0cc40798ce) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: supervisor now prefers each sub-agent’s `purpose` over full `instructions` when listing specialized agents, keeping prompts concise and preventing accidental directive leakage; added test coverage, docs, and example updates to encourage setting a short purpose per sub-agent. - Enhanced AI response types to align with Vercel AI SDK's API and provide better metadata: +## 1.2.14 - **For `streamObject`:** - - Added optional `object?: Promise` property that resolves to the final generated object - - Added optional `usage?: Promise` property that resolves to token usage information - - Added optional `warnings?: Promise` property for provider warnings +### Patch Changes - **For `streamText`:** - - Added optional `text?: Promise` property that resolves to the full generated text - - Added optional `finishReason?: Promise` property that resolves to the reason generation stopped - - Added optional `usage?: Promise` property that resolves to token usage information - - Added optional `reasoning?: Promise` property that resolves to model's reasoning text +- [#830](https://github.com/VoltAgent/voltagent/pull/830) [`972889f`](https://github.com/VoltAgent/voltagent/commit/972889f68a0973f80cd981c3322043c11df5f223) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: tool error handling to return structured, JSON-safe payloads instead of crashing on circular axios errors. #829 - **For `generateText` and `generateObject`:** - - Added optional `reasoning?: string` property for model's reasoning text (generateText only) - - Added optional `warnings?: any[]` property for provider warnings +## 1.2.13 - These properties are optional to maintain backward compatibility. Providers that support these features (like Vercel AI) now return these values, allowing users to access rich metadata: +### Patch Changes - ```typescript - // For streamObject - const response = await agent.streamObject(input, schema); - const finalObject = await response.object; // Promise - const usage = await response.usage; // Promise +- [#825](https://github.com/VoltAgent/voltagent/pull/825) [`fd1428b`](https://github.com/VoltAgent/voltagent/commit/fd1428b73abfcac29c238e0cee5229ff227cb72b) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: remove redundant "You are ${this.name}" prefix from system prompt construction - #813 - // For streamText - const response = await agent.streamText(input); - const fullText = await response.text; // Promise - const usage = await response.usage; // Promise + The system prompt construction in `Agent` class was redundantly prepending "You are ${this.name}" even when the user provided their own system prompt. This change removes the prefix, allowing the user's instructions to be used exactly as provided. - // For generateText - const response = await agent.generateText(input); - console.log(response.warnings); // Any provider warnings - console.log(response.reasoning); // Model's reasoning (if available) - ``` +## 1.2.12 -## 0.1.68 +### Patch Changes + +- [`28661fc`](https://github.com/VoltAgent/voltagent/commit/28661fc24f945b0e52c12703a5a09a033317d8fa) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: enable persistence for live evaluations + +## 1.2.11 ### Patch Changes -- [#423](https://github.com/VoltAgent/voltagent/pull/423) [`089c039`](https://github.com/VoltAgent/voltagent/commit/089c03993e3b9e05655a1108355e7bee940d33a7) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add message type filtering support to memory storage implementations +- [#817](https://github.com/VoltAgent/voltagent/pull/817) [`decfda5`](https://github.com/VoltAgent/voltagent/commit/decfda5898128ef9097cd1dc456ca563ee49def1) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: pass complete OperationContext to retrievers when used as object instances - Added the ability to filter messages by type when retrieving conversation history. This enhancement allows the framework to distinguish between different message types (text, tool-call, tool-result) and retrieve only the desired types, improving context preparation for LLMs. + ## The Problem - ## Key Changes - - **MessageFilterOptions**: Added optional `types` parameter to filter messages by type - - **prepareConversationContext**: Now filters to only include text messages, excluding tool-call and tool-result messages for cleaner LLM context - - **All storage implementations**: Added database-level filtering for better performance + When a retriever was assigned directly to an agent as an object instance (e.g., `retriever: myRetriever`), it wasn't receiving the `userId` and `conversationId` from the OperationContext. This prevented user-specific and conversation-aware retrieval when retrievers were used in this way, even though these fields were correctly passed when retrievers were used as tools. - ## Usage + ## The Solution - ```typescript - // Get only text messages - const textMessages = await memory.getMessages({ - userId: "user-123", - conversationId: "conv-456", - types: ["text"], - }); + Updated the `getRetrieverContext` method in the Agent class to pass the complete OperationContext to retrievers, ensuring consistency between tool-based and object-based retriever usage. - // Get tool-related messages - const toolMessages = await memory.getMessages({ - userId: "user-123", - conversationId: "conv-456", - types: ["tool-call", "tool-result"], + ## What Changed + + ```typescript + // Before - only partial context was passed + return await this.retriever.retrieve(retrieverInput, { + context: oc.context, + logger: retrieverLogger, }); - // Get all messages (default behavior - backward compatible) - const allMessages = await memory.getMessages({ - userId: "user-123", - conversationId: "conv-456", + // After - complete OperationContext is passed + return await this.retriever.retrieve(retrieverInput, { + ...oc, + logger: retrieverLogger, }); ``` - ## Implementation Details - - **InMemoryStorage**: Filters messages in memory after retrieval - - **LibSQLStorage**: Adds SQL WHERE clause with IN operator for type filtering - - **PostgreSQL**: Uses parameterized IN clause with proper parameter counting - - **Supabase**: Utilizes query builder's `.in()` method for type filtering - - This change ensures that `prepareConversationContext` provides cleaner, more focused context to LLMs by excluding intermediate tool execution details, while maintaining full backward compatibility for existing code. + ## Impact + - **Consistent behavior:** Retrievers now receive `userId` and `conversationId` regardless of how they're configured + - **User-specific retrieval:** Enables filtering results by user in multi-tenant scenarios + - **Conversation awareness:** Retrievers can now access conversation context when used as object instances + - **No breaking changes:** This is a backward-compatible fix that adds missing context fields -## 0.1.67 +- [#820](https://github.com/VoltAgent/voltagent/pull/820) [`c5e0c89`](https://github.com/VoltAgent/voltagent/commit/c5e0c89554d85c895e3d6cbfc83ad47bd53a1b9f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: expose createdAt in memory.getMessages -### Patch Changes + ## What Changed -- [#417](https://github.com/VoltAgent/voltagent/pull/417) [`67450c3`](https://github.com/VoltAgent/voltagent/commit/67450c3bc4306ab6021ca8feed2afeef6dcc320e) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: dynamic toolkit resolution and VoltOps UI visibility + The `createdAt` timestamp is now exposed in the `metadata` object of messages retrieved via `memory.getMessages()`. This ensures that the creation time of messages is accessible across all storage adapters (`InMemory`, `Supabase`, `LibSQL`, `PostgreSQL`). - Fixed an issue where dynamic tools and toolkits weren't being displayed in VoltOps UI when resolved during agent execution. The fix includes: + ## Usage - **Key Changes:** - - **Dynamic Tool Resolution**: Modified `prepareToolsForGeneration` to properly accept and process both `BaseTool` and `Toolkit` types - - **VoltOps UI Integration**: Dynamic tools now appear in the Console UI by updating history metadata when tools are resolved - - **Data Persistence**: Tools persist across page refreshes by storing them in history entry metadata + You can now access the `createdAt` timestamp from the message metadata: - **Technical Details:** - - `prepareToolsForGeneration` now accepts `(BaseTool | Toolkit)[]` instead of just `BaseTool[]` - - Uses temporary ToolManager with `addItems()` to handle both tools and toolkits consistently - - Updates history entry metadata with complete agent snapshot when dynamic tools are resolved - - Removed WebSocket-based TOOLS_UPDATE events in favor of metadata-based approach + ```typescript + const messages = await memory.getMessages(userId, conversationId); - This ensures that dynamic tools like `createReasoningTools()` and other toolkits work seamlessly when provided through the `dynamicTools` parameter. + messages.forEach((message) => { + console.log(`Message ID: ${message.id}`); + console.log(`Created At: ${message.metadata?.createdAt}`); + }); + ``` -- [#418](https://github.com/VoltAgent/voltagent/pull/418) [`aa024c1`](https://github.com/VoltAgent/voltagent/commit/aa024c1a7c643b2aff7a5fd0d150c87f8a9a1858) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: memory storage implementations now correctly return the most recent messages when using context limit + This change aligns the behavior of all storage adapters and ensures consistent access to message timestamps. - Fixed an issue where memory storage implementations (LibSQL, PostgreSQL, Supabase) were returning the oldest messages instead of the most recent ones when a context limit was specified. This was causing AI agents to lose important recent context in favor of old conversation history. +- [`53ff6bf`](https://github.com/VoltAgent/voltagent/commit/53ff6bfcae59e0f72dc4de6f8550241392e25864) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: voltops actions serverless fetch usage - **Before:** - - `contextLimit: 10` returned the first 10 messages (oldest) - - Agents were working with outdated context +## 1.2.10 - **After:** - - `contextLimit: 10` returns the last 10 messages (most recent) in chronological order - - Agents now have access to the most relevant recent context - - InMemoryStorage was already working correctly and remains unchanged +### Patch Changes - Changes: - - LibSQLStorage: Modified query to use `ORDER BY DESC` with `LIMIT`, then reverse results - - PostgreSQL: Modified query to use `ORDER BY DESC` with `LIMIT`, then reverse results - - Supabase: Modified query to use `ascending: false` with `limit`, then reverse results +- [#815](https://github.com/VoltAgent/voltagent/pull/815) [`148f550`](https://github.com/VoltAgent/voltagent/commit/148f550ceafa412534fd2d1c4cfb44c8255636ab) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: eliminate duplicate code in Agent.getSystemMessage method through refactoring - #813 - This ensures consistent behavior across all storage implementations where context limits provide the most recent messages, improving AI agent response quality and relevance. + ## The Problem -- [#418](https://github.com/VoltAgent/voltagent/pull/418) [`aa024c1`](https://github.com/VoltAgent/voltagent/commit/aa024c1a7c643b2aff7a5fd0d150c87f8a9a1858) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: tool errors now properly recorded in conversation history and allow agent retry - #349 + The `getSystemMessage` method in the Agent class contained significant code duplication between two code paths: + - Lines 2896-2929: Handling `promptContent.type === "text"` + - Lines 2933-2967: Handling default string instructions - Fixed critical issues where tool execution errors were halting agent runs and not being recorded in conversation/event history. This prevented agents from retrying failed tool calls and lost important error context. + Both paths contained identical logic for: + 1. Adding toolkit instructions + 2. Adding markdown formatting instructions + 3. Adding retriever context + 4. Adding working memory context + 5. Adding supervisor instructions for sub-agents - **Before:** - - Tool errors would throw and halt agent execution immediately - - No error events or steps were recorded in conversation history - - Agents couldn't learn from or retry after tool failures - - Error context was lost, making debugging difficult + This duplication violated the DRY (Don't Repeat Yourself) principle and made maintenance more difficult, as any changes to instruction enrichment logic would need to be applied in multiple places. - **After:** - - Tool errors are caught and handled gracefully - - Error events (`tool:error`) are created and persisted - - Error steps are added to conversation history with full error details - - Agents can continue execution and retry within `maxSteps` limit - - Tool lifecycle hooks (onEnd) are properly called even on errors + ## The Solution - Changes: - - Added `handleToolError` helper method to centralize error handling logic - - Modified `generateText` to catch and handle tool errors without halting execution - - Updated `streamText` onError callback to use the same error handling - - Ensured tool errors are saved to memory storage for context retention + **Refactoring with Helper Method:** + - Created a new private method `enrichInstructions` that consolidates all common instruction enrichment logic + - Updated both code paths to use this centralized helper method + - Eliminated ~35 lines of duplicate code while preserving exact functionality - This improves agent resilience and debugging capabilities when working with potentially unreliable tools. + **New Method Signature:** -## 0.1.66 + ```typescript + private async enrichInstructions( + baseContent: string, + retrieverContext: string | null, + workingMemoryContext: string | null, + oc: OperationContext, + ): Promise + ``` -### Patch Changes + ## Impact + - ✅ **Improved Maintainability:** Single source of truth for instruction enrichment logic + - ✅ **Reduced Complexity:** Cleaner, more readable code with better separation of concerns + - ✅ **Better Testability:** Dedicated unit tests for the `enrichInstructions` method + - ✅ **No Breaking Changes:** Pure refactoring with identical behavior + - ✅ **Comprehensive Testing:** Added 16 new tests covering all enrichment scenarios and edge cases -- [`1f8ce22`](https://github.com/VoltAgent/voltagent/commit/1f8ce226fec449f16f1dce6c2b96cef7030eff3a) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: zod peer dependency to allow flexible versioning (^3.24.2 instead of 3.24.2) to resolve npm install conflicts + ## Technical Details -## 0.1.65 + The refactored `enrichInstructions` method handles: + - Toolkit instructions injection from registered toolkits + - Markdown formatting directive when enabled + - Retriever context integration for RAG patterns + - Working memory context from conversation history + - Supervisor instructions for multi-agent orchestration -### Patch Changes + All existing functionality is preserved with improved code organization and test coverage. -- [#404](https://github.com/VoltAgent/voltagent/pull/404) [`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: integrate comprehensive logging system with @voltagent/logger support +## 1.2.9 - Enhanced the core package with a flexible logging infrastructure that supports both the built-in ConsoleLogger and the advanced @voltagent/logger package. This update provides better debugging, monitoring, and observability capabilities across all VoltAgent components. +### Patch Changes - **Key Changes:** - - **Logger Integration**: VoltAgent, Agents, and Workflows now accept a logger instance for centralized logging - - **Default ConsoleLogger**: Built-in logger for quick prototyping with basic timestamp formatting - - **Logger Propagation**: Parent loggers automatically create child loggers for agents and workflows - - **Context Preservation**: Child loggers maintain context (component names, IDs) throughout execution - - **Environment Variables**: Support for `VOLTAGENT_LOG_LEVEL` and `LOG_LEVEL` environment variables - - **Backward Compatible**: Existing code works without changes, using the default ConsoleLogger +- [#812](https://github.com/VoltAgent/voltagent/pull/812) [`0f64363`](https://github.com/VoltAgent/voltagent/commit/0f64363a2b577e025fae41276cc0d85ef7fc0644) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: comprehensive authentication system with JWT, Console Access, and WebSocket support + + ## The Problem + + VoltAgent's authentication system had several critical gaps that made it difficult to secure production deployments: + 1. **No Authentication Support:** The framework lacked built-in authentication, forcing developers to implement their own security + 2. **WebSocket Security:** WebSocket connections for observability had no authentication, exposing sensitive telemetry data + 3. **Browser Limitations:** Browsers cannot send custom headers during WebSocket handshake, making authentication impossible + 4. **Development vs Production:** No clear separation between development convenience and production security + 5. **Console Access:** No secure way for the VoltAgent Console to access observability endpoints in production + + ## The Solution + + **JWT Authentication (`@voltagent/server-core`, `@voltagent/server-hono`):** + - Added pluggable `jwtAuth` provider with configurable secret and options + - Implemented `mapUser` function to transform JWT payloads into user objects + - Created flexible route protection with `defaultPrivate` mode (opt-out vs opt-in) + - Added `publicRoutes` configuration for fine-grained control + + **WebSocket Authentication:** + - Implemented query parameter authentication for browser WebSocket connections + - Added dual authentication support (headers for servers, query params for browsers) + - Created WebSocket-specific authentication helpers for observability endpoints + - Preserved user context throughout WebSocket connection lifecycle + + **Console Access System:** + - Introduced `VOLTAGENT_CONSOLE_ACCESS_KEY` environment variable for production Console access + - Added `x-console-access-key` header support for HTTP requests + - Implemented query parameter `?key=` for WebSocket connections + - Created `hasConsoleAccess()` utility for unified access checking + + **Development Experience:** + - Enhanced `x-voltagent-dev` header to work with both HTTP and WebSocket + - Added `isDevRequest()` helper that requires both header AND non-production environment + - Implemented query parameter `?dev=true` for browser WebSocket connections + - Maintained zero-config development mode while ensuring production security + + **Route Matching Improvements:** + - Added wildcard support with `/observability/*` pattern for all observability endpoints + - Implemented double-star pattern `/api/**` for path and all children + - Enhanced `pathMatches()` function with proper segment matching + - Protected all observability, workflow control, and system update endpoints by default + + ## Impact + - ✅ **Production Ready:** Complete authentication system for securing VoltAgent deployments + - ✅ **WebSocket Security:** Browser-compatible authentication for real-time observability + - ✅ **Console Integration:** Secure access for VoltAgent Console in production environments + - ✅ **Developer Friendly:** Zero-config development with automatic authentication bypass + - ✅ **Flexible Security:** Choose between opt-in (default) or opt-out authentication modes + - ✅ **User Context:** Automatic user injection into agent and workflow execution context + + ## Technical Details + + **Protected Routes (Default):** - **Installation:** + ```typescript + // Agent/Workflow Execution + POST /agents/:id/text + POST /agents/:id/stream + POST /workflows/:id/run - ```bash - # npm - npm install @voltagent/logger + // All Observability Endpoints + /observability/* // Traces, logs, memory - all methods - # pnpm - pnpm add @voltagent/logger + // Workflow Control + POST /workflows/:id/executions/:executionId/suspend + POST /workflows/:id/executions/:executionId/resume - # yarn - yarn add @voltagent/logger + // System Updates + GET /updates + POST /updates/:packageName ``` - **Usage Examples:** + **Authentication Modes:** ```typescript - // Using default ConsoleLogger - const voltAgent = new VoltAgent({ agents: [agent] }); + // Opt-in mode (default) - Only execution endpoints protected + auth: jwtAuth({ + secret: process.env.JWT_SECRET, + }); - // Using @voltagent/logger for production - import { createPinoLogger } from "@voltagent/logger"; + // Opt-out mode - Everything protected except specified routes + auth: jwtAuth({ + secret: process.env.JWT_SECRET, + defaultPrivate: true, + publicRoutes: ["GET /health", "POST /webhooks/*"], + }); + ``` - const logger = createPinoLogger({ level: "info" }); - const voltAgent = new VoltAgent({ - logger, - agents: [agent], + **WebSocket Authentication Flow:** + + ```typescript + // Browser WebSocket with query params + new WebSocket("ws://localhost:3000/ws/observability?key=console-key"); + new WebSocket("ws://localhost:3000/ws/observability?dev=true"); + + // Server WebSocket with headers + ws.connect({ + headers: { + "x-console-access-key": "console-key", + "x-voltagent-dev": "true", + }, }); ``` - This update lays the foundation for comprehensive observability and debugging capabilities in VoltAgent applications. + ## Migration Notes -- Updated dependencies [[`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726)]: - - @voltagent/internal@0.0.6 + **For Existing Users:** + 1. **No Breaking Changes:** Authentication is optional. Existing deployments continue to work without configuration. + 2. **To Enable Authentication:** -## 0.1.64 + ```typescript + import { jwtAuth } from "@voltagent/server-hono"; -### Patch Changes + new VoltAgent({ + server: honoServer({ + auth: jwtAuth({ + secret: process.env.JWT_SECRET, + }), + }), + }); + ``` -- [`aea3c78`](https://github.com/VoltAgent/voltagent/commit/aea3c78c467e42c53d10ad6c0890514dff861fca) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: replace `npm-check-updates` with native package manager support + 3. **For Production Console:** - This update replaces the `npm-check-updates` dependency with a native implementation that properly detects installed package versions and supports all major package managers (`npm`, `pnpm`, `yarn`, `bun`). + ```bash + # .env + VOLTAGENT_CONSOLE_ACCESS_KEY=your-secure-key + NODE_ENV=production + ``` - ### Key improvements: - - **Native package manager support**: Automatically detects and uses npm, pnpm, yarn, or bun based on lock files - - **Accurate version detection**: Shows actual installed versions instead of package.json semver ranges (e.g., shows 1.0.63 instead of ^1.0.0) - - **Monorepo compatibility**: Smart version detection that works with hoisted dependencies and workspace protocols - - **Non-blocking startup**: Update checks run in background without slowing down application startup (70-80% faster) - - **Intelligent caching**: 1-hour cache with package.json hash validation to reduce redundant checks - - **Major version updates**: Fixed update commands to use add/install instead of update to handle breaking changes - - **Restart notifications**: Added requiresRestart flag to API responses for better UX + 4. **Generate Secrets:** - ### Technical details: - - Removed execSync calls in favor of direct file system operations - - Parallel HTTP requests to npm registry for better performance - - Multiple fallback methods for version detection (direct access → require.resolve → tree search) - - Background processing with Promise.resolve().then() for true async behavior + ```bash + # JWT Secret + openssl rand -hex 32 - This change significantly improves the developer experience with faster startup times and more accurate dependency information. + # Console Access Key + openssl rand -hex 32 + ``` -## 0.1.63 + 5. **Test Token Generation:** + ```javascript + // generate-token.js + import jwt from "jsonwebtoken"; + const token = jwt.sign({ id: "user-1", email: "test@example.com" }, process.env.JWT_SECRET, { + expiresIn: "24h", + }); + console.log(token); + ``` + + ## Documentation + + Comprehensive authentication documentation has been added to `/website/docs/api/authentication.md` covering: + - Getting started with three authentication options + - Common use cases with code examples + - Advanced configuration with `mapUser` function + - Console and observability authentication + - Security best practices + - Troubleshooting guide + +## 1.2.8 ### Patch Changes -- [`6089462`](https://github.com/VoltAgent/voltagent/commit/60894629cef27950021da323390f455098b5bce2) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: prevent duplicate column errors in LibSQL agent_history table initialization +- [#810](https://github.com/VoltAgent/voltagent/pull/810) [`efcfe52`](https://github.com/VoltAgent/voltagent/commit/efcfe52dbe2c095057ce08a5e053d1defafd4e62) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: ensure reliable trace export and context propagation in serverless environments - Fixed a first-time database initialization error where the `migrateAgentHistorySchema` function was attempting to add `userId` and `conversationId` columns that already existed in newly created `agent_history` tables. + ## The Problem - The issue occurred because: - - The CREATE TABLE statement now includes `userId` and `conversationId` columns by default - - The migration function was still trying to add these columns, causing "duplicate column name" SQLite errors + Trigger-initiated agent executions in serverless environments (Cloudflare Workers, Vercel Edge Functions) were experiencing inconsistent trace exports and missing parent-child span relationships. This manifested as: + 1. Agent traces not appearing in observability tools despite successful execution + 2. Trigger and agent spans appearing as separate, disconnected traces instead of a single coherent trace tree + 3. Spans being lost due to serverless functions terminating before export completion - Changes: - - Added check in `migrateAgentHistorySchema` to skip migration if both columns already exist - - Properly set migration flag to prevent unnecessary migration attempts - - Ensured backward compatibility for older databases that need the migration + ## The Solution -## 0.1.62 + **Serverless Trace Export (`@voltagent/serverless-hono`):** + - Implemented reliable span flushing using Cloudflare's `waitUntil` API to ensure spans are exported before function termination + - Switched from `SimpleSpanProcessor` to `BatchSpanProcessor` with serverless-optimized configuration (immediate export, small batch sizes) + - Added automatic flush on trigger completion with graceful fallback to `forceFlush` when `waitUntil` is unavailable -### Patch Changes + **Context Propagation (`@voltagent/core`):** + - Integrated official `@opentelemetry/context-async-hooks` package to replace custom context manager implementation + - Ensured `AsyncHooksContextManager` is registered in both Node.js and serverless environments for consistent async context tracking + - Fixed `resolveParentSpan` logic to correctly identify scorer spans while avoiding framework-generated ambient spans + - Exported `propagation` and `ROOT_CONTEXT` from `@opentelemetry/api` for HTTP header-based trace context injection/extraction -- [`6fadbb0`](https://github.com/VoltAgent/voltagent/commit/6fadbb098fe40d8b658aa3386e6126fea155f117) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: createAsyncIterableStream import issue + **Node.js Reliability:** + - Updated `NodeVoltAgentObservability.flushOnFinish()` to call `forceFlush()` instead of being a no-op, ensuring spans are exported in short-lived processes -- Updated dependencies [[`6fadbb0`](https://github.com/VoltAgent/voltagent/commit/6fadbb098fe40d8b658aa3386e6126fea155f117)]: - - @voltagent/internal@0.0.5 + ## Impact + - ✅ Serverless traces are now reliably exported and visible in observability tools + - ✅ Trigger and agent spans form a single, coherent trace tree with proper parent-child relationships + - ✅ Consistent tracing behavior across Node.js and serverless runtimes + - ✅ No more missing or orphaned spans in Cloudflare Workers, Vercel Edge Functions, or similar platforms -## 0.1.61 + ## Technical Details + - Uses `BatchSpanProcessor` with `maxExportBatchSize: 32` and `scheduledDelayMillis: 100` for serverless + - Leverages `globalThis.___voltagent_wait_until` for non-blocking span export in Cloudflare Workers + - Implements `AsyncHooksContextManager` for robust async context tracking across `Promise` chains and `async/await` + - Maintains backward compatibility with existing Node.js deployments + + ## Migration Notes + + No breaking changes. Existing deployments will automatically benefit from improved trace reliability. Ensure your `wrangler.toml` includes `nodejs_compat` flag for Cloudflare Workers: + + ```toml + compatibility_flags = ["nodejs_compat"] + ``` + +## 1.2.7 ### Patch Changes -- [#391](https://github.com/VoltAgent/voltagent/pull/391) [`57c4874`](https://github.com/VoltAgent/voltagent/commit/57c4874d4d4807c50242b2e34ab9574fc6129888) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: improve workflow execute API with context-based pattern +- [#806](https://github.com/VoltAgent/voltagent/pull/806) [`b56e5a0`](https://github.com/VoltAgent/voltagent/commit/b56e5a087378c7ba5ce4a2c1756a0fe3dfb738b5) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: pass complete ToolExecuteOptions to retriever.retrieve() method - Breaking change: The workflow execute functions now use a context-based API for better developer experience and extensibility. + ## The Problem - **Before:** + Previously, `createRetrieverTool` only passed `context` and `logger` from `ToolExecuteOptions` to the retriever's `retrieve()` method. This prevented retrievers from accessing important operation metadata like: + - `userId` - for user-specific filtering + - `conversationId` - for conversation-aware retrieval + - `operationId` - for tracking + - Other `OperationContext` fields + + This limitation meant retrievers could only provide public knowledge and couldn't implement: + - Multi-tenant retrieval with user-specific namespaces + - Private knowledge bases per user + - User-filtered database queries + - Context-aware retrieval strategies + + ## The Solution + + **Core Changes:** + - Updated `RetrieveOptions` interface to extend `Partial`, providing access to all operation metadata + - Modified `createRetrieverTool` to pass the complete `options` object to `retriever.retrieve()` instead of just `{ context, logger }` + - Maintained full backward compatibility - all existing retrievers continue to work without changes + + **What's Now Available in retrieve() method:** ```typescript - .andThen({ - execute: async (data, state) => { - // old API with separate parameters - return { ...data, processed: true }; + class UserSpecificRetriever extends BaseRetriever { + async retrieve(input, options) { + // Access operation context + const { userId, conversationId, logger } = options; + + // User-specific filtering + const results = await db.query("SELECT * FROM documents WHERE user_id = $1", [userId]); + + return results; } - }) + } ``` - **After:** + ## Impact + - **Multi-tenant Support:** Retrievers can now filter by user using different namespaces, indexes, or database filters + - **Private Knowledge:** Support for user-specific knowledge bases and personalized retrieval + - **Better Context:** Access to conversation and operation metadata for smarter retrieval + - **Backward Compatible:** Existing retrievers work without any code changes + + ## Usage Examples + + ### User-Specific Vector Search ```typescript - .andThen({ - execute: async ({ data, state, getStepData }) => { - // new API with context object - const previousStep = getStepData("step-id"); - return { ...data, processed: true }; + class MultiTenantRetriever extends BaseRetriever { + async retrieve(input, options) { + const query = typeof input === "string" ? input : input[input.length - 1].content; + const { userId } = options; + + // Use user-specific namespace in Pinecone + const results = await this.pinecone.query({ + vector: await this.embed(query), + namespace: `user-${userId}`, + topK: 5, + }); + + return results.matches.map((m) => m.metadata.text).join("\n\n"); } - }) - ``` + } - This change applies to: - - `andThen` execute functions - - `andAgent` prompt functions - - `andWhen` condition functions - - `andTap` execute functions + // Use with userId + const response = await agent.generateText("Find my documents", { + userId: "user-123", + }); + ``` - The new API provides: - - Better TypeScript inference - - Access to previous step data via `getStepData` - - Cleaner, more extensible design + ### Conversation-Aware Retrieval -- [#399](https://github.com/VoltAgent/voltagent/pull/399) [`da66f86`](https://github.com/VoltAgent/voltagent/commit/da66f86d92a278007c2d3386d22b482fa70d93ff) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add suspend/resume functionality for workflows + ```typescript + class ConversationRetriever extends BaseRetriever { + async retrieve(input, options) { + const { conversationId, userId } = options; + + // Retrieve documents relevant to this conversation + const results = await db.query( + "SELECT * FROM documents WHERE user_id = $1 AND conversation_id = $2", + [userId, conversationId] + ); - **Workflows can now be paused and resumed!** Perfect for human-in-the-loop processes, waiting for external events, or managing long-running operations. + return results.map((r) => r.content).join("\n\n"); + } + } + ``` - ## Two Ways to Suspend + ## Migration Guide - ### 1. Internal Suspension (Inside Steps) + No migration needed! Existing retrievers automatically receive the full `options` object and can access new fields when ready: ```typescript - const approvalWorkflow = createWorkflowChain({ - id: "simple-approval", - name: "Simple Approval", - input: z.object({ item: z.string() }), - result: z.object({ approved: z.boolean() }), - }).andThen({ - id: "wait-for-approval", - execute: async ({ data, suspend, resumeData }) => { - // If resuming, return the decision - if (resumeData) { - return { approved: resumeData.approved }; - } - - // Otherwise suspend and wait - await suspend("Waiting for approval"); - }, - }); + // Before (still works) + async retrieve(input, options) { + const { context, logger } = options; + // ... + } - // Run and resume - const execution = await approvalWorkflow.run({ item: "New laptop" }); - const result = await execution.resume({ approved: true }); + // After (now possible) + async retrieve(input, options) { + const { context, logger, userId, conversationId } = options; + // Can now use userId and conversationId + } ``` - ### 2. External Suspension (From Outside) +## 1.2.6 - ```typescript - import { createSuspendController } from "@voltagent/core"; +### Patch Changes - // Create controller - const controller = createSuspendController(); +- [#801](https://github.com/VoltAgent/voltagent/pull/801) [`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add triggers DSL improvements and event payload simplification + - Introduce the new `createTriggers` DSL and expose trigger events via sensible provider names (e.g. `on.airtable.recordCreated`) rather than raw catalog IDs. + - Add trigger span metadata propagation so VoltAgent agents receive trigger context automatically without manual mapping. + - Simplify action dispatch payloads: `payload` now contains only the event’s raw data while trigger context lives in the `event`/`metadata` blocks, reducing boilerplate in handlers. - // Run workflow with controller - const execution = await workflow.run(input, { - suspendController: controller, - }); + ```ts + import { VoltAgent, createTriggers } from "@voltagent/core"; - // Pause from outside (e.g., user clicks pause) - controller.suspend("User paused workflow"); + new VoltAgent({ + // ... + triggers: createTriggers((on) => { + on.airtable.recordCreated(({ payload, event }) => { + console.log("New Airtable row", payload, event.metadata); + }); - // Resume later - if (execution.status === "suspended") { - const result = await execution.resume(); - } + on.gmail.newEmail(({ payload }) => { + console.log("New Gmail message", payload); + }); + }), + }); ``` - ## Key Features - - ⏸️ **Internal suspension** with `await suspend()` inside steps - - 🎮 **External control** with `createSuspendController()` - - 📝 **Type-safe resume data** with schemas - - 💾 **State persists** across server restarts - - 🚀 **Simplified API** - just pass `suspendController`, no need for separate `signal` +- [#801](https://github.com/VoltAgent/voltagent/pull/801) [`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749) Thanks [@omeraplak](https://github.com/omeraplak)! - Add full Discord action coverage to `VoltOpsActionsClient`, including typed helpers for messaging, reactions, channels, and guild roles. **All VoltOps Actions now require the inline `credential` payload**—pass `{ id: "cred_xyz" }` to reuse a saved credential or provide provider-specific secrets on the fly. Each provider now has explicit credential typing (Airtable ⇒ `{ apiKey }`, Slack ⇒ `{ botToken }`, Discord ⇒ `{ botToken } | { webhookUrl }`), so editors autocomplete only the valid fields. The SDK propagates these types so apps can invoke VoltOps Actions without managing separate credential IDs. - 📚 **For detailed documentation: [https://voltagent.dev/docs/workflows/suspend-resume](https://voltagent.dev/docs/workflows/suspend-resume)** +## 1.2.5 -- [#401](https://github.com/VoltAgent/voltagent/pull/401) [`4a7145d`](https://github.com/VoltAgent/voltagent/commit/4a7145debd66c7b1dfb953608e400b6c1ed02db7) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve TypeScript performance issues by fixing Zod dependency configuration (#377) +### Patch Changes - Moved Zod from direct dependencies to peer dependencies in @voltagent/vercel-ai to prevent duplicate Zod installations that were causing TypeScript server slowdowns. Also standardized Zod versions across the workspace to ensure consistency. +- [#798](https://github.com/VoltAgent/voltagent/pull/798) [`3168cc3`](https://github.com/VoltAgent/voltagent/commit/3168cc3bc241b74434bb35c2f6f80240beeac64c) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: enhanced message-helpers to support both MessageContent and UIMessage using TypeScript overloads - #796 - Changes: - - @voltagent/vercel-ai: Moved `zod` from dependencies to peerDependencies - - @voltagent/docs-mcp: Updated `zod` from `^3.23.8` to `3.24.2` - - @voltagent/with-postgres: Updated `zod` from `^3.24.2` to `3.24.2` (removed caret) + ## The Problem - This fix significantly improves TypeScript language server performance by ensuring only one Zod version is processed, eliminating the "Type instantiation is excessively deep and possibly infinite" errors that users were experiencing. + When working with messages in VoltAgent, there were two different message formats: + 1. **MessageContent** - The `content` property from AI SDK's `ModelMessage` (string or array of content parts) + 2. **UIMessage** - The newer format returned by memory operations and AI SDK's UI utilities (object with `id`, `role`, and `parts` array) -## 0.1.60 + The existing `message-helpers` utilities only supported MessageContent, making it cumbersome to extract information from UIMessage objects retrieved from memory or other sources. Users had to manually navigate the UIMessage structure or convert between formats. -### Patch Changes + ## The Solution -- [#371](https://github.com/VoltAgent/voltagent/pull/371) [`6ddedc2`](https://github.com/VoltAgent/voltagent/commit/6ddedc2b9be9c3dc4978dc53198a43c2cba74945) Thanks [@omeraplak](https://github.com/omeraplak)! - This update adds a powerful, type-safe workflow engine to `@voltagent/core`. You can now build complex, multi-step processes that chain together your code, AI models, and conditional logic with full type-safety and built-in observability. + All message helper functions now accept **both MessageContent and UIMessage** using TypeScript function overloads. This provides a seamless experience regardless of which message format you're working with. - Here is a quick example of what you can build: + **Enhanced Functions:** + - `extractText()` - Extract text from MessageContent or UIMessage + - `extractTextParts()` - Get text parts from either format + - `extractImageParts()` - Get image parts from either format + - `extractFileParts()` - Get file parts from either format + - `hasTextPart()` - Check for text parts in either format + - `hasImagePart()` - Check for image parts in either format + - `hasFilePart()` - Check for file parts in either format + - `getContentLength()` - Get content length from either format + + ## Usage Example ```typescript - import { createWorkflowChain, Agent, VoltAgent } from "@voltagent/core"; - import { z } from "zod"; - import { VercelAIProvider } from "@voltagent/vercel-ai"; - import { openai } from "@ai-sdk/openai"; + import { extractText, hasImagePart } from "@voltagent/core"; - // Define an agent to use in the workflow - const analyzerAgent = new Agent({ - name: "Analyzer", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - instructions: "You are a text analyzer.", - }); + // Works with MessageContent (existing usage - no changes needed!) + const content = [{ type: "text", text: "Hello world" }]; + extractText(content); // "Hello world" - // 1. Define the workflow chain - const workflow = createWorkflowChain({ - id: "greeting-analyzer", - name: "Greeting Analyzer", - input: z.object({ name: z.string() }), - result: z.object({ greeting: z.string(), sentiment: z.string() }), - }) - .andThen({ - id: "create-greeting", - execute: async ({ name }) => ({ greeting: `Hello, ${name}!` }), - }) - .andAgent( - (data) => `Analyze the sentiment of this greeting: "${data.greeting}"`, - analyzerAgent, - { - schema: z.object({ sentiment: z.string().describe("e.g., positive") }), - } - ); + // Now also works with UIMessage directly! + const messages = await memory.getMessages(userId, conversationId); + const firstMessage = messages[0]; - // You can run the chain directly - const result = await workflow.run({ name: "World" }); + // Extract text directly from UIMessage + const text = extractText(firstMessage); // "Hello world" + + // Check for images in UIMessage + if (hasImagePart(firstMessage)) { + const images = extractImageParts(firstMessage); + // Process images... + } + + // TypeScript inference works perfectly for both! ``` - To make your workflow runs visible in the **VoltOps Console** for debugging and monitoring, register both the workflow and its agents with a `VoltAgent` instance: + ## Benefits + 1. **Zero Breaking Changes** - All existing code continues to work exactly as before + 2. **Cleaner API** - Single function name for both formats instead of `extractText()` vs `extractTextFromUIMessage()` + 3. **Type Safety** - Full TypeScript type inference and autocomplete for both formats + 4. **Memory Integration** - Works seamlessly with messages retrieved from `memory.getMessages()` + 5. **Intuitive** - "Extract text" is just `extractText()` regardless of message format - ![VoltOps Workflow Observability](https://cdn.voltagent.dev/docs/workflow-observability-demo.gif) + ## Migration - ```typescript - // 2. Register the workflow and agent to enable observability - new VoltAgent({ - agents: { - analyzerAgent, - }, - workflows: { - workflow, - }, - }); + **No migration needed!** Your existing code using MessageContent continues to work. You can now also pass UIMessage objects directly to these functions when working with memory or other sources that return UIMessage format. - // Now, when you run the workflow, its execution will appear in VoltOps. - await workflow.run({ name: "Alice" }); + ```typescript + // Before: Had to manually navigate UIMessage structure + const message = messages[0]; + const text = message.parts + .filter((p) => p.type === "text") + .map((p) => p.text) + .join(""); + + // After: Use the same helper function! + const text = extractText(message); ``` - This example showcases the fluent API, data flow between steps, type-safety, and integration with Agents, which are the core pillars of this new feature. + ## Technical Details + - Uses TypeScript function overloads for clean API surface + - Type guard (`isUIMessage`) automatically detects format + - Returns appropriate types based on input (e.g., `TextUIPart[]` for UIMessage, generic array for MessageContent) + - Fully tested with 50 comprehensive test cases covering both formats -## 0.1.59 +## 1.2.4 ### Patch Changes -- [#382](https://github.com/VoltAgent/voltagent/pull/382) [`86acef0`](https://github.com/VoltAgent/voltagent/commit/86acef01dd6ce2e213b13927136c32bcf1078484) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: Allow workflow.run to accept userContext, conversationId, and userId and pass along to all steps & agents +- [#794](https://github.com/VoltAgent/voltagent/pull/794) [`39704ad`](https://github.com/VoltAgent/voltagent/commit/39704ad30069fe940577006146c23d0218e16968) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: remove ambient parent spans in serverless environments to ensure proper trace completion -- [#375](https://github.com/VoltAgent/voltagent/pull/375) [`1f55501`](https://github.com/VoltAgent/voltagent/commit/1f55501ec7a221002c11a3a0e87779c8f1379bed) Thanks [@SashankMeka1](https://github.com/SashankMeka1)! - feat(core): MCPServerConfig timeouts - #363. + ## The Problem - Add MCPServerConfig timeouts + When deploying VoltAgent to serverless platforms like Vercel/Next.js, Netlify Functions, or Cloudflare Workers, traces would remain in "pending" status in VoltOps even though: + - All spans were successfully exported to the backend + - The agent execution completed successfully + - The finish reason was captured correctly - ```ts - const mcpConfig = new MCPConfiguration({ - servers: { - filesystem: { - type: "stdio", - command: "npx", - args: ["-y", "@modelcontextprotocol/server-filesystem", path.resolve("./data")], - timeout: 10000, - }, - }, - }); + **Root Cause**: VoltAgent was using `context.active()` when creating root spans, which inherited ambient spans from the hosting framework (e.g., Next.js instrumentation, Vercel telemetry). This caused agent root spans to appear as child spans with framework-generated parent span IDs, preventing the backend from recognizing them as trace roots. + + Example of the issue: + + ```typescript + // Backend received: + { + name: 'Supervisor', + parentSpanId: '8423d7ed5539b430', // ❌ Next.js ambient span + isRootSpan: false, // ❌ Not detected as root + agentState: 'completed', + } + // Result: Trace stayed "pending" forever ``` -- [#385](https://github.com/VoltAgent/voltagent/pull/385) [`bfb13c3`](https://github.com/VoltAgent/voltagent/commit/bfb13c390a8ff59ad61a08144a5f6fa0439d25b7) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix(core): Add back the result for a workflow execution, as the result was removed due to change in state management process + ## The Solution -- [#384](https://github.com/VoltAgent/voltagent/pull/384) [`757219c`](https://github.com/VoltAgent/voltagent/commit/757219cc76e7f0320074230788012714f91e81bb) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - feat(core): Add ability to pass hooks into the generate functions (i.e. streamText) that do not update/mutate the agent hooks + Updated `trace-context.ts` to use `trace.deleteSpan(context.active())` instead of `context.active()` when no explicit parent span exists. This removes ambient spans from the context, ensuring agent root spans are truly root. - ### Usage + **Before**: - ```ts - const agent = new Agent({ - name: "My Agent with Hooks", - instructions: "An assistant demonstrating hooks", - llm: provider, - model: openai("gpt-4o"), - hooks: myAgentHooks, - }); + ```typescript + const parentContext = parentSpan ? trace.setSpan(context.active(), parentSpan) : context.active(); // ❌ Includes ambient spans + ``` - // both the myAgentHooks and the hooks passed in the generateText method will be called - await agent.generateText("Hello, how are you?", { - hooks: { - onEnd: async ({ context }) => { - console.log("End of generation but only on this invocation!"); - }, - }, - }); + **After**: + + ```typescript + const parentContext = parentSpan + ? trace.setSpan(context.active(), parentSpan) + : trace.deleteSpan(context.active()); // ✅ Clean context ``` -- [#381](https://github.com/VoltAgent/voltagent/pull/381) [`b52cdcd`](https://github.com/VoltAgent/voltagent/commit/b52cdcd2d8072fa93011e14c41841b6ff8a97b0b) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - feat: Add ability to tap into workflow without mutating the data by adding the `andTap` step + This follows OpenTelemetry's official pattern from `@opentelemetry/sdk-trace-base`: - ### Usage + ```typescript + if (options.root) { + context = api.trace.deleteSpan(context); + } + ``` - The andTap step is useful when you want to tap into the workflow without mutating the data, for example: + ## Impact + - ✅ **Serverless environments**: Traces now properly complete in VoltOps on Vercel, Netlify, Cloudflare Workers + - ✅ **Framework compatibility**: Works correctly alongside Next.js, Express, and other instrumented frameworks + - ✅ **Proper trace hierarchy**: Agent root spans are no longer children of ambient framework spans + - ✅ **No breaking changes**: Only affects root span context creation, existing functionality preserved + - ✅ **Observability improvements**: Backend can now correctly identify root spans and mark traces as "completed" - ```ts - const workflow = createWorkflowChain(config) - .andTap({ - execute: async (data) => { - console.log("🔄 Translating text:", data); - }, - }) - .andTap({ - id: "sleep", - execute: async (data) => { - console.log("🔄 Sleeping for 1 second"); - await new Promise((resolve) => setTimeout(resolve, 1000)); - return data; - }, - }) - .andThen({ - execute: async (data) => { - return { ...data, translatedText: data.translatedText }; - }, - }) - .run({ - originalText: "Hello, world!", - targetLanguage: "en", - }); + ## Verification + + After the fix, backend logs show: + + ```typescript + { + name: 'Supervisor', + parentSpanId: undefined, // ✅ No ambient parent + isRootSpan: true, // ✅ Correctly detected + agentState: 'completed', + } + // Result: Trace marked as "completed" ✅ ``` - You will notice that the `andTap` step is not included in the result, BUT it is `awaited` and `executed` before the next step, so you can block processing safely if needed. + ## Usage -## 0.1.58 + No code changes required - this fix is automatic for all VoltAgent applications deployed to serverless environments. + + **Note**: If you previously added workarounds like `after()` with `forceFlush()` in Next.js routes, those are no longer necessary for trace completion (though they may still be useful for ensuring spans are exported before function termination on some platforms). + +## 1.2.3 ### Patch Changes -- [#342](https://github.com/VoltAgent/voltagent/pull/342) [`8448674`](https://github.com/VoltAgent/voltagent/commit/84486747b1b40eaca315b900c56fd2ad976780ea) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - feat: add Workflow support (alpha) +- [#787](https://github.com/VoltAgent/voltagent/pull/787) [`5e81d65`](https://github.com/VoltAgent/voltagent/commit/5e81d6568ba3bee26083ca2a8e5d31f158e36fc0) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add full conversation step persistence across the stack: + - Core now exposes managed-memory step APIs, and the VoltAgent managed memory adapter persists/retrieves steps through VoltOps. + - LibSQL, PostgreSQL, Supabase, and server handlers provision the new `_steps` table, wire up DTOs/routes, and surface the data in Observability/Steps UI (including managed-memory backends). - **🧪 ALPHA FEATURE: Workflow orchestration system is now available for early testing.** This feature allows you to create complex, multi-step agent workflows with chaining API and conditional branching. The API is experimental and may change in future releases. + fixes: #613 - ## 📋 Usage +## 1.2.2 - **Basic Workflow Chain Creation:** +### Patch Changes - ```typescript - import { openai } from "@ai-sdk/openai"; - import { Agent, VoltAgent, createWorkflowChain } from "@voltagent/core"; - import { VercelAIProvider } from "@voltagent/vercel-ai"; - import { z } from "zod"; +- [#785](https://github.com/VoltAgent/voltagent/pull/785) [`f4b9524`](https://github.com/VoltAgent/voltagent/commit/f4b9524ea24b7dfc7e863547d5ee01e876524eba) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: the `/agents/:id/text` response to always include tool calling data. Previously we only bubbled up the last step's `toolCalls`/`toolResults`, so multi-step providers (like `ollama-ai-provider-v2`) returned empty arrays even though the tool actually ran. We now aggregate tool activity across every step before returning the result, restoring parity with GPT-style providers and matching the AI SDK output. - // Create workflow agents - const analyzerAgent = new Agent({ - name: "DataAnalyzer", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - instructions: "Analyze input data and extract key insights with confidence scores", - }); +- [#783](https://github.com/VoltAgent/voltagent/pull/783) [`46597cf`](https://github.com/VoltAgent/voltagent/commit/46597cf5a6ff8ff1ff5b8a61ab45c4195049f550) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: unwrap provider-executed tool outputs when persisting conversation history so Anthropic’s `server_tool_use` IDs stay unique on replay - const processorAgent = new Agent({ - name: "DataProcessor", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - instructions: "Process and transform analyzed data into structured format", - }); +- [#786](https://github.com/VoltAgent/voltagent/pull/786) [`f262b51`](https://github.com/VoltAgent/voltagent/commit/f262b51f0a65923d6dfac4f410b37f54a7f81cd2) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: ensure sub-agent metadata is persisted alongside supervisor history so supervisor conversations know which sub-agent produced each tool event and memory record. You can now filter historical events the same way you handle live streams: - const reporterAgent = new Agent({ - name: "ReportGenerator", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - instructions: "Generate comprehensive reports from processed data", - }); + ```ts + const memoryMessages = await memory.getMessages(userId, conversationId); - // Create workflow chain - const dataProcessingWorkflow = createWorkflowChain({ - id: "data-processing-workflow", - name: "Data Processing Pipeline", - purpose: "Analyze, process, and generate reports from raw data", - input: z.object({ - rawData: z.string(), - analysisType: z.string(), - }), - result: z.object({ - originalData: z.string(), - analysisResults: z.object({ - insights: z.array(z.string()), - confidence: z.number().min(0).max(1), - }), - processedData: z.object({ - summary: z.string(), - keyPoints: z.array(z.string()), - }), - finalReport: z.string(), - processingTime: z.number(), - }), - }) - .andAgent( - async (data) => { - return `Analyze the following data: ${data.rawData}. Focus on ${data.analysisType} analysis.`; - }, - analyzerAgent, - { - schema: z.object({ - insights: z.array(z.string()), - confidence: z.number().min(0).max(1), - }), - } - ) - .andThen({ - execute: async (data, state) => { - // Skip processing if confidence is too low - if (data.confidence < 0.5) { - throw new Error(`Analysis confidence too low: ${data.confidence}`); + const formatterSteps = memoryMessages.filter( + (message) => message.metadata?.subAgentId === "Formatter" + ); + + for (const message of formatterSteps) { + console.log(`[${message.metadata?.subAgentName}]`, message.parts); + } + ``` + + The same metadata also exists on live `fullStream` chunks, so you can keep the streaming UI and the historical memory explorer in sync. + +## 1.2.1 + +### Patch Changes + +- [`65e3317`](https://github.com/VoltAgent/voltagent/commit/65e331786645a124f16f06d08dfa55a675959bc8) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add tags support for tools + +## 1.2.0 + +### Minor Changes + +- [#761](https://github.com/VoltAgent/voltagent/pull/761) [`0d13b73`](https://github.com/VoltAgent/voltagent/commit/0d13b73db5e6d1d144229bda9657abb776fafab4) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add `onHandoffComplete` hook for early termination in supervisor/subagent workflows + + ## The Problem + + When using the supervisor/subagent pattern, subagents **always** return to the supervisor for processing, even when they generate final outputs (like JSON structures or reports) that need no additional handling. This causes unnecessary token consumption. + + **Current flow**: + + ``` + Supervisor → SubAgent (generates 2K token JSON) → Supervisor (processes JSON) → User + ↑ Wastes ~2K tokens + ``` + + **Example impact**: + - Current: ~2,650 tokens per request + - With bail: ~560 tokens per request + - Savings: **79%** (~2,000 tokens / ~$0.020 per request) + + ## The Solution + + Added `onHandoffComplete` hook that allows supervisors to intercept subagent results and optionally **bail** (skip supervisor processing) when the subagent produces final output. + + **New flow**: + + ``` + Supervisor → SubAgent → bail() → User ✅ + ``` + + ## API + + The hook receives a `bail()` function that can be called to terminate early: + + ```typescript + const supervisor = new Agent({ + name: "Workout Supervisor", + subAgents: [exerciseAgent, workoutBuilder], + hooks: { + onHandoffComplete: async ({ agent, result, bail, context }) => { + // Workout Builder produces final JSON - no processing needed + if (agent.name === "Workout Builder") { + context.logger?.info("Final output received, bailing"); + bail(); // Skip supervisor, return directly to user + return; } - return { - analysisResults: data, - originalData: state.input.rawData, - }; - }, - }) - .andAgent( - async (data, state) => { - return `Process these insights: ${JSON.stringify(data.analysisResults.insights)}`; - }, - processorAgent, - { - schema: z.object({ - summary: z.string(), - keyPoints: z.array(z.string()), - }), - } - ) - .andAgent( - async (data, state) => { - return `Generate a final report based on: ${JSON.stringify(data)}`; - }, - reporterAgent, - { - schema: z.object({ - finalReport: z.string(), - }), - } - ) - .andThen({ - execute: async (data, state) => { - return { - ...data, - processingTime: Date.now() - state.startAt.getTime(), - }; - }, - }); - // Execute workflow - const result = await dataProcessingWorkflow.run({ - rawData: "User input data...", - analysisType: "sentiment", + // Large result - bail to save tokens + if (result.length > 2000) { + context.logger?.warn("Large result, bailing to save tokens"); + bail(); + return; + } + + // Transform and bail + if (agent.name === "Report Generator") { + const transformed = `# Final Report\n\n${result}\n\n---\nGenerated at: ${new Date().toISOString()}`; + bail(transformed); // Bail with transformed result + return; + } + + // Default: continue to supervisor for processing + }, + }, }); + ``` - console.log(result.analysisResults); // Analysis results - console.log(result.finalReport); // Generated report + ## Hook Arguments + + ```typescript + interface OnHandoffCompleteHookArgs { + agent: Agent; // Target agent (subagent) + sourceAgent: Agent; // Source agent (supervisor) + result: string; // Subagent's output + messages: UIMessage[]; // Full conversation messages + usage?: UsageInfo; // Token usage info + context: OperationContext; // Operation context + bail: (transformedResult?: string) => void; // Call to bail + } ``` - **Conditional Logic Example:** + ## Features + - ✅ **Clean API**: No return value needed, just call `bail()` + - ✅ **True early termination**: Supervisor execution stops immediately, no LLM calls wasted + - ✅ **Conditional bail**: Decide based on agent, result content, size, etc. + - ✅ **Optional transformation**: `bail(newResult)` to transform before bailing + - ✅ **Observability**: Automatic logging and OpenTelemetry events with visual indicators + - ✅ **Backward compatible**: Existing code works without changes + - ✅ **Error handling**: Hook errors logged, flow continues normally + + ## How Bail Works (Implementation Details) + + When `bail()` is called in the `onHandoffComplete` hook: + + **1. Hook Level** (`packages/core/src/agent/subagent/index.ts`): + - Sets `bailed: true` flag in handoff return value + - Adds OpenTelemetry span attributes to both supervisor and subagent spans + - Logs the bail event with metadata + + **2. Tool Level** (`delegate_task` tool): + - Includes `bailed: true` in tool result structure + - Adds note: "One or more subagents produced final output. No further processing needed." + + **3. Step Handler Level** (`createStepHandler` in `agent.ts`): + - Detects bail during step execution when tool results arrive + - Creates `BailError` and aborts execution via `abortController.abort(bailError)` + - Stores bailed result in `systemContext` for retrieval + - **Works for both `generateText` and `streamText`** + + **4. Catch Block Level** (method-specific handling): + - **generateText**: Catches `BailError`, retrieves bailed result from `systemContext`, applies guardrails, calls hooks, returns as successful generation + - **streamText**: `onError` catches `BailError` gracefully (not logged as error), `onFinish` retrieves and uses bailed result + + This unified abort-based implementation ensures true early termination for all generation methods. + + ### Stream Support (NEW) + + **For `streamText` supervisors:** + + When a subagent bails during streaming, the supervisor stream is immediately aborted using a `BailError`: + 1. **Detection during streaming** (`createStepHandler`): + - Tool results are checked in `onStepFinish` handler + - If `bailed: true` found, `BailError` is created and stream is aborted via `abortController.abort(bailError)` + - Bailed result stored in `systemContext` for retrieval in `onFinish` + 2. **Graceful error handling** (`streamText` onError): + - `BailError` is detected and handled gracefully (not logged as error) + - Error hooks are NOT called for bail + - Stream abort is treated as successful early termination + 3. **Final result** (`streamText` onFinish): + - Bailed result retrieved from `systemContext` + - Output guardrails applied to bailed result + - `onEnd` hook called with bailed result + + **Benefits for streaming:** + - ✅ Stream stops immediately when bail detected (no wasted supervisor chunks) + - ✅ No unnecessary LLM calls after bail + - ✅ Works with `fullStreamEventForwarding` - subagent chunks already forwarded + - ✅ Clean abort semantic with `BailError` class + - ✅ Graceful handling - not treated as error + + **Supported methods:** + - ✅ `generateText` - Aborts execution during step handler, catches `BailError` and returns bailed result + - ✅ `streamText` - Aborts stream during step handler, handles `BailError` in `onError` and `onFinish` + - ❌ `generateObject` - No tool support, bail not applicable + - ❌ `streamObject` - No tool support, bail not applicable + + **Key difference from initial implementation:** + - ❌ **OLD**: Post-execution check in `generateText` (after AI SDK completes) - redundant + - ✅ **NEW**: Unified abort mechanism in `createStepHandler` - works for both methods, stops execution immediately + + ## Use Cases + + Perfect for scenarios where specialized subagents generate final outputs: + 1. **JSON/Structured data generators**: Workout builders, report generators + 2. **Large content producers**: Document creators, data exports + 3. **Token optimization**: Skip processing for expensive results + 4. **Business logic**: Conditional routing based on result characteristics + + ## Observability + + When bail occurs, both logging and OpenTelemetry tracking provide full visibility: + + **Logging:** + - Log event: `Supervisor bailed after handoff` + - Includes: supervisor name, subagent name, result length, transformation status + + **OpenTelemetry:** + - Span event: `supervisor.handoff.bailed` (for timeline events) + - Span attributes added to **both supervisor and subagent spans**: + - `bailed`: `true` + - `bail.supervisor`: supervisor agent name (on subagent span) + - `bail.subagent`: subagent name (on supervisor span) + - `bail.transformed`: `true` if result was transformed + + **Console Visualization:** + Bailed subagents are visually distinct in the observability react-flow view: + - Purple border with shadow (`border-purple-500 shadow-purple-600/50`) + - "⚡ BAILED" badge in the header (shows "⚡ BAILED (T)" if transformed) + - Tooltip showing which supervisor initiated the bail + - Node opacity remains at 1.0 (fully visible) + - Status badge shows "BAILED" with purple styling instead of error + - Details panel shows "Early Termination" info section with supervisor info + + ## Type Safety Improvements + + Also improved type safety by replacing `usage?: any` with proper `UsageInfo` type: ```typescript - const conditionalWorkflow = createWorkflowChain({ - id: "conditional-workflow", - name: "Smart Processing Pipeline", - purpose: "Process data based on complexity level", - input: z.object({ - data: z.string(), + export type UsageInfo = { + promptTokens: number; + completionTokens: number; + totalTokens: number; + cachedInputTokens?: number; + reasoningTokens?: number; + }; + ``` + + This provides: + - ✅ Better autocomplete in IDEs + - ✅ Compile-time type checking + - ✅ Clear documentation of available fields + + ## Breaking Changes + + None - this is a purely additive feature. The `UsageInfo` type structure is fully compatible with existing code. + +### Patch Changes + +- [#754](https://github.com/VoltAgent/voltagent/pull/754) [`c80d18f`](https://github.com/VoltAgent/voltagent/commit/c80d18f344ee37c16f52495edb88c72f74701610) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: encapsulate tool-specific metadata in toolContext + prevent AI SDK context collision + + ## Changes + + ### 1. Tool Context Encapsulation + + Tool-specific metadata now organized under optional `toolContext` field for better separation and future-proofing. + + **Migration:** + + ```typescript + // Before + execute: async ({ location }, options) => { + // Fields were flat (planned, not released) + }; + + // After + execute: async ({ location }, options) => { + const { name, callId, messages, abortSignal } = options?.toolContext || {}; + + // Session context remains flat + const userId = options?.userId; + const logger = options?.logger; + const context = options?.context; + }; + ``` + + ### 2. AI SDK Context Field Protection + + Explicitly exclude `context` from being spread into AI SDK calls to prevent future naming collisions if AI SDK renames `experimental_context` → `context`. + + ## Benefits + - ✅ Better organization - tool metadata in one place + - ✅ Clearer separation - session context vs tool context + - ✅ Future-proof - easy to add new tool metadata fields + - ✅ Namespace safety - no collision with OperationContext or AI SDK fields + - ✅ Backward compatible - `toolContext` is optional for external callers (MCP servers) + - ✅ Protected from AI SDK breaking changes + +- [#754](https://github.com/VoltAgent/voltagent/pull/754) [`c80d18f`](https://github.com/VoltAgent/voltagent/commit/c80d18f344ee37c16f52495edb88c72f74701610) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add multi-modal tool results support with toModelOutput - #722 + + Tools can now return images, media, and rich content to AI models using the `toModelOutput` function. + + ## The Problem + + AI agents couldn't receive visual information from tools - everything had to be text or JSON. This limited use cases like: + - Computer use agents that need to see screenshots + - Image analysis workflows + - Visual debugging tools + - Any tool that produces media output + + ## The Solution + + Added `toModelOutput?: (output) => ToolResultOutput` to tool options. This function transforms your tool's output into a format the AI model can understand, including images and media. + + ```typescript + import { createTool } from "@voltagent/core"; + import fs from "fs"; + + const screenshotTool = createTool({ + name: "take_screenshot", + description: "Takes a screenshot of the screen", + parameters: z.object({ + region: z.string().optional().describe("Region to capture"), }), - result: z.object({ - complexity: z.string(), - processedData: z.string(), - processingMethod: z.string(), + execute: async ({ region }) => { + const imageData = fs.readFileSync("./screenshot.png").toString("base64"); + return { + type: "image", + data: imageData, + timestamp: new Date().toISOString(), + }; + }, + toModelOutput: (result) => ({ + type: "content", + value: [ + { type: "text", text: `Screenshot captured at ${result.timestamp}` }, + { type: "media", data: result.data, mediaType: "image/png" }, + ], }), - }) - .andAgent( - async (data) => { - return `Analyze complexity of: ${data.data}`; - }, - validatorAgent, - { - schema: z.object({ - complexity: z.enum(["low", "medium", "high"]), - }), - } - ) - .andThen({ - execute: async (data, state) => { - // Route to different processing based on complexity - if (data.complexity === "low") { - return { ...data, processingMethod: "simple" }; - } else { - return { ...data, processingMethod: "advanced" }; - } - }, - }) - .andAgent( - async (data, state) => { - if (data.processingMethod === "simple") { - return `Simple processing for: ${state.input.data}`; - } else { - return `Advanced processing for: ${state.input.data}`; - } - }, - data.processingMethod === "simple" ? simpleProcessor : advancedProcessor, - { - schema: z.object({ - processedData: z.string(), - }), - } - ); + }); ``` - **⚠️ Alpha Limitations:** - - **NOT READY FOR PRODUCTION** - This is an experimental feature - - Visual flow UI integration is in development - - Error handling and recovery mechanisms are basic - - Performance optimizations pending - - **API may change significantly** based on community feedback - - Limited documentation and examples + ## Return Formats + + The `toModelOutput` function can return multiple formats: + + **Text output:** + + ```typescript + toModelOutput: (result) => ({ + type: "text", + value: result.summary, + }); + ``` + + **JSON output:** + + ```typescript + toModelOutput: (result) => ({ + type: "json", + value: { status: "success", data: result }, + }); + ``` + + **Multi-modal content (text + media):** + + ```typescript + toModelOutput: (result) => ({ + type: "content", + value: [ + { type: "text", text: "Analysis complete" }, + { type: "media", data: result.imageBase64, mediaType: "image/png" }, + ], + }); + ``` + + **Error handling:** + + ```typescript + toModelOutput: (result) => ({ + type: "error-text", + value: result.errorMessage, + }); + ``` + + ## Impact + - **Visual AI Workflows**: Build computer use agents that can see and interact with UIs + - **Image Generation**: Tools can return generated images directly to the model + - **Debugging**: Return screenshots and visual debugging information + - **Rich Responses**: Combine text explanations with visual evidence + + ## Usage with Anthropic + + ```typescript + const agent = createAgent({ + name: "visual-assistant", + tools: [screenshotTool], + model: anthropic("claude-3-5-sonnet-20241022"), + }); + + const result = await agent.generateText({ + prompt: "Take a screenshot and describe what you see", + }); + // Agent receives both text and image, can analyze the screenshot + ``` + + See [AI SDK documentation](https://sdk.vercel.ai/docs/ai-sdk-core/tools-and-tool-calling#multi-modal-tool-results) for more details on multi-modal tool results. + +- [#754](https://github.com/VoltAgent/voltagent/pull/754) [`c80d18f`](https://github.com/VoltAgent/voltagent/commit/c80d18f344ee37c16f52495edb88c72f74701610) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add providerOptions support to tools for provider-specific features - #759 + + Tools can now accept `providerOptions` to enable provider-specific features like Anthropic's cache control. This aligns VoltAgent tools with the AI SDK's tool API. + + ## The Problem + + Users wanted to use provider-specific features like Anthropic's prompt caching to reduce costs and latency, but VoltAgent's `createTool()` didn't support the `providerOptions` field that AI SDK tools have. + + ## The Solution + + **What Changed:** + - Added `providerOptions?: ProviderOptions` field to `ToolOptions` type + - VoltAgent tools now accept and pass through provider options to the AI SDK + - Supports all provider-specific features: cache control, reasoning settings, etc. + + **What Gets Enabled:** + + ```typescript + import { createTool } from "@voltagent/core"; + import { z } from "zod"; + + const cityAttractionsTool = createTool({ + name: "get_city_attractions", + description: "Get tourist attractions for a city", + parameters: z.object({ + city: z.string().describe("The city name"), + }), + providerOptions: { + anthropic: { + cacheControl: { type: "ephemeral" }, + }, + }, + execute: async ({ city }) => { + return await fetchAttractions(city); + }, + }); + ``` + + ## Impact + - **Cost Optimization:** Anthropic cache control reduces API costs for repeated tool calls + - **Future-Proof:** Any new provider features work automatically + - **Type-Safe:** Uses official AI SDK `ProviderOptions` type + - **Zero Breaking Changes:** Optional field, fully backward compatible + + ## Usage + + Use with any provider that supports provider-specific options: + + ```typescript + const agent = new Agent({ + name: "Travel Assistant", + model: anthropic("claude-3-5-sonnet"), + tools: [cityAttractionsTool], // Tool with cacheControl enabled + }); + + await agent.generateText("What are the top attractions in Paris?"); + // Tool definition cached by Anthropic for improved performance + ``` + + Learn more: [Anthropic Cache Control](https://ai-sdk.dev/providers/ai-sdk-providers/anthropic#cache-control) + +## 1.1.39 + +### Patch Changes + +- [#757](https://github.com/VoltAgent/voltagent/pull/757) [`a0509c4`](https://github.com/VoltAgent/voltagent/commit/a0509c493b85619c7eafb2eebd2257c348868133) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: evals & guardrails observability issue + +## 1.1.38 + +### Patch Changes + +- [#744](https://github.com/VoltAgent/voltagent/pull/744) [`e9e467a`](https://github.com/VoltAgent/voltagent/commit/e9e467a433a0fe0ba14f56554fc65fccce1cb888) Thanks [@marinoska](https://github.com/marinoska)! - Refactor ToolManager into hierarchical architecture with BaseToolManager and ToolkitManager + + Introduces new class hierarchy for improved tool management: + - **BaseToolManager**: Abstract base class with core tool management functionality + - **ToolManager**: Main manager supporting standalone tools, provider tools, and toolkits + - **ToolkitManager**: Specialized manager for toolkit-scoped tools (no nested toolkits) + + Features: + - Enhanced type-safe tool categorization with type guards + - Conflict detection for toolkit tools + - Reorganized tool preparation process - moved `prepareToolsForExecution` logic from agent into ToolManager, simplifying agent code + + Public API remains compatible. + +- [#752](https://github.com/VoltAgent/voltagent/pull/752) [`002ebad`](https://github.com/VoltAgent/voltagent/commit/002ebad1e95a82998c1693b3998b683d5bb04bb2) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: forward AI SDK tool call metadata (including `toolCallId`) to server-side tool executions - #746 + + Tool wrappers now receive the full options object from the AI SDK, so custom tools and hook listeners can access `toolCallId`, abort signals, and other metadata. We also propagate the real call id to OpenTelemetry spans. Existing tools keep working (the extra argument is optional), but they can now inspect the third `options` parameter if they need richer context. + +## 1.1.37 + +### Patch Changes + +- [#740](https://github.com/VoltAgent/voltagent/pull/740) [`bac1f49`](https://github.com/VoltAgent/voltagent/commit/bac1f4992e3841b940c5d5bce4474c63257dbe63) Thanks [@marinoska](https://github.com/marinoska)! - Stable fix for the providerMetadata openai entries normalization bug: https://github.com/VoltAgent/voltagent/issues/718 + +- [#738](https://github.com/VoltAgent/voltagent/pull/738) [`d3ed347`](https://github.com/VoltAgent/voltagent/commit/d3ed347e064cb36e04ed1ea98d9305b63fd968ec) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: persist workflow execution timeline events to prevent data loss after completion - #647 + + ## The Problem + + When workflows executed, their timeline events (step-start, step-complete, workflow-complete, etc.) were only visible during streaming. Once the workflow completed, the WebSocket state update would replace the execution object without the events field, causing the timeline UI to reset and lose all execution history. Users couldn't see what happened in completed or suspended workflows. + + **Symptoms:** + - Timeline showed events during execution + - Timeline cleared/reset when workflow completed + - No execution history for completed workflows + - Events were lost after browser refresh + + ## The Solution + + **Backend (Framework)**: + - Added `events`, `output`, and `cancellation` fields to `WorkflowStateEntry` interface + - Modified workflow execution to collect all stream events in memory during execution + - Persist collected events to workflow state when workflow completes, suspends, fails, or is cancelled + - Updated all storage adapters to support the new fields: + - **LibSQL**: Added schema columns + automatic migration method (`addWorkflowStateColumns`) + - **Supabase**: Added schema columns + migration detection + ALTER TABLE migration SQL + - **Postgres**: Added schema columns + INSERT/UPDATE queries + - **In-Memory**: Automatically supported via TypeScript interface + + **Frontend (Console)**: + - Updated `WorkflowPlaygroundProvider` to include events when converting `WorkflowStateEntry` → `WorkflowHistoryEntry` + - Implemented smart merge strategy for WebSocket updates: Use backend persisted events when workflow finishes, keep streaming events during execution + - Events are now preserved across page refreshes and always visible in timeline UI + + ## What Gets Persisted + + ```typescript + // In WorkflowStateEntry (stored in Memory V2): + { + "events": [ + { + "id": "evt_123", + "type": "workflow-start", + "name": "Workflow Started", + "startTime": "2025-01-24T10:00:00Z", + "status": "running", + "input": { "userId": "123" } + }, + { + "id": "evt_124", + "type": "step-complete", + "name": "Step: fetch-user", + "startTime": "2025-01-24T10:00:01Z", + "endTime": "2025-01-24T10:00:02Z", + "status": "success", + "output": { "user": { "name": "John" } } + } + ], + "output": { "result": "success" }, + "cancellation": { + "cancelledAt": "2025-01-24T10:00:05Z", + "reason": "User requested cancellation" + } + } + ``` + + ## Migration Guide + + ### LibSQL Users + + No action required - migrations run automatically on next initialization. + + ### Supabase Users + + When you upgrade and initialize the adapter, you'll see migration SQL in the console. Run it in your Supabase SQL Editor: + + ```sql + -- Add workflow event persistence columns + ALTER TABLE voltagent_workflow_states + ADD COLUMN IF NOT EXISTS events JSONB; + + ALTER TABLE voltagent_workflow_states + ADD COLUMN IF NOT EXISTS output JSONB; + + ALTER TABLE voltagent_workflow_states + ADD COLUMN IF NOT EXISTS cancellation JSONB; + ``` + + ### Postgres Users + + No action required - migrations run automatically on next initialization. + + ### In-Memory Users + + No action required - automatically supported. + + ### VoltAgent Managed Memory Users + + No action required - migrations run automatically on first request per managed memory database after API deployment. The API has been updated to: + - Include new columns in ManagedMemoryProvisioner CREATE TABLE statements (new databases) + - Run automatic column addition migration for existing databases (lazy migration on first request) + - Update PostgreSQL memory adapter to persist and retrieve events, output, and cancellation fields + + **Zero-downtime deployment:** Existing managed memory databases will be migrated lazily when first accessed after the API update. + + ## Impact + - ✅ Workflow execution timeline is now persistent and survives completion + - ✅ Full execution history visible for completed, suspended, and failed workflows + - ✅ Events, output, and cancellation metadata preserved in database + - ✅ Console UI timeline works consistently across all workflow states + - ✅ All storage backends (LibSQL, Supabase, Postgres, In-Memory) behave consistently + - ✅ No data loss on workflow completion or page refresh + +- [#743](https://github.com/VoltAgent/voltagent/pull/743) [`55e3555`](https://github.com/VoltAgent/voltagent/commit/55e3555ab912a37e2028270f707824b9c88a8cb2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add OperationContext support to Memory adapters for dynamic runtime behavior + + ## The Problem + + Memory adapters (InMemory, PostgreSQL, custom) had fixed configuration at instantiation time. Users couldn't: + 1. Pass different memory limits per `generateText()` call (e.g., 10 messages for quick responses, 100 for summaries) + 2. Access agent execution context (logger, tracing, abort signals) within memory operations + 3. Implement context-aware memory behavior without modifying adapter configuration + + ## The Solution + + **Framework (VoltAgent Core):** + - Added optional `context?: OperationContext` parameter to all `StorageAdapter` methods + - Memory adapters now receive full agent execution context including: + - `context.context` - User-provided key-value map for dynamic parameters + - `context.logger` - Contextual logger for debugging + - `context.traceContext` - OpenTelemetry tracing integration + - `context.abortController` - Cancellation support + - `userId`, `conversationId`, and other operation metadata + + **Type Safety:** + - Replaced `any` types with proper `OperationContext` type + - No circular dependencies (type-only imports) + - Full IDE autocomplete support + + ## Usage Example + + ### Dynamic Memory Limits + + ```typescript + import { Agent, Memory, InMemoryStorageAdapter } from "@voltagent/core"; + import type { OperationContext } from "@voltagent/core/agent"; + + class DynamicMemoryAdapter extends InMemoryStorageAdapter { + async getMessages( + userId: string, + conversationId: string, + options?: GetMessagesOptions, + context?: OperationContext + ): Promise { + // Extract dynamic limit from context + const dynamicLimit = context?.context.get("memoryLimit") as number; + return super.getMessages( + userId, + conversationId, + { + ...options, + limit: dynamicLimit || options?.limit || 10, + }, + context + ); + } + } + + const agent = new Agent({ + memory: new Memory({ storage: new DynamicMemoryAdapter() }), + }); + + // Short context for quick queries + await agent.generateText("Quick question", { + context: new Map([["memoryLimit", 5]]), + }); + + // Long context for detailed analysis + await agent.generateText("Summarize everything", { + context: new Map([["memoryLimit", 100]]), + }); + ``` + + ### Access Logger and Tracing + + ```typescript + class ObservableMemoryAdapter extends InMemoryStorageAdapter { + async getMessages(...args, context?: OperationContext) { + context?.logger.debug("Fetching messages", { + traceId: context.traceContext.getTraceId(), + userId: args[0], + }); + return super.getMessages(...args, context); + } + } + ``` + + ## Impact + - ✅ **Dynamic behavior per request** without changing adapter configuration + - ✅ **Full observability** - Access to logger, tracing, and operation metadata + - ✅ **Type-safe** - Proper TypeScript types with IDE autocomplete + - ✅ **Backward compatible** - Context parameter is optional + - ✅ **Extensible** - Custom adapters can implement context-aware logic + + ## Breaking Changes + + None - the `context` parameter is optional on all methods. + +## 1.1.36 + +### Patch Changes + +- [#736](https://github.com/VoltAgent/voltagent/pull/736) [`348bda0`](https://github.com/VoltAgent/voltagent/commit/348bda0f0fffdcbd75c8a6aa2c2d8bd15195cd22) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: respect configured log levels for console output while sending all logs to OpenTelemetry - #646 + + ## The Problem + + When users configured a custom logger with a specific log level (e.g., `level: "error"`), DEBUG and INFO logs were still appearing in console output, cluttering the development environment. This happened because: + 1. `LoggerProxy` was forwarding all log calls to the underlying logger without checking the configured level + 2. Multiple components (agents, workflows, retrievers, memory adapters, observability) were logging at DEBUG level unconditionally + 3. OpenTelemetry logs were also being filtered by the same level, preventing observability platforms from receiving all logs + + ## The Solution + + **Framework Changes:** + - Updated `LoggerProxy` to check configured log level before forwarding to console/stdout + - Added `shouldLog(level)` method that inspects the underlying logger's level (supports both Pino and ConsoleLogger) + - Separated console output filtering from OpenTelemetry emission: + - **Console/stdout**: Respects configured level (error level → only shows error/fatal) + - **OpenTelemetry**: Always receives all logs (debug, info, warn, error, fatal) + + **What Gets Fixed:** + + ```typescript + const logger = createPinoLogger({ level: "error" }); + + logger.debug("Agent created"); + // Console: ❌ Hidden (keeps dev environment clean) + // OpenTelemetry: ✅ Sent (full observability) + + logger.error("Generation failed"); + // Console: ✅ Shown (important errors visible) + // OpenTelemetry: ✅ Sent (full observability) + ``` + + ## Impact + - **Cleaner Development**: Console output now respects configured log levels + - **Full Observability**: OpenTelemetry platforms receive all logs regardless of console level + - **Better Debugging**: Debug/trace logs available in observability tools even in production + - **No Breaking Changes**: Existing code works as-is with improved behavior + + ## Usage + + No code changes needed - the fix applies automatically: + + ```typescript + // Create logger with error level + const logger = createPinoLogger({ + level: "error", + name: "my-app", + }); + + // Use it with VoltAgent + new VoltAgent({ + agents: { myAgent }, + logger, // Console will be clean, OpenTelemetry gets everything + }); + ``` + + ## Migration Notes + + If you were working around this issue by: + - Filtering console output manually + - Using different loggers for different components + - Avoiding debug logs altogether + + You can now remove those workarounds and use a single logger with your preferred console level while maintaining full observability. + +## 1.1.35 + +### Patch Changes + +- [#730](https://github.com/VoltAgent/voltagent/pull/730) [`1244b3e`](https://github.com/VoltAgent/voltagent/commit/1244b3eef1c1d1feea8e7a3934556782200a760e) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add finish reason and max steps observability to agent execution traces - #721 + + ## The Problem + + When agents hit the maximum steps limit (via `maxSteps` or `stopWhen` conditions), execution would terminate abruptly without clear indication in observability traces. This created confusion as: + 1. The AI SDK's `finishReason` (e.g., `stop`, `tool-calls`, `length`, `error`) was not being captured in OpenTelemetry spans + 2. MaxSteps termination looked like a normal completion with `finishReason: "tool-calls"` + 3. Users couldn't easily debug why their agent stopped executing + + ## The Solution + + **Framework (VoltAgent Core):** + - Added `setFinishReason(finishReason: string)` method to `AgentTraceContext` to capture AI SDK finish reasons in OpenTelemetry spans as `ai.response.finish_reason` attribute + - Added `setStopConditionMet(stepCount: number, maxSteps: number)` method to track when maxSteps limit is reached + - Updated `agent.generateText()` and `agent.streamText()` to automatically record: + - `ai.response.finish_reason` - The AI SDK finish reason (`stop`, `tool-calls`, `length`, `error`, etc.) + - `voltagent.stopped_by_max_steps` - Boolean flag when maxSteps is reached + - `voltagent.step_count` - Actual number of steps executed + - `voltagent.max_steps` - The maxSteps limit that was configured + + **What Gets Captured:** + + ```typescript + // In OpenTelemetry spans: + { + "ai.response.finish_reason": "tool-calls", + "voltagent.stopped_by_max_steps": true, + "voltagent.step_count": 10, + "voltagent.max_steps": 10 + } + ``` + + ## Impact + - **Better Debugging:** Users can now clearly see why their agent execution terminated + - **Observability:** All AI SDK finish reasons are now visible in traces + - **MaxSteps Detection:** Explicit tracking when agents hit step limits + - **Console UI Ready:** These attributes power warning UI in VoltOps Console to alert users when maxSteps is reached + + ## Usage + + No code changes needed - this is automatically tracked for all agent executions: + + ```typescript + const agent = new Agent({ + name: "my-agent", + maxSteps: 5, // Will be tracked in spans + }); + + await agent.generateText("Hello"); + // Span will include ai.response.finish_reason and maxSteps metadata + ``` + +## 1.1.34 + +### Patch Changes + +- [#727](https://github.com/VoltAgent/voltagent/pull/727) [`59da0b5`](https://github.com/VoltAgent/voltagent/commit/59da0b587cd72ff6065fa7fde9fcaecf0a92d830) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add agent.toTool() for converting agents into tools + + Agents can now be converted to tools using the `.toTool()` method, enabling multi-agent coordination where one agent uses other specialized agents as tools. This is useful when the LLM should dynamically decide which agents to call based on the request. + + ## Usage Example + + ```typescript + import { Agent } from "@voltagent/core"; + import { openai } from "@ai-sdk/openai"; + + // Create specialized agents + const writerAgent = new Agent({ + id: "writer", + purpose: "Writes blog posts", + model: openai("gpt-4o-mini"), + }); + + const editorAgent = new Agent({ + id: "editor", + purpose: "Edits content", + model: openai("gpt-4o-mini"), + }); + + // Coordinator uses them as tools + const coordinator = new Agent({ + tools: [writerAgent.toTool(), editorAgent.toTool()], + model: openai("gpt-4o-mini"), + }); + + // LLM decides which agents to call + await coordinator.generateText("Create a blog post about AI"); + ``` + + ## Key Features + - **Dynamic agent selection**: LLM intelligently chooses which agents to invoke + - **Composable agents**: Reuse agents as building blocks across multiple coordinators + - **Type-safe**: Full TypeScript support with automatic type inference + - **Context preservation**: Automatically passes through userId, conversationId, and operation context + - **Customizable**: Optional custom name, description, and parameter schema + + ## Customization + + ```typescript + const customTool = agent.toTool({ + name: "professional_writer", + description: "Writes professional blog posts", + parametersSchema: z.object({ + topic: z.string(), + style: z.enum(["formal", "casual"]), + }), + }); + ``` + + ## When to Use + - **Use `agent.toTool()`** when the LLM should decide which agents to call (e.g., customer support routing) + - **Use Workflows** for deterministic, code-defined pipelines (e.g., always: Step A → Step B → Step C) + - **Use Sub-agents** for fixed sets of collaborating agents + + See the [documentation](https://docs.voltagent.ai/agents) and [`examples/with-agent-tool`](https://github.com/VoltAgent/voltagent/tree/main/examples/with-agent-tool) for more details. + +## 1.1.33 + +### Patch Changes + +- [#724](https://github.com/VoltAgent/voltagent/pull/724) [`efe4be6`](https://github.com/VoltAgent/voltagent/commit/efe4be634f52aaef00d6b188a9146b1ad00b5968) Thanks [@marinoska](https://github.com/marinoska)! - Temporary fix for providerMetadata bug: https://github.com/vercel/ai/pull/9756 + +## 1.1.32 + +### Patch Changes + +- [#719](https://github.com/VoltAgent/voltagent/pull/719) [`3a1d214`](https://github.com/VoltAgent/voltagent/commit/3a1d214790cf49c5020eac3e9155a6daab2ff1db) Thanks [@marinoska](https://github.com/marinoska)! - Strip providerMetadata from text parts before calling convertToModelMessages to prevent invalid providerOptions in the resulting ModelMessage[]. + +## 1.1.31 + +### Patch Changes + +- [#711](https://github.com/VoltAgent/voltagent/pull/711) [`461ecec`](https://github.com/VoltAgent/voltagent/commit/461ecec60aa90b56a413713070b6e9f43efbd74b) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: sanitize stored assistant/tool messages so GPT-5 conversations no longer crash with "missing reasoning item" errors when replaying memory history + + fixes: + - #706 + +## 1.1.30 + +### Patch Changes + +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` +- Updated dependencies [[`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e)]: + - @voltagent/internal@0.0.12 + +## 1.1.29 + +### Patch Changes + +- [`d5170ce`](https://github.com/VoltAgent/voltagent/commit/d5170ced80fbc9fd2de03bb7eaff1cb31424d618) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add runtime payload support for evals + +## 1.1.28 + +### Patch Changes + +- [#688](https://github.com/VoltAgent/voltagent/pull/688) [`5b9484f`](https://github.com/VoltAgent/voltagent/commit/5b9484f1c6643fd8a8d2547be640ccd296ef2266) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add guardrails - #677 + + ## Guardrails overview + - streamText/generateText now run guardrails through a dedicated pipeline + - streaming handlers can redact or drop chunks in-flight + - final handlers see the original and sanitized text + provider metadata + - guardrail spans inherit the guardrail name so VoltOps shows human-readable labels + - helper factories: createSensitiveNumberGuardrail, createEmailRedactorGuardrail, createPhoneNumberGuardrail, createProfanityGuardrail, createMaxLengthGuardrail, createDefaultPIIGuardrails, createDefaultSafetyGuardrails + + ### Usage + + ```ts + import { Agent } from "@voltagent/core"; + import { openai } from "@ai-sdk/openai"; + import { createSensitiveNumberGuardrail, createDefaultSafetyGuardrails } from "@voltagent/core"; + + const agent = new Agent({ + name: "Guarded Assistant", + instructions: "Answer without leaking PII.", + model: openai("gpt-4o-mini"), + outputGuardrails: [ + createSensitiveNumberGuardrail(), + createDefaultSafetyGuardrails({ maxLength: { maxCharacters: 400 } }), + ], + }); + + const response = await agent.streamText("Customer card 4242 4242 1234 5678"); + console.log(await response.text); // Sanitized output with digits redacted + length capped + ``` + +## 1.1.27 + +### Patch Changes + +- [#674](https://github.com/VoltAgent/voltagent/pull/674) [`5aa84b5`](https://github.com/VoltAgent/voltagent/commit/5aa84b5bcf57d19bbe33cc791f0892c96bb3944b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add live evals + +- [#674](https://github.com/VoltAgent/voltagent/pull/674) [`5aa84b5`](https://github.com/VoltAgent/voltagent/commit/5aa84b5bcf57d19bbe33cc791f0892c96bb3944b) Thanks [@omeraplak](https://github.com/omeraplak)! - ## What Changed + + Removed automatic message pruning functionality from all storage adapters (PostgreSQL, Supabase, LibSQL, and InMemory). Previously, messages were automatically deleted when the count exceeded `storageLimit` (default: 100 messages per conversation). + + ## Why This Change + + Users reported unexpected data loss when their conversation history exceeded the storage limit. Many users expect their conversation history to be preserved indefinitely rather than automatically deleted. This change gives users full control over their data retention policies. + + ## Migration Guide + + ### Before + + ```ts + const memory = new Memory({ + storage: new PostgreSQLMemoryAdapter({ + connection: process.env.DATABASE_URL, + storageLimit: 200, // Messages auto-deleted after 200 + }), + }); + ``` + + ### After + + ```ts + const memory = new Memory({ + storage: new PostgreSQLMemoryAdapter({ + connection: process.env.DATABASE_URL, + // No storageLimit - all messages preserved + }), + }); + ``` + + ### If You Need Message Cleanup + + Implement your own cleanup logic using the `clearMessages()` method: + + ```ts + // Clear all messages for a conversation + await memory.clearMessages(userId, conversationId); + + // Clear all messages for a user + await memory.clearMessages(userId); + ``` + + ## Affected Packages + - `@voltagent/core` - Removed `storageLimit` from types + - `@voltagent/postgres` - Removed from PostgreSQL adapter + - `@voltagent/supabase` - Removed from Supabase adapter + - `@voltagent/libsql` - Removed from LibSQL adapter + + ## Impact + - ✅ No more unexpected data loss + - ✅ Users have full control over message retention + - ⚠️ Databases may grow larger over time (consider implementing manual cleanup) + - ⚠️ Breaking change: `storageLimit` parameter no longer accepted + +## 1.1.26 + +### Patch Changes + +- [#654](https://github.com/VoltAgent/voltagent/pull/654) [`78b9727`](https://github.com/VoltAgent/voltagent/commit/78b9727e85a31fd8eaa9c333de373d982f58b04f) Thanks [@VISHWAJ33T](https://github.com/VISHWAJ33T)! - feat(workflow): Improve typing for state parameter in steps. + +- [#669](https://github.com/VoltAgent/voltagent/pull/669) [`6d00793`](https://github.com/VoltAgent/voltagent/commit/6d007938d31c6d928185153834661c50227af326) Thanks [@marinoska](https://github.com/marinoska)! - Fix duplicate tool registration during agent preparation. + +- [#663](https://github.com/VoltAgent/voltagent/pull/663) [`7fef3a7`](https://github.com/VoltAgent/voltagent/commit/7fef3a7ea1b3f7f8c780a528d3c3abce312f3be9) Thanks [@VISHWAJ33T](https://github.com/VISHWAJ33T)! - feat(workflow): add support for dynamic schemas in agent steps + +- [#659](https://github.com/VoltAgent/voltagent/pull/659) [`c4d13f2`](https://github.com/VoltAgent/voltagent/commit/c4d13f2be129013eed6392990863ae85cdbd8855) Thanks [@marinoska](https://github.com/marinoska)! - Add first-class support for client-side tool calls and Vercel AI hooks integration. + + This enables tools to run in the browser (no execute function) while the model remains on the server. Tool calls are surfaced to the client via Vercel AI hooks (useChat/useAssistant), executed with access to browser APIs, and their results are sent back to the model using addToolResult with the original toolCallId. + + Highlights: + - Define a client-side tool by omitting the execute function. + - Automatic interception of tool calls on the client via onToolCall in useChat/useAssistant. + - Report outputs and errors back to the model via addToolResult(toolCallId, payload), preserving conversation state. + - Example added/updated: examples/with-client-side-tools (Next.js + Vercel AI). + + Docs: + - README: Clarifies client-side tool support and where it fits in the stack. + - website/docs/agents/tools.md: New/updated “Client-Side Tools” section, end-to-end flow with useChat/useAssistant, addToolResult usage, and error handling. + +## 1.1.25 + +### Patch Changes + +- [#648](https://github.com/VoltAgent/voltagent/pull/648) [`882480d`](https://github.com/VoltAgent/voltagent/commit/882480debb10575d16e9752b9fead136fe6a7050) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add input and output to OperationContext for improved observability + + ## What Changed + + Added `input` and `output` fields to `OperationContext`, making them accessible throughout the agent's execution lifecycle. + + ## New Fields in OperationContext + + ```typescript + export type OperationContext = { + // ... existing fields + + /** Input provided to the agent operation (string, UIMessages, or BaseMessages) */ + input?: string | UIMessage[] | BaseMessage[]; + + /** Output generated by the agent operation (text or object) */ + output?: string | object; + }; + ``` + + ## Usage in Tools and Hooks + + ```typescript + // Access input and output in tools + const myTool = createTool({ + name: "exampleTool", + parameters: z.object({}), + async execute(args, context) { + // Access the original input + console.log("Original input:", context.input); + + return { status: "ok" }; + }, + }); + + // Access in hooks + const agent = new Agent({ + hooks: { + onEnd: async ({ context }) => { + // Both input and output are available + console.log("Input:", context.input); + console.log("Output:", context.output); + }, + }, + }); + ``` + + ## Why This Matters + - **Better Debugging**: Tools and hooks can now see both the original input and final output + - **Enhanced Observability**: Full context available for logging and monitoring + - **Consistent with Tracing**: Aligns with how AgentTraceContext already handles input/output for OpenTelemetry + - **No Breaking Changes**: Existing code continues to work; these are new optional fields + +## 1.1.24 + +### Patch Changes + +- [#641](https://github.com/VoltAgent/voltagent/pull/641) [`4c42bf7`](https://github.com/VoltAgent/voltagent/commit/4c42bf72834d3cd45ff5246ef65d7b08470d6a8e) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: introduce managed memory - ready-made cloud storage for VoltAgent + + ## What Changed for You + + VoltAgent now offers a managed memory solution that eliminates the need to run your own database infrastructure. The new `@voltagent/voltagent-memory` package provides a `ManagedMemoryAdapter` that connects to VoltOps Managed Memory service, perfect for pilots, demos, and production workloads. + + ## New Package: @voltagent/voltagent-memory + + ### Automatic Setup (Recommended) + + Get your credentials from [console.voltagent.dev/memory/managed-memory](https://console.voltagent.dev/memory/managed-memory) and set environment variables: + + ```bash + # .env + VOLTAGENT_PUBLIC_KEY=pk_... + VOLTAGENT_SECRET_KEY=sk_... + ``` + + ```typescript + import { Agent, Memory } from "@voltagent/core"; + import { ManagedMemoryAdapter } from "@voltagent/voltagent-memory"; + import { openai } from "@ai-sdk/openai"; + + // Adapter automatically uses VoltOps credentials from environment + const agent = new Agent({ + name: "Assistant", + instructions: "You are a helpful assistant", + model: openai("gpt-4o-mini"), + memory: new Memory({ + storage: new ManagedMemoryAdapter({ + databaseName: "production-memory", + }), + }), + }); + + // Use like any other agent - memory is automatically persisted + const result = await agent.generateText("Hello!", { + userId: "user-123", + conversationId: "conv-456", + }); + ``` + + ### Manual Setup + + Pass a `VoltOpsClient` instance explicitly: + + ```typescript + import { Agent, Memory, VoltOpsClient } from "@voltagent/core"; + import { ManagedMemoryAdapter } from "@voltagent/voltagent-memory"; + import { openai } from "@ai-sdk/openai"; + + const voltOpsClient = new VoltOpsClient({ + publicKey: process.env.VOLTAGENT_PUBLIC_KEY!, + secretKey: process.env.VOLTAGENT_SECRET_KEY!, + }); + + const agent = new Agent({ + name: "Assistant", + instructions: "You are a helpful assistant", + model: openai("gpt-4o-mini"), + memory: new Memory({ + storage: new ManagedMemoryAdapter({ + databaseName: "production-memory", + voltOpsClient, // explicit client + }), + }), + }); + ``` + + ### Vector Storage (Optional) + + Enable semantic search with `ManagedMemoryVectorAdapter`: + + ```typescript + import { ManagedMemoryAdapter, ManagedMemoryVectorAdapter } from "@voltagent/voltagent-memory"; + import { AiSdkEmbeddingAdapter, Memory } from "@voltagent/core"; + import { openai } from "@ai-sdk/openai"; + + const memory = new Memory({ + storage: new ManagedMemoryAdapter({ + databaseName: "production-memory", + }), + embedding: new AiSdkEmbeddingAdapter(openai.embedding("text-embedding-3-small")), + vector: new ManagedMemoryVectorAdapter({ + databaseName: "production-memory", + }), + }); + ``` + + ## Key Features + - **Zero Infrastructure**: No need to provision or manage databases + - **Quick Setup**: Create a managed memory database in under 3 minutes from VoltOps Console + - **Framework Parity**: Works identically to local Postgres, LibSQL, or Supabase adapters + - **Production Ready**: Managed infrastructure with reliability guardrails + - **Multi-Region**: Available in US (Virginia) and EU (Germany) + + ## Getting Started + 1. **Install the package**: + + ```bash + npm install @voltagent/voltagent-memory + # or + pnpm add @voltagent/voltagent-memory + ``` + + 2. **Create a managed database**: + - Navigate to [console.voltagent.dev/memory/managed-memory](https://console.voltagent.dev/memory/managed-memory) + - Click **Create Database** + - Enter a name and select region (US or EU) + - Copy your VoltOps API keys from Settings + 3. **Configure environment variables**: + + ```bash + VOLTAGENT_PUBLIC_KEY=pk_... + VOLTAGENT_SECRET_KEY=sk_... + ``` + + 4. **Use the adapter**: + + ```typescript + import { ManagedMemoryAdapter } from "@voltagent/voltagent-memory"; + import { Memory } from "@voltagent/core"; + + const memory = new Memory({ + storage: new ManagedMemoryAdapter({ + databaseName: "your-database-name", + }), + }); + ``` + + ## Why This Matters + - **Faster Prototyping**: Launch pilots without database setup + - **Reduced Complexity**: No infrastructure management overhead + - **Consistent Experience**: Same StorageAdapter interface across all memory providers + - **Scalable Path**: Start with managed memory, migrate to self-hosted when needed + - **Multi-Region Support**: Deploy close to your users in US or EU + + ## Migration Notes + + Existing agents using local storage adapters (InMemory, LibSQL, Postgres, Supabase) continue to work unchanged. Managed memory is an optional addition that provides a cloud-hosted alternative for teams who prefer not to manage their own database infrastructure. + +- [#637](https://github.com/VoltAgent/voltagent/pull/637) [`b7ee693`](https://github.com/VoltAgent/voltagent/commit/b7ee6936280b5d09b893db6500ad58b4ac80eaf2) Thanks [@marinoska](https://github.com/marinoska)! - - Introduced tests and documentation for the `ToolDeniedError`. + - Added a feature to terminate the process flow when the `onToolStart` hook triggers a `ToolDeniedError`. + - Enhanced error handling mechanisms to ensure proper flow termination in specific error scenarios. + +## 1.1.23 + +### Patch Changes + +- [#632](https://github.com/VoltAgent/voltagent/pull/632) [`9bd1cf5`](https://github.com/VoltAgent/voltagent/commit/9bd1cf5ab0b0ff54f2bc301a40a486b36d76c3f4) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: ensure agents expose their default in-memory storage so observability APIs can read it + fix: keep tool call inputs intact when persisted so VoltOps observability shows them instead of empty payloads + +## 1.1.22 + +### Patch Changes + +- [#629](https://github.com/VoltAgent/voltagent/pull/629) [`3e64b9c`](https://github.com/VoltAgent/voltagent/commit/3e64b9ce58d0e91bc272f491be2c1932a005ef48) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add memory observability + +## 1.1.21 + +### Patch Changes + +- [#625](https://github.com/VoltAgent/voltagent/pull/625) [`ec76c47`](https://github.com/VoltAgent/voltagent/commit/ec76c47a9533fd4bcf9ffd22153e3d99248f00fa) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add `onPrepareModelMessages` hook + - ensure `onPrepareMessages` now receives the sanitized UI payload while exposing `rawMessages` for audit or metadata recovery without sending it to the LLM. + - introduce `onPrepareModelMessages` so developers can tweak the final provider-facing message array (e.g. add guardrails, adapt to provider quirks) after conversion. + + ```ts + const hooks = createHooks({ + onPrepareMessages: ({ messages, rawMessages }) => ({ + messages: messages.map((msg) => + messageHelpers.addTimestampToMessage(msg, new Date().toISOString()) + ), + rawMessages, // still available for logging/analytics + }), + onPrepareModelMessages: ({ modelMessages }) => ({ + modelMessages: modelMessages.map((message, idx) => + idx === modelMessages.length - 1 && message.role === "assistant" + ? { + ...message, + content: [ + ...message.content, + { type: "text", text: "Please keep the summary under 200 words." }, + ], + } + : message + ), + }), + }); + ``` + +- [#625](https://github.com/VoltAgent/voltagent/pull/625) [`ec76c47`](https://github.com/VoltAgent/voltagent/commit/ec76c47a9533fd4bcf9ffd22153e3d99248f00fa) Thanks [@omeraplak](https://github.com/omeraplak)! - - preserve Anthropic-compatible providerOptions on system messages - #593 + + ```ts + const agent = new Agent({ + name: "Cacheable System", + model: anthropic("claude-3-7-sonnet-20250219"), + instructions: { + type: "chat", + messages: [ + { + role: "system", + content: "remember to use cached context", + providerOptions: { + anthropic: { cacheControl: { type: "ephemeral", ttl: "5m" } }, + }, + }, + ], + }, + }); + + await agent.generateText("ping"); // providerOptions now flow through unchanged + ``` + +- [#623](https://github.com/VoltAgent/voltagent/pull/623) [`0d91d90`](https://github.com/VoltAgent/voltagent/commit/0d91d9081381a6c259188209cd708293271e5e3e) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: allow constructing `VoltAgent` without passing an `agents` map so workflows-only setups boot without boilerplate. + +## 1.1.20 + +### Patch Changes + +- [#621](https://github.com/VoltAgent/voltagent/pull/621) [`f4fa7e2`](https://github.com/VoltAgent/voltagent/commit/f4fa7e297fec2f602c9a24a0c77e645aa971f2b9) Thanks [@omeraplak](https://github.com/omeraplak)! - ## @voltagent/core + - Folded the serverless runtime entry point into the main build – importing `@voltagent/core` now auto-detects the runtime and provisions either the Node or serverless observability pipeline. + - Rebuilt serverless observability on top of `BasicTracerProvider`, fetch-based OTLP exporters, and an execution-context `waitUntil` hook. Exports run with exponential backoff, never block the response, and automatically reuse VoltOps credentials (or fall back to the in-memory span/log store) so VoltOps Console transparently swaps to HTTP polling when WebSockets are unavailable. + - Hardened the runtime utilities for Workers/Functions: added universal `randomUUID`, base64, and event-emitter helpers, and taught the default logger to emit OpenTelemetry logs without relying on Node globals. This removes the last Node-only dependencies from the serverless bundle. + + ```ts + import { Agent, VoltAgent } from "@voltagent/core"; + import { serverlessHono } from "@voltagent/serverless-hono"; + import { openai } from "@ai-sdk/openai"; + + import { weatherTool } from "./tools"; + + const assistant = new Agent({ + name: "serverless-assistant", + instructions: "You are a helpful assistant.", + model: openai("gpt-4o-mini"), + }); + + const voltAgent = new VoltAgent({ + agents: { assistant }, + serverless: serverlessHono(), + }); + + export default voltAgent.serverless().toCloudflareWorker(); + ``` + + ## @voltagent/serverless-hono + - Renamed the edge provider to **serverless** and upgraded it to power any fetch-based runtime (Cloudflare Workers, Vercel Edge Functions, Deno Deploy, Netlify Functions). + - Wrapped the Cloudflare adapter in a first-class `HonoServerlessProvider` that installs a scoped `waitUntil` bridge, reuses the shared routing layer, and exposes a `/ws` health stub so VoltOps Console can cleanly fall back to polling. + - Dropped the manual environment merge – Workers should now enable the `nodejs_compat_populate_process_env` flag (documented in the new deployment guide) instead of calling `mergeProcessEnv` themselves. + + ## @voltagent/server-core + - Reworked the observability handlers around the shared storage API, including a new `POST /setup-observability` helper that writes VoltOps keys into `.env` and expanded trace/log queries that match the serverless storage contract. + + ## @voltagent/cli + - Added `volt deploy --target ` to scaffold the right config files. The Cloudflare template now ships with the required compatibility flags (`nodejs_compat`, `nodejs_compat_populate_process_env`, `no_handle_cross_request_promise_resolution`) so new projects run on Workers without extra tweaking. + +- [#620](https://github.com/VoltAgent/voltagent/pull/620) [`415cc82`](https://github.com/VoltAgent/voltagent/commit/415cc822938e5cc1e925438ad21e88f4295984c1) Thanks [@marinoska](https://github.com/marinoska)! - Workflows can be streamed directly into `useChat` by converting raw events + (`workflow-start`, `workflow-complete`, etc.) into `data-*` UI messages via + `toUIMessageStreamResponse`. + + Related to #589 + +## 1.1.19 + +### Patch Changes + +- [#617](https://github.com/VoltAgent/voltagent/pull/617) [`02a78af`](https://github.com/VoltAgent/voltagent/commit/02a78afed1870fe00968a60f44db912df7fbabe6) Thanks [@omeraplak](https://github.com/omeraplak)! - - preserve raw UI messages in storage, sanitize only before LLM invocation + +## 1.1.18 + +### Patch Changes + +- [`8a99f4f`](https://github.com/VoltAgent/voltagent/commit/8a99f4fb9365da3b80a0d4e5b6df4bd50ac19288) Thanks [@omeraplak](https://github.com/omeraplak)! - - refine message normalization and persistence pipeline + - rely on AI SDK reasoning metadata directly + - drop synthetic tool-result injection and trust AI SDK stream output + +- [`bbd6c17`](https://github.com/VoltAgent/voltagent/commit/bbd6c176b2bed532a4f03b5f8f7011806aa746c2) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: reasoning parts - #614 + +## 1.1.17 + +### Patch Changes + +- [`78b2298`](https://github.com/VoltAgent/voltagent/commit/78b2298c561e86bbef61f783b0fee83667c25d8a) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: `tool_use` ids were found without `tool_result` blocks immediately after + +## 1.1.16 + +### Patch Changes + +- [#609](https://github.com/VoltAgent/voltagent/pull/609) [`942663f`](https://github.com/VoltAgent/voltagent/commit/942663f74dca0df70cdac323102acb18c050fa65) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add workflow cancellation support, including cancellation metadata, default controller updates, and a new API endpoint for cancelling executions - #608 + + ## Usage Example + + ```ts + import { createSuspendController } from "@voltagent/core"; + + const controller = createSuspendController(); + const stream = workflow.stream(input, { suspendController: controller }); + + // Cancel from application code + controller.cancel("User stopped the workflow"); + + // Or via HTTP + await fetch(`/api/workflows/${workflowId}/executions/${executionId}/cancel`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ reason: "User stopped the workflow" }), + }); + ``` + +## 1.1.15 + +### Patch Changes + +- [#602](https://github.com/VoltAgent/voltagent/pull/602) [`14932b6`](https://github.com/VoltAgent/voltagent/commit/14932b69cce36abefcea2200e912bc2614216e1f) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: only process VoltAgent spans by default and expose spanFilters config + +## 1.1.14 + +### Patch Changes + +- [#598](https://github.com/VoltAgent/voltagent/pull/598) [`783d334`](https://github.com/VoltAgent/voltagent/commit/783d334a1d9252eb227ef2e1d69d3e939765a13f) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve workflow stream text-delta empty output and improve type safety + + ## The Problem + + When forwarding agent.streamText() results to workflow streams via writer.pipeFrom(), text-delta events had empty output fields. This was caused by incorrect field mapping - the code was accessing `part.textDelta` but AI SDK v5 uses `part.text` for text-delta events. + + ## The Solution + + Fixed field mappings to match AI SDK v5 conventions: + - text-delta: `textDelta` → `text` + - tool-call: `args` → `input` + - tool-result: `result` → `output` + - finish: `usage` → `totalUsage` + + Also improved type safety by: + - Using `VoltAgentTextStreamPart` type instead of `any` for fullStream parameter + - Proper type guards with `in` operator to check field existence + - Eliminated need for `as any` casts + + ## Impact + - Fixes "output field is undefined" for text-delta events in workflow streams + - Provides proper TypeScript type checking for stream parts + - Ensures compatibility with AI SDK v5 field conventions + - Better IDE support and compile-time error detection + +- [#600](https://github.com/VoltAgent/voltagent/pull/600) [`31ded11`](https://github.com/VoltAgent/voltagent/commit/31ded113253dd73c28a797f185b2ea0595160cf7) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: add missing export `MCPConfiguration` + +## 1.1.13 + +### Patch Changes + +- [#596](https://github.com/VoltAgent/voltagent/pull/596) [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7) Thanks [@omeraplak](https://github.com/omeraplak)! - - add `@voltagent/a2a-server`, a JSON-RPC Agent-to-Agent (A2A) server that lets external agents call your VoltAgent instance over HTTP/SSE + - teach `@voltagent/core`, `@voltagent/server-core`, and `@voltagent/server-hono` to auto-register configured A2A servers so adding `{ a2aServers: { ... } }` on `VoltAgent` and opting into `honoServer` instantly exposes discovery and RPC endpoints + - forward request context (`userId`, `sessionId`, metadata) into agent invocations and provide task management hooks, plus allow filtering/augmenting exposed agents by default + - document the setup in `website/docs/agents/a2a/a2a-server.md` and refresh `examples/with-a2a-server` with basic usage and task-store customization + - A2A endpoints are now described in Swagger/OpenAPI and listed in the startup banner whenever an A2A server is registered, making discovery of `/.well-known/...` and `/a2a/:serverId` routes trivial. + + **Getting started** + + ```ts + import { Agent, VoltAgent } from "@voltagent/core"; + import { A2AServer } from "@voltagent/a2a-server"; + import { honoServer } from "@voltagent/server-hono"; + + const assistant = new Agent({ + name: "SupportAgent", + purpose: "Handle support questions from partner agents.", + model: myModel, + }); + + const a2aServer = new A2AServer({ + name: "support-agent", + version: "0.1.0", + }); + + export const voltAgent = new VoltAgent({ + agents: { assistant }, + a2aServers: { a2aServer }, + server: honoServer({ port: 3141 }), + }); + ``` + +- [#596](https://github.com/VoltAgent/voltagent/pull/596) [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7) Thanks [@omeraplak](https://github.com/omeraplak)! - ## ✨ New: first-class Model Context Protocol support + + We shipped a complete MCP integration stack: + - `@voltagent/mcp-server` exposes VoltAgent registries (agents, workflows, tools) over stdio/HTTP/SSE transports. + - `@voltagent/server-core` and `@voltagent/server-hono` gained ready-made route handlers so HTTP servers can proxy MCP traffic with a few lines of glue code. + - `@voltagent/core` exports the shared types that the MCP layers rely on. + + ### Quick start + + ```ts title="src/mcp/server.ts" + import { MCPServer } from "@voltagent/mcp-server"; + import { Agent, createTool } from "@voltagent/core"; + import { openai } from "@ai-sdk/openai"; + import { z } from "zod"; + + const status = createTool({ + name: "status", + description: "Return the current time", + parameters: z.object({}), + async execute() { + return { status: "ok", time: new Date().toISOString() }; + }, + }); + + const assistant = new Agent({ + name: "Support Agent", + instructions: "Route customer tickets to the correct queue.", + model: openai("gpt-4o-mini"), + tools: [status], + }); + + export const mcpServer = new MCPServer({ + name: "voltagent-example", + version: "0.1.0", + description: "Expose VoltAgent over MCP", + agents: { support: assistant }, + tools: { status }, + filterTools: ({ items }) => items.filter((tool) => tool.name !== "debug"), + }); + ``` + + With the server registered on your VoltAgent instance (and the Hono MCP routes enabled), the same agents, workflows, and tools become discoverable from VoltOps Console or any MCP-compatible IDE. + +- [#596](https://github.com/VoltAgent/voltagent/pull/596) [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7) Thanks [@omeraplak](https://github.com/omeraplak)! - - Ship `@voltagent/mcp-server`, a transport-agnostic MCP provider that surfaces VoltAgent agents, workflows, tools, prompts, and resources over stdio, SSE, and HTTP. + - Wire MCP registration through `@voltagent/core`, `@voltagent/server-core`, and `@voltagent/server-hono` so a single `VoltAgent` constructor opt-in (optionally with `honoServer`) exposes stdio mode immediately and HTTP/SSE endpoints when desired. + - Filter child sub-agents automatically and lift an agent's `purpose` (fallback to `instructions`) into the MCP tool description for cleaner IDE listings out of the box. + - Document the workflow in `website/docs/agents/mcp/mcp-server.md` and refresh `examples/with-mcp-server` with stdio-only and HTTP/SSE configurations. + - When MCP is enabled we now publish REST endpoints in Swagger/OpenAPI and echo them in the startup banner so you can discover `/mcp/*` routes without digging through code. + + **Getting started** + + ```ts + import { Agent, VoltAgent } from "@voltagent/core"; + import { MCPServer } from "@voltagent/mcp-server"; + import { honoServer } from "@voltagent/server-hono"; + + const assistant = new Agent({ + name: "AssistantAgent", + purpose: "Respond to support questions and invoke helper tools when needed.", + model: myModel, + }); + + const mcpServer = new MCPServer({ + name: "support-mcp", + version: "1.0.0", + agents: { assistant }, + protocols: { stdio: true, http: false, sse: false }, + }); + + export const voltAgent = new VoltAgent({ + agents: { assistant }, + mcpServers: { primary: mcpServer }, + server: honoServer({ port: 3141 }), // flip http/sse to true when you need remote clients + }); + ``` + +- Updated dependencies [[`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7), [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7)]: + - @voltagent/internal@0.0.11 + +## 1.1.12 + +### Patch Changes + +- [#590](https://github.com/VoltAgent/voltagent/pull/590) [`4292460`](https://github.com/VoltAgent/voltagent/commit/42924609b3fc72c918addba050d6f85e8e8712d8) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve Zod v4 compatibility issue in delegate_task tool schema + + Fixed a compatibility issue where `z.record(z.unknown())` in the delegate_task tool's context parameter was causing JSON schema generation errors with Zod v4. Changed to `z.record(z.string(), z.any())` which works correctly with both Zod v3 and v4. + + The error occurred when using the MCP server or other components that convert Zod schemas to JSON schemas: + + ``` + TypeError: Cannot read properties of undefined (reading '_zod') + ``` + + This fix ensures the delegate_task tool works seamlessly across all Zod versions supported by the framework (^3.25.0 || ^4.0.0). + +## 1.1.11 + +### Patch Changes + +- [#584](https://github.com/VoltAgent/voltagent/pull/584) [`00838b0`](https://github.com/VoltAgent/voltagent/commit/00838b0f4f75f03fad606589a6159121be0b40ba) Thanks [@omeraplak](https://github.com/omeraplak)! - refactor: add ConversationBuffer + MemoryPersistQueue so tool calls, results, and assistant text persist as a single step and flush on errors + +## 1.1.10 + +### Patch Changes + +- [`103c48c`](https://github.com/VoltAgent/voltagent/commit/103c48cb197e23fdedf61a4804f1a50c4ccdc655) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve UIMessage tool persistence issue causing OpenAI API errors and useChat display problems + + Fixed a critical issue where tool messages weren't being properly converted between UIMessage and ModelMessage formats, causing two problems: + 1. OpenAI API rejecting requests with "An assistant message with 'tool_calls' must be followed by tool messages" + 2. useChat hook showing tools as "working/running" despite having `state: "output-available"` + + ## The Problem + + When converting tool messages to UIMessages for persistence: + - Tool role messages were incorrectly having `providerExecuted: false` set + - This caused AI SDK's `convertToModelMessages` to misinterpret client-executed tools + - The conversion logic was not properly preserving the tool execution context + + ## The Solution + - Removed explicit `providerExecuted` assignments for tool role messages + - Tool role messages now correctly indicate client execution by omitting the flag + - Removed unnecessary `step-start` insertions that were added during message conversion + - Now exactly mimics AI SDK's UIMessage generation behavior + + ## Technical Details + + The `providerExecuted` flag determines how tools are converted: + - `providerExecuted: true` → tool results embedded in assistant message (provider-executed) + - `providerExecuted: undefined/false` → separate tool role messages (client-executed) + + By not setting this flag for tool role messages, the AI SDK correctly: + 1. Generates required tool messages after tool_calls (fixes OpenAI API error) + 2. Recognizes tools as completed rather than "working" (fixes useChat display) + +## 1.1.9 + +### Patch Changes + +- [#577](https://github.com/VoltAgent/voltagent/pull/577) [`749bbdf`](https://github.com/VoltAgent/voltagent/commit/749bbdfc12a42242ebc3b93e0fea5b439e5b84bf) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve subagent tool call/result pairing issue with Claude/Bedrock + + Fixed a critical issue where subagents performing tool calls would break the conversation flow with Claude/Bedrock models. The error "tool_use ids were found without tool_result blocks" occurred because the tool result messages were not being properly included when converting subagent responses to UI message streams. + + ## The Problem + + When a subagent executed a tool call, the parent agent would receive incomplete message history: + - Direct agents: Called `toUIMessageStream` with `sendStart: false` and `originalMessages`, which only included the initial task message + - StreamText configs: Called `toUIMessageStream` without any parameters + - Both approaches failed to include the complete tool call/result sequence + + ## The Solution + - Removed explicit parameters from `toUIMessageStream` calls in both direct agent and streamText configuration paths + - Let the AI SDK handle the default behavior for proper message inclusion + - This ensures tool_use and tool_result messages remain properly paired in the conversation + + ## Impact + - Fixes "No output generated" errors when subagents use tools + - Resolves conversation breakage after subagent tool calls + - Maintains proper message history for Claude/Bedrock compatibility + - No breaking changes - the fix simplifies the internal implementation + +## 1.1.8 + +### Patch Changes + +- [#573](https://github.com/VoltAgent/voltagent/pull/573) [`51cc774`](https://github.com/VoltAgent/voltagent/commit/51cc774445e5c4e676563b5576868ad45d8ecb9c) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve subagent tracing hierarchy and entity filtering + + ## What Changed + + Fixed OpenTelemetry span hierarchy issues where subagent spans were overriding parent delegate_task spans instead of being properly nested as children. Also resolved entity ID filtering returning incorrect traces for subagent queries. + + ## The Problem + + When a supervisor agent delegated tasks to subagents: + 1. **Span Hierarchy**: Subagent spans appeared to replace delegate_task spans instead of being children + 2. **Entity Filtering**: Querying by subagent entity ID (e.g., `entityId=Formatter`) incorrectly returned traces that should only be associated with the root agent (e.g., `entityId=Supervisor`) + + ## The Solution + + Implemented namespace-based attribute management in trace-context: + - **Root agents** use `entity.id`, `entity.type`, `entity.name` attributes + - **Subagents** use `subagent.id`, `subagent.name`, `subagent.type` namespace + - **Subagents inherit** parent's `entity.id` for correct trace association + - **Span naming** clearly identifies subagents with `subagent:AgentName` prefix + + ## Example + + ```typescript + // Before: Incorrect hierarchy and filtering + // delegate_task span seemed to disappear + // entityId=Formatter returned Supervisor's traces + + // After: Proper hierarchy and filtering + const supervisor = new Agent({ + name: "Supervisor", + subAgents: [formatter, writer], + }); + + // Trace structure now shows: + // - Supervisor (root span) + // - delegate_task: Formatter (tool span) + // - subagent:Formatter (subagent span with proper parent) + // - (formatter's tools and operations) + + // Filtering works correctly: + // entityId=Supervisor ✓ Returns supervisor traces + // entityId=Formatter ✗ Returns no traces (correct - Formatter is a subagent) + ``` + + ## Impact + - Proper parent-child relationships in span hierarchy + - Correct trace filtering by entity ID + - Clear distinction between root agents and subagents in observability data + - Better debugging experience with properly nested spans + +## 1.1.7 + +### Patch Changes + +- [#571](https://github.com/VoltAgent/voltagent/pull/571) [`b801a8d`](https://github.com/VoltAgent/voltagent/commit/b801a8da47da5cad15b8637635f83acab5e0d6fc) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Zod v4 support (backwards-compatible with v3) + + What’s new + - Core + server now support `zod` v4 while keeping v3 working. + - Peer ranges expanded to `"zod": "^3.25.0 || ^4.0.0"`. + - JSON Schema → Zod conversion handles both versions: + - Uses `zod-from-json-schema@^0.5.0` when Zod v4 is detected. + - Falls back to `zod-from-json-schema@^0.0.5` via alias `zod-from-json-schema-v3` for Zod v3. + - Implemented in MCP client (core) and object handlers (server-core). + + Why + - Zod v4 introduces changes that require a version-aware conversion path. This update adds seamless compatibility for both major versions. + + Impact + - No breaking changes. Projects on Zod v3 continue to work unchanged. Projects can upgrade to Zod v4 without code changes. + + Notes + - If your bundler disallows npm aliasing, ensure it can resolve `zod-from-json-schema-v3` (alias to `zod-from-json-schema@^0.0.5`). + +## 1.1.7-next.1 + +### Patch Changes + +- [`78a5046`](https://github.com/VoltAgent/voltagent/commit/78a5046ca4d768a96650ebee63ae1630b0dff7a7) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Zod v4 support (backwards-compatible with v3) + + What’s new + - Core + server now support `zod` v4 while keeping v3 working. + - Peer ranges expanded to `"zod": "^3.25.0 || ^4.0.0"`. + - JSON Schema → Zod conversion handles both versions: + - Uses `zod-from-json-schema@^0.5.0` when Zod v4 is detected. + - Falls back to `zod-from-json-schema@^0.0.5` via alias `zod-from-json-schema-v3` for Zod v3. + - Implemented in MCP client (core) and object handlers (server-core). + + Why + - Zod v4 introduces changes that require a version-aware conversion path. This update adds seamless compatibility for both major versions. + + Impact + - No breaking changes. Projects on Zod v3 continue to work unchanged. Projects can upgrade to Zod v4 without code changes. + + Notes + - If your bundler disallows npm aliasing, ensure it can resolve `zod-from-json-schema-v3` (alias to `zod-from-json-schema@^0.0.5`). + +## 1.1.7-next.0 + +### Patch Changes + +- [#551](https://github.com/VoltAgent/voltagent/pull/551) [`77a3f64`](https://github.com/VoltAgent/voltagent/commit/77a3f64dea6e8a06fbbd72878711efa9ceb90bc3) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Zod v4 support (backwards-compatible with v3) + + What’s new + - Core + server now support `zod` v4 while keeping v3 working. + - Peer ranges expanded to `"zod": "^3.25.0 || ^4.0.0"`. + - JSON Schema → Zod conversion handles both versions: + - Uses `zod-from-json-schema@^0.5.0` when Zod v4 is detected. + - Falls back to `zod-from-json-schema@^0.0.5` via alias `zod-from-json-schema-v3` for Zod v3. + - Implemented in MCP client (core) and object handlers (server-core). + + Why + - Zod v4 introduces changes that require a version-aware conversion path. This update adds seamless compatibility for both major versions. + + Impact + - No breaking changes. Projects on Zod v3 continue to work unchanged. Projects can upgrade to Zod v4 without code changes. + + Notes + - If your bundler disallows npm aliasing, ensure it can resolve `zod-from-json-schema-v3` (alias to `zod-from-json-schema@^0.0.5`). + +## 1.1.6 + +### Patch Changes + +- [#565](https://github.com/VoltAgent/voltagent/pull/565) [`b14d953`](https://github.com/VoltAgent/voltagent/commit/b14d95345f0bce653931ff27e5dac59e4750c123) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add experimental_output support for structured generation - #428 + + ## What Changed for You + + VoltAgent now supports ai-sdk v5's experimental structured output features! You can now generate type-safe structured data directly from your agents using Zod schemas. + + ## Features Added + - **`experimental_output`** for `generateText` - Get fully typed structured output + - **`experimental_partialOutputStream`** for `streamText` - Stream partial objects as they're being generated + + ## Using Structured Output with `generateText` + + ```typescript + import { Agent } from "@voltagent/core"; + import { Output } from "ai"; + import { z } from "zod"; + + // Define your schema + const RecipeSchema = z.object({ + name: z.string(), + ingredients: z.array(z.string()), + instructions: z.array(z.string()), + prepTime: z.number(), + cookTime: z.number(), + }); + + // Generate structured output + const result = await agent.generateText("Create a pasta recipe", { + experimental_output: Output.object({ + schema: RecipeSchema, + }), + }); + + // Access the typed object directly! + console.log(result.experimental_output); + // { + // name: "Creamy Garlic Pasta", + // ingredients: ["pasta", "garlic", "cream", ...], + // instructions: ["Boil water", "Cook pasta", ...], + // prepTime: 10, + // cookTime: 15 + // } + ``` + + ## Streaming Partial Objects with `streamText` + + ```typescript + // Stream partial objects as they're generated + const stream = await agent.streamText("Create a detailed recipe", { + experimental_output: Output.object({ + schema: RecipeSchema, + }), + }); + + // Access the partial object stream + for await (const partial of stream.experimental_partialOutputStream ?? []) { + console.log(partial); + // Partial objects that build up over time: + // { name: "Creamy..." } + // { name: "Creamy Garlic Pasta", ingredients: ["pasta"] } + // { name: "Creamy Garlic Pasta", ingredients: ["pasta", "garlic"] } + // ... until the full object is complete + } + ``` + + ## Text Mode for Constrained Output + + You can also use `Output.text()` for text generation with specific constraints: + + ```typescript + const result = await agent.generateText("Write a haiku", { + experimental_output: Output.text({ + maxLength: 100, + description: "A traditional haiku poem", + }), + }); + + console.log(result.experimental_output); // The generated haiku text + ``` + + ## Important Notes + - These are **experimental features** from ai-sdk v5 and may change + - TypeScript may show `experimental_output` as `any` due to type inference limitations + - `generateText` returns the complete structured output in `experimental_output` + - `streamText` provides partial objects via `experimental_partialOutputStream` + - Both features require importing `Output` from `@voltagent/core` (re-exported from ai-sdk) + + ## Why This Matters + - **Type-safe output** - No more parsing JSON strings and hoping for the best + - **Real-time streaming** - See structured data build up as it's generated + - **Zod validation** - Automatic validation against your schemas + - **Better DX** - Work with typed objects instead of unstructured text + +## 1.1.5 + +### Patch Changes + +- [#562](https://github.com/VoltAgent/voltagent/pull/562) [`2886b7a`](https://github.com/VoltAgent/voltagent/commit/2886b7aab5bda296cebc0b8b2bd56d684324d799) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: using `safeStringify` instead of `JSON.stringify` + +- [#561](https://github.com/VoltAgent/voltagent/pull/561) [`ca6a8ec`](https://github.com/VoltAgent/voltagent/commit/ca6a8ec9e45de4c262864e8819f45b1a83679592) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - chore: updated the underlying AgentError creation and types for improved upstream types & internal usage + +## 1.1.4 + +### Patch Changes + +- [#559](https://github.com/VoltAgent/voltagent/pull/559) [`134bf9a`](https://github.com/VoltAgent/voltagent/commit/134bf9a2978f0b069f842910fb4fb3e969f70390) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: add deps that the core types rely on, i.e. `type-fest` or they are not installed by default by package managers + +- [`a0d9e84`](https://github.com/VoltAgent/voltagent/commit/a0d9e8404fe3e2cebfc146cd4622b607bd16b462) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: @voltagent/logger dependency version + +- Updated dependencies [[`134bf9a`](https://github.com/VoltAgent/voltagent/commit/134bf9a2978f0b069f842910fb4fb3e969f70390)]: + - @voltagent/internal@0.0.10 + +## 1.1.3 + +### Patch Changes + +- [#557](https://github.com/VoltAgent/voltagent/pull/557) [`4c2919e`](https://github.com/VoltAgent/voltagent/commit/4c2919e9d531681d72586505174ff3d688666e2b) Thanks [@omeraplak](https://github.com/omeraplak)! - fix(core): preserve context Map instance across operations and subagents + + ## What Changed + - Reuse the same `context` Map instance instead of cloning it on every call. + - `createOperationContext` no longer creates a fresh `new Map(...)` for user or parent context; it reuses the incoming Map to keep state alive. + - All results now expose the same context reference: + - `generateText`, `streamText`, `generateObject`, `streamObject` return `{ context: oc.context }` instead of `new Map(oc.context)`. + - Subagents invoked via `delegate_task` receive and update the same shared context through `parentOperationContext`. + + ## Merge Precedence (no overwrites of parent) + + `parentOperationContext.context` > `options.context` > agent default context. Only missing keys are filled from lower-precedence sources; parent context values are not overridden. + + ## Why + + Previously, context was effectively reset by cloning on each call, which broke continuity and sharing across subagents. This fix ensures a single source of truth for context throughout an operation chain. + + ## Potential Impact + - If you relied on context being cloned (new Map identity per call), note that the instance is now shared. For isolation, pass `new Map(existingContext)` yourself when needed. + + ## Affected Files + - `packages/core/src/agent/agent.ts` (createOperationContext; return shapes for generate/stream methods) + +## 1.1.2 + +### Patch Changes + +- [#556](https://github.com/VoltAgent/voltagent/pull/556) [`3d3deb9`](https://github.com/VoltAgent/voltagent/commit/3d3deb98379066072392f29d08b43b431c0d3b9b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat(core): semantic memory defaults and retrieval fixes + + ## Summary + - Default `semanticMemory.mergeStrategy` is now `"append"` (previously `"prepend"`). + - Default `semanticMemory.semanticThreshold` is `0.7`. + - Fix: propagate `semanticMemory` options end‑to‑end (Agent → MemoryManager → Memory). + - Fix: preserve vector result order when mapping `messageIds` → `UIMessage`. + - Docs: updated Semantic Search/Overview to reflect new defaults. + - Examples: long conversation demo with optional real LLM seeding. + + ## Why + + Appending semantic hits after the recent context reduces stale facts overriding recent ones (e.g., old name "Ömer" overshadowing newer "Ahmet"). Preserving vector result order ensures the most relevant semantic hits remain in ranked order. + + ## Defaults + + When `userId` + `conversationId` are provided and vectors are configured: + - `enabled: true` + - `semanticLimit: 5` + - `semanticThreshold: 0.7` + - `mergeStrategy: "append"` + + ## Migration Notes + + If you relied on the previous default `mergeStrategy: "prepend"`, explicitly set: + + ```ts + await agent.generateText(input, { + userId, + conversationId, + semanticMemory: { mergeStrategy: "prepend" }, + }); + ``` + + Otherwise, no action is required. + +- [`9b08cff`](https://github.com/VoltAgent/voltagent/commit/9b08cff97c2e8616807a12e89bdbd3dceaf66d33) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: node:crypto import issue on workflow + +## 1.1.1 + +### Patch Changes + +- [#552](https://github.com/VoltAgent/voltagent/pull/552) [`89f3f37`](https://github.com/VoltAgent/voltagent/commit/89f3f373a4efe97875c725a9be8374ed31c5bf40) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve shutdown handlers to properly stop server and clean up resources - #528 + + ## What Changed + + Fixed the shutdown handler to properly stop the VoltAgent server and clean up all resources when receiving SIGINT/SIGTERM signals. This ensures the process can exit cleanly when multiple signal handlers exist from other frameworks. + + ## The Problem (Before) + + When multiple SIGINT/SIGTERM handlers existed (from frameworks like Adonis, NestJS, etc.), the VoltAgent server would remain open after shutdown, preventing the process from exiting cleanly. The previous fix only addressed the `process.exit()` issue but didn't actually stop the server. + + ## The Solution (After) + - **Server Cleanup**: The shutdown handler now properly stops the server using `stopServer()` + - **Telemetry Shutdown**: Added telemetry/observability shutdown for complete cleanup + - **Public API**: Added a new `shutdown()` method for programmatic cleanup + - **Resource Order**: Resources are cleaned up in the correct order: server → workflows → telemetry + - **Framework Compatibility**: Still respects other frameworks' handlers using `isSoleSignalHandler` check + + ## Usage + + ```typescript + // Programmatic shutdown (new) + const voltAgent = new VoltAgent({ agents, server }); + await voltAgent.shutdown(); // Cleanly stops server, workflows, and telemetry + + // Automatic cleanup on SIGINT/SIGTERM still works + // Server is now properly stopped, allowing the process to exit + ``` + + This ensures VoltAgent plays nicely with other frameworks while properly cleaning up all resources during shutdown. + +## 1.1.0 + +### Minor Changes + +- [#549](https://github.com/VoltAgent/voltagent/pull/549) [`63d4787`](https://github.com/VoltAgent/voltagent/commit/63d4787bd92135fa2d6edffb3b610889ddc0e3f5) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: ai sdk v5 ModelMessage support across Agent + Workflow; improved image/file handling and metadata preservation. + + What's new + - Agent I/O: `generateText`, `streamText`, `generateObject`, `streamObject` now accept `string | UIMessage[] | ModelMessage[]` (AI SDK v5) as input. No breaking changes for existing callers. + - Conversion layer: Robust `ModelMessage → UIMessage` handling with: + - Image support: `image` parts are mapped to UI `file` parts; URLs and `data:` URIs are preserved, raw/base64 strings become `data:;base64,...`. + - File support: string data is auto-detected as URL (`http(s)://`, `data:`) or base64; binary is encoded to data URI. + - Metadata: `providerOptions` on text/reasoning/image/file parts is preserved as `providerMetadata` on UI parts. + - Step boundaries: Inserts `step-start` after tool results when followed by assistant text. + - Workflow: `andAgent` step and `WorkflowInput` types now also accept `UIMessage[] | ModelMessage[]` in addition to `string`. + + Usage examples + 1. Agent with AI SDK v5 ModelMessage input (multimodal) + + ```ts + import type { ModelMessage } from "@ai-sdk/provider-utils"; + + const messages: ModelMessage[] = [ + { + role: "user", + content: [ + { type: "image", image: "https://example.com/cat.jpg", mediaType: "image/jpeg" }, + { type: "text", text: "What's in this picture?" }, + ], + }, + ]; + + const result = await agent.generateText(messages); + console.log(result.text); + ``` + + 2. Agent with UIMessage input + + ```ts + import type { UIMessage } from "ai"; + + const uiMessages: UIMessage[] = [ + { + id: crypto.randomUUID(), + role: "user", + parts: [ + { type: "file", url: "https://example.com/cat.jpg", mediaType: "image/jpeg" }, + { type: "text", text: "What's in this picture?" }, + ], + }, + ]; + + const result = await agent.generateText(uiMessages); + ``` + + 3. Provider metadata preservation (files/images) + + ```ts + import type { ModelMessage } from "@ai-sdk/provider-utils"; + + const msgs: ModelMessage[] = [ + { + role: "assistant", + content: [ + { + type: "file", + mediaType: "image/png", + data: "https://cdn.example.com/img.png", + providerOptions: { source: "cdn" }, + }, + ], + }, + ]; + + // Internally preserved as providerMetadata on the UI file part + await agent.generateText(msgs); + ``` + + 4. Workflow andAgent with ModelMessage[] or UIMessage[] + + ```ts + import { z } from "zod"; + import type { ModelMessage } from "@ai-sdk/provider-utils"; + + workflow + .andAgent( + ({ data }) => + [ + { + role: "user", + content: [{ type: "text", text: `Hello ${data.name}` }], + }, + ] as ModelMessage[], + agent, + { schema: z.object({ reply: z.string() }) } + ) + .andThen({ + id: "extract", + execute: async ({ data }) => data.reply, + }); + ``` + + Notes + - No breaking changes. Existing string/UIMessage inputs continue to work. + - Multimodal inputs are passed through correctly to the model after conversion. + +## 1.0.1 + +### Patch Changes + +- [#546](https://github.com/VoltAgent/voltagent/pull/546) [`f12f344`](https://github.com/VoltAgent/voltagent/commit/f12f34405edf0fcb417ed098deba62570260fb81) Thanks [@omeraplak](https://github.com/omeraplak)! - chore: align Zod to ^3.25.76 and fix type mismatch with AI SDK + + We aligned Zod versions across packages to `^3.25.76` to match AI SDK peer ranges and avoid multiple Zod instances at runtime. + + Why this matters + - Fixes TypeScript narrowing issues in workflows when consuming `@voltagent/core` from npm with a different Zod instance (e.g., `ai` packages pulling newer Zod). + - Prevents errors like "Spread types may only be created from object types" where `data` failed to narrow because `z.ZodTypeAny` checks saw different Zod identities. + + What changed + - `@voltagent/server-core`, `@voltagent/server-hono`: dependencies.zod → `^3.25.76`. + - `@voltagent/docs-mcp`, `@voltagent/core`: devDependencies.zod → `^3.25.76`. + - Examples and templates updated to use `^3.25.76` for consistency (non-publishable). + + Notes for consumers + - Ensure a single Zod version is installed (consider a workspace override to pin Zod to `3.25.76`). + - This improves compatibility with `ai@5.x` packages that require `zod@^3.25.76 || ^4`. + +## 1.0.0 + +### Major Changes + +- [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93) Thanks [@omeraplak](https://github.com/omeraplak)! - # Core 1.x — AI SDK native, Memory V2, pluggable server + + Breaking but simple to migrate. Key changes and copy‑paste examples below. + + Full migration guide: [Migration Guide](https://voltagent.dev/docs/getting-started/migration-guide/) + + ## Agent: remove `llm`, use ai‑sdk model directly + + Before (0.1.x): + + ```ts + import { Agent } from "@voltagent/core"; + import { VercelAIProvider } from "@voltagent/vercel-ai"; + import { openai } from "@ai-sdk/openai"; + + const agent = new Agent({ + name: "app", + instructions: "Helpful", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + ``` + + After (1.x): + + ```ts + import { Agent } from "@voltagent/core"; + import { openai } from "@ai-sdk/openai"; + + const agent = new Agent({ + name: "app", + instructions: "Helpful", + model: openai("gpt-4o-mini"), // ai-sdk native + }); + ``` + + Note: `@voltagent/core@1.x` has a peer dependency on `ai@^5`. Install `ai` and a provider like `@ai-sdk/openai`. + + ## Memory V2: use `Memory({ storage: })` + + Before (0.1.x): + + ```ts + import { LibSQLStorage } from "@voltagent/libsql"; + + const agent = new Agent({ + // ... + memory: new LibSQLStorage({ url: "file:./.voltagent/memory.db" }), + }); + ``` + + After (1.x): + + ```ts + import { Memory } from "@voltagent/core"; + import { LibSQLMemoryAdapter } from "@voltagent/libsql"; + + const agent = new Agent({ + // ... + memory: new Memory({ + storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }), + }), + }); + ``` + + Default memory is in‑memory when omitted. + + ## Server: moved out of core → use `@voltagent/server-hono` + + Before (0.1.x): + + ```ts + import { VoltAgent } from "@voltagent/core"; + + new VoltAgent({ agents: { agent }, port: 3141, enableSwaggerUI: true }); + ``` + + After (1.x): + + ```ts + import { VoltAgent } from "@voltagent/core"; + import { honoServer } from "@voltagent/server-hono"; + + new VoltAgent({ + agents: { agent }, + server: honoServer({ port: 3141, enableSwaggerUI: true }), + }); + ``` + + ## Abort: option renamed + + ```ts + // 0.1.x + await agent.generateText("...", { abortController: new AbortController() }); + + // 1.x + const ac = new AbortController(); + await agent.generateText("...", { abortSignal: ac.signal }); + ``` + + ## Observability: OTel‑based, zero code required + + Set keys and run: + + ```bash + VOLTAGENT_PUBLIC_KEY=pk_... VOLTAGENT_SECRET_KEY=sk_... + ``` + + Remote export auto‑enables when keys are present. Local Console streaming remains available. + +## 1.0.0-next.2 + +### Major Changes + +- [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93) Thanks [@omeraplak](https://github.com/omeraplak)! - # Core 1.x — AI SDK native, Memory V2, pluggable server + + Breaking but simple to migrate. Key changes and copy‑paste examples below. + + Full migration guide: [Migration Guide](https://voltagent.dev/docs/getting-started/migration-guide/) + + ## Agent: remove `llm`, use ai‑sdk model directly + + Before (0.1.x): + + ```ts + import { Agent } from "@voltagent/core"; + import { VercelAIProvider } from "@voltagent/vercel-ai"; + import { openai } from "@ai-sdk/openai"; + + const agent = new Agent({ + name: "app", + instructions: "Helpful", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + ``` + + After (1.x): + + ```ts + import { Agent } from "@voltagent/core"; + import { openai } from "@ai-sdk/openai"; + + const agent = new Agent({ + name: "app", + instructions: "Helpful", + model: openai("gpt-4o-mini"), // ai-sdk native + }); + ``` + + Note: `@voltagent/core@1.x` has a peer dependency on `ai@^5`. Install `ai` and a provider like `@ai-sdk/openai`. + + ## Memory V2: use `Memory({ storage: })` + + Before (0.1.x): + + ```ts + import { LibSQLStorage } from "@voltagent/libsql"; + + const agent = new Agent({ + // ... + memory: new LibSQLStorage({ url: "file:./.voltagent/memory.db" }), + }); + ``` + + After (1.x): + + ```ts + import { Memory } from "@voltagent/core"; + import { LibSQLMemoryAdapter } from "@voltagent/libsql"; + + const agent = new Agent({ + // ... + memory: new Memory({ + storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }), + }), + }); + ``` + + Default memory is in‑memory when omitted. + + ## Server: moved out of core → use `@voltagent/server-hono` + + Before (0.1.x): + + ```ts + import { VoltAgent } from "@voltagent/core"; + + new VoltAgent({ agents: { agent }, port: 3141, enableSwaggerUI: true }); + ``` + + After (1.x): + + ```ts + import { VoltAgent } from "@voltagent/core"; + import { honoServer } from "@voltagent/server-hono"; + + new VoltAgent({ + agents: { agent }, + server: honoServer({ port: 3141, enableSwaggerUI: true }), + }); + ``` + + ## Abort: option renamed + + ```ts + // 0.1.x + await agent.generateText("...", { abortController: new AbortController() }); + + // 1.x + const ac = new AbortController(); + await agent.generateText("...", { abortSignal: ac.signal }); + ``` + + ## Observability: OTel‑based, zero code required + + Set keys and run: + + ```bash + VOLTAGENT_PUBLIC_KEY=pk_... VOLTAGENT_SECRET_KEY=sk_... + ``` + + Remote export auto‑enables when keys are present. Local Console streaming remains available. + +### Patch Changes + +- Updated dependencies [[`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93)]: + - @voltagent/logger@1.0.0-next.0 + +## 1.0.0-next.1 + +### Major Changes + +- [#514](https://github.com/VoltAgent/voltagent/pull/514) [`e86cadb`](https://github.com/VoltAgent/voltagent/commit/e86cadb5ae9ee9719bfd1f12e7116d95224699ce) Thanks [@omeraplak](https://github.com/omeraplak)! - # Agent Class - AI SDK Native Integration + + The Agent class has been completely refactored to use AI SDK directly, removing the provider abstraction layer for better performance and simpler API. + + ## Breaking Changes + + ### Provider System Removed + + The Agent class no longer uses the provider abstraction. It now works directly with AI SDK's LanguageModel. + + **Before:** + + ```typescript + import { VercelAIProvider } from "@voltagent/vercel-ai"; + + const agent = new Agent({ + name: "assistant", + description: "You are a helpful assistant", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + ``` + + **After:** + + ```typescript + import { openai } from "@ai-sdk/openai"; + + const agent = new Agent({ + name: "assistant", + instructions: "You are a helpful assistant", // description -> instructions + model: openai("gpt-4o-mini"), + }); + ``` + + ### Description Field Removed + + The deprecated `description` field has been completely removed in favor of `instructions`. + + **Before:** + + ```typescript + const agent = new Agent({ + name: "assistant", + description: "You are a helpful assistant", // @deprecated + instructions: "You are a helpful assistant", // Had to use both + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + ``` + + **After:** + + ```typescript + const agent = new Agent({ + name: "assistant", + instructions: "You are a helpful assistant", // Only instructions now + model: openai("gpt-4o-mini"), + }); + ``` + + ### Context API Changes + + The context property has been renamed from `userContext` to `context` and can now accept plain objects. + + **Before:** + + ```typescript + // userContext only accepted Map + const agent = new Agent({ + userContext: new Map([["key", "value"]]), + }); + + await agent.generateText({ + input: "Hello", + userContext: new Map([["key", "value"]]), + }); + ``` + + **After:** + + ```typescript + // context accepts both Map and plain objects + const agent = new Agent({ + context: { key: "value" }, // Can be Map or plain object + }); + + await agent.generateText({ + input: "Hello", + context: { key: "value" }, // ContextInput type: Map or Record + }); + ``` + + ```ts + // New AgentContext structure used internally: + interface AgentContext { + context: Map; + operation: { + id: string; + userId?: string; + conversationId?: string; + parentAgentId?: string; + parentHistoryId?: string; + }; + system: { + logger: Logger; + signal?: AbortSignal; + startTime: string; + }; + } + ``` + + ### Hook System Simplified + + Hooks are now defined directly without createHooks wrapper. + + **Before:** + + ```typescript + import { createHooks } from "@voltagent/core"; + + const agent = new Agent({ + hooks: createHooks({ + onStart: async (context) => {}, + onEnd: async (context, result) => {}, + }), + }); + ``` + + **After:** + + ```ts + const agent = new Agent({ + hooks: { + onStart: async (context: AgentContext) => {}, + onEnd: async (context: AgentContext, result, error?) => {}, + onError: async (context: AgentContext, error) => {}, + onPrepareMessages: async (messages: UIMessage[], context) => { + // New hook for message preparation + return { messages }; + }, + onToolStart: async (context, tool) => {}, + onToolEnd: async (context, tool, output, error?) => {}, + }, + }); + ``` + + ### Method Signatures Now Use AI SDK Options + + All generation methods now accept AI SDK's CallSettings. + + **Before:** + + ```typescript + await agent.generateText({ + input: "Hello", + userId: "123", + conversationId: "conv-1", + provider: { + maxTokens: 1000, + temperature: 0.7, + }, + }); + ``` + + **After:** + + ```typescript + await agent.generateText({ + input: "Hello", + // VoltAgent specific + userId: "123", + conversationId: "conv-1", + context: { key: "value" }, + // AI SDK CallSettings + maxTokens: 1000, + temperature: 0.7, + topP: 0.9, + presencePenalty: 0.1, + frequencyPenalty: 0.1, + seed: 12345, + maxRetries: 3, + }); + ``` + + ### Message Format Changes + + Agent now accepts UIMessage format from AI SDK. + + **Before:** + + ```typescript + // BaseMessage format + await agent.generateText({ + input: [ + { role: "user", content: "Hello" }, + { role: "assistant", content: "Hi there!" }, + ], + }); + ``` + + **After:** + + ```typescript + // UIMessage format (AI SDK compatible) + await agent.generateText({ + input: [ + { + id: "1", + role: "user", + parts: [{ type: "text", text: "Hello" }], + }, + { + id: "2", + role: "assistant", + parts: [{ type: "text", text: "Hi there!" }], + }, + ], + }); + + // UIMessage structure from AI SDK: + interface UIMessage { + id: string; + role: "system" | "user" | "assistant"; + metadata?: unknown; // For custom data like createdAt + parts: Array; // text, tool, reasoning, etc. + } + ``` + + ## New Features + + ### Direct AI SDK Integration + - Better performance without abstraction overhead + - Access to all AI SDK features directly + - Simplified error handling + - Native streaming support + + ### Enhanced Type Safety + + ```typescript + // All methods now have proper generic types + const result = await agent.generateObject({ + input: "Generate user data", + schema: userSchema, + }); + // result.object is properly typed + ``` + + ### Streamlined API + + ```typescript + // All generation methods follow same pattern + const textResult = await agent.generateText(options); + const textStream = await agent.streamText(options); + const objectResult = await agent.generateObject(options); + const objectStream = await agent.streamObject(options); + ``` + + ## Migration Guide + + ### 1. Remove Deprecated Packages + + ```diff + - "@voltagent/vercel-ai": "^0.9.0", + - "@voltagent/vercel-ui": "^0.9.0", + - "@voltagent/xsai": "^0.9.0", + ``` + + ```bash + npm uninstall @voltagent/vercel-ai @voltagent/vercel-ui @voltagent/xsai + ``` + + ### 2. Install AI SDK Directly + + ```diff + + "ai": "^5.0.0", + + "@ai-sdk/openai": "^1.0.0", + + "@ai-sdk/anthropic": "^1.0.0", + ``` + + ```bash + npm install ai @ai-sdk/openai @ai-sdk/anthropic + ``` + + ### 3. Update Your Code + + ```diff + // imports + - import { VercelAIProvider } from '@voltagent/vercel-ai'; + + import { openai } from '@ai-sdk/openai'; + + // agent creation + const agent = new Agent({ + name: 'assistant', + - description: 'You are a helpful assistant', + + instructions: 'You are a helpful assistant', + - llm: new VercelAIProvider(), + - model: 'gpt-4o-mini', + + model: openai('gpt-4o-mini'), + }); + + // hooks + - import { createHooks } from '@voltagent/core'; + - hooks: createHooks({ onStart: () => {} }) + + hooks: { onStart: () => {} } + + // context + - userContext: new Map([['key', 'value']]) + + context: { key: 'value' } + ``` + + ## Benefits + - **Simpler API**: No provider abstraction complexity + - **Better Performance**: Direct AI SDK usage + - **Type Safety**: Improved TypeScript support + - **Future Proof**: Aligned with AI SDK ecosystem + - **Smaller Bundle**: Removed abstraction layer code + +- [#514](https://github.com/VoltAgent/voltagent/pull/514) [`e86cadb`](https://github.com/VoltAgent/voltagent/commit/e86cadb5ae9ee9719bfd1f12e7116d95224699ce) Thanks [@omeraplak](https://github.com/omeraplak)! - # VoltAgent Server Architecture - Pluggable Server Providers + + VoltAgent's server architecture has been completely redesigned with a pluggable server provider pattern, removing the built-in server in favor of optional server packages. + + ## Breaking Changes + + ### Built-in Server Removed + + The built-in server has been removed from the core package. Server functionality is now provided through separate server packages. + + **Before:** + + ```typescript + import { VoltAgent } from "@voltagent/core"; + + // Server was built-in and auto-started + const voltAgent = new VoltAgent({ + agents: { myAgent }, + port: 3000, + enableSwaggerUI: true, + autoStart: true, // Server auto-started + }); + ``` + + **After:** + + ```typescript + import { VoltAgent } from "@voltagent/core"; + import { honoServer } from "@voltagent/server-hono"; + + // Server is now optional and explicitly configured + const voltAgent = new VoltAgent({ + agents: { myAgent }, + server: honoServer({ + port: 3000, + enableSwaggerUI: true, + }), + }); + ``` + + ### Custom Endpoints Removed + + Custom endpoint registration methods have been removed. Custom routes should now be added through the server provider's `configureApp` option. + + **Before:** + + ```typescript + voltAgent.registerCustomEndpoint({ + path: "/custom", + method: "GET", + handler: async (req) => { + return { message: "Hello" }; + }, + }); + ``` + + **After:** + + ```typescript + import { honoServer } from "@voltagent/server-hono"; + + new VoltAgent({ + agents: { myAgent }, + server: honoServer({ + port: 3000, + // Configure custom routes via configureApp callback + configureApp: (app) => { + app.get("/api/custom", (c) => { + return c.json({ message: "Hello" }); + }); + + app.post("/api/calculate", async (c) => { + const { a, b } = await c.req.json(); + return c.json({ result: a + b }); + }); + }, + }), + }); + ``` + + ### Server Management Methods Changed + + **Before:** + + ```typescript + // Server started automatically or with: + voltAgent.startServer(); + // No stop method available + ``` + + **After:** + + ```typescript + // Server starts automatically if provider is configured + voltAgent.startServer(); // Still available + voltAgent.stopServer(); // New method for graceful shutdown + ``` + + ## New Server Provider Pattern + + ### IServerProvider Interface + + Server providers must implement the `IServerProvider` interface: + + ```typescript + interface IServerProvider { + start(): Promise<{ port: number }>; + stop(): Promise; + isRunning(): boolean; + } + ``` + + ### Available Server Providers + + #### @voltagent/server-hono (Recommended) + + Edge-optimized server using Hono framework: + + ```typescript + import { honoServer } from "@voltagent/server-hono"; + + new VoltAgent({ + agents: { myAgent }, + server: honoServer({ + port: 3141, + enableSwaggerUI: true, + auth: { + provider: "jwt", + secret: "your-secret", + }, + configureApp: (app) => { + // Add custom routes + app.get("/api/health", (c) => { + return c.json({ status: "healthy" }); + }); + }, + }), + }); + ``` + + Features: + - **Built-in JWT Authentication**: Secure your API with JWT tokens + - **Swagger UI Support**: Interactive API documentation + - **WebSocket Support**: Real-time streaming capabilities + - **Edge Runtime Compatible**: Deploy to Vercel Edge, Cloudflare Workers, etc. + - **Fast and Lightweight**: Optimized for performance + + #### Authentication & Authorization + + The server-hono package includes comprehensive JWT authentication support: + + ```typescript + import { honoServer, jwtAuth } from "@voltagent/server-hono"; + + new VoltAgent({ + agents: { myAgent }, + server: honoServer({ + port: 3141, + + // Configure JWT authentication + auth: jwtAuth({ + secret: process.env.JWT_SECRET, + + // Map JWT payload to user object + mapUser: (payload) => ({ + id: payload.sub, + email: payload.email, + role: payload.role, + permissions: payload.permissions || [], + }), + + // Define public routes (no auth required) + publicRoutes: ["/health", "/metrics"], + + // JWT verification options + verifyOptions: { + algorithms: ["HS256"], + audience: "your-app", + issuer: "your-auth-server", + }, + }), + }), + }); + ``` + + **Accessing User Context in Agents:** + + ```typescript + const agent = new Agent({ + name: "SecureAgent", + instructions: "You are a secure assistant", + model: openai("gpt-4o-mini"), + + // Access authenticated user in hooks + hooks: { + onStart: async ({ context }) => { + const user = context.get("user"); + if (user?.role === "admin") { + // Admin-specific logic + } + }, + }, + }); + ``` + + **Making Authenticated Requests:** + + ```bash + # Include JWT token in Authorization header + curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + http://localhost:3141/api/agent/chat + ``` + + ### No Server Configuration + + For serverless or custom deployments: + + ```typescript + new VoltAgent({ + agents: { myAgent }, + // No server property - runs without HTTP server + }); + ``` + + ## Migration Guide + 1. **Install server package**: + + ```bash + npm install @voltagent/server-hono + ``` + + 2. **Update imports**: + + ```typescript + import { honoServer } from "@voltagent/server-hono"; + ``` + + 3. **Update VoltAgent configuration**: + - Remove: `port`, `enableSwaggerUI`, `autoStart`, `customEndpoints` + - Add: `server: honoServer({ /* config */ })` + 4. **Handle custom routes**: + - Use `configureApp` callback in server config + - Access full Hono app instance for custom routes + +## 1.0.0-next.0 + +### Major Changes + +- [#485](https://github.com/VoltAgent/voltagent/pull/485) [`64a50e6`](https://github.com/VoltAgent/voltagent/commit/64a50e6800dec844fad7b9f3a3b1c2c8d0486229) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: change default memory storage from LibSQL to InMemoryStorage for serverless compatibility + + ## Breaking Change ⚠️ + + The default memory storage has been changed from LibSQL to InMemoryStorage to fix serverless deployment issues with native binary dependencies. + + ## Migration Guide + + ### If you need persistent storage with LibSQL: + 1. Install the new package: + + ```bash + npm install @voltagent/libsql + # or + pnpm add @voltagent/libsql + ``` + + 2. Import and configure LibSQLStorage: + + ```typescript + import { Agent } from "@voltagent/core"; + import { LibSQLStorage } from "@voltagent/libsql"; + + // Use with Agent + const agent = new Agent({ + name: "Assistant", + instructions: "You are a helpful assistant", + // Pass LibSQL storage explicitly + memory: new LibSQLStorage({ + url: "file:./.voltagent/memory.db", // It's default value + }), + // ... other config + }); + ``` + + ### If you're fine with in-memory storage: + + No changes needed! Your agents will use InMemoryStorage by default: + + ```typescript + const agent = new Agent({ + name: "Assistant", + instructions: "You are a helpful assistant", + // memory defaults to InMemoryStorage (no persistence) + }); + ``` + + ## Why This Change? + - **Lambda Compatibility**: Fixes "Cannot find module '@libsql/linux-x64-gnu'" error in AWS Lambda + - **Smaller Core Bundle**: Removes native dependencies from core package + - **Better Defaults**: InMemoryStorage works everywhere without configuration + - **Modular Architecture**: Use only the storage backends you need + +- [`9e8b211`](https://github.com/VoltAgent/voltagent/commit/9e8b2119a783942f114459f0a9b93e645727445e) Thanks [@omeraplak](https://github.com/omeraplak)! - Initial v1.0.0 prerelease + + This is the first prerelease for VoltAgent v1.0.0. This release includes various improvements and prepares for the upcoming major version. + + Testing the prerelease workflow with the next branch. + +## 0.1.84 + +### Patch Changes + +- [#462](https://github.com/VoltAgent/voltagent/pull/462) [`23ecea4`](https://github.com/VoltAgent/voltagent/commit/23ecea421b8c699f5c395dc8aed687f94d558b6c) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add cachedInputTokens and reasoningTokens to UsageInfo type + + Enhanced the `UsageInfo` type to include additional token usage metrics: + - Added `cachedInputTokens?: number` to track tokens served from cache + - Added `reasoningTokens?: number` to track tokens used for model reasoning + + These optional fields provide more granular usage information when supported by the underlying LLM provider. The Vercel AI provider now passes through these values when available from the AI SDK. + +- [#462](https://github.com/VoltAgent/voltagent/pull/462) [`23ecea4`](https://github.com/VoltAgent/voltagent/commit/23ecea421b8c699f5c395dc8aed687f94d558b6c) Thanks [@omeraplak](https://github.com/omeraplak)! - Update Zod to v3.25.0 for compatibility with Vercel AI@5 + - Updated Zod dependency to ^3.25.0 across all packages + - Maintained compatibility with zod-from-json-schema@0.0.5 + - Fixed TypeScript declaration build hanging issue + - Resolved circular dependency issues in the build process + +## 0.1.83 + +### Patch Changes + +- Updated dependencies [[`5968cef`](https://github.com/VoltAgent/voltagent/commit/5968cef5fe417cd118867ac78217dddfbd60493d)]: + - @voltagent/internal@0.0.9 + +## 0.1.82 + +### Patch Changes + +- [#492](https://github.com/VoltAgent/voltagent/pull/492) [`17d73f2`](https://github.com/VoltAgent/voltagent/commit/17d73f2972f061d8f468c209b79c42b5241cf06f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add addTools method and deprecate addItems for better developer experience - #487 + + ## What Changed + - Added new `addTools()` method to Agent class for dynamically adding tools and toolkits + - Deprecated `addItems()` method in favor of more intuitive `addTools()` naming + - Fixed type signature to accept `Tool` instead of `Tool` to support tools with output schemas + + ## Before + + ```typescript + // ❌ Method didn't exist - would throw error + agent.addTools([weatherTool]); + + // ❌ Type error with tools that have outputSchema + agent.addItems([weatherTool]); // Type error if weatherTool has outputSchema + ``` + + ## After + + ```typescript + // ✅ Works with new addTools method + agent.addTools([weatherTool]); + + // ✅ Also supports toolkits + agent.addTools([myToolkit]); + + // ✅ No type errors with outputSchema tools + const weatherTool = createTool({ + name: "getWeather", + outputSchema: weatherOutputSchema, // Works without type errors + // ... + }); + agent.addTools([weatherTool]); + ``` + + ## Migration + + The `addItems()` method is deprecated but still works. Update your code to use `addTools()`: + + ```typescript + // Old (deprecated) + agent.addItems([tool1, tool2]); + + // New (recommended) + agent.addTools([tool1, tool2]); + ``` + + This change improves developer experience by using more intuitive method naming and fixing TypeScript compatibility issues with tools that have output schemas. + +## 0.1.81 + +### Patch Changes + +- [#489](https://github.com/VoltAgent/voltagent/pull/489) [`fc79d81`](https://github.com/VoltAgent/voltagent/commit/fc79d81a2657a8472fdc2169213f6ef9f93e9b22) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add separate stream method for workflows with real-time event streaming + + ## What Changed + + Workflows now have a dedicated `.stream()` method that returns an AsyncIterable for real-time event streaming, separate from the `.run()` method. This provides better separation of concerns and improved developer experience. + + ## New Stream Method + + ```typescript + // Stream workflow execution with real-time events + const stream = workflow.stream(input); + + // Iterate through events as they happen + for await (const event of stream) { + console.log(`[${event.type}] ${event.from}`, event); + + if (event.type === "workflow-suspended") { + // Resume continues the same stream + await stream.resume({ approved: true }); + } + } + + // Get final result after stream completes + const result = await stream.result; + ``` + + ## Key Features + - **Separate `.stream()` method**: Clean API separation from `.run()` + - **AsyncIterable interface**: Native async iteration support + - **Promise-based fields**: Result, status, and usage resolve when execution completes + - **Continuous streaming**: Stream remains open across suspend/resume cycles (programmatic API) + - **Type safety**: Full TypeScript support with `WorkflowStreamResult` type + + ## REST API Streaming + + Added Server-Sent Events (SSE) endpoint for workflow streaming: + + ```typescript + POST / workflows / { id } / stream; + + // Returns SSE stream with real-time workflow events + // Note: Due to stateless architecture, stream closes on suspension + // Resume operations return complete results (not streamed) + ``` + + ## Technical Details + - Stream events flow through central `WorkflowStreamController` + - No-op stream writer for non-streaming execution + - Suspension events properly emitted to stream + - Documentation updated with streaming examples and architecture notes + +- [#490](https://github.com/VoltAgent/voltagent/pull/490) [`3d278cf`](https://github.com/VoltAgent/voltagent/commit/3d278cfb1799ffb2b2e460d5595ad68fc5f5c812) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: InMemoryStorage timestamp field for VoltOps history display + + Fixed an issue where VoltOps history wasn't displaying when using InMemoryStorage. The problem was caused by using `updatedAt` field instead of `timestamp` when setting history entries. + + The fix ensures that the `timestamp` field is properly preserved when updating history entries in InMemoryStorage, allowing VoltOps to correctly display workflow execution history. + +## 0.1.80 + +### Patch Changes + +- [#484](https://github.com/VoltAgent/voltagent/pull/484) [`6a638f5`](https://github.com/VoltAgent/voltagent/commit/6a638f52b682e7282747a95cac5c3a917caaaf5b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add real-time stream support and usage tracking for workflows + + ## What Changed for You + + Workflows now support real-time event streaming and token usage tracking, providing complete visibility into workflow execution and resource consumption. Previously, workflows only returned final results without intermediate visibility or usage metrics. + + ## Before - Limited Visibility + + ```typescript + // ❌ OLD: Only final result, no streaming or usage tracking + const workflow = createWorkflowChain(config) + .andThen({ execute: async ({ data }) => processData(data) }) + .andAgent(prompt, agent, { schema }); + + const result = await workflow.run(input); + // Only got final result, no intermediate events or usage info + ``` + + ## After - Full Stream Support and Usage Tracking + + ```typescript + // ✅ NEW: Real-time streaming and usage tracking + const workflow = createWorkflowChain(config) + .andThen({ + execute: async ({ data, writer }) => { + // Emit custom events for monitoring + writer.write({ + type: "processing-started", + metadata: { itemCount: data.items.length }, + }); + + const processed = await processData(data); + + writer.write({ + type: "processing-complete", + output: { processedCount: processed.length }, + }); + + return processed; + }, + }) + .andAgent(prompt, agent, { schema }); + + // Get both result and stream + const execution = await workflow.run(input); + + // Monitor events in real-time + for await (const event of execution.stream) { + console.log(`[${event.type}] ${event.from}:`, event); + // Events: workflow-start, step-start, custom events, step-complete, workflow-complete + } + + // Access token usage from all andAgent steps + console.log("Total tokens used:", execution.usage); + // { promptTokens: 250, completionTokens: 150, totalTokens: 400 } + ``` + + ## Advanced: Agent Stream Piping + + ```typescript + // ✅ NEW: Pipe agent's streaming output directly to workflow stream + .andThen({ + execute: async ({ data, writer }) => { + const agent = new Agent({ /* ... */ }); + + // Stream agent's response with full visibility + const response = await agent.streamText(prompt); + + // Pipe all agent events (text-delta, tool-call, etc.) to workflow stream + if (response.fullStream) { + await writer.pipeFrom(response.fullStream, { + prefix: "agent-", // Optional: prefix event types + filter: (part) => part.type !== "finish" // Optional: filter events + }); + } + + const result = await response.text; + return { ...data, agentResponse: result }; + } + }) + ``` + + ## Key Features + + ### 1. Stream Events + + Every workflow execution now includes a stream of events: + - `workflow-start` / `workflow-complete` - Workflow lifecycle + - `step-start` / `step-complete` - Step execution tracking + - Custom events via `writer.write()` - Application-specific monitoring + - Piped agent events via `writer.pipeFrom()` - Full agent visibility + + ### 2. Writer API in All Steps + + The `writer` is available in all step types: + + ```typescript + // andThen + .andThen({ execute: async ({ data, writer }) => { /* ... */ } }) + + // andTap (observe without modifying) + .andTap({ execute: async ({ data, writer }) => { + writer.write({ type: "checkpoint", metadata: { data } }); + }}) + + // andWhen + .andWhen({ + condition: async ({ data, writer }) => { + writer.write({ type: "condition-check", input: data }); + return data.shouldProcess; + }, + execute: async ({ data, writer }) => { /* ... */ } + }) + ``` + + ### 3. Usage Tracking + + Token usage from all `andAgent` steps is automatically accumulated: + + ```typescript + const execution = await workflow.run(input); + + // Total usage across all andAgent steps + const { promptTokens, completionTokens, totalTokens } = execution.usage; + + // Usage is always available (defaults to 0 if no agents used) + console.log(`Cost: ${totalTokens * 0.0001}`); // Example cost calculation + ``` + + ## Why This Matters + - **Real-time Monitoring**: See what's happening as workflows execute + - **Debugging**: Track data flow through each step with custom events + - **Cost Control**: Monitor token usage across complex workflows + - **Agent Integration**: Full visibility into agent operations within workflows + - **Production Ready**: Stream events for logging, monitoring, and alerting + + ## Technical Details + - Stream is always available (non-optional) for consistent API + - Events include execution context (executionId, timestamp, status) + - Writer functions are synchronous for `write()`, async for `pipeFrom()` + - Usage tracking only counts `andAgent` steps (not custom agent calls in `andThen`) + - All events flow through a central `WorkflowStreamController` for ordering + +## 0.1.79 + +### Patch Changes + +- [#481](https://github.com/VoltAgent/voltagent/pull/481) [`2fd8bb4`](https://github.com/VoltAgent/voltagent/commit/2fd8bb47af2906bcfff9be4aac8c6a53a264b628) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add configurable subagent event forwarding for enhanced stream control + + ## What Changed for You + + You can now control which events from subagents are forwarded to the parent stream, providing fine-grained control over stream verbosity and performance. Previously, only `tool-call` and `tool-result` events were forwarded with no way to customize this behavior. + + ## Before - Fixed Event Forwarding + + ```typescript + // ❌ OLD: Only tool-call and tool-result events were forwarded (hardcoded) + const supervisor = new Agent({ + name: "Supervisor", + subAgents: [writerAgent, editorAgent], + // No way to change which events were forwarded + }); + + const result = await supervisor.streamText("Create content"); + + // Stream only contained tool-call and tool-result from subagents + for await (const event of result.fullStream) { + console.log("Event", event); + } + ``` + + ## After - Full Control Over Event Forwarding + + ```typescript + // ✅ NEW: Configure exactly which events to forward + const supervisor = new Agent({ + name: "Supervisor", + subAgents: [writerAgent, editorAgent], + + supervisorConfig: { + fullStreamEventForwarding: { + // Choose which event types to forward (default: ['tool-call', 'tool-result']) + types: ["tool-call", "tool-result", "text-delta"], + + // Control tool name prefixing (default: true) + addSubAgentPrefix: true, // "WriterAgent: search_tool" vs "search_tool" + }, + }, + }); + + // Stream only contains configured event types from subagents + const result = await supervisor.streamText("Create content"); + + // Filter subagent events in your application + for await (const event of result.fullStream) { + if (event.subAgentId && event.subAgentName) { + console.log(`Event from ${event.subAgentName}: ${event.type}`); + } + } + ``` + + ## Configuration Options + + ```typescript + // Minimal - Only tool events (default) + fullStreamEventForwarding: { + types: ['tool-call', 'tool-result'], + } + + // Verbose - See what subagents are saying and doing + fullStreamEventForwarding: { + types: ['tool-call', 'tool-result', 'text-delta'], + } + + // Full visibility - All events for debugging + fullStreamEventForwarding: { + types: ['tool-call', 'tool-result', 'text-delta', 'reasoning', 'source', 'error', 'finish'], + } + + // Clean tool names without agent prefix + fullStreamEventForwarding: { + types: ['tool-call', 'tool-result'], + addSubAgentPrefix: false, + } + ``` + + ## Why This Matters + - **Better Performance**: Reduce stream overhead by forwarding only necessary events + - **Cleaner Streams**: Focus on meaningful actions rather than all intermediate steps + - **Type Safety**: Use `StreamEventType[]` for compile-time validation of event types + - **Backward Compatible**: Existing code continues to work with sensible defaults + + ## Technical Details + - Default configuration: `['tool-call', 'tool-result']` with `addSubAgentPrefix: true` + - Events from subagents include `subAgentId` and `subAgentName` properties for filtering + - Configuration available through `supervisorConfig.fullStreamEventForwarding` + - Utilizes the `streamEventForwarder` utility for consistent event filtering + +## 0.1.78 + +### Patch Changes + +- [#466](https://github.com/VoltAgent/voltagent/pull/466) [`730232e`](https://github.com/VoltAgent/voltagent/commit/730232e730cdbd1bb7de6acff8519e8af93f2abf) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add message helper utilities to simplify working with complex message content + + ## What Changed for You + + Working with message content (which can be either a string or an array of content parts) used to require complex if/else blocks. Now you have simple helper functions that handle all the complexity. + + ## Before - Your Old Code (Complex) + + ```typescript + // Adding timestamps to messages - 30+ lines of code + const enhancedMessages = messages.map((msg) => { + if (msg.role === "user") { + const timestamp = new Date().toLocaleTimeString(); + + // Handle string content + if (typeof msg.content === "string") { + return { + ...msg, + content: `[${timestamp}] ${msg.content}`, + }; + } + + // Handle structured content (array of content parts) + if (Array.isArray(msg.content)) { + return { + ...msg, + content: msg.content.map((part) => { + if (part.type === "text") { + return { + ...part, + text: `[${timestamp}] ${part.text}`, + }; + } + return part; + }), + }; + } + } + return msg; + }); + + // Extracting text from content - another 15+ lines + function getText(content) { + if (typeof content === "string") { + return content; + } + if (Array.isArray(content)) { + return content + .filter((part) => part.type === "text") + .map((part) => part.text) + .join(""); + } + return ""; + } + ``` + + ## After - Your New Code (Simple) + + ```typescript + import { messageHelpers } from "@voltagent/core"; + + // Adding timestamps - 1 line! + const enhancedMessages = messages.map((msg) => + messageHelpers.addTimestampToMessage(msg, timestamp) + ); + + // Extracting text - 1 line! + const text = messageHelpers.extractText(content); + + // Check if has images - 1 line! + if (messageHelpers.hasImagePart(content)) { + // Handle image content + } + + // Build complex content - fluent API + const content = new messageHelpers.MessageContentBuilder() + .addText("Here's an image:") + .addImage("screenshot.png") + .addText("And a file:") + .addFile("document.pdf") + .build(); + ``` + + ## Real Use Case in Hooks + + ```typescript + import { Agent, messageHelpers } from "@voltagent/core"; + + const agent = new Agent({ + name: "Assistant", + hooks: { + onPrepareMessages: async ({ messages }) => { + // Before: 30+ lines of complex if/else + // After: 2 lines! + const timestamp = new Date().toLocaleTimeString(); + return { + messages: messages.map((msg) => messageHelpers.addTimestampToMessage(msg, timestamp)), + }; + }, + }, + }); + ``` + + ## What You Get + - **No more if/else blocks** for content type checking + - **Type-safe operations** with TypeScript support + - **30+ lines → 1 line** for common operations + - **Works everywhere**: hooks, tools, custom logic + + ## Available Helpers + + ```typescript + import { messageHelpers } from "@voltagent/core"; + + // Check content type + messageHelpers.isTextContent(content); // Is it a string? + messageHelpers.hasImagePart(content); // Has images? + + // Extract content + messageHelpers.extractText(content); // Get all text + messageHelpers.extractImageParts(content); // Get all images + + // Transform content + messageHelpers.transformTextContent(content, (text) => text.toUpperCase()); + messageHelpers.addTimestampToMessage(message, "10:30:00"); + + // Build content + new messageHelpers.MessageContentBuilder().addText("Hello").addImage("world.png").build(); + ``` + + Your message handling code just got 90% simpler! + +- [#466](https://github.com/VoltAgent/voltagent/pull/466) [`730232e`](https://github.com/VoltAgent/voltagent/commit/730232e730cdbd1bb7de6acff8519e8af93f2abf) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add onPrepareMessages hook - transform messages before they reach the LLM + + ## What Changed for You + + You can now modify, filter, or enhance messages before they're sent to the LLM. Previously impossible without forking the framework. + + ## Before - What You Couldn't Do + + ```typescript + // ❌ No way to: + // - Add timestamps to messages + // - Filter sensitive data (SSN, credit cards) + // - Add user context to messages + // - Remove duplicate messages + // - Inject system prompts dynamically + + const agent = new Agent({ + name: "Assistant", + // Messages went straight to LLM - no control! + }); + ``` + + ## After - What You Can Do Now + + ```typescript + import { Agent, messageHelpers } from "@voltagent/core"; + + const agent = new Agent({ + name: "Assistant", + + hooks: { + // ✅ NEW: Intercept and transform messages! + onPrepareMessages: async ({ messages, context }) => { + // Add timestamps + const timestamp = new Date().toLocaleTimeString(); + const enhanced = messages.map((msg) => + messageHelpers.addTimestampToMessage(msg, timestamp) + ); + + return { messages: enhanced }; + }, + }, + }); + + // Your message: "What time is it?" + // LLM receives: "[14:30:45] What time is it?" + ``` + + ## When It Runs + + ```typescript + // 1. User sends message + await agent.generateText("Hello"); + + // 2. Memory loads previous messages + // [previous messages...] + + // 3. ✨ onPrepareMessages runs HERE + // You can transform messages + + // 4. Messages sent to LLM + // [your transformed messages] + ``` + + ## What You Need to Know + - **Runs on every LLM call**: generateText, streamText, generateObject, streamObject + - **Gets all messages**: Including system prompt and memory messages + - **Return transformed messages**: Or return nothing to keep original + - **Access to context**: userContext, operationId, agent reference + + Your app just got smarter without changing any existing code! + +- [#466](https://github.com/VoltAgent/voltagent/pull/466) [`730232e`](https://github.com/VoltAgent/voltagent/commit/730232e730cdbd1bb7de6acff8519e8af93f2abf) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: memory messages now return parsed objects instead of JSON strings + + ## What Changed for You + + Memory messages that contain structured content (like tool calls or multi-part messages) now return as **parsed objects** instead of **JSON strings**. This is a breaking change if you were manually parsing these messages. + + ## Before - You Had to Parse JSON Manually + + ```typescript + // ❌ OLD BEHAVIOR: Content came as JSON string + const messages = await memory.getMessages({ conversationId: "123" }); + + // What you got from memory: + console.log(messages[0]); + // { + // role: "user", + // content: '[{"type":"text","text":"Hello"},{"type":"image","image":"data:..."}]', // STRING! + // type: "text" + // } + + // You had to manually parse the JSON string: + const content = JSON.parse(messages[0].content); // Parse required! + console.log(content); + // [ + // { type: "text", text: "Hello" }, + // { type: "image", image: "data:..." } + // ] + + // Tool calls were also JSON strings: + console.log(messages[1].content); + // '[{"type":"tool-call","toolCallId":"123","toolName":"weather"}]' // STRING! + ``` + + ## After - You Get Parsed Objects Automatically + + ```typescript + // ✅ NEW BEHAVIOR: Content comes as proper objects + const messages = await memory.getMessages({ conversationId: "123" }); + + // What you get from memory NOW: + console.log(messages[0]); + // { + // role: "user", + // content: [ + // { type: "text", text: "Hello" }, // OBJECT! + // { type: "image", image: "data:..." } // OBJECT! + // ], + // type: "text" + // } + + // Direct access - no JSON.parse needed! + const content = messages[0].content; // Already parsed! + console.log(content[0].text); // "Hello" + + // Tool calls are proper objects: + console.log(messages[1].content); + // [ + // { type: "tool-call", toolCallId: "123", toolName: "weather" } // OBJECT! + // ] + ``` + + ## Breaking Change Warning ⚠️ + + If your code was doing this: + + ```typescript + // This will now FAIL because content is already parsed + const parsed = JSON.parse(msg.content); // ❌ Error: not a string! + ``` + + Change it to: + + ```typescript + // Just use the content directly + const content = msg.content; // ✅ Already an object/array + ``` + + ## What Gets Auto-Parsed + - **String content** → Stays as string ✅ + - **Structured content** (arrays) → Auto-parsed to objects ✅ + - **Tool calls** → Auto-parsed to objects ✅ + - **Tool results** → Auto-parsed to objects ✅ + - **Metadata fields** → Auto-parsed to objects ✅ + + ## Why This Matters + - **No more JSON.parse errors** in your application + - **Type-safe access** to structured content + - **Cleaner code** without try/catch blocks + - **Consistent behavior** with how agents handle messages + + ## Migration Guide + 1. **Remove JSON.parse calls** for message content + 2. **Remove try/catch** blocks around parsing + 3. **Use content directly** as objects/arrays + + Your memory messages now "just work" without manual parsing! + +## 0.1.77 + +### Patch Changes + +- [#472](https://github.com/VoltAgent/voltagent/pull/472) [`8de5785`](https://github.com/VoltAgent/voltagent/commit/8de5785e385bec632f846bcae44ee5cb22a9022e) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: Migrate to using `safeStringify` to prevent issues using the JSON.stringify/parse method, in addition use structuredClone via Nodejs instead legacy method that errors + +- Updated dependencies [[`8de5785`](https://github.com/VoltAgent/voltagent/commit/8de5785e385bec632f846bcae44ee5cb22a9022e)]: + - @voltagent/internal@0.0.8 + +## 0.1.76 + +### Patch Changes + +- [#468](https://github.com/VoltAgent/voltagent/pull/468) [`c7fec1b`](https://github.com/VoltAgent/voltagent/commit/c7fec1b6c09547adce7dfdb779a2eae7e2fbd153) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: separate system-managed context from user context in operationContext + + Separated system-managed values from userContext by introducing a new `systemContext` field in OperationContext. This provides cleaner separation of concerns between user-provided context and internal system tracking. + + ### What Changed + - Added `systemContext` field to `OperationContext` type for internal system values + - Moved system-managed values from `userContext` to `systemContext`: + - `agent_start_time`: Agent execution start timestamp + - `agent_start_event_id`: Agent start event identifier + - `tool_${toolId}`: Tool execution tracking (eventId and startTime) + + ### Why This Matters + + Previously, system values were mixed with user context, which could: + - Pollute the user's context namespace + - Make it unclear which values were user-provided vs system-generated + - Potentially cause conflicts if users used similar key names + + Now there's a clear separation: + - `userContext`: Contains only user-provided values + - `systemContext`: Contains only system-managed internal tracking values + + ### Migration + + This is an internal change that doesn't affect the public API. User code remains unchanged. + + ```typescript + // User API remains the same + const response = await agent.generateText("Hello", { + userContext: new Map([["userId", "123"]]), + }); + + // userContext now only contains user values + console.log(response.userContext.get("userId")); // "123" + // System values are kept separate internally + ``` + +- [#465](https://github.com/VoltAgent/voltagent/pull/465) [`4fe0f21`](https://github.com/VoltAgent/voltagent/commit/4fe0f21e1dde82bb80fcaab4a7039b446b8d9153) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: abort signal propagation to LLM providers for proper cancellation support + + Fixed an issue where abort signals were not correctly propagated to LLM providers in agent methods (`generateText`, `streamText`, `generateObject`, `streamObject`). The methods were using `internalOptions.signal` instead of `operationContext.signal`, which contains the properly derived signal from the AbortController. + + ## What's Fixed + - **Signal Propagation**: All agent methods now correctly pass `operationContext.signal` to LLM providers + - **AbortController Support**: Abort signals from parent agents properly cascade to subagents + - **Cancellation Handling**: Operations can now be properly cancelled when AbortController is triggered + + ## Usage Example + + ```typescript + import { Agent, isAbortError } from "@voltagent/core"; + import { VercelAIProvider } from "@voltagent/vercel-ai"; + import { openai } from "@ai-sdk/openai"; + + const abortController = new AbortController(); + + // Create supervisor with subagents + const supervisor = new Agent({ + name: "Supervisor", + instructions: "Coordinate tasks", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + subAgents: [contentAgent, formatterAgent], + hooks: { + onEnd: async ({ error }) => { + // Check if the operation was aborted + if (isAbortError(error)) { + console.log("Operation was aborted:", error.message); + // Handle cleanup for aborted operations + return; + } + + if (error) { + console.error("Operation failed:", error); + } + }, + }, + }); + + // Start streaming with abort controller + const stream = await supervisor.streamText("Create a story", { + abortController, + }); + + // Abort after 500ms - now properly stops all subagent operations + setTimeout(() => { + abortController.abort(); + }, 500); + + try { + // Stream will properly terminate when aborted + for await (const chunk of stream.textStream) { + console.log(chunk); + } + } catch (error) { + if (isAbortError(error)) { + console.log("Stream aborted successfully"); + } + } + ``` + + ## Error Handling in Hooks + + The `onEnd` hook now receives `AbortError` type errors when operations are cancelled: + + ```typescript + import { isAbortError } from "@voltagent/core"; + + const agent = new Agent({ + // ... agent config + hooks: { + onEnd: async ({ error }) => { + if (isAbortError(error)) { + // error is typed as AbortError + // error.name === "AbortError" + // Handle abort-specific logic + await cleanupResources(); + return; + } + + // Handle other errors + if (error) { + await logError(error); + } + }, + }, + }); + ``` + + This fix ensures that expensive operations can be properly cancelled, preventing unnecessary computation and improving resource efficiency when users navigate away or cancel requests. + +## 0.1.75 + +### Patch Changes + +- [`3a3ebd2`](https://github.com/VoltAgent/voltagent/commit/3a3ebd2bc72ed5d14dd924d824b54203b73ab19d) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: voltops client validation to prevent empty string keys from creating invalid clients + - VoltOpsClient now validates keys before initializing services + - Keys must not be empty and must have correct prefixes (pk* and sk*) + - Added hasValidKeys() method to check client validity + - Updated /setup-observability endpoint to update existing keys in .env file instead of adding duplicates + +## 0.1.74 + +### Patch Changes + +- [#463](https://github.com/VoltAgent/voltagent/pull/463) [`760a294`](https://github.com/VoltAgent/voltagent/commit/760a294e4d68742d8701d54dc1c541c87959e5d8) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: improve /setup-observability endpoint to handle commented .env entries + + ### What's New + + The `/setup-observability` API endpoint now intelligently updates existing .env files by replacing commented VoltOps key entries instead of creating duplicates. + + ### Changes + - **Smart .env Updates**: When setting up observability, the endpoint now finds and updates commented entries like `# VOLTAGENT_PUBLIC_KEY=` + - **No More Duplicates**: Prevents duplicate key entries by updating existing lines (both commented and active) + - **Cleaner Configuration**: Results in a cleaner .env file without confusing duplicate entries + + ### Before + + ```bash + # VoltAgent Observability (Optional) + # VOLTAGENT_PUBLIC_KEY= + # VOLTAGENT_SECRET_KEY= + + # ... later in file ... + + # VoltAgent Observability + VOLTAGENT_PUBLIC_KEY=your-public-key + VOLTAGENT_SECRET_KEY=your-secret-key + ``` + + ### After + + ```bash + # VoltAgent Observability (Optional) + VOLTAGENT_PUBLIC_KEY=your-public-key + VOLTAGENT_SECRET_KEY=your-secret-key + ``` + + This change improves the developer experience by maintaining a clean .env file structure when setting up observability through the VoltOps Console. + +- [#463](https://github.com/VoltAgent/voltagent/pull/463) [`760a294`](https://github.com/VoltAgent/voltagent/commit/760a294e4d68742d8701d54dc1c541c87959e5d8) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add VoltOps API key validation and improved auto-configuration + + ### What's New + - **API Key Validation**: VoltAgent now validates VoltOps API keys to ensure they have the correct format (must start with `pk_` for public keys and `sk_` for secret keys) + - **Smart Auto-Configuration**: The VoltAgent constructor only creates VoltOpsClient when valid API keys are detected + - **Dummy Key Protection**: Placeholder values like "your-public-key" are now properly rejected + + ### Changes + - Added `isValidVoltOpsKeys()` utility function to validate API key formats + - Updated VoltAgent constructor to check key validity before auto-configuring VoltOpsClient + - Environment variables with invalid keys are now silently ignored instead of causing errors + + ### Usage + + ```typescript + // Valid keys - VoltOpsClient will be auto-configured + // .env file: + // VOLTAGENT_PUBLIC_KEY=your-public-key + // VOLTAGENT_SECRET_KEY=your-secret-key + + // Invalid keys - VoltOpsClient will NOT be created + // .env file: + // VOLTAGENT_PUBLIC_KEY=your-public-key // ❌ Rejected + // VOLTAGENT_SECRET_KEY=your-secret-key // ❌ Rejected + + const voltAgent = new VoltAgent({ + agents: { myAgent }, + // No need to manually configure VoltOpsClient if valid keys exist in environment + }); + ``` + + This change improves the developer experience by preventing confusion when placeholder API keys are present in the environment variables. + +- [#459](https://github.com/VoltAgent/voltagent/pull/459) [`980d037`](https://github.com/VoltAgent/voltagent/commit/980d037ce535bcc85cc7df3f64354c823453a147) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add userContext to logger context for better traceability + + ### What's New + + The `userContext` is now automatically included in the logger context for all agent operations. This provides better traceability and debugging capabilities by associating custom context data with all log messages generated during an agent's execution. + + ### Usage + + When you pass a `userContext` to any agent method, it will automatically appear in all log messages: + + ```typescript + const userContext = new Map([ + ["sessionId", "session-123"], + ["userId", "user-456"], + ["customKey", "customValue"], + ]); + + await agent.generateText("Hello", { userContext }); + + // All logs during this operation will include: + // { + // "component": "agent", + // "agentId": "TestAgent", + // "executionId": "...", + // "userContext": { + // "sessionId": "session-123", + // "userId": "user-456", + // "customKey": "customValue" + // } + // } + ``` + + ### Benefits + - **Better Debugging**: Easily correlate logs with specific user sessions or requests + - **Enhanced Observability**: Track custom context throughout the entire agent execution + - **Multi-tenant Support**: Associate logs with specific tenants, users, or organizations + - **Request Tracing**: Follow a request through all agent operations and sub-agents + + This change improves the observability experience by ensuring all log messages include the relevant user context, making it easier to debug issues and track operations in production environments. + +## 0.1.73 + +### Patch Changes + +- [#457](https://github.com/VoltAgent/voltagent/pull/457) [`8d89469`](https://github.com/VoltAgent/voltagent/commit/8d8946919820c0298bffea13731ea08660b72c4b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: optimize agent event system and add pagination to agent history API + + Significantly improved agent performance and UI scalability with two major enhancements: + + ## 1. Event System Optimization + + Refactored agent event system to emit events immediately before database writes, matching the workflow event system behavior. This provides real-time event visibility without waiting for persistence operations. + + **Before:** + - Events were queued and only emitted after database write completion + - Real-time monitoring was delayed by persistence operations + + **After:** + - Events emit immediately for real-time updates + - Database persistence happens asynchronously in the background + - Consistent behavior with workflow event system + + ## 2. Agent History Pagination + + Added comprehensive pagination support to agent history API, preventing performance issues when loading large history datasets. + + **New API:** + + ```typescript + // Agent class + const history = await agent.getHistory({ page: 0, limit: 20 }); + // Returns: { entries: AgentHistoryEntry[], pagination: { page, limit, total, totalPages } } + + // REST API + GET /agents/:id/history?page=0&limit=20 + // Returns paginated response format + ``` + + **Implementation Details:** + - Added pagination to all storage backends (LibSQL, PostgreSQL, Supabase, InMemory) + - Updated WebSocket initial load to use pagination + - Maintained backward compatibility (when page/limit not provided, returns first 100 entries) + - Updated all tests to work with new pagination format + + **Storage Changes:** + - LibSQL: Added LIMIT/OFFSET support + - PostgreSQL: Added pagination with proper SQL queries + - Supabase: Used `.range()` method for efficient pagination + - InMemory: Implemented array slicing with total count + + This improves performance for agents with extensive history and provides better UX for viewing agent execution history. + +- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements + + This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + + **Key improvements:** + - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs + - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration + - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries + - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup + - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + + These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. + +- [#447](https://github.com/VoltAgent/voltagent/pull/447) [`71500c5`](https://github.com/VoltAgent/voltagent/commit/71500c5368cce3ed4aacfb0fb2749752bf71badd) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - feat: (experimental) Allow for dynamic `andAll` steps when using the `createWorkflow` API. + + ### Usage + + You can now provide a function to the `steps` property of `andAll` to dynamically generate the steps. + + > [!NOTE] + > This is an experimental feature and may change in the future, its only supported for `andAll` steps in the `createWorkflow` API. + + ```typescript + const workflow = createWorkflow( + { + id: "my-workflow", + name: "My Workflow", + input: z.object({ + id: z.string(), + }), + result: z.object({ + name: z.string(), + }), + memory, + }, + andThen({ + id: "fetch-data", + name: "Fetch data", + execute: async ({ data }) => { + return request.get(`https://api.example.com/data/${data.id}`); + }, + }), + andAll({ + id: "transform-data", + name: "Transform data", + steps: async (context) => + context.data.map((item) => + andThen({ + id: `transform-${item.id}`, + name: `Transform ${item.id}`, + execute: async ({ data }) => { + return { + ...item, + name: [item.name, item.id].join("-"), + }; + }, + }) + ), + }), + andThen({ + id: "pick-data", + name: "Pick data", + execute: async ({ data }) => { + return { + name: data[0].name, + }; + }, + }) + ); + ``` + +- [#452](https://github.com/VoltAgent/voltagent/pull/452) [`6cc552a`](https://github.com/VoltAgent/voltagent/commit/6cc552ada896b1a8344976c46a08b53d2b3a5743) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: Expose the `andWorkflow` function as it was built but not re-exported + +- Updated dependencies [[`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5)]: + - @voltagent/internal@0.0.7 + +## 0.1.72 + +### Patch Changes + +- [#445](https://github.com/VoltAgent/voltagent/pull/445) [`a658ae6`](https://github.com/VoltAgent/voltagent/commit/a658ae6fd5ae404448a43026f21bfa0351189f01) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: Fixed types in andAll and andRace where the inferred result from the steps was NOT being passed along + +## 0.1.71 + +### Patch Changes + +- [#438](https://github.com/VoltAgent/voltagent/pull/438) [`99fe836`](https://github.com/VoltAgent/voltagent/commit/99fe83662e9b3e550380fce066521a5c27d69eb3) Thanks [@danielyogel](https://github.com/danielyogel)! - feat: add optional outputSchema validation for tools + + VoltAgent now supports optional output schema validation for tools, providing runtime type safety and enabling LLM self-correction when tool outputs don't match expected formats. + + **Key Features:** + - **Optional Output Schema**: Tools can now define an `outputSchema` using Zod schemas + - **Runtime Validation**: Tool outputs are validated against the schema when provided + - **LLM Error Recovery**: Validation errors are returned to the LLM instead of throwing, allowing it to retry with corrected output + - **Full Backward Compatibility**: Existing tools without output schemas continue to work as before + - **TypeScript Type Safety**: Output types are inferred from schemas when provided + + **Usage Example:** + + ```typescript + import { createTool } from "@voltagent/core"; + import { z } from "zod"; + + // Define output schema + const weatherOutputSchema = z.object({ + temperature: z.number(), + condition: z.enum(["sunny", "cloudy", "rainy", "snowy"]), + humidity: z.number().min(0).max(100), + }); + + // Create tool with output validation + const weatherTool = createTool({ + name: "getWeather", + description: "Get current weather", + parameters: z.object({ + location: z.string(), + }), + outputSchema: weatherOutputSchema, // Optional + execute: async ({ location }) => { + // Return value will be validated + return { + temperature: 22, + condition: "sunny", + humidity: 65, + }; + }, + }); + ``` + + **Validation Behavior:** + + When a tool with `outputSchema` is executed: + 1. The output is validated against the schema + 2. If validation succeeds, the validated output is returned + 3. If validation fails, an error object is returned to the LLM: + ```json + { + "error": true, + "message": "Output validation failed: Expected number, received string", + "validationErrors": [...], + "actualOutput": {...} + } + ``` + 4. The LLM can see the error and potentially fix it by calling the tool again + + This feature enhances tool reliability while maintaining the flexibility for LLMs to handle validation errors gracefully. + +## 0.1.70 + +### Patch Changes + +- [#400](https://github.com/VoltAgent/voltagent/pull/400) [`57825dd`](https://github.com/VoltAgent/voltagent/commit/57825ddb359177b5abc3696f3c54e5fc873ea621) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - feat(core): Add in new `andWorkflow` step to allow for running a workflow from another workflow + +- [#436](https://github.com/VoltAgent/voltagent/pull/436) [`89e4ef1`](https://github.com/VoltAgent/voltagent/commit/89e4ef1f0e84f3f42bb208cf70f39cca0898ddc7) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: make tool errors non-fatal for better agent resilience - #430 & #349 + + Previously, when tools encountered errors (timeouts, connection issues, etc.), the entire agent execution would fail. This change improves resilience by: + - Catching tool execution errors and returning them as structured results instead of throwing + - Allowing the LLM to see tool errors and decide whether to retry or use alternative approaches + - Including error details (message and stack trace) in the tool result for debugging + - Ensuring agent execution only fails when it reaches maxSteps or the LLM cannot proceed + + The error result format includes: + + ```json + { + "error": true, + "message": "Error message", + "stack": "Error stack trace (optional)" + } + ``` + + This change makes agents more robust when dealing with unreliable external tools or transient network issues. + +## 0.1.69 + +### Patch Changes + +- [#425](https://github.com/VoltAgent/voltagent/pull/425) [`8605e70`](https://github.com/VoltAgent/voltagent/commit/8605e708d17e6fa0150bd13235e795288422c52b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Promise-based properties and warnings to AI responses - #422 + + Enhanced AI response types to align with Vercel AI SDK's API and provide better metadata: + + **For `streamObject`:** + - Added optional `object?: Promise` property that resolves to the final generated object + - Added optional `usage?: Promise` property that resolves to token usage information + - Added optional `warnings?: Promise` property for provider warnings + + **For `streamText`:** + - Added optional `text?: Promise` property that resolves to the full generated text + - Added optional `finishReason?: Promise` property that resolves to the reason generation stopped + - Added optional `usage?: Promise` property that resolves to token usage information + - Added optional `reasoning?: Promise` property that resolves to model's reasoning text + + **For `generateText` and `generateObject`:** + - Added optional `reasoning?: string` property for model's reasoning text (generateText only) + - Added optional `warnings?: any[]` property for provider warnings + + These properties are optional to maintain backward compatibility. Providers that support these features (like Vercel AI) now return these values, allowing users to access rich metadata: + + ```typescript + // For streamObject + const response = await agent.streamObject(input, schema); + const finalObject = await response.object; // Promise + const usage = await response.usage; // Promise + + // For streamText + const response = await agent.streamText(input); + const fullText = await response.text; // Promise + const usage = await response.usage; // Promise + + // For generateText + const response = await agent.generateText(input); + console.log(response.warnings); // Any provider warnings + console.log(response.reasoning); // Model's reasoning (if available) + ``` + +## 0.1.68 + +### Patch Changes + +- [#423](https://github.com/VoltAgent/voltagent/pull/423) [`089c039`](https://github.com/VoltAgent/voltagent/commit/089c03993e3b9e05655a1108355e7bee940d33a7) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add message type filtering support to memory storage implementations + + Added the ability to filter messages by type when retrieving conversation history. This enhancement allows the framework to distinguish between different message types (text, tool-call, tool-result) and retrieve only the desired types, improving context preparation for LLMs. + + ## Key Changes + - **MessageFilterOptions**: Added optional `types` parameter to filter messages by type + - **prepareConversationContext**: Now filters to only include text messages, excluding tool-call and tool-result messages for cleaner LLM context + - **All storage implementations**: Added database-level filtering for better performance + + ## Usage + + ```typescript + // Get only text messages + const textMessages = await memory.getMessages({ + userId: "user-123", + conversationId: "conv-456", + types: ["text"], + }); + + // Get tool-related messages + const toolMessages = await memory.getMessages({ + userId: "user-123", + conversationId: "conv-456", + types: ["tool-call", "tool-result"], + }); + + // Get all messages (default behavior - backward compatible) + const allMessages = await memory.getMessages({ + userId: "user-123", + conversationId: "conv-456", + }); + ``` + + ## Implementation Details + - **InMemoryStorage**: Filters messages in memory after retrieval + - **LibSQLStorage**: Adds SQL WHERE clause with IN operator for type filtering + - **PostgreSQL**: Uses parameterized IN clause with proper parameter counting + - **Supabase**: Utilizes query builder's `.in()` method for type filtering + + This change ensures that `prepareConversationContext` provides cleaner, more focused context to LLMs by excluding intermediate tool execution details, while maintaining full backward compatibility for existing code. + +## 0.1.67 + +### Patch Changes + +- [#417](https://github.com/VoltAgent/voltagent/pull/417) [`67450c3`](https://github.com/VoltAgent/voltagent/commit/67450c3bc4306ab6021ca8feed2afeef6dcc320e) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: dynamic toolkit resolution and VoltOps UI visibility + + Fixed an issue where dynamic tools and toolkits weren't being displayed in VoltOps UI when resolved during agent execution. The fix includes: + + **Key Changes:** + - **Dynamic Tool Resolution**: Modified `prepareToolsForGeneration` to properly accept and process both `BaseTool` and `Toolkit` types + - **VoltOps UI Integration**: Dynamic tools now appear in the Console UI by updating history metadata when tools are resolved + - **Data Persistence**: Tools persist across page refreshes by storing them in history entry metadata + + **Technical Details:** + - `prepareToolsForGeneration` now accepts `(BaseTool | Toolkit)[]` instead of just `BaseTool[]` + - Uses temporary ToolManager with `addItems()` to handle both tools and toolkits consistently + - Updates history entry metadata with complete agent snapshot when dynamic tools are resolved + - Removed WebSocket-based TOOLS_UPDATE events in favor of metadata-based approach + + This ensures that dynamic tools like `createReasoningTools()` and other toolkits work seamlessly when provided through the `dynamicTools` parameter. + +- [#418](https://github.com/VoltAgent/voltagent/pull/418) [`aa024c1`](https://github.com/VoltAgent/voltagent/commit/aa024c1a7c643b2aff7a5fd0d150c87f8a9a1858) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: memory storage implementations now correctly return the most recent messages when using context limit + + Fixed an issue where memory storage implementations (LibSQL, PostgreSQL, Supabase) were returning the oldest messages instead of the most recent ones when a context limit was specified. This was causing AI agents to lose important recent context in favor of old conversation history. + + **Before:** + - `contextLimit: 10` returned the first 10 messages (oldest) + - Agents were working with outdated context + + **After:** + - `contextLimit: 10` returns the last 10 messages (most recent) in chronological order + - Agents now have access to the most relevant recent context + - InMemoryStorage was already working correctly and remains unchanged + + Changes: + - LibSQLStorage: Modified query to use `ORDER BY DESC` with `LIMIT`, then reverse results + - PostgreSQL: Modified query to use `ORDER BY DESC` with `LIMIT`, then reverse results + - Supabase: Modified query to use `ascending: false` with `limit`, then reverse results + + This ensures consistent behavior across all storage implementations where context limits provide the most recent messages, improving AI agent response quality and relevance. + +- [#418](https://github.com/VoltAgent/voltagent/pull/418) [`aa024c1`](https://github.com/VoltAgent/voltagent/commit/aa024c1a7c643b2aff7a5fd0d150c87f8a9a1858) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: tool errors now properly recorded in conversation history and allow agent retry - #349 + + Fixed critical issues where tool execution errors were halting agent runs and not being recorded in conversation/event history. This prevented agents from retrying failed tool calls and lost important error context. + + **Before:** + - Tool errors would throw and halt agent execution immediately + - No error events or steps were recorded in conversation history + - Agents couldn't learn from or retry after tool failures + - Error context was lost, making debugging difficult + + **After:** + - Tool errors are caught and handled gracefully + - Error events (`tool:error`) are created and persisted + - Error steps are added to conversation history with full error details + - Agents can continue execution and retry within `maxSteps` limit + - Tool lifecycle hooks (onEnd) are properly called even on errors + + Changes: + - Added `handleToolError` helper method to centralize error handling logic + - Modified `generateText` to catch and handle tool errors without halting execution + - Updated `streamText` onError callback to use the same error handling + - Ensured tool errors are saved to memory storage for context retention + + This improves agent resilience and debugging capabilities when working with potentially unreliable tools. + +## 0.1.66 + +### Patch Changes + +- [`1f8ce22`](https://github.com/VoltAgent/voltagent/commit/1f8ce226fec449f16f1dce6c2b96cef7030eff3a) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: zod peer dependency to allow flexible versioning (^3.24.2 instead of 3.24.2) to resolve npm install conflicts + +## 0.1.65 + +### Patch Changes + +- [#404](https://github.com/VoltAgent/voltagent/pull/404) [`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: integrate comprehensive logging system with @voltagent/logger support + + Enhanced the core package with a flexible logging infrastructure that supports both the built-in ConsoleLogger and the advanced @voltagent/logger package. This update provides better debugging, monitoring, and observability capabilities across all VoltAgent components. + + **Key Changes:** + - **Logger Integration**: VoltAgent, Agents, and Workflows now accept a logger instance for centralized logging + - **Default ConsoleLogger**: Built-in logger for quick prototyping with basic timestamp formatting + - **Logger Propagation**: Parent loggers automatically create child loggers for agents and workflows + - **Context Preservation**: Child loggers maintain context (component names, IDs) throughout execution + - **Environment Variables**: Support for `VOLTAGENT_LOG_LEVEL` and `LOG_LEVEL` environment variables + - **Backward Compatible**: Existing code works without changes, using the default ConsoleLogger + + **Installation:** + + ```bash + # npm + npm install @voltagent/logger + + # pnpm + pnpm add @voltagent/logger + + # yarn + yarn add @voltagent/logger + ``` + + **Usage Examples:** + + ```typescript + // Using default ConsoleLogger + const voltAgent = new VoltAgent({ agents: [agent] }); + + // Using @voltagent/logger for production + import { createPinoLogger } from "@voltagent/logger"; + + const logger = createPinoLogger({ level: "info" }); + const voltAgent = new VoltAgent({ + logger, + agents: [agent], + }); + ``` + + This update lays the foundation for comprehensive observability and debugging capabilities in VoltAgent applications. + +- Updated dependencies [[`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726)]: + - @voltagent/internal@0.0.6 + +## 0.1.64 + +### Patch Changes + +- [`aea3c78`](https://github.com/VoltAgent/voltagent/commit/aea3c78c467e42c53d10ad6c0890514dff861fca) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: replace `npm-check-updates` with native package manager support + + This update replaces the `npm-check-updates` dependency with a native implementation that properly detects installed package versions and supports all major package managers (`npm`, `pnpm`, `yarn`, `bun`). + + ### Key improvements: + - **Native package manager support**: Automatically detects and uses npm, pnpm, yarn, or bun based on lock files + - **Accurate version detection**: Shows actual installed versions instead of package.json semver ranges (e.g., shows 1.0.63 instead of ^1.0.0) + - **Monorepo compatibility**: Smart version detection that works with hoisted dependencies and workspace protocols + - **Non-blocking startup**: Update checks run in background without slowing down application startup (70-80% faster) + - **Intelligent caching**: 1-hour cache with package.json hash validation to reduce redundant checks + - **Major version updates**: Fixed update commands to use add/install instead of update to handle breaking changes + - **Restart notifications**: Added requiresRestart flag to API responses for better UX + + ### Technical details: + - Removed execSync calls in favor of direct file system operations + - Parallel HTTP requests to npm registry for better performance + - Multiple fallback methods for version detection (direct access → require.resolve → tree search) + - Background processing with Promise.resolve().then() for true async behavior + + This change significantly improves the developer experience with faster startup times and more accurate dependency information. + +## 0.1.63 + +### Patch Changes + +- [`6089462`](https://github.com/VoltAgent/voltagent/commit/60894629cef27950021da323390f455098b5bce2) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: prevent duplicate column errors in LibSQL agent_history table initialization + + Fixed a first-time database initialization error where the `migrateAgentHistorySchema` function was attempting to add `userId` and `conversationId` columns that already existed in newly created `agent_history` tables. + + The issue occurred because: + - The CREATE TABLE statement now includes `userId` and `conversationId` columns by default + - The migration function was still trying to add these columns, causing "duplicate column name" SQLite errors + + Changes: + - Added check in `migrateAgentHistorySchema` to skip migration if both columns already exist + - Properly set migration flag to prevent unnecessary migration attempts + - Ensured backward compatibility for older databases that need the migration + +## 0.1.62 + +### Patch Changes + +- [`6fadbb0`](https://github.com/VoltAgent/voltagent/commit/6fadbb098fe40d8b658aa3386e6126fea155f117) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: createAsyncIterableStream import issue + +- Updated dependencies [[`6fadbb0`](https://github.com/VoltAgent/voltagent/commit/6fadbb098fe40d8b658aa3386e6126fea155f117)]: + - @voltagent/internal@0.0.5 + +## 0.1.61 + +### Patch Changes + +- [#391](https://github.com/VoltAgent/voltagent/pull/391) [`57c4874`](https://github.com/VoltAgent/voltagent/commit/57c4874d4d4807c50242b2e34ab9574fc6129888) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: improve workflow execute API with context-based pattern + + Breaking change: The workflow execute functions now use a context-based API for better developer experience and extensibility. + + **Before:** + + ```typescript + .andThen({ + execute: async (data, state) => { + // old API with separate parameters + return { ...data, processed: true }; + } + }) + ``` + + **After:** + + ```typescript + .andThen({ + execute: async ({ data, state, getStepData }) => { + // new API with context object + const previousStep = getStepData("step-id"); + return { ...data, processed: true }; + } + }) + ``` + + This change applies to: + - `andThen` execute functions + - `andAgent` prompt functions + - `andWhen` condition functions + - `andTap` execute functions + + The new API provides: + - Better TypeScript inference + - Access to previous step data via `getStepData` + - Cleaner, more extensible design + +- [#399](https://github.com/VoltAgent/voltagent/pull/399) [`da66f86`](https://github.com/VoltAgent/voltagent/commit/da66f86d92a278007c2d3386d22b482fa70d93ff) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add suspend/resume functionality for workflows + + **Workflows can now be paused and resumed!** Perfect for human-in-the-loop processes, waiting for external events, or managing long-running operations. + + ## Two Ways to Suspend + + ### 1. Internal Suspension (Inside Steps) + + ```typescript + const approvalWorkflow = createWorkflowChain({ + id: "simple-approval", + name: "Simple Approval", + input: z.object({ item: z.string() }), + result: z.object({ approved: z.boolean() }), + }).andThen({ + id: "wait-for-approval", + execute: async ({ data, suspend, resumeData }) => { + // If resuming, return the decision + if (resumeData) { + return { approved: resumeData.approved }; + } + + // Otherwise suspend and wait + await suspend("Waiting for approval"); + }, + }); + + // Run and resume + const execution = await approvalWorkflow.run({ item: "New laptop" }); + const result = await execution.resume({ approved: true }); + ``` + + ### 2. External Suspension (From Outside) + + ```typescript + import { createSuspendController } from "@voltagent/core"; + + // Create controller + const controller = createSuspendController(); + + // Run workflow with controller + const execution = await workflow.run(input, { + suspendController: controller, + }); + + // Pause from outside (e.g., user clicks pause) + controller.suspend("User paused workflow"); + + // Resume later + if (execution.status === "suspended") { + const result = await execution.resume(); + } + ``` + + ## Key Features + - ⏸️ **Internal suspension** with `await suspend()` inside steps + - 🎮 **External control** with `createSuspendController()` + - 📝 **Type-safe resume data** with schemas + - 💾 **State persists** across server restarts + - 🚀 **Simplified API** - just pass `suspendController`, no need for separate `signal` + + 📚 **For detailed documentation: [https://voltagent.dev/docs/workflows/suspend-resume](https://voltagent.dev/docs/workflows/suspend-resume)** + +- [#401](https://github.com/VoltAgent/voltagent/pull/401) [`4a7145d`](https://github.com/VoltAgent/voltagent/commit/4a7145debd66c7b1dfb953608e400b6c1ed02db7) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve TypeScript performance issues by fixing Zod dependency configuration (#377) + + Moved Zod from direct dependencies to peer dependencies in @voltagent/vercel-ai to prevent duplicate Zod installations that were causing TypeScript server slowdowns. Also standardized Zod versions across the workspace to ensure consistency. + + Changes: + - @voltagent/vercel-ai: Moved `zod` from dependencies to peerDependencies + - @voltagent/docs-mcp: Updated `zod` from `^3.23.8` to `3.24.2` + - @voltagent/with-postgres: Updated `zod` from `^3.24.2` to `3.24.2` (removed caret) + + This fix significantly improves TypeScript language server performance by ensuring only one Zod version is processed, eliminating the "Type instantiation is excessively deep and possibly infinite" errors that users were experiencing. + +## 0.1.60 + +### Patch Changes + +- [#371](https://github.com/VoltAgent/voltagent/pull/371) [`6ddedc2`](https://github.com/VoltAgent/voltagent/commit/6ddedc2b9be9c3dc4978dc53198a43c2cba74945) Thanks [@omeraplak](https://github.com/omeraplak)! - This update adds a powerful, type-safe workflow engine to `@voltagent/core`. You can now build complex, multi-step processes that chain together your code, AI models, and conditional logic with full type-safety and built-in observability. + + Here is a quick example of what you can build: + + ```typescript + import { createWorkflowChain, Agent, VoltAgent } from "@voltagent/core"; + import { z } from "zod"; + import { VercelAIProvider } from "@voltagent/vercel-ai"; + import { openai } from "@ai-sdk/openai"; + + // Define an agent to use in the workflow + const analyzerAgent = new Agent({ + name: "Analyzer", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + instructions: "You are a text analyzer.", + }); + + // 1. Define the workflow chain + const workflow = createWorkflowChain({ + id: "greeting-analyzer", + name: "Greeting Analyzer", + input: z.object({ name: z.string() }), + result: z.object({ greeting: z.string(), sentiment: z.string() }), + }) + .andThen({ + id: "create-greeting", + execute: async ({ name }) => ({ greeting: `Hello, ${name}!` }), + }) + .andAgent( + (data) => `Analyze the sentiment of this greeting: "${data.greeting}"`, + analyzerAgent, + { + schema: z.object({ sentiment: z.string().describe("e.g., positive") }), + } + ); + + // You can run the chain directly + const result = await workflow.run({ name: "World" }); + ``` + + To make your workflow runs visible in the **VoltOps Console** for debugging and monitoring, register both the workflow and its agents with a `VoltAgent` instance: + + ![VoltOps Workflow Observability](https://cdn.voltagent.dev/docs/workflow-observability-demo.gif) + + ```typescript + // 2. Register the workflow and agent to enable observability + new VoltAgent({ + agents: { + analyzerAgent, + }, + workflows: { + workflow, + }, + }); + + // Now, when you run the workflow, its execution will appear in VoltOps. + await workflow.run({ name: "Alice" }); + ``` + + This example showcases the fluent API, data flow between steps, type-safety, and integration with Agents, which are the core pillars of this new feature. + +## 0.1.59 + +### Patch Changes + +- [#382](https://github.com/VoltAgent/voltagent/pull/382) [`86acef0`](https://github.com/VoltAgent/voltagent/commit/86acef01dd6ce2e213b13927136c32bcf1078484) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: Allow workflow.run to accept userContext, conversationId, and userId and pass along to all steps & agents + +- [#375](https://github.com/VoltAgent/voltagent/pull/375) [`1f55501`](https://github.com/VoltAgent/voltagent/commit/1f55501ec7a221002c11a3a0e87779c8f1379bed) Thanks [@SashankMeka1](https://github.com/SashankMeka1)! - feat(core): MCPServerConfig timeouts - #363. + + Add MCPServerConfig timeouts + + ```ts + const mcpConfig = new MCPConfiguration({ + servers: { + filesystem: { + type: "stdio", + command: "npx", + args: ["-y", "@modelcontextprotocol/server-filesystem", path.resolve("./data")], + timeout: 10000, + }, + }, + }); + ``` + +- [#385](https://github.com/VoltAgent/voltagent/pull/385) [`bfb13c3`](https://github.com/VoltAgent/voltagent/commit/bfb13c390a8ff59ad61a08144a5f6fa0439d25b7) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix(core): Add back the result for a workflow execution, as the result was removed due to change in state management process + +- [#384](https://github.com/VoltAgent/voltagent/pull/384) [`757219c`](https://github.com/VoltAgent/voltagent/commit/757219cc76e7f0320074230788012714f91e81bb) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - feat(core): Add ability to pass hooks into the generate functions (i.e. streamText) that do not update/mutate the agent hooks + + ### Usage + + ```ts + const agent = new Agent({ + name: "My Agent with Hooks", + instructions: "An assistant demonstrating hooks", + llm: provider, + model: openai("gpt-4o"), + hooks: myAgentHooks, + }); + + // both the myAgentHooks and the hooks passed in the generateText method will be called + await agent.generateText("Hello, how are you?", { + hooks: { + onEnd: async ({ context }) => { + console.log("End of generation but only on this invocation!"); + }, + }, + }); + ``` + +- [#381](https://github.com/VoltAgent/voltagent/pull/381) [`b52cdcd`](https://github.com/VoltAgent/voltagent/commit/b52cdcd2d8072fa93011e14c41841b6ff8a97b0b) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - feat: Add ability to tap into workflow without mutating the data by adding the `andTap` step + + ### Usage + + The andTap step is useful when you want to tap into the workflow without mutating the data, for example: + + ```ts + const workflow = createWorkflowChain(config) + .andTap({ + execute: async (data) => { + console.log("🔄 Translating text:", data); + }, + }) + .andTap({ + id: "sleep", + execute: async (data) => { + console.log("🔄 Sleeping for 1 second"); + await new Promise((resolve) => setTimeout(resolve, 1000)); + return data; + }, + }) + .andThen({ + execute: async (data) => { + return { ...data, translatedText: data.translatedText }; + }, + }) + .run({ + originalText: "Hello, world!", + targetLanguage: "en", + }); + ``` + + You will notice that the `andTap` step is not included in the result, BUT it is `awaited` and `executed` before the next step, so you can block processing safely if needed. + +## 0.1.58 + +### Patch Changes + +- [#342](https://github.com/VoltAgent/voltagent/pull/342) [`8448674`](https://github.com/VoltAgent/voltagent/commit/84486747b1b40eaca315b900c56fd2ad976780ea) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - feat: add Workflow support (alpha) + + **🧪 ALPHA FEATURE: Workflow orchestration system is now available for early testing.** This feature allows you to create complex, multi-step agent workflows with chaining API and conditional branching. The API is experimental and may change in future releases. + + ## 📋 Usage + + **Basic Workflow Chain Creation:** + + ```typescript + import { openai } from "@ai-sdk/openai"; + import { Agent, VoltAgent, createWorkflowChain } from "@voltagent/core"; + import { VercelAIProvider } from "@voltagent/vercel-ai"; + import { z } from "zod"; + + // Create workflow agents + const analyzerAgent = new Agent({ + name: "DataAnalyzer", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + instructions: "Analyze input data and extract key insights with confidence scores", + }); + + const processorAgent = new Agent({ + name: "DataProcessor", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + instructions: "Process and transform analyzed data into structured format", + }); + + const reporterAgent = new Agent({ + name: "ReportGenerator", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + instructions: "Generate comprehensive reports from processed data", + }); + + // Create workflow chain + const dataProcessingWorkflow = createWorkflowChain({ + id: "data-processing-workflow", + name: "Data Processing Pipeline", + purpose: "Analyze, process, and generate reports from raw data", + input: z.object({ + rawData: z.string(), + analysisType: z.string(), + }), + result: z.object({ + originalData: z.string(), + analysisResults: z.object({ + insights: z.array(z.string()), + confidence: z.number().min(0).max(1), + }), + processedData: z.object({ + summary: z.string(), + keyPoints: z.array(z.string()), + }), + finalReport: z.string(), + processingTime: z.number(), + }), + }) + .andAgent( + async (data) => { + return `Analyze the following data: ${data.rawData}. Focus on ${data.analysisType} analysis.`; + }, + analyzerAgent, + { + schema: z.object({ + insights: z.array(z.string()), + confidence: z.number().min(0).max(1), + }), + } + ) + .andThen({ + execute: async (data, state) => { + // Skip processing if confidence is too low + if (data.confidence < 0.5) { + throw new Error(`Analysis confidence too low: ${data.confidence}`); + } + return { + analysisResults: data, + originalData: state.input.rawData, + }; + }, + }) + .andAgent( + async (data, state) => { + return `Process these insights: ${JSON.stringify(data.analysisResults.insights)}`; + }, + processorAgent, + { + schema: z.object({ + summary: z.string(), + keyPoints: z.array(z.string()), + }), + } + ) + .andAgent( + async (data, state) => { + return `Generate a final report based on: ${JSON.stringify(data)}`; + }, + reporterAgent, + { + schema: z.object({ + finalReport: z.string(), + }), + } + ) + .andThen({ + execute: async (data, state) => { + return { + ...data, + processingTime: Date.now() - state.startAt.getTime(), + }; + }, + }); + + // Execute workflow + const result = await dataProcessingWorkflow.run({ + rawData: "User input data...", + analysisType: "sentiment", + }); + + console.log(result.analysisResults); // Analysis results + console.log(result.finalReport); // Generated report + ``` + + **Conditional Logic Example:** + + ```typescript + const conditionalWorkflow = createWorkflowChain({ + id: "conditional-workflow", + name: "Smart Processing Pipeline", + purpose: "Process data based on complexity level", + input: z.object({ + data: z.string(), + }), + result: z.object({ + complexity: z.string(), + processedData: z.string(), + processingMethod: z.string(), + }), + }) + .andAgent( + async (data) => { + return `Analyze complexity of: ${data.data}`; + }, + validatorAgent, + { + schema: z.object({ + complexity: z.enum(["low", "medium", "high"]), + }), + } + ) + .andThen({ + execute: async (data, state) => { + // Route to different processing based on complexity + if (data.complexity === "low") { + return { ...data, processingMethod: "simple" }; + } else { + return { ...data, processingMethod: "advanced" }; + } + }, + }) + .andAgent( + async (data, state) => { + if (data.processingMethod === "simple") { + return `Simple processing for: ${state.input.data}`; + } else { + return `Advanced processing for: ${state.input.data}`; + } + }, + data.processingMethod === "simple" ? simpleProcessor : advancedProcessor, + { + schema: z.object({ + processedData: z.string(), + }), + } + ); + ``` + + **⚠️ Alpha Limitations:** + - **NOT READY FOR PRODUCTION** - This is an experimental feature + - Visual flow UI integration is in development + - Error handling and recovery mechanisms are basic + - Performance optimizations pending + - **API may change significantly** based on community feedback + - Limited documentation and examples + + **🤝 Help Shape Workflows:** + We need your feedback to make Workflows awesome! The API will evolve based on real-world usage and community input. + - 💬 **[Join our Discord](https://s.voltagent.dev/discord)**: Share ideas, discuss use cases, and get help + - 🐛 **[GitHub Issues](https://github.com/VoltAgent/voltagent/issues)**: Report bugs, request features, or suggest improvements + - 🚀 **Early Adopters**: Build experimental projects and share your learnings + - 📝 **API Feedback**: Tell us what's missing, confusing, or could be better + + **🔄 Future Plans:** + - React Flow integration for visual workflow editor + - Advanced error handling and retry mechanisms + - Workflow templates and presets + - Real-time execution monitoring + - Comprehensive documentation and tutorials + +## 0.1.57 + +### Patch Changes + +- [`894be7f`](https://github.com/VoltAgent/voltagent/commit/894be7feb97630c10e036cf3691974a5e351472c) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: export PromptContent type to resolve "cannot be named" TypeScript error + +## 0.1.56 + +### Patch Changes + +- [#351](https://github.com/VoltAgent/voltagent/pull/351) [`f8f8d04`](https://github.com/VoltAgent/voltagent/commit/f8f8d04340d6f9609450f6ae000c9fe1d71072d7) Thanks [@alasano](https://github.com/alasano)! - fix: add historyMemory option to Agent configuration + +## 0.1.55 + +### Patch Changes + +- [#352](https://github.com/VoltAgent/voltagent/pull/352) [`b7dcded`](https://github.com/VoltAgent/voltagent/commit/b7dcdedfbbdda5bfb1885317b59b4d4e2495c956) Thanks [@alasano](https://github.com/alasano)! - fix(core): store and use userContext from Agent constructor + +- [#345](https://github.com/VoltAgent/voltagent/pull/345) [`822739c`](https://github.com/VoltAgent/voltagent/commit/822739c901bbc679cd11dd2c9df99cd041fc40c7) Thanks [@thujee](https://github.com/thujee)! - fix: moves zod from direct to dev dependency to avoid version conflicts in consuming app + +## 0.1.54 + +### Patch Changes + +- [#346](https://github.com/VoltAgent/voltagent/pull/346) [`5100f7f`](https://github.com/VoltAgent/voltagent/commit/5100f7f9419db7e26aa18681b0ad3c09c0957b10) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: export PromptContent type to resolve "cannot be named" TypeScript error + + Fixed a TypeScript compilation error where users would get "cannot be named" errors when exporting variables that use `InstructionsDynamicValue` type. This occurred because `InstructionsDynamicValue` references `PromptContent` type, but `PromptContent` was not being re-exported from the public API. + + **Before:** + + ```typescript + export type { DynamicValueOptions, DynamicValue, PromptHelper }; + ``` + + **After:** + + ```typescript + export type { DynamicValueOptions, DynamicValue, PromptHelper, PromptContent }; + ``` + + This ensures that all types referenced by public API types are properly exported, preventing TypeScript compilation errors when users export agents or variables that use dynamic instructions. + +## 0.1.53 + +### Patch Changes + +- [#343](https://github.com/VoltAgent/voltagent/pull/343) [`096bda4`](https://github.com/VoltAgent/voltagent/commit/096bda41d5333e110da2c034e57f60b4ce7b9076) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: extend SubAgent functionality with support for multiple execution methods and flexible configuration API + + **SubAgent functionality has been significantly enhanced to support all four agent execution methods (generateText, streamText, generateObject, streamObject) with flexible per-subagent configuration.** Previously, SubAgents only supported `streamText` method. Now you can configure each SubAgent to use different execution methods with custom options and schemas. + + ## 📋 Usage + + **New SubAgent API with createSubagent():** + + ```typescript + import { Agent, createSubagent } from "@voltagent/core"; + import { VercelAIProvider } from "@voltagent/vercel-ai"; + import { openai } from "@ai-sdk/openai"; + import { z } from "zod"; + + // Define schemas for structured output + const analysisSchema = z.object({ + summary: z.string(), + keyFindings: z.array(z.string()), + confidence: z.number().min(0).max(1), + }); + + const reportSchema = z.object({ + title: z.string(), + sections: z.array( + z.object({ + heading: z.string(), + content: z.string(), + priority: z.enum(["high", "medium", "low"]), + }) + ), + }); + + // Create specialized subagents + const dataAnalyst = new Agent({ + name: "DataAnalyst", + instructions: "Analyze data and provide structured insights", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + + const reportGenerator = new Agent({ + name: "ReportGenerator", + instructions: "Generate comprehensive reports", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + + const summaryWriter = new Agent({ + name: "SummaryWriter", + instructions: "Create concise summaries", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + + // Supervisor with enhanced SubAgent configuration + const supervisor = new Agent({ + name: "AdvancedSupervisor", + instructions: "Coordinate specialized agents with different methods", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + subAgents: [ + // ✅ OLD STYLE: Direct agent (defaults to streamText) - still supported + summaryWriter, + + // ✅ NEW STYLE: generateObject with schema + createSubagent({ + agent: dataAnalyst, + method: "generateObject", + schema: analysisSchema, + options: { + temperature: 0.3, // Precise analysis + maxTokens: 1500, + }, + }), + + // ✅ NEW STYLE: streamObject with schema + createSubagent({ + agent: reportGenerator, + method: "streamObject", + schema: reportSchema, + options: { + temperature: 0.5, + maxTokens: 2000, + }, + }), + + // ✅ NEW STYLE: generateText with custom options + createSubagent({ + agent: summaryWriter, + method: "generateText", + options: { + temperature: 0.7, // Creative writing + maxTokens: 800, + }, + }), + ], + }); + ``` + + **Backward Compatibility:** + + ```typescript + // ✅ OLD STYLE: Still works (defaults to streamText) + const supervisor = new Agent({ + name: "Supervisor", + subAgents: [agent1, agent2, agent3], // Direct Agent instances + // ... other config + }); + ``` + +- [#344](https://github.com/VoltAgent/voltagent/pull/344) [`5d908c5`](https://github.com/VoltAgent/voltagent/commit/5d908c5a83569848c91d86c5ecfcd3d4d4ffae42) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add supervisorConfig API for customizing supervisor agent behavior + + **SupervisorConfig API enables complete control over supervisor agent system messages and behavior** when working with SubAgents, allowing users to customize guidelines, override system messages, and control memory inclusion. + + ## 🎯 What's New + + **🚀 SupervisorConfig API:** + + ```typescript + const supervisor = new Agent({ + name: "Custom Supervisor", + instructions: "Coordinate specialized tasks", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + subAgents: [writerAgent, editorAgent], + + supervisorConfig: { + // Complete system message override + systemMessage: "You are TaskBot. Use delegate_task to assign work.", + + // Add custom rules to default guidelines + customGuidelines: ["Always verify sources", "Include confidence levels"], + + // Control memory inclusion (default: true) + includeAgentsMemory: false, + }, + }); + ``` + + ## 🔧 Configuration Options + - **`systemMessage`**: Complete system message override - replaces default template + - **`customGuidelines`**: Add custom rules to default supervisor guidelines + - **`includeAgentsMemory`**: Control whether previous agent interactions are included + +- [#340](https://github.com/VoltAgent/voltagent/pull/340) [`ef778c5`](https://github.com/VoltAgent/voltagent/commit/ef778c543acb229edd049da2e7bbed2ae5fe40cf) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: separate conversation memory from history storage when memory: false + + When `memory: false` is set, conversation memory and user messages should be disabled, but history storage and timeline events should continue working. Previously, both conversation memory and history storage were being disabled together. + + **Before:** + + ```typescript + const agent = new Agent({ + name: "TestAgent", + instructions: "You are a helpful assistant", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + memory: false, // ❌ Disabled both conversation memory AND history storage + }); + + // Result: No conversation context + No history/events tracking + ``` + + **After:** + + ```typescript + const agent = new Agent({ + name: "TestAgent", + instructions: "You are a helpful assistant", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + memory: false, // ✅ Disables only conversation memory, history storage remains active + }); + + // Result: No conversation context + History/events tracking still works + ``` + + **What this means for users:** + - ✅ `memory: false` now only disables conversation memory (user messages and context) + - ✅ History storage and timeline events continue to work for debugging and observability + - ✅ Agent interactions are still tracked in VoltAgent Console + - ✅ Tools and sub-agents can still access operation context and history + + This change improves the observability experience while maintaining the expected behavior of disabling conversation memory when `memory: false` is set. + + Fixes the issue where setting `memory: false` would prevent history and events from being tracked in the VoltAgent Console. + +## 0.1.52 + +### Patch Changes + +- [#338](https://github.com/VoltAgent/voltagent/pull/338) [`3e9a863`](https://github.com/VoltAgent/voltagent/commit/3e9a8631c0e4774d0623825263040ad3a14c23d0) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: implement configurable maxSteps parameter with parent-child agent inheritance + + **Agents now support configurable maxSteps parameter at the API level, allowing fine-grained control over computational resources. Parent agents automatically pass their effective maxSteps to subagents, ensuring consistent resource management across the agent hierarchy.** + + ## 🎯 What's New + + **🚀 Configurable MaxSteps System** + - **API-Level Configuration**: Set maxSteps dynamically for any agent call + - **Agent-Level Defaults**: Configure default maxSteps when creating agents + - **Automatic Inheritance**: SubAgents automatically inherit parent's effective maxSteps + - **Configurable Supervisor**: Enhanced supervisor system message generation with agent memory + + ## 📋 Usage Examples + + **API-Level MaxSteps Configuration:** + + ```typescript + import { Agent, VoltAgent } from "@voltagent/core"; + import { VercelAIProvider } from "@voltagent/vercel-ai"; + import { openai } from "@ai-sdk/openai"; + + // Create agent with default maxSteps + const agent = new Agent({ + name: "AssistantAgent", + instructions: "Help users with their questions", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + maxSteps: 10, // Default maxSteps for this agent + }); + + // Usage examples: + + // 1. Use agent's default maxSteps (10) + const result1 = await agent.generateText("Simple question"); + + // 2. Override with API-level maxSteps + const result2 = await agent.generateText("Complex question", { + maxSteps: 25, // Override agent's default (10) with API-level (25) + }); + + // 3. Stream with custom maxSteps + const stream = await agent.streamText("Long conversation", { + maxSteps: 50, // Allow more steps for complex interactions + }); + + // 4. Generate object with specific maxSteps + const objectResult = await agent.generateObject("Create structure", schema, { + maxSteps: 5, // Limit steps for simple object generation + }); + ``` + + **Parent-Child Agent Inheritance:** + + ```typescript + // Create specialized subagents + const contentCreator = new Agent({ + name: "ContentCreator", + instructions: "Create engaging content", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + + const formatter = new Agent({ + name: "Formatter", + instructions: "Format and style content", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + + // Create supervisor with subagents + const supervisor = new Agent({ + name: "Supervisor", + instructions: "Coordinate content creation and formatting", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + subAgents: [contentCreator, formatter], + maxSteps: 15, // Agent limit + }); + + // Parent-child inheritance examples: + + // 1. Use supervisor's default maxSteps + const result1 = await supervisor.generateText("Create a blog post"); + // Supervisor uses: maxSteps: 15 + // SubAgents inherit: maxSteps: 15 + + // 2. Override with API-level maxSteps + const result2 = await supervisor.generateText("Create a blog post", { + maxSteps: 8, // API-level override + }); + // Supervisor uses: maxSteps: 8 + // SubAgents inherit: maxSteps: 8 + + // 3. Direct subagent calls use their own defaults + const directResult = await contentCreator.generateText("Create content"); + // Uses contentCreator's own maxSteps or default calculation + ``` + + **REST API Usage:** + + ```bash + # with generateText + curl -X POST http://localhost:3141/agents/my-agent-id/generate \ + -H "Content-Type: application/json" \ + -d '{ + "input": "Explain quantum physics", + "options": { + "maxSteps": 10, + } + }' + + # with streamText + curl -N -X POST http://localhost:3141/agents/supervisor-agent-id/stream \ + -H "Content-Type: application/json" \ + -d '{ + "input": "Coordinate research and writing workflow", + "options": { + "maxSteps": 15, + } + }' + ``` + + This enhancement provides fine-grained control over agent computational resources while maintaining backward compatibility with existing agent configurations. + +## 0.1.51 + +### Patch Changes + +- [#333](https://github.com/VoltAgent/voltagent/pull/333) [`721372a`](https://github.com/VoltAgent/voltagent/commit/721372a59edab1095ee608488ca96b81326fd1cc) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add abort signal support for operation cancellation + + **Abort Signal Support enables graceful cancellation of agent operations.** Users can now cancel expensive operations when they navigate away or change their minds. + + ## 🎯 Key Features + - **Stream API Cancellation**: `/stream` and `/stream-object` endpoints now handle client disconnection automatically + - **Agent Method Support**: All agent methods (`generateText`, `streamText`, `generateObject`, `streamObject`) support abort signals + - **SubAgent Propagation**: Abort signals cascade through sub-agent hierarchies + + ## 📋 Usage + + ```typescript + // Create AbortController + const abortController = new AbortController(); + + // Cancel when user navigates away or clicks stop + window.addEventListener("beforeunload", () => abortController.abort()); + + // Stream request with abort signal + const response = await fetch("http://localhost:3141/agents/my-agent/stream", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ + input: "Write a very long story...", + options: { maxTokens: 4000 }, + }), + signal: abortController.signal, // ✅ Automatic cancellation + }); + + // Manual cancellation after 10 seconds + setTimeout(() => abortController.abort(), 10000); + ``` + + This prevents unnecessary computation and improves resource efficiency. + +## 0.1.50 + +### Patch Changes + +- [#329](https://github.com/VoltAgent/voltagent/pull/329) [`9406552`](https://github.com/VoltAgent/voltagent/commit/94065520f51a1743be91c3b5be9ab5370d47f666) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: userContext changes in onEnd hook now properly reflected in final response + + The `userContext` changes made in the `onEnd` hook were not being reflected in the final response from `.generateText()` and `.generateObject()` methods. This was because the userContext snapshot was taken before the `onEnd` hook execution, causing any modifications made within the hook to be lost. + + **Before**: + + ```typescript + const agent = new Agent({ + name: "TestAgent", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + hooks: createHooks({ + onEnd: ({ context }) => { + // This change was lost in the final response + context.userContext.set("agent_response", "bye"); + }, + }), + }); + + const response = await agent.generateText("Hello", { + userContext: new Map([["agent_response", "hi"]]), + }); + + console.log(response.userContext?.get("agent_response")); // ❌ "hi" (old value) + ``` + + **After**: + + ```typescript + const agent = new Agent({ + name: "TestAgent", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + hooks: createHooks({ + onEnd: ({ context }) => { + // This change is now preserved in the final response + context.userContext.set("agent_response", "bye"); + }, + }), + }); + + const response = await agent.generateText("Hello", { + userContext: new Map([["agent_response", "hi"]]), + }); + + console.log(response.userContext?.get("agent_response")); // ✅ "bye" (updated value) + ``` + +## 0.1.49 + +### Patch Changes + +- [#324](https://github.com/VoltAgent/voltagent/pull/324) [`8da1ecc`](https://github.com/VoltAgent/voltagent/commit/8da1eccd0332d1f9037085e16cb0b7d5afaac479) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add enterprise-grade VoltOps Prompt Management platform with team collaboration and analytics + + **VoltOps Prompt Management transforms VoltAgent from a simple framework into an enterprise-grade platform for managing AI prompts at scale.** Think "GitHub for prompts" with built-in team collaboration, version control, environment management, and performance analytics. + + ## 🎯 What's New + + **🚀 VoltOps Prompt Management Platform** + - **Team Collaboration**: Non-technical team members can edit prompts via web console + - **Version Control**: Full prompt versioning with commit messages and rollback capabilities + - **Environment Management**: Promote prompts from development → staging → production with labels + - **Template Variables**: Dynamic `{{variable}}` substitution with validation + - **Performance Analytics**: Track prompt effectiveness, costs, and usage patterns + + ## 📋 Usage Examples + + **Basic VoltOps Setup:** + + ```typescript + import { Agent, VoltAgent, VoltOpsClient } from "@voltagent/core"; + import { VercelAIProvider } from "@voltagent/vercel-ai"; + import { openai } from "@ai-sdk/openai"; + + // 1. Initialize VoltOps client + const voltOpsClient = new VoltOpsClient({ + publicKey: process.env.VOLTAGENT_PUBLIC_KEY, + secretKey: process.env.VOLTAGENT_SECRET_KEY, + }); + + // 2. Create agent with VoltOps prompts + const supportAgent = new Agent({ + name: "SupportAgent", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + instructions: async ({ prompts }) => { + return await prompts.getPrompt({ + promptName: "customer-support-prompt", + label: process.env.NODE_ENV === "production" ? "production" : "development", + variables: { + companyName: "VoltAgent Corp", + tone: "friendly and professional", + supportLevel: "premium", + }, + }); + }, + }); + + // 3. Initialize VoltAgent with global VoltOps client + const voltAgent = new VoltAgent({ + agents: { supportAgent }, + voltOpsClient: voltOpsClient, + }); + ``` + +- [#324](https://github.com/VoltAgent/voltagent/pull/324) [`8da1ecc`](https://github.com/VoltAgent/voltagent/commit/8da1eccd0332d1f9037085e16cb0b7d5afaac479) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: introduce VoltOpsClient as unified replacement for deprecated telemetryExporter + + **VoltOpsClient** is the new unified platform client for VoltAgent that replaces the deprecated `telemetryExporter`. + + ## 📋 Usage + + ```typescript + import { Agent, VoltAgent, VoltOpsClient } from "@voltagent/core"; + + const voltOpsClient = new VoltOpsClient({ + publicKey: process.env.VOLTAGENT_PUBLIC_KEY, + secretKey: process.env.VOLTAGENT_SECRET_KEY, + observability: true, // Enable observability - default is true + prompts: true, // Enable prompt management - default is true + }); + + const voltAgent = new VoltAgent({ + agents: { myAgent }, + voltOpsClient: voltOpsClient, // ✅ New approach + }); + ``` + + ## 🔄 Migration from telemetryExporter + + Replace the deprecated `telemetryExporter` with the new `VoltOpsClient`: + + ```diff + import { Agent, VoltAgent } from "@voltagent/core"; + - import { VoltAgentExporter } from "@voltagent/core"; + + import { VoltOpsClient } from "@voltagent/core"; + + const voltAgent = new VoltAgent({ + agents: { myAgent }, + - telemetryExporter: new VoltAgentExporter({ + + voltOpsClient: new VoltOpsClient({ + publicKey: process.env.VOLTAGENT_PUBLIC_KEY, + secretKey: process.env.VOLTAGENT_SECRET_KEY, + - baseUrl: "https://api.voltagent.dev", + }), + }); + ``` + + ## ⚠️ Deprecation Notice + + `telemetryExporter` is now **deprecated** and will be removed in future versions: + + ```typescript + // ❌ Deprecated - Don't use + new VoltAgent({ + agents: { myAgent }, + telemetryExporter: new VoltAgentExporter({...}), // Deprecated! + }); + + // ✅ Correct approach + new VoltAgent({ + agents: { myAgent }, + voltOpsClient: new VoltOpsClient({...}), + }); + ``` + + **For migration guide, see:** `/docs/observability/developer-console#migration-guide` + + ## 🔧 Advanced Configuration + + ```typescript + const voltOpsClient = new VoltOpsClient({ + publicKey: process.env.VOLTAGENT_PUBLIC_KEY, + secretKey: process.env.VOLTAGENT_SECRET_KEY, + baseUrl: "https://api.voltagent.dev", // Default + observability: true, // Enable observability export - default is true + prompts: false, // Observability only - default is true + promptCache: { + enabled: true, // Enable prompt cache - default is true + ttl: 300, // 5 minute cache - default is 300 + maxSize: 100, // Max size of the cache - default is 100 + }, + }); + ``` + +- Updated dependencies [[`8da1ecc`](https://github.com/VoltAgent/voltagent/commit/8da1eccd0332d1f9037085e16cb0b7d5afaac479)]: + - @voltagent/internal@0.0.4 + +## 0.1.48 + +### Patch Changes + +- [#296](https://github.com/VoltAgent/voltagent/pull/296) [`4621e09`](https://github.com/VoltAgent/voltagent/commit/4621e09118fc652d8a05f40758b02d5108e38967) Thanks [@Ajay-Satish-01](https://github.com/Ajay-Satish-01)! - The `UserContext` was properly propagated through tools and hooks, but was not being returned in the final response from `.generateText()` and `.generateObject()` methods. This prevented post-processing logic from accessing the UserContext data. + + **Before**: + + ```typescript + const result = await agent.generateText(...); + + result.userContext; // ❌ Missing userContext + ``` + + **After**: + + ```typescript + const result = await agent.generateText(...); + + return result.userContext; // ✅ Includes userContext + + **How users can see the changes**: + + Now users can access the `userContext` in the response from all agent methods: + + // Set custom context before calling the agent + const customContext = new Map(); + customContext.set("sessionId", "user-123"); + customContext.set("requestId", "req-456"); + + // generateText now returns userContext + const result = await agent.generateText("Hello", { + userContext: customContext, + }); + + // Access the userContext from the response + console.log(result.userContext.get("sessionId")); // 'user-123' + console.log(result.userContext.get("requestId")); // 'req-456' + + // GenerateObject + const objectResult = await agent.generateObject("Create a summary", schema, { + userContext: customContext, + }); + console.log(objectResult.userContext.get("sessionId")); // 'user-123' + + // Streaming methods + const streamResult = await agent.streamText("Hello", { + userContext: customContext, + }); + console.log(streamResult.userContext?.get("sessionId")); // 'user-123' + ``` + + Fixes: [#283](https://github.com/VoltAgent/voltagent/issues/283) + +## 0.1.47 + +### Patch Changes + +- [#311](https://github.com/VoltAgent/voltagent/pull/311) [`1f7fa14`](https://github.com/VoltAgent/voltagent/commit/1f7fa140fcc4062fe85220e61f276e439392b0b4) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix(core, vercel-ui): Currently the `convertToUIMessages` function does not handle tool calls in steps correctly as it does not properly default filter non-tool related steps for sub-agents, same as the `data-stream` functions and in addition in the core the `operationContext` does not have the `subAgent` fields set correctly. + + ### Changes + - deprecated `isSubAgentStreamPart` in favor of `isSubAgent` for universal use + - by default `convertToUIMessages` now filters out non-tool related steps for sub-agents + - now able to exclude specific parts or steps (from OperationContext) in `convertToUIMessages` + + *** + + ### Internals + + New utils were added to the internal package: + - `isObject` + - `isFunction` + - `isPlainObject` + - `isEmptyObject` + - `isNil` + - `hasKey` + +- Updated dependencies [[`1f7fa14`](https://github.com/VoltAgent/voltagent/commit/1f7fa140fcc4062fe85220e61f276e439392b0b4)]: + - @voltagent/internal@0.0.3 + +## 0.1.46 + +### Patch Changes + +- [#309](https://github.com/VoltAgent/voltagent/pull/309) [`b81a6b0`](https://github.com/VoltAgent/voltagent/commit/b81a6b09c33d95f7e586501cc058ae8381c854c4) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix(core): Default to filtering `error` types from the `fullStream` to allow for error handling to happen properly + +## 0.1.45 + +### Patch Changes + +- [#308](https://github.com/VoltAgent/voltagent/pull/308) [`33afe6e`](https://github.com/VoltAgent/voltagent/commit/33afe6ef40ef56c501f7fa69be42da730f87d29d) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: subAgents now share conversation steps and context with parent agents + + SubAgents automatically inherit and contribute to their parent agent's operation context, including `userContext` and conversation history. This creates a unified workflow where all agents (supervisor + subagents) add steps to the same `conversationSteps` array, providing complete visibility and traceability across the entire agent hierarchy. + + ## Usage + + ```typescript + import { Agent, createHooks } from "@voltagent/core"; + import { VercelAIProvider } from "@voltagent/vercel-ai"; + import { openai } from "@ai-sdk/openai"; + + // SubAgent automatically receives parent's context + const translatorAgent = new Agent({ + name: "Translator Agent", + hooks: createHooks({ + onStart: ({ context }) => { + // Access parent's userContext automatically + const projectId = context.userContext.get("projectId"); + const language = context.userContext.get("language"); + console.log(`Translating for project ${projectId} to ${language}`); + }, + }), + instructions: "You are a skilled translator", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + + // Supervisor agent with context + const supervisorAgent = new Agent({ + name: "Supervisor Agent", + subAgents: [translatorAgent], + hooks: createHooks({ + onEnd: ({ context }) => { + // Access complete workflow history from all agents + const allSteps = context.conversationSteps; + console.log(`Total workflow steps: ${allSteps.length}`); + // Includes supervisor's delegate_task calls + subagent's processing steps + }, + }), + instructions: "Coordinate translation workflow", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + + // Usage - context automatically flows to subagents + const response = await supervisorAgent.streamText("Translate this text", { + userContext: new Map([ + ["projectId", "proj-123"], + ["language", "Spanish"], + ]), + }); + + // Final context includes data from both supervisor and subagents + console.log("Project:", response.userContext?.get("projectId")); + ``` + +- [#306](https://github.com/VoltAgent/voltagent/pull/306) [`b8529b5`](https://github.com/VoltAgent/voltagent/commit/b8529b53313fa97e941ecacb8c1555205de49c19) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix(core): Revert original fix by @omeraplak to pass the task role as "user" instead of prompt to prevent errors in providers such as Anthropic, Grok, etc. + +## 0.1.44 + +### Patch Changes + +- Updated dependencies [[`94de46a`](https://github.com/VoltAgent/voltagent/commit/94de46ab2b7ccead47a539e93c72b357f17168f6)]: + - @voltagent/internal@0.0.2 + +## 0.1.43 + +### Patch Changes + +- [#287](https://github.com/VoltAgent/voltagent/pull/287) [`4136a9b`](https://github.com/VoltAgent/voltagent/commit/4136a9bd1a2f687bf009858dda4e56a50574c9c2) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: optimize streamText/generateText/genereteObject/streamObject performance with background event publishing and memory operations + + Significantly improved agent response times by optimizing blocking operations during stream initialization. Stream start time reduced by 70-80% while maintaining full conversation context quality. + + ## What's Fixed + - **Background Event Publishing**: Timeline events now publish asynchronously, eliminating blocking delays + - **Memory Operations**: Context loading optimized with background conversation setup and input saving + + ## Performance Impact + - Stream initialization: ~300-500ms → ~150-200ms + - 70-80% faster response start times + - Zero impact on conversation quality or history tracking + + Perfect for production applications requiring fast AI interactions. + +- [#287](https://github.com/VoltAgent/voltagent/pull/287) [`4136a9b`](https://github.com/VoltAgent/voltagent/commit/4136a9bd1a2f687bf009858dda4e56a50574c9c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add `deepClone` function to `object-utils` module + + Added a new `deepClone` utility function to the object-utils module for creating deep copies of complex JavaScript objects. This utility provides safe cloning of nested objects, arrays, and primitive values while handling circular references and special object types. + + Usage: + + ```typescript + import { deepClone } from "@voltagent/core/utils/object-utils"; + + const original = { + nested: { + array: [1, 2, { deep: "value" }], + date: new Date(), + }, + }; + + const cloned = deepClone(original); + // cloned is completely independent from original + ``` + + This utility is particularly useful for agent state management, configuration cloning, and preventing unintended mutations in complex data structures. + +- [#287](https://github.com/VoltAgent/voltagent/pull/287) [`4136a9b`](https://github.com/VoltAgent/voltagent/commit/4136a9bd1a2f687bf009858dda4e56a50574c9c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: optimize performance with new `BackgroundQueue` utility class and non-blocking background operations + + Added a new `BackgroundQueue` utility class for managing background operations with enhanced reliability, performance, and order preservation. Significantly improved agent response times by optimizing blocking operations during stream initialization and agent interactions. + + ## Performance Improvements + + **All blocking operations have been moved to background jobs**, resulting in significant performance gains: + - **Agent execution is no longer blocked** by history persistence, memory operations, or telemetry exports + - **3-5x faster response times** for agent interactions due to non-blocking background processing + - **Zero blocking delays** during agent conversations and tool executions + + ## Stream Operations Optimized + - **Background Event Publishing**: Timeline events now publish asynchronously, eliminating blocking delays + - **Memory Operations**: Context loading optimized with background conversation setup and input saving + - **Stream initialization**: ~300-500ms → ~150-200ms (70-80% faster response start times) + - **Zero impact on conversation quality or history tracking** + + Perfect for production applications requiring fast AI interactions with enhanced reliability and order preservation. + +## 0.1.42 + +### Patch Changes + +- [#286](https://github.com/VoltAgent/voltagent/pull/286) [`73632ea`](https://github.com/VoltAgent/voltagent/commit/73632ea229917ab4042bb58b61d5e6dbd9b72804) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - Fixed issue where fullStream processing was erroring due to inability to access a Nil value + +## 0.1.41 + +### Patch Changes + +- [`7705108`](https://github.com/VoltAgent/voltagent/commit/7705108317a8166bb1324838f99691ad8879b94d) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: reverted subagent handoff message role from `user` back to `system`. + +## 0.1.40 + +### Patch Changes + +- [#284](https://github.com/VoltAgent/voltagent/pull/284) [`003ea5e`](https://github.com/VoltAgent/voltagent/commit/003ea5e0aab1e3e4a1398ed5ebf54b20fc9e27f3) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: subagent task delegation system message handling for Google Gemini compatibility + + Fixed an issue where subagent task delegation was sending tasks as system messages, which caused errors with certain AI models like Google Gemini that have strict system message requirements. The task delegation now properly sends tasks as user messages instead of system messages. + + This change improves compatibility across different AI providers, particularly Google Gemini, which expects a specific system message format and doesn't handle multiple or dynamic system messages well during task delegation workflows. + +- [#284](https://github.com/VoltAgent/voltagent/pull/284) [`003ea5e`](https://github.com/VoltAgent/voltagent/commit/003ea5e0aab1e3e4a1398ed5ebf54b20fc9e27f3) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: userContext reference preservation in agent history initialization + +## 0.1.39 + +### Patch Changes + +- [#276](https://github.com/VoltAgent/voltagent/pull/276) [`937ccf8`](https://github.com/VoltAgent/voltagent/commit/937ccf8bf84a4261ee9ed2c94aab9f8c49ab69bd) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add dynamic agent parameters with userContext support - #272 + + Added dynamic agent parameters functionality that allows agents to adapt their behavior, models, and tools based on runtime context. This enables personalized, multi-tenant, and role-based AI experiences. + + ## Features + - **Dynamic Instructions**: Agent instructions that change based on user context + - **Dynamic Models**: Different AI models based on subscription tiers or user roles + - **Dynamic Tools**: Role-based tool access and permissions + - **REST API Integration**: Full userContext support via REST endpoints + - **VoltOps Integration**: Visual testing interface for dynamic agents + + ## Usage + + ```typescript + import { Agent } from "@voltagent/core"; + import { VercelAIProvider } from "@voltagent/vercel-ai"; + import { openai } from "@ai-sdk/openai"; + + const dynamicAgent = new Agent({ + name: "Adaptive Assistant", + + // Dynamic instructions based on user context + instructions: ({ userContext }) => { + const role = (userContext.get("role") as string) || "user"; + const language = (userContext.get("language") as string) || "English"; + + if (role === "admin") { + return `You are an admin assistant with special privileges. Respond in ${language}.`; + } else { + return `You are a helpful assistant. Respond in ${language}.`; + } + }, + + // Dynamic model selection based on subscription tier + model: ({ userContext }) => { + const tier = (userContext.get("tier") as string) || "free"; + + switch (tier) { + case "premium": + return openai("gpt-4o"); + case "pro": + return openai("gpt-4o-mini"); + default: + return openai("gpt-3.5-turbo"); + } + }, + + // Dynamic tools based on user role + tools: ({ userContext }) => { + const role = (userContext.get("role") as string) || "user"; + + if (role === "admin") { + return [basicTool, adminTool]; + } else { + return [basicTool]; + } + }, + + llm: new VercelAIProvider(), + }); + + // Usage with userContext + const userContext = new Map([ + ["role", "admin"], + ["language", "Spanish"], + ["tier", "premium"], + ]); + + const response = await dynamicAgent.generateText("Help me manage the system", { userContext }); + ``` + + ## REST API Integration + + Dynamic agents work seamlessly with REST API endpoints: + + ```bash + # POST /agents/my-agent/text + curl -X POST http://localhost:3141/agents/my-agent/text \ + -H "Content-Type: application/json" \ + -d '{ + "input": "I need admin access", + "options": { + "userContext": { + "role": "admin", + "language": "Spanish", + "tier": "premium" + } + } + }' + ``` + + Perfect for multi-tenant applications, role-based access control, subscription tiers, internationalization, and A/B testing scenarios. + +## 0.1.38 + +### Patch Changes + +- [#267](https://github.com/VoltAgent/voltagent/pull/267) [`f7e5a34`](https://github.com/VoltAgent/voltagent/commit/f7e5a344a5bcb63d1a225e580f01dfa5886b6a01) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: subagent event ordering and stream injection + + Fixed an issue where subagent events were not being properly included in the main agent's stream before subagent completion. Previously, subagent events (text-delta, tool-call, tool-result, etc.) would sometimes miss being included in the parent agent's real-time stream, causing incomplete event visibility for monitoring and debugging. + +## 0.1.37 + +### Patch Changes + +- [#252](https://github.com/VoltAgent/voltagent/pull/252) [`88f2d06`](https://github.com/VoltAgent/voltagent/commit/88f2d0682413d27a7ac2d1d8cd502fd9c665e547) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add userId and conversationId support to agent history tables + + This release adds comprehensive support for `userId` and `conversationId` fields in agent history tables across all memory storage implementations, enabling better conversation tracking and user-specific history management. + + ### New Features + - **Agent History Enhancement**: Added `userId` and `conversationId` columns to agent history tables + - **Cross-Implementation Support**: Consistent implementation across PostgreSQL, Supabase, LibSQL, and In-Memory storage + - **Automatic Migration**: Safe schema migrations for existing installations + - **Backward Compatibility**: Existing history entries remain functional + + ### Migration Notes + + **PostgreSQL & Supabase**: Automatic schema migration with user-friendly SQL scripts + **LibSQL**: Seamless column addition with proper indexing + **In-Memory**: No migration required, immediate support + + ### Technical Details + - **Database Schema**: Added `userid TEXT` and `conversationid TEXT` columns (PostgreSQL uses lowercase) + - **Indexing**: Performance-optimized indexes for new columns + - **Migration Safety**: Non-destructive migrations with proper error handling + - **API Consistency**: Unified interface across all storage implementations + +- [#261](https://github.com/VoltAgent/voltagent/pull/261) [`b63fe67`](https://github.com/VoltAgent/voltagent/commit/b63fe675dfca9121862a9dd67a0fae5d39b9db90) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: subAgent event propagation in fullStream for enhanced streaming experience + + Fixed an issue where SubAgent events (text-delta, tool-call, tool-result, reasoning, source, finish) were not being properly forwarded to the parent agent's fullStream. This enhancement improves the streaming experience by ensuring all SubAgent activities are visible in the parent stream with proper metadata (subAgentId, subAgentName) for UI filtering and display. + +## 0.1.36 + +### Patch Changes + +- [#251](https://github.com/VoltAgent/voltagent/pull/251) [`be0cf47`](https://github.com/VoltAgent/voltagent/commit/be0cf47ec6e9640119d752dd6b608097d06bf69d) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add fullStream support and subagent event forwarding + + Added `fullStream` support to the core agent system for enhanced streaming with detailed chunk types (text-delta, tool-call, tool-result, reasoning, finish, error). Also improved event forwarding between subagents for better multi-agent workflows. SubAgent events are now fully forwarded to parent agents, with filtering moved to the client side for better flexibility. + + Real-world example: + + ```typescript + const response = await agent.streamText("What's the weather in Istanbul?"); + + if (response.fullStream) { + for await (const chunk of response.fullStream) { + // Filter out SubAgent text, reasoning, and source events for cleaner UI + if (chunk.subAgentId && chunk.subAgentName) { + if (chunk.type === "text" || chunk.type === "reasoning" || chunk.type === "source") { + continue; // Skip these events from sub-agents + } + } + + switch (chunk.type) { + case "text-delta": + process.stdout.write(chunk.textDelta); // Stream text in real-time + break; + case "tool-call": + console.log(`🔧 Using tool: ${chunk.toolName}`); + break; + case "tool-result": + console.log(`✅ Tool completed: ${chunk.toolName}`); + break; + case "reasoning": + console.log(`🤔 AI thinking: ${chunk.reasoning}`); + break; + case "finish": + console.log(`\n✨ Done! Tokens used: ${chunk.usage?.totalTokens}`); + break; + } + } + } + ``` + +- [#248](https://github.com/VoltAgent/voltagent/pull/248) [`a3b4e60`](https://github.com/VoltAgent/voltagent/commit/a3b4e604e6f79281903ff0c28422e6ee2863b340) Thanks [@alasano](https://github.com/alasano)! - feat(core): add streamable HTTP transport support for MCP + - Upgrade @modelcontextprotocol/sdk from 1.10.1 to 1.12.1 + - Add support for streamable HTTP transport (the newer MCP protocol) + - Modified existing `type: "http"` to use automatic selection with streamable HTTP → SSE fallback + - Added two new transport types: + - `type: "sse"` - Force SSE transport only (legacy) + - `type: "streamable-http"` - Force streamable HTTP only (no fallback) + - Maintain full backward compatibility - existing `type: "http"` configurations continue to work via automatic fallback + + Fixes #246 + +- [#247](https://github.com/VoltAgent/voltagent/pull/247) [`20119ad`](https://github.com/VoltAgent/voltagent/commit/20119ada182ec5f313a7f46956218d593180e096) Thanks [@Ajay-Satish-01](https://github.com/Ajay-Satish-01)! - feat(core): Enhanced server configuration with unified `server` object and Swagger UI control + + Server configuration options have been enhanced with a new unified `server` object for better organization and flexibility while maintaining full backward compatibility. + + **What's New:** + - **Unified Server Configuration:** All server-related options (`autoStart`, `port`, `enableSwaggerUI`, `customEndpoints`) are now grouped under a single `server` object. + - **Swagger UI Control:** Fine-grained control over Swagger UI availability with environment-specific defaults. + - **Backward Compatibility:** Legacy individual options are still supported but deprecated. + - **Override Logic:** New `server` object takes precedence over deprecated individual options. + + **Migration Guide:** + + **New Recommended Usage:** + + ```typescript + import { Agent, VoltAgent } from "@voltagent/core"; + import { VercelAIProvider } from "@voltagent/vercel-ai"; + import { openai } from "@ai-sdk/openai"; + + const agent = new Agent({ + name: "My Assistant", + instructions: "A helpful assistant", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + + new VoltAgent({ + agents: { agent }, + server: { + autoStart: true, + port: 3000, + enableSwaggerUI: true, + customEndpoints: [ + { + path: "/health", + method: "get", + handler: async (c) => c.json({ status: "ok" }), + }, + ], + }, + }); + ``` + + **Legacy Usage (Deprecated but Still Works):** + + ```typescript + new VoltAgent({ + agents: { agent }, + autoStart: true, // @deprecated - use server.autoStart + port: 3000, // @deprecated - use server.port + customEndpoints: [], // @deprecated - use server.customEndpoints + }); + ``` + + **Mixed Usage (Server Object Overrides):** + + ```typescript + new VoltAgent({ + agents: { agent }, + autoStart: false, // This will be overridden + server: { + autoStart: true, // This takes precedence + }, + }); + ``` + + **Swagger UI Defaults:** + - Development (`NODE_ENV !== 'production'`): Swagger UI enabled + - Production (`NODE_ENV === 'production'`): Swagger UI disabled + - Override with `server.enableSwaggerUI: true/false` + + Resolves [#241](https://github.com/VoltAgent/voltagent/issues/241) + +## 0.1.35 + +### Patch Changes + +- [#240](https://github.com/VoltAgent/voltagent/pull/240) [`8605863`](https://github.com/VoltAgent/voltagent/commit/860586377bff11b9e7ba80e06fd26b0098bd334a) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - trim the system prompt so we don't have extra newlines and offset text + +## 0.1.34 + +### Patch Changes + +- [#238](https://github.com/VoltAgent/voltagent/pull/238) [`ccdba7a`](https://github.com/VoltAgent/voltagent/commit/ccdba7ac58e284dcda9f6b7bec2c8d2e69892940) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: user messages saving with proper content serialization + + Fixed an issue where user messages were not being saved correctly to storage due to improper content formatting. The message content is now properly stringified when it's not already a string, ensuring consistent storage format across PostgreSQL and LibSQL implementations. + +## 0.1.33 + +### Patch Changes + +- [#236](https://github.com/VoltAgent/voltagent/pull/236) [`5d39cdc`](https://github.com/VoltAgent/voltagent/commit/5d39cdc68c4ec36ec2f0bf86a29dbf1225644416) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: Remove userId parameter from addMessage method + + Simplified the `addMessage` method signature by removing the `userId` parameter. This change makes the API cleaner and more consistent with the conversation-based approach where user context is handled at the conversation level. + + ### Changes + - **Removed**: `userId` parameter from `addMessage` method + - **Before**: `addMessage(message: MemoryMessage, userId: string, conversationId: string)` + - **After**: `addMessage(message: MemoryMessage, conversationId: string)` + + ### Migration Guide + + If you were calling `addMessage` with a `userId` parameter, simply remove it: + + ```typescript + // Before + await memory.addMessage(message, conversationId, userId); + + // After + await memory.addMessage(message, conversationId); + ``` + + ### Rationale + + User context is now properly managed at the conversation level, making the API more intuitive and reducing parameter complexity. The user association is handled through the conversation's `userId` property instead of requiring it on every message operation. + + **Breaking Change:** + + This is a minor breaking change. Update your `addMessage` calls to remove the `userId` parameter. + +- [#235](https://github.com/VoltAgent/voltagent/pull/235) [`16c2a86`](https://github.com/VoltAgent/voltagent/commit/16c2a863d3ecdc09f09219bd40f2dbf1d789194d) Thanks [@alasano](https://github.com/alasano)! - fix: onHandoff hook invocation to pass arguments as object instead of positional parameters + +- [#233](https://github.com/VoltAgent/voltagent/pull/233) [`0d85f0e`](https://github.com/VoltAgent/voltagent/commit/0d85f0e960dbc6e8df6a79a16c775ca7a34043bb) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: adding in missing changeset from [PR #226](https://github.com/VoltAgent/voltagent/pull/226) + +## 0.1.32 + +### Patch Changes + +- [#215](https://github.com/VoltAgent/voltagent/pull/215) [`f2f4539`](https://github.com/VoltAgent/voltagent/commit/f2f4539af7722f25a5aad9f01c2b7b5e50ba51b8) Thanks [@Ajay-Satish-01](https://github.com/Ajay-Satish-01)! - This release introduces powerful new methods for managing conversations with user-specific access control and improved developer experience. + + ### Simple Usage Example + + ```typescript + // Get all conversations for a user + const conversations = await storage.getUserConversations("user-123").limit(10).execute(); + + console.log(conversations); + + // Get first conversation and its messages + const conversation = conversations[0]; + if (conversation) { + const messages = await storage.getConversationMessages(conversation.id); + console.log(messages); + } + ``` + + ### Pagination Support + + ```typescript + // Get paginated conversations + const result = await storage.getPaginatedUserConversations("user-123", 1, 20); + console.log(result.conversations); // Array of conversations + console.log(result.hasMore); // Boolean indicating if more pages exist + ``` + +- [#229](https://github.com/VoltAgent/voltagent/pull/229) [`0eba8a2`](https://github.com/VoltAgent/voltagent/commit/0eba8a265c35241da74324613e15801402f7b778) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: migrate the provider streams to `AsyncIterableStream` + + Example: + + ```typescript + const stream = createAsyncIterableStream( + new ReadableStream({ + start(controller) { + controller.enqueue("Hello"); + controller.enqueue(", "); + controller.enqueue("world!"); + controller.close(); + }, + }) + ); + + for await (const chunk of stream) { + console.log(chunk); + } + + // in the agent + const result = await agent.streamObject({ + messages, + model: "test-model", + schema, + }); + + for await (const chunk of result.objectStream) { + console.log(chunk); + } + ``` + + New exports: + - `createAsyncIterableStream` + - `type AsyncIterableStream` + +## 0.1.31 + +### Patch Changes + +- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 + +- [#223](https://github.com/VoltAgent/voltagent/pull/223) [`80fd3c0`](https://github.com/VoltAgent/voltagent/commit/80fd3c069de4c23116540a55082b891c4b376ce6) Thanks [@omeraplak](https://github.com/omeraplak)! - Add userContext support to retrievers for tracking references and metadata + + Retrievers can now store additional information (like references, sources, citations) in userContext that can be accessed from agent responses. This enables tracking which documents were used to generate responses, perfect for citation systems and audit trails. + + ```ts + class MyRetriever extends BaseRetriever { + async retrieve(input: string, options: RetrieveOptions): Promise { + // Find relevant documents + const docs = this.findRelevantDocs(input); + + const references = docs.map((doc) => ({ + id: doc.id, + title: doc.title, + source: doc.source, + })); + options.userContext.set("references", references); + + return docs.map((doc) => doc.content).join("\n"); + } + } + + // Access references from response + const response = await agent.generateText("What is VoltAgent?"); + const references = response.userContext?.get("references"); + ``` + +## 0.1.30 + +### Patch Changes + +- [#201](https://github.com/VoltAgent/voltagent/pull/201) [`04dd320`](https://github.com/VoltAgent/voltagent/commit/04dd3204455b09dc490d1bdfbd0cfeea13c3c409) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: include modelParameters in agent event metadata + + This adds the `modelParameters` field to agent event metadata to improve observability and debugging of model-specific behavior during agent execution. + +## 0.1.29 + +### Patch Changes + +- [#191](https://github.com/VoltAgent/voltagent/pull/191) [`07d99d1`](https://github.com/VoltAgent/voltagent/commit/07d99d133232babf78ba4e1c32fe235d5b3c9944) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - Remove console based logging in favor of a dev-only logger that will not output logs in production environments by leveraging the NODE_ENV + +- [#196](https://github.com/VoltAgent/voltagent/pull/196) [`67b0e7e`](https://github.com/VoltAgent/voltagent/commit/67b0e7ea704d23bf9efb722c0b0b4971d0974153) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add `systemPrompt` and `messages` array to metadata for display on VoltOps Platform + +## 0.1.28 + +### Patch Changes + +- [#189](https://github.com/VoltAgent/voltagent/pull/189) [`07138fc`](https://github.com/VoltAgent/voltagent/commit/07138fc85ef27c9136d303233559f6b358ad86de) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - Added the 'purpose' field to agents (subagents) to provide a limited description of the purpose of the agent to the supervisor instead of passing the instructions for the subagent directly to the supervisor + + ```ts + const storyAgent = new Agent({ + name: "Story Agent", + purpose: "A story writer agent that creates original, engaging short stories.", + instructions: "You are a creative story writer. Create original, engaging short stories.", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + ``` + + > The supervisor agent's system prompt is automatically modified to include instructions on how to manage its subagents effectively. It lists the available subagents and their `purpose` and provides guidelines for delegation, communication, and response aggregation. + +- [#186](https://github.com/VoltAgent/voltagent/pull/186) [`adad41a`](https://github.com/VoltAgent/voltagent/commit/adad41a930e338c4683306b9dbffec22096eba5c) Thanks [@necatiozmen](https://github.com/necatiozmen)! - chore: update "VoltAgent Console" -> "VoltOps Platform" + +## 0.1.27 + +### Patch Changes + +- [#126](https://github.com/VoltAgent/voltagent/pull/126) [`2c47bc1`](https://github.com/VoltAgent/voltagent/commit/2c47bc1e9cd845cc60e6e9d7e86df40c98b82614) Thanks [@fav-devs](https://github.com/fav-devs)! - feat: add custom endpoints feature to VoltAgent API server, allowing developers to extend the API with their own endpoints + + ```typescript + import { VoltAgent } from "@voltagent/core"; + + new VoltAgent({ + agents: { myAgent }, + customEndpoints: [ + { + path: "/api/health", + method: "get", + handler: async (c) => { + return c.json({ + success: true, + data: { status: "healthy" }, + }); + }, + }, + ], + }); + ``` + +## 0.1.26 + +### Patch Changes + +- [#181](https://github.com/VoltAgent/voltagent/pull/181) [`1b4a9fd`](https://github.com/VoltAgent/voltagent/commit/1b4a9fd78b84d9b758120380cb80a940c2354020) Thanks [@omeraplak](https://github.com/omeraplak)! - Implement comprehensive error handling for streaming endpoints - #170 + - **Backend**: Added error handling to `streamRoute` and `streamObjectRoute` with onError callbacks, safe stream operations, and multiple error layers (setup, iteration, stream errors) + - **Documentation**: Added detailed error handling guide with examples for fetch-based SSE streaming + + Fixes issue where streaming errors weren't being communicated to frontend users, leaving them without feedback when API calls failed during streaming operations. + +## 0.1.25 + +### Patch Changes + +- [`13d25b4`](https://github.com/VoltAgent/voltagent/commit/13d25b4033c3a4b41d501e954e2893b50553d8d4) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: update zod-from-json-schema dependency version to resolve MCP tools compatibility issues + +## 0.1.24 + +### Patch Changes + +- [#176](https://github.com/VoltAgent/voltagent/pull/176) [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: removed `@n8n/json-schema-to-zod` dependency - #177 + +- [#176](https://github.com/VoltAgent/voltagent/pull/176) [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275) Thanks [@omeraplak](https://github.com/omeraplak)! - The `error` column has been deprecated and replaced with `statusMessage` column for better consistency and clearer messaging. The old `error` column is still supported for backward compatibility but will be removed in a future major version. + + Changes: + - Deprecated `error` column (still functional) + - Improved error handling and status reporting + +## 0.1.23 + +### Patch Changes + +- [`b2f423d`](https://github.com/VoltAgent/voltagent/commit/b2f423d55ee031fc02b0e8eda5175cfe15e38a42) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: zod import issue - #161 + + Fixed incorrect zod import that was causing OpenAPI type safety errors. Updated to use proper import from @hono/zod-openapi package. + +## 0.1.22 + +### Patch Changes + +- [#149](https://github.com/VoltAgent/voltagent/pull/149) [`0137a4e`](https://github.com/VoltAgent/voltagent/commit/0137a4e67deaa2490b4a07f9de5f13633f2c473c) Thanks [@VenomHare](https://github.com/VenomHare)! - Added JSON schema support for REST API `generateObject` and `streamObject` functions. The system now accepts JSON schemas which are internally converted to Zod schemas for validation. This enables REST API usage where Zod schemas cannot be directly passed. #87 + + Additional Changes: + - Included the JSON schema from `options.schema` in the system message for the `generateObject` and `streamObject` functions in both `anthropic-ai` and `groq-ai` providers. + - Enhanced schema handling to convert JSON schemas to Zod internally for seamless REST API compatibility. + +- [#151](https://github.com/VoltAgent/voltagent/pull/151) [`4308b85`](https://github.com/VoltAgent/voltagent/commit/4308b857ab2133f6ca60f22271dcf30bad8b4c08) Thanks [@process.env.POSTGRES_USER](https://github.com/process.env.POSTGRES_USER)! - feat: Agent memory can now be stored in PostgreSQL database. This feature enables agents to persistently store conversation history in PostgreSQL. - #16 + + ## Usage + + ```tsx + import { openai } from "@ai-sdk/openai"; + import { Agent, VoltAgent } from "@voltagent/core"; + import { PostgresStorage } from "@voltagent/postgres"; + import { VercelAIProvider } from "@voltagent/vercel-ai"; + + // Configure PostgreSQL Memory Storage + const memoryStorage = new PostgresStorage({ + // Read connection details from environment variables + connection: { + host: process.env.POSTGRES_HOST || "localhost", + port: Number.parseInt(process.env.POSTGRES_PORT || "5432"), + database: process.env.POSTGRES_DB || "voltagent", + || "postgres", + password: process.env.POSTGRES_PASSWORD || "password", + ssl: process.env.POSTGRES_SSL === "true", + }, + + // Alternative: Use connection string + // connection: process.env.DATABASE_URL || "postgresql://postgres:password@localhost:5432/voltagent", + + // Optional: Customize table names + tablePrefix: "voltagent_memory", + + // Optional: Configure connection pool + maxConnections: 10, + + // Optional: Set storage limit for messages + storageLimit: 100, + + // Optional: Enable debug logging for development + debug: process.env.NODE_ENV === "development", + }); + + // Create agent with PostgreSQL memory + const agent = new Agent({ + name: "PostgreSQL Memory Agent", + description: "A helpful assistant that remembers conversations using PostgreSQL.", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + memory: memoryStorage, // Use the configured PostgreSQL storage + }); + ``` + +## 0.1.21 + +### Patch Changes + +- [#160](https://github.com/VoltAgent/voltagent/pull/160) [`03ed437`](https://github.com/VoltAgent/voltagent/commit/03ed43723cd56f29ac67088f0624a88632a14a1b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: improved event system architecture for better observability + + We've updated the event system architecture to improve observability capabilities. The system includes automatic migrations to maintain backward compatibility, though some events may not display perfectly due to the architectural changes. Overall functionality remains stable and most features work as expected. + + No action required - the system will automatically handle the migration process. If you encounter any issues, feel free to reach out on [Discord](https://s.voltagent.dev/discord) for support. + + **What's Changed:** + - Enhanced event system for better observability and monitoring + - Automatic database migrations for seamless upgrades + - Improved agent history tracking and management + + **Migration Notes:** + - Backward compatibility is maintained through automatic migrations + - Some legacy events may display differently but core functionality is preserved + - No manual intervention needed - migrations run automatically + + **Note:** + Some events may not display perfectly due to architecture changes, but the system will automatically migrate and most functionality will work as expected. + +## 0.1.20 + +### Patch Changes + +- [#155](https://github.com/VoltAgent/voltagent/pull/155) [`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c) Thanks [@baseballyama](https://github.com/baseballyama)! - chore: update `tsconfig.json`'s `target` to `ES2022` + +- [#162](https://github.com/VoltAgent/voltagent/pull/162) [`b164bd0`](https://github.com/VoltAgent/voltagent/commit/b164bd014670452cb162b388f03565db992767af) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: pin zod version to 3.24.2 to avoid "Type instantiation is excessively deep and possibly infinite" error + + Fixed compatibility issues between different zod versions that were causing TypeScript compilation errors. This issue occurs when multiple packages use different patch versions of zod (e.g., 3.23.x vs 3.24.x), leading to type instantiation depth problems. By pinning to 3.24.2, we ensure consistent behavior across all packages. + + See: https://github.com/colinhacks/zod/issues/3435 + +- [#158](https://github.com/VoltAgent/voltagent/pull/158) [`9412cf0`](https://github.com/VoltAgent/voltagent/commit/9412cf0633f20d6b77c87625fc05e9e216936758) Thanks [@baseballyama](https://github.com/baseballyama)! - chore(core): fixed a type error that occurred in src/server/api.ts + +## 0.1.19 + +### Patch Changes + +- [#128](https://github.com/VoltAgent/voltagent/pull/128) [`d6cf2e1`](https://github.com/VoltAgent/voltagent/commit/d6cf2e194d47352565314c93f1a4e477701563c1) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add VoltAgentExporter for production observability 🚀 + + VoltAgentExporter enables persistent storage and monitoring of AI agents in production environments: + - Send agent telemetry data to the VoltAgent cloud platform + - Access historical execution data through your project dashboard + - Monitor deployed agents over time + - Debug production issues with comprehensive tracing + + To configure your project with VoltAgentExporter, visit the new tracing setup page at [`https://console.voltagent.dev/tracing-setup`](https://console.voltagent.dev/tracing-setup). + + For more information about production tracing with VoltAgentExporter, see our [developer documentation](https://voltagent.dev/docs/observability/developer-console/#production-tracing-with-voltagentexporter). + +## 0.1.18 + +### Patch Changes + +- [#113](https://github.com/VoltAgent/voltagent/pull/113) [`0a120f4`](https://github.com/VoltAgent/voltagent/commit/0a120f4bf1b71575a4b6c67c94104633c58e1410) Thanks [@nhc](https://github.com/nhc)! - export createTool from toolkit + +## 0.1.17 + +### Patch Changes + +- [#106](https://github.com/VoltAgent/voltagent/pull/106) [`b31c8f2`](https://github.com/VoltAgent/voltagent/commit/b31c8f2ad1b4bf242b197a094300cb3397109a94) Thanks [@omeraplak](https://github.com/omeraplak)! - Enabled `userContext` to be passed from supervisor agents to their sub-agents, allowing for consistent contextual data across delegated tasks. This ensures that sub-agents can operate with the necessary shared information provided by their parent agent. + + ```typescript + // Supervisor Agent initiates an operation with userContext: + const supervisorContext = new Map(); + supervisorContext.set("globalTransactionId", "tx-supervisor-12345"); + + await supervisorAgent.generateText( + "Delegate analysis of transaction tx-supervisor-12345 to the financial sub-agent.", + { userContext: supervisorContext } + ); + + // In your sub-agent's hook definition (e.g., within createHooks): + onStart: ({ agent, context }: OnStartHookArgs) => { + const inheritedUserContext = context.userContext; // Access the OperationContext's userContext + const transactionId = inheritedUserContext.get("globalTransactionId"); + console.log(`[${agent.name}] Hook: Operating with Transaction ID: ${transactionId}`); + // Expected log: [FinancialSubAgent] Hook: Operating with Transaction ID: tx-supervisor-12345 + }; + + // Example: Inside a Tool executed by the Sub-Agent + // In your sub-agent tool's execute function: + execute: async (params: { someParam: string }, options?: ToolExecutionContext) => { + if (options?.operationContext?.userContext) { + const inheritedUserContext = options.operationContext.userContext; + const transactionId = inheritedUserContext.get("globalTransactionId"); + console.log(`[SubAgentTool] Tool: Processing with Transaction ID: ${transactionId}`); + // Expected log: [SubAgentTool] Tool: Processing with Transaction ID: tx-supervisor-12345 + return `Processed ${params.someParam} for transaction ${transactionId}`; + } + return "Error: OperationContext not available for tool"; + }; + ``` + +## 0.1.14 + +### Patch Changes + +- [#102](https://github.com/VoltAgent/voltagent/pull/102) [`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3) Thanks [@omeraplak](https://github.com/omeraplak)! - refactor: use 'instructions' field for Agent definitions in examples - #88 + + Updated documentation examples (READMEs, docs, blogs) and relevant package code examples to use the `instructions` field instead of `description` when defining `Agent` instances. + + This change aligns the examples with the preferred API usage for the `Agent` class, where `instructions` provides behavioral guidance to the agent/LLM. This prepares for the eventual deprecation of the `description` field specifically for `Agent` class definitions. + + **Example Change for Agent Definition:** + + ```diff + const agent = new Agent({ + name: "My Assistant", + - description: "A helpful assistant.", + + instructions: "A helpful assistant.", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + ``` + +## 0.1.13 + +### Patch Changes + +- [`f7de864`](https://github.com/VoltAgent/voltagent/commit/f7de864503d598cf7131cc01afa3779639190107) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: add `toolName` to event metadata to ensure `delegate_task` name is visible in VoltOps LLM Observability Platform + +- [`13db262`](https://github.com/VoltAgent/voltagent/commit/13db2621ae6b730667f9991d3c2129c85265e925) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: Update Zod to version 3.24.2 to resolve "Type instantiation is excessively deep and possibly infinite" error (related to https://github.com/colinhacks/zod/issues/3435). + +## 0.1.12 + +### Patch Changes + +- [#94](https://github.com/VoltAgent/voltagent/pull/94) [`004df81`](https://github.com/VoltAgent/voltagent/commit/004df81fa6a23571391e6ddeba0dfe6bfea267e8) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Add Langfuse Observability Exporter + + This introduces a new package `@voltagent/langfuse-exporter` that allows you to export OpenTelemetry traces generated by `@voltagent/core` directly to Langfuse (https://langfuse.com/) for detailed observability into your agent's operations. + + **How to Use:** + + ## Installation + + Install the necessary packages: + + ```bash + npm install @voltagent/langfuse-exporter + ``` + + ## Configuration + + Configure the `LangfuseExporter` and pass it to `VoltAgent`: + + ```typescript + import { Agent, VoltAgent } from "@voltagent/core"; + import { VercelAIProvider } from "@voltagent/vercel-ai"; + import { openai } from "@ai-sdk/openai"; + + import { LangfuseExporter } from "@voltagent/langfuse-exporter"; + + // Ensure LANGFUSE_SECRET_KEY and LANGFUSE_PUBLIC_KEY are set in your environment + + // Define your agent(s) + const agent = new Agent({ + name: "my-voltagent-app", + instructions: "A helpful assistant that answers questions without using tools", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + + // Configure the Langfuse Exporter + const langfuseExporter = new LangfuseExporter({ + publicKey: process.env.LANGFUSE_PUBLIC_KEY, + secretKey: process.env.LANGFUSE_SECRET_KEY, + baseUrl: process.env.LANGFUSE_BASE_URL, // Optional: Defaults to Langfuse Cloud + // debug: true // Optional: Enable exporter logging + }); + + // Initialize VoltAgent with the exporter + // This automatically sets up OpenTelemetry tracing + new VoltAgent({ + agents: { + agent, // Register your agent(s) + }, + telemetryExporter: langfuseExporter, // Pass the exporter instance + }); + + console.log("VoltAgent initialized with Langfuse exporter."); + + // Now, any operations performed by 'agent' (e.g., agent.generateText(...)) + // will automatically generate traces and send them to Langfuse. + ``` + + By providing the `telemetryExporter` to `VoltAgent`, OpenTelemetry is automatically configured, and detailed traces including LLM interactions, tool usage, and agent metadata will appear in your Langfuse project. + +## 0.1.11 + +### Patch Changes + +- [`e5b3a46`](https://github.com/VoltAgent/voltagent/commit/e5b3a46e2e61f366fa3c67f9a37d4e4d9e0fe426) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: enhance API Overview documentation + - Added `curl` examples for all key generation endpoints (`/text`, `/stream`, `/object`, `/stream-object`). + - Clarified that `userId` and `conversationId` options are optional. + - Provided separate `curl` examples demonstrating usage both with and without optional parameters (`userId`, `conversationId`). + - Added a new "Common Generation Options" section with a detailed table explaining parameters like `temperature`, `maxTokens`, `contextLimit`, etc., including their types and default values. + +- [`4649c3c`](https://github.com/VoltAgent/voltagent/commit/4649c3ccb9e56a7fcabfe6a0bcef2383ff6506ef) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve agent event handling and error processing + - Enhanced start event emission in agent operations + - Fixed timeline event creation for agent operations + +- [`8e6d2e9`](https://github.com/VoltAgent/voltagent/commit/8e6d2e994398c1a727d4afea39d5e34ffc4a5fca) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Allow passing arbitrary provider-specific options via the `provider` object in agent generation methods (`generateText`, `streamText`, etc.). + + Added an index signature `[key: string]: unknown;` to the `ProviderOptions` type (`voltagent/packages/core/src/agent/types.ts`). This allows users to pass any provider-specific parameters directly through the `provider` object, enhancing flexibility and enabling the use of features not covered by the standard options. + + Example using a Vercel AI SDK option: + + ```typescript + import { Agent } from "@voltagent/core"; + import { VercelProvider } from "@voltagent/vercel-ai"; + import { openai } from "@ai-sdk/openai"; + + const agent = new Agent({ + name: "Example Agent", + llm: new VercelProvider(), + model: openai("gpt-4o-mini"), + }); + + await agent.streamText("Tell me a joke", { + provider: { + // Standard options can still be used + temperature: 0.7, + // Provider-specific options are now allowed by the type + experimental_activeTools: ["tool1", "tool2"], + anotherProviderOption: "someValue", + }, + }); + ``` + +## 0.1.10 + +### Patch Changes + +- [#77](https://github.com/VoltAgent/voltagent/pull/77) [`beaa8fb`](https://github.com/VoltAgent/voltagent/commit/beaa8fb1f1bc6351f1bede0b65a6a189cc1b6ea2) Thanks [@omeraplak](https://github.com/omeraplak)! - **API & Providers:** Standardized message content format for array inputs. + - The API (`/text`, `/stream`, `/object`, `/stream-object` endpoints) now strictly expects the `content` field within message objects (when `input` is an array) to be either a `string` or an `Array` of content parts (e.g., `[{ type: 'text', text: '...' }]`). + - The previous behavior of allowing a single content object (e.g., `{ type: 'text', ... }`) directly as the value for `content` in message arrays is no longer supported in the API schema. Raw string inputs remain unchanged. + - Provider logic (`google-ai`, `groq-ai`, `xsai`) updated to align with this stricter definition. + + **Console:** + - **Added file and image upload functionality to the Assistant Chat.** Users can now attach multiple files/images via a button, preview attachments, and send them along with text messages. + - Improved the Assistant Chat resizing: Replaced size toggle buttons with a draggable handle (top-left corner). + - Chat window dimensions are now saved to local storage and restored on reload. + + **Internal:** + - Added comprehensive test suites for Groq and XsAI providers. + +## 0.1.9 + +### Patch Changes + +- [#71](https://github.com/VoltAgent/voltagent/pull/71) [`1f20509`](https://github.com/VoltAgent/voltagent/commit/1f20509528fc2cb2ba00f86d649848afae34af04) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Introduce `userContext` for passing custom data through agent operations + + Introduced `userContext`, a `Map` within the `OperationContext`. This allows developers to store and retrieve custom data across agent lifecycle hooks (`onStart`, `onEnd`) and tool executions for a specific agent operation (like a `generateText` call). This context is isolated per operation, providing a way to manage state specific to a single request or task. + + **Usage Example:** + + ```typescript + import { + Agent, + createHooks, + createTool, + type OperationContext, + type ToolExecutionContext, + } from "@voltagent/core"; + import { z } from "zod"; + + // Define hooks that set and retrieve data + const hooks = createHooks({ + onStart: (agent: Agent, context: OperationContext) => { + // Set data needed throughout the operation and potentially by tools + const requestId = `req-${Date.now()}`; + const traceId = `trace-${Math.random().toString(16).substring(2, 8)}`; + context.userContext.set("requestId", requestId); + context.userContext.set("traceId", traceId); + console.log( + `[${agent.name}] Operation started. RequestID: ${requestId}, TraceID: ${traceId}` + ); + }, + onEnd: (agent: Agent, result: any, context: OperationContext) => { + // Retrieve data at the end of the operation + const requestId = context.userContext.get("requestId"); + const traceId = context.userContext.get("traceId"); // Can retrieve traceId here too + console.log( + `[${agent.name}] Operation finished. RequestID: ${requestId}, TraceID: ${traceId}` + ); + // Use these IDs for logging, metrics, cleanup, etc. + }, + }); + + // Define a tool that uses the context data set in onStart + const customContextTool = createTool({ + name: "custom_context_logger", + description: "Logs a message using trace ID from the user context.", + parameters: z.object({ + message: z.string().describe("The message to log."), + }), + execute: async (params: { message: string }, options?: ToolExecutionContext) => { + // Access userContext via options.operationContext + const traceId = options?.operationContext?.userContext?.get("traceId") || "unknown-trace"; + const requestId = + options?.operationContext?.userContext?.get("requestId") || "unknown-request"; // Can access requestId too + const logMessage = `[RequestID: ${requestId}, TraceID: ${traceId}] Tool Log: ${params.message}`; + console.log(logMessage); + // In a real scenario, you might interact with external systems using these IDs + return `Logged message with RequestID: ${requestId} and TraceID: ${traceId}`; + }, + }); + + // Create an agent with the tool and hooks + const agent = new Agent({ + name: "MyCombinedAgent", + llm: myLlmProvider, // Your LLM provider instance + model: myModel, // Your model instance + tools: [customContextTool], + hooks: hooks, + }); + + // Trigger the agent. The LLM might decide to use the tool. + await agent.generateText( + "Log the following information using the custom logger: 'User feedback received.'" + ); + + // Console output will show logs from onStart, the tool (if called), and onEnd, + // demonstrating context data flow. + ``` + +- [#71](https://github.com/VoltAgent/voltagent/pull/71) [`1f20509`](https://github.com/VoltAgent/voltagent/commit/1f20509528fc2cb2ba00f86d649848afae34af04) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Standardize Agent Error and Finish Handling + + This change introduces a more robust and consistent way errors and successful finishes are handled across the `@voltagent/core` Agent and LLM provider implementations (like `@voltagent/vercel-ai`). + + **Key Improvements:** + - **Standardized Errors (`VoltAgentError`):** + - Introduced `VoltAgentError`, `ToolErrorInfo`, and `StreamOnErrorCallback` types in `@voltagent/core`. + - LLM Providers (e.g., Vercel) now wrap underlying SDK/API errors into a structured `VoltAgentError` before passing them to `onError` callbacks or throwing them. + - Agent methods (`generateText`, `streamText`, `generateObject`, `streamObject`) now consistently handle `VoltAgentError`, enabling richer context (stage, code, tool details) in history events and logs. + + - **Standardized Stream Finish Results:** + - Introduced `StreamTextFinishResult`, `StreamTextOnFinishCallback`, `StreamObjectFinishResult`, and `StreamObjectOnFinishCallback` types in `@voltagent/core`. + - LLM Providers (e.g., Vercel) now construct these standardized result objects upon successful stream completion. + - Agent streaming methods (`streamText`, `streamObject`) now receive these standardized results in their `onFinish` handlers, ensuring consistent access to final output (`text` or `object`), `usage`, `finishReason`, etc., for history, events, and hooks. + + - **Updated Interfaces:** The `LLMProvider` interface and related options types (`StreamTextOptions`, `StreamObjectOptions`) have been updated to reflect these new standardized callback types and error-throwing expectations. + + These changes lead to more predictable behavior, improved debugging capabilities through structured errors, and a more consistent experience when working with different LLM providers. + +- [`7a7a0f6`](https://github.com/VoltAgent/voltagent/commit/7a7a0f672adbe42635c3edc5f0a7f282575d0932) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Refactor Agent Hooks Signature to Use Single Argument Object - #57 + + This change refactors the signature for all agent hooks (`onStart`, `onEnd`, `onToolStart`, `onToolEnd`, `onHandoff`) in `@voltagent/core` to improve usability, readability, and extensibility. + + **Key Changes:** + - **Single Argument Object:** All hooks now accept a single argument object containing named properties (e.g., `{ agent, context, output, error }`) instead of positional arguments. + - **`onEnd` / `onToolEnd` Refinement:** The `onEnd` and `onToolEnd` hooks no longer use an `isError` flag or a combined `outputOrError` parameter. They now have distinct `output: | undefined` and `error: VoltAgentError | undefined` properties, making it explicit whether the operation or tool execution succeeded or failed. + - **Unified `onEnd` Output:** The `output` type for the `onEnd` hook (`AgentOperationOutput`) is now a standardized union type, providing a consistent structure regardless of which agent method (`generateText`, `streamText`, etc.) completed successfully. + + **Migration Guide:** + + If you have implemented custom agent hooks, you will need to update their signatures: + + **Before:** + + ```typescript + const myHooks = { + onStart: async (agent, context) => { + /* ... */ + }, + onEnd: async (agent, outputOrError, context, isError) => { + if (isError) { + // Handle error (outputOrError is the error) + } else { + // Handle success (outputOrError is the output) + } + }, + onToolStart: async (agent, tool, context) => { + /* ... */ + }, + onToolEnd: async (agent, tool, result, context) => { + // Assuming result might contain an error or be the success output + }, + // ... + }; + ``` + + **After:** + + ```typescript + import type { + OnStartHookArgs, + OnEndHookArgs, + OnToolStartHookArgs, + OnToolEndHookArgs, + // ... other needed types + } from "@voltagent/core"; + + const myHooks = { + onStart: async (args: OnStartHookArgs) => { + const { agent, context } = args; + /* ... */ + }, + onEnd: async (args: OnEndHookArgs) => { + const { agent, output, error, context } = args; + if (error) { + // Handle error (error is VoltAgentError) + } else if (output) { + // Handle success (output is AgentOperationOutput) + } + }, + onToolStart: async (args: OnToolStartHookArgs) => { + const { agent, tool, context } = args; + /* ... */ + }, + onToolEnd: async (args: OnToolEndHookArgs) => { + const { agent, tool, output, error, context } = args; + if (error) { + // Handle tool error (error is VoltAgentError) + } else { + // Handle tool success (output is the result) + } + }, + // ... + }; + ``` + + Update your hook function definitions to accept the single argument object and use destructuring or direct property access (`args.propertyName`) to get the required data. + +## 0.1.8 + +### Patch Changes + +- [#51](https://github.com/VoltAgent/voltagent/pull/51) [`55c58b0`](https://github.com/VoltAgent/voltagent/commit/55c58b0da12dd94a3095aad4bc74c90757c98db4) Thanks [@kwaa](https://github.com/kwaa)! - Use the latest Hono to avoid duplicate dependencies + +- [#59](https://github.com/VoltAgent/voltagent/pull/59) [`d40cb14`](https://github.com/VoltAgent/voltagent/commit/d40cb14860a5abe8771e0b91200d10f522c62881) Thanks [@kwaa](https://github.com/kwaa)! - fix: add package exports + +- [`e88cb12`](https://github.com/VoltAgent/voltagent/commit/e88cb1249c4189ced9e245069bed5eab71cdd894) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Enhance `createPrompt` with Template Literal Type Inference + + Improved the `createPrompt` utility to leverage TypeScript's template literal types. This provides strong type safety by: + - Automatically inferring required variable names directly from `{{variable}}` placeholders in the template string. + - Enforcing the provision of all required variables with the correct types at compile time when calling `createPrompt`. + + This significantly reduces the risk of runtime errors caused by missing or misspelled prompt variables. + +- [#65](https://github.com/VoltAgent/voltagent/pull/65) [`0651d35`](https://github.com/VoltAgent/voltagent/commit/0651d35442cda32b6057f8b7daf7fd8655a9a2a4) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Add OpenAPI (Swagger) Documentation for Core API - #64 + - Integrated `@hono/zod-openapi` and `@hono/swagger-ui` to provide interactive API documentation. + - Documented the following core endpoints with request/response schemas, parameters, and examples: + - `GET /agents`: List all registered agents. + - `POST /agents/{id}/text`: Generate text response. + - `POST /agents/{id}/stream`: Stream text response (SSE). + - `POST /agents/{id}/object`: Generate object response (Note: Requires backend update to fully support JSON Schema input). + - `POST /agents/{id}/stream-object`: Stream object response (SSE) (Note: Requires backend update to fully support JSON Schema input). + - Added `/doc` endpoint serving the OpenAPI 3.1 specification in JSON format. + - Added `/ui` endpoint serving the interactive Swagger UI. + - Improved API discoverability: + - Added links to Swagger UI and OpenAPI Spec on the root (`/`) endpoint. + - Added links to Swagger UI in the server startup console logs. + - Refactored API schemas and route definitions into `api.routes.ts` for better organization. + - Standardized generation options (like `userId`, `temperature`, `maxTokens`) in the API schema with descriptions, examples, and sensible defaults. + +## 0.1.7 + +### Patch Changes + +- [`e328613`](https://github.com/VoltAgent/voltagent/commit/e32861366852f4bb7ad8854527b2bb6525703a25) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: prevent `ReferenceError: module is not defined` in ES module environments by adding guards around the CommonJS-specific `require.main === module` check in the main entry point. + +## 0.1.6 + +### Patch Changes + +- [#41](https://github.com/VoltAgent/voltagent/pull/41) [`52d5fa9`](https://github.com/VoltAgent/voltagent/commit/52d5fa94045481dc43dc260a40b701606190585c) Thanks [@omeraplak](https://github.com/omeraplak)! - ## Introducing Toolkits for Better Tool Management + + Managing related tools and their instructions is now simpler with `Toolkit`s. + + **Motivation:** + - Defining shared instructions for multiple related tools was cumbersome. + - The logic for deciding which instructions to add to the agent's system prompt could become complex. + - We wanted a cleaner way to group tools logically. + + **What's New: The `Toolkit`** + + A `Toolkit` bundles related tools and allows defining shared `instructions` and an `addInstructions` flag _at the toolkit level_. + + ```typescript + // packages/core/src/tool/toolkit.ts + export type Toolkit = { + /** + * Unique identifier name for the toolkit. + */ + name: string; + /** + * A brief description of what the toolkit does. Optional. + */ + description?: string; + /** + * Shared instructions for the LLM on how to use the tools within this toolkit. + * Optional. + */ + instructions?: string; + /** + * Whether to automatically add the toolkit's `instructions` to the agent's system prompt. + * Defaults to false. + */ + addInstructions?: boolean; + /** + * An array of Tool instances that belong to this toolkit. + */ + tools: Tool[]; + }; + ``` + + **Key Changes to Core:** + 1. **`ToolManager` Upgrade:** Now manages both `Tool` and `Toolkit` objects. + 2. **`AgentOptions` Update:** The `tools` option accepts `(Tool | Toolkit)[]`. + 3. **Simplified Instruction Handling:** `Agent` now only adds instructions from `Toolkit`s where `addInstructions` is true. + + This change leads to a clearer separation of concerns, simplifies the agent's internal logic, and makes managing tool instructions more predictable and powerful. + + ### New `createToolkit` Helper + + We've also added a helper function, `createToolkit`, to simplify the creation of toolkits. It provides default values and basic validation: + + ```typescript + // packages/core/src/tool/toolkit.ts + export const createToolkit = (options: Toolkit): Toolkit => { + if (!options.name) { + throw new Error("Toolkit name is required"); + } + if (!options.tools || options.tools.length === 0) { + console.warn(`Toolkit '${options.name}' created without any tools.`); + } + + return { + name: options.name, + description: options.description || "", // Default empty description + instructions: options.instructions, + addInstructions: options.addInstructions || false, // Default to false + tools: options.tools || [], // Default to empty array + }; + }; + ``` + + **Example Usage:** + + ```typescript + import { createTool, createToolkit } from "@voltagent/core"; + import { z } from "zod"; + + // Define some tools first + const getWeather = createTool({ + name: "getWeather", + description: "Gets the weather for a location.", + schema: z.object({ location: z.string() }), + run: async ({ location }) => ({ temperature: "25C", condition: "Sunny" }), + }); + + const searchWeb = createTool({ + name: "searchWeb", + description: "Searches the web for a query.", + schema: z.object({ query: z.string() }), + run: async ({ query }) => ({ results: ["Result 1", "Result 2"] }), + }); + + // Create a toolkit using the helper + const webInfoToolkit = createToolkit({ + name: "web_information", + description: "Tools for getting information from the web.", + addInstructions: true, // Add the instructions to the system prompt + tools: [getWeather, searchWeb], + }); + + console.log(webInfoToolkit); + /* + Output: + { + name: 'web_information', + description: 'Tools for getting information from the web.', + instructions: 'Use these tools to find current information online.', + addInstructions: true, + tools: [ [Object Tool: getWeather], [Object Tool: searchWeb] ] + } + */ + ``` + +- [#33](https://github.com/VoltAgent/voltagent/pull/33) [`3ef2eaa`](https://github.com/VoltAgent/voltagent/commit/3ef2eaa9661e8ecfebf17af56b09af41285d0ca9) Thanks [@kwaa](https://github.com/kwaa)! - Update package.json files: + - Remove `src` directory from the `files` array. + - Add explicit `exports` field for better module resolution. + +- [#41](https://github.com/VoltAgent/voltagent/pull/41) [`52d5fa9`](https://github.com/VoltAgent/voltagent/commit/52d5fa94045481dc43dc260a40b701606190585c) Thanks [@omeraplak](https://github.com/omeraplak)! - ## Introducing Reasoning Tools Helper + + This update introduces a new helper function, `createReasoningTools`, to easily add step-by-step reasoning capabilities to your agents. #24 + + ### New `createReasoningTools` Helper + + **Feature:** Easily add `think` and `analyze` tools for step-by-step reasoning. + + We've added a new helper function, `createReasoningTools`, which makes it trivial to equip your agents with structured thinking capabilities, similar to patterns seen in advanced AI systems. + - **What it does:** Returns a pre-configured `Toolkit` named `reasoning_tools`. + - **Tools included:** Contains the `think` tool (for internal monologue/planning) and the `analyze` tool (for evaluating results and deciding next steps). + - **Instructions:** Includes detailed instructions explaining how the agent should use these tools iteratively to solve problems. You can choose whether these instructions are automatically added to the system prompt via the `addInstructions` option. + + ```typescript + import { createReasoningTools, type Toolkit } from "@voltagent/core"; + + // Get the reasoning toolkit (with instructions included in the system prompt) + const reasoningToolkit: Toolkit = createReasoningTools({ addInstructions: true }); + + // Get the toolkit without automatically adding instructions + const reasoningToolkitManual: Toolkit = createReasoningTools({ addInstructions: false }); + ``` + + ### How to Use Reasoning Tools + + Pass the `Toolkit` object returned by `createReasoningTools` directly to the agent's `tools` array. + + ```typescript + // Example: Using the new reasoning tools helper + import { Agent, createReasoningTools, type Toolkit } from "@voltagent/core"; + import { VercelAIProvider } from "@voltagent/vercel-ai"; + import { openai } from "@ai-sdk/openai"; + + const reasoningToolkit: Toolkit = createReasoningTools({ + addInstructions: true, + }); + + const agent = new Agent({ + name: "MyThinkingAgent", + instructions: "An agent equipped with reasoning tools.", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + tools: [reasoningToolkit], // Pass the toolkit + }); + + // Agent's system message will include reasoning instructions. + ``` + + This change simplifies adding reasoning capabilities to your agents. + +## 0.1.5 + +### Patch Changes + +- [#35](https://github.com/VoltAgent/voltagent/pull/35) [`9acbbb8`](https://github.com/VoltAgent/voltagent/commit/9acbbb898a517902cbdcb7ae7a8460e9d35f3dbe) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: Prevent potential error when accessing debug option in LibSQLStorage - #34 + - Modified the `debug` method within the `LibSQLStorage` class. + - Changed the access to `this.options.debug` to use optional chaining (`this.options?.debug`). + + This change prevents runtime errors that could occur in specific environments, such as Next.js, if the `debug` method is invoked before the `options` object is fully initialized or if `options` becomes unexpectedly `null` or `undefined`. It ensures the debug logging mechanism is more robust. + +## 0.1.4 + +### Patch Changes + +- [#27](https://github.com/VoltAgent/voltagent/pull/27) [`3c0829d`](https://github.com/VoltAgent/voltagent/commit/3c0829dcec4db9596147b583a9cf2d4448bc30f1) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve sub-agent context sharing for sequential task execution - #30 + + Enhanced the Agent system to properly handle context sharing between sub-agents, enabling reliable sequential task execution. The changes include: + - Adding `contextMessages` parameter to `getSystemMessage` method + - Refactoring `prepareAgentsMemory` to properly format conversation history + - Ensuring conversation context is correctly passed between delegated tasks + - Enhancing system prompts to better handle sequential workflows + + This fixes issues where the second agent in a sequence would not have access to the first agent's output, causing failures in multi-step workflows. + +## 0.1.1 + +- 🚀 **Introducing VoltAgent: TypeScript AI Agent Framework!** + + This initial release marks the beginning of VoltAgent, a powerful toolkit crafted for the JavaScript developer community. We saw the challenges: the complexity of building AI from scratch, the limitations of No-Code tools, and the lack of first-class AI tooling specifically for JS. + + ![VoltAgent Demo](https://cdn.voltagent.dev/readme/demo.gif) + VoltAgent aims to fix that by providing the building blocks you need: + - **`@voltagent/core`**: The foundational engine for agent capabilities. + - **`@voltagent/voice`**: Easily add voice interaction. + - **`@voltagent/vercel-ai`**: Seamless integration with [Vercel AI SDK](https://sdk.vercel.ai/docs/introduction). + - **`@voltagent/xsai`**: A Seamless integration with [xsAI](https://xsai.js.org/). + - **`@voltagent/cli` & `create-voltagent-app`**: Quick start tools to get you building _fast_. + + We're combining the flexibility of code with the clarity of visual tools (like our **currently live [VoltOps LLM Observability Platform](https://console.voltagent.dev/)**) to make AI development easier, clearer, and more powerful. Join us as we build the future of AI in JavaScript! + + Explore the [Docs](https://voltagent.dev/docs/) and join our [Discord community](https://s.voltagent.dev/discord)! + +--- + +## Package: @voltagent/a2a-server + +## 2.0.2 + +### Patch Changes + +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505)]: + - @voltagent/internal@1.0.2 + +## 2.0.1 + +### Patch Changes + +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2)]: + - @voltagent/internal@1.0.1 + +## 2.0.0 + +### Major Changes + +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +### Patch Changes + +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/core@2.0.0 + - @voltagent/internal@1.0.0 + +## 1.0.2 + +### Patch Changes + +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` +- Updated dependencies [[`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e)]: + - @voltagent/internal@0.0.12 + +## 1.0.1 + +### Patch Changes + +- [#596](https://github.com/VoltAgent/voltagent/pull/596) [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7) Thanks [@omeraplak](https://github.com/omeraplak)! - - add `@voltagent/a2a-server`, a JSON-RPC Agent-to-Agent (A2A) server that lets external agents call your VoltAgent instance over HTTP/SSE + - teach `@voltagent/core`, `@voltagent/server-core`, and `@voltagent/server-hono` to auto-register configured A2A servers so adding `{ a2aServers: { ... } }` on `VoltAgent` and opting into `honoServer` instantly exposes discovery and RPC endpoints + - forward request context (`userId`, `sessionId`, metadata) into agent invocations and provide task management hooks, plus allow filtering/augmenting exposed agents by default + - document the setup in `website/docs/agents/a2a/a2a-server.md` and refresh `examples/with-a2a-server` with basic usage and task-store customization + - A2A endpoints are now described in Swagger/OpenAPI and listed in the startup banner whenever an A2A server is registered, making discovery of `/.well-known/...` and `/a2a/:serverId` routes trivial. + + **Getting started** + + ```ts + import { Agent, VoltAgent } from "@voltagent/core"; + import { A2AServer } from "@voltagent/a2a-server"; + import { honoServer } from "@voltagent/server-hono"; + + const assistant = new Agent({ + name: "SupportAgent", + purpose: "Handle support questions from partner agents.", + model: myModel, + }); + + const a2aServer = new A2AServer({ + name: "support-agent", + version: "0.1.0", + }); + + export const voltAgent = new VoltAgent({ + agents: { assistant }, + a2aServers: { a2aServer }, + server: honoServer({ port: 3141 }), + }); + ``` + +- Updated dependencies [[`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7), [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7)]: + - @voltagent/internal@0.0.11 + +--- + +## Package: @voltagent/ag-ui + +## 1.0.2 + +### Patch Changes + +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +## 1.0.1 + +### Patch Changes + +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +## 1.0.0 + +### Major Changes + +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +### Patch Changes + +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/internal@1.0.0 + +## 0.1.0 + +### Minor Changes + +- [#861](https://github.com/VoltAgent/voltagent/pull/861) [`9854d43`](https://github.com/VoltAgent/voltagent/commit/9854d4374c977751f29f73b097164ed33c2290d5) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add AG-UI adapter for CopilotKit integration #295 + + New `@voltagent/ag-ui` package enables seamless CopilotKit integration with VoltAgent agents. + + ## Features + - **VoltAgent AGUI**: AG-UI protocol adapter that wraps VoltAgent agents, streaming events (text chunks, tool calls, state snapshots) in AG-UI format + - **registerCopilotKitRoutes**: One-liner to mount CopilotKit runtime on any Hono-based VoltAgent server + - **State persistence**: Automatically syncs AG-UI state to VoltAgent working memory for cross-turn context + - **Tool mapping**: VoltAgent tools are exposed to CopilotKit clients with full streaming support + + ## Usage + + ```ts + import { registerCopilotKitRoutes } from "@voltagent/ag-ui"; + import { honoServer } from "@voltagent/server-hono"; + + new VoltAgent({ + agents: { myAgent }, + server: honoServer({ + configureApp: (app) => registerCopilotKitRoutes({ app, resourceIds: ["myAgent"] }), + }), + }); + ``` + + Includes `with-copilotkit` example with Vite React client and VoltAgent server setup. + +--- + +## Package: @voltagent/cli + +## 0.1.21 + +### Patch Changes + +- [#934](https://github.com/VoltAgent/voltagent/pull/934) [`12519f5`](https://github.com/VoltAgent/voltagent/commit/12519f572b3facbd32d35f939be08a0ad1b40b45) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: offline-first local prompts with version + label selection + + ### What's New + - Local prompt resolution now supports multiple versions and labels stored as + `.voltagent/prompts//.md`. + - Local files are used first; VoltOps is only queried if the local prompt is missing. + - If a local prompt is behind the online version, the agent logs a warning and records metadata. + - CLI `pull` can target labels or versions; `push` compares local vs online and creates new versions. + + ### CLI Usage + + ```bash + # Pull latest prompts (default) + volt prompts pull + + # Pull a specific label or version (stored under .voltagent/prompts//.md) + volt prompts pull --names support-agent --label production + volt prompts pull --names support-agent --prompt-version 4 + + # Push local changes (creates new versions after diff/confirm) + volt prompts push + ``` + + ### Agent Usage + + ```typescript + instructions: async ({ prompts }) => { + return await prompts.getPrompt({ + promptName: "support-agent", + version: 4, + }); + }; + ``` + + ```typescript + instructions: async ({ prompts }) => { + return await prompts.getPrompt({ + promptName: "support-agent", + label: "production", + }); + }; + ``` + + ### Offline-First Workflow + - Pull once, then run fully offline with local Markdown files. + - Point the runtime to your local directory: + + ```bash + export VOLTAGENT_PROMPTS_PATH="./.voltagent/prompts" + ``` + +## 0.1.20 + +### Patch Changes + +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505)]: + - @voltagent/evals@2.0.2 + - @voltagent/internal@1.0.2 + - @voltagent/sdk@2.0.2 + +## 0.1.19 + +### Patch Changes + +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2)]: + - @voltagent/evals@2.0.1 + - @voltagent/internal@1.0.1 + - @voltagent/sdk@2.0.1 + +## 0.1.18 + +### Patch Changes + +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/evals@2.0.0 + - @voltagent/internal@1.0.0 + - @voltagent/sdk@2.0.0 + +## 0.1.17 + +### Patch Changes + +- [`d3e0995`](https://github.com/VoltAgent/voltagent/commit/d3e09950fb8708db8beb9db2f1b8eafbe47686ea) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add CLI announcements system for server startup + + VoltAgent server now displays announcements during startup, keeping developers informed about new features and updates. + + ## How It Works + + When the server starts, it fetches announcements from a centralized GitHub-hosted JSON file and displays them in a minimal, non-intrusive format: + + ``` + ⚡ Introducing VoltOps Deployments → https://console.voltagent.dev/deployments + ``` + + ## Key Features + - **Dynamic updates**: Announcements are fetched from GitHub at runtime, so new announcements appear without requiring a package update + - **Non-blocking**: Uses a 3-second timeout and fails silently to never delay server startup + - **Minimal footprint**: Single-line format inspired by Next.js, doesn't clutter the console + - **Toggle support**: Each announcement has an `enabled` flag for easy control + + ## Technical Details + - Announcements source: `https://raw.githubusercontent.com/VoltAgent/voltagent/main/announcements.json` + - New `showAnnouncements()` function exported from `@voltagent/server-core` + - Integrated into both `BaseServerProvider` and `HonoServerProvider` startup flow + +## 0.1.16 + +### Patch Changes + +- [#787](https://github.com/VoltAgent/voltagent/pull/787) [`5e81d65`](https://github.com/VoltAgent/voltagent/commit/5e81d6568ba3bee26083ca2a8e5d31f158e36fc0) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add authentication and tunnel prefix support to VoltAgent CLI + + ## Authentication Commands + + Added `volt login` and `volt logout` commands for managing VoltAgent CLI authentication: + + ### volt login + - Implements Device Code Flow authentication + - Opens browser to `https://console.voltagent.dev/cli-auth` for authorization + - Stores authentication token in XDG-compliant config location: + - macOS/Linux: `~/.config/voltcli/config.json` + - Windows: `%APPDATA%\voltcli\config.json` + - Tokens expire after 365 days + - Enables persistent subdomains for Core/Pro plan users + + ```bash + pnpm volt login + ``` + + ### volt logout + - Removes authentication token from local machine + - Clears stored credentials + + ```bash + pnpm volt logout + ``` + + ## Persistent Tunnel Subdomains + + Authenticated Core/Pro users now receive persistent subdomains based on their username: + + **Before (unauthenticated or free plan):** + + ```bash + pnpm volt tunnel 3141 + # → https://happy-cat-42.tunnel.voltagent.dev (changes each time) + ``` + + **After (authenticated Core/Pro):** + + ```bash + pnpm volt tunnel 3141 + # → https://john-doe.tunnel.voltagent.dev (same URL every time) + ``` + + ## Tunnel Prefix Support + + Added `--prefix` flag to organize multiple tunnels with custom subdomain prefixes: + + ```bash + pnpm volt tunnel 3141 --prefix agent + # → https://agent-john-doe.tunnel.voltagent.dev + + pnpm volt tunnel 8080 --prefix api + # → https://api-john-doe.tunnel.voltagent.dev + ``` + + **Prefix validation rules:** + - 1-20 characters + - Alphanumeric and dash only + - Must start with letter or number + - Reserved prefixes: `www`, `mail`, `admin`, `console`, `api-voltagent` + + **Error handling:** + - Subdomain collision detection (if already in use by another user) + - Clear error messages with suggestions to try different prefixes + + ## Config Migration + + Config location migrated from `.voltcli` to XDG-compliant paths for better cross-platform support and adherence to OS conventions. + + See the [local tunnel documentation](https://voltagent.dev/docs/deployment/local-tunnel) for complete usage examples. + +## 0.1.15 + +### Patch Changes + +- [#767](https://github.com/VoltAgent/voltagent/pull/767) [`cc1f5c0`](https://github.com/VoltAgent/voltagent/commit/cc1f5c032cd891ed4df0b718885f70853c344690) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add tunnel command + + ## New: `volt tunnel` + + Expose your local VoltAgent server over a secure public URL with a single command: + + ```bash + pnpm volt tunnel 3141 + ``` + + The CLI handles tunnel creation for `localhost:3141` and keeps the connection alive until you press `Ctrl+C`. You can omit the port argument to use the default. + +## 0.1.14 + +### Patch Changes + +- [#734](https://github.com/VoltAgent/voltagent/pull/734) [`2084fd4`](https://github.com/VoltAgent/voltagent/commit/2084fd491db4dbc89c432d1e72a633ec0c42d92b) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: auto-detect package managers and add automatic installation to `volt update` command + + ## The Problem + + The `volt update` CLI command had several UX issues: + 1. Only updated `package.json` without installing packages + 2. Required users to manually run installation commands + 3. Always suggested `npm install` regardless of the user's actual package manager (pnpm, yarn, or bun) + 4. No way to skip automatic installation when needed + + This was inconsistent with the HTTP API's `updateSinglePackage` and `updateAllPackages` functions, which properly detect and use the correct package manager. + + ## The Solution + + Enhanced the `volt update` command to match the HTTP API behavior: + + **Package Manager Auto-Detection:** + - Automatically detects package manager by checking lock files: + - `pnpm-lock.yaml` → runs `pnpm install` + - `yarn.lock` → runs `yarn install` + - `package-lock.json` → runs `npm install` + - `bun.lockb` → runs `bun install` + + **Automatic Installation:** + - After updating `package.json`, automatically runs the appropriate install command + - Shows detected package manager and installation progress + - Works in both interactive mode and `--apply` mode + + **Optional Skip:** + - Added `--no-install` flag to skip automatic installation when needed + - Useful for CI/CD pipelines or when manual control is preferred + + ## Usage Examples + + **Default behavior (auto-install with detected package manager):** + + ```bash + $ volt update + Found 3 outdated VoltAgent packages: + @voltagent/core: 1.1.34 → 1.1.35 + @voltagent/server-hono: 0.1.10 → 0.1.11 + @voltagent/cli: 0.0.45 → 0.0.46 + + ✓ Updated 3 packages in package.json + + Detected package manager: pnpm + Running pnpm install... + ⠹ Installing packages... + ✓ Packages installed successfully + ``` + + **Skip automatic installation:** + + ```bash + $ volt update --no-install + ✓ Updated 3 packages in package.json + ⚠ Automatic installation skipped + Run 'pnpm install' to install updated packages + ``` + + **Non-interactive mode:** + + ```bash + $ volt update --apply + ✓ Updates applied to package.json + Detected package manager: pnpm + Running pnpm install... + ✓ Packages installed successfully + ``` + + ## Benefits + - **Better UX**: No manual steps required - updates are fully automatic + - **Package Manager Respect**: Uses your chosen package manager (pnpm/yarn/npm/bun) + - **Consistency**: CLI now matches HTTP API behavior + - **Flexibility**: `--no-install` flag for users who need manual control + - **CI/CD Friendly**: Works seamlessly in automated workflows + +## 0.1.13 + +### Patch Changes + +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` +- Updated dependencies [[`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e)]: + - @voltagent/internal@0.0.12 + - @voltagent/evals@1.0.3 + - @voltagent/sdk@1.0.1 + +## 0.1.12 + +### Patch Changes + +- [#674](https://github.com/VoltAgent/voltagent/pull/674) [`5aa84b5`](https://github.com/VoltAgent/voltagent/commit/5aa84b5bcf57d19bbe33cc791f0892c96bb3944b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add eval commands + +- Updated dependencies [[`5aa84b5`](https://github.com/VoltAgent/voltagent/commit/5aa84b5bcf57d19bbe33cc791f0892c96bb3944b), [`5aa84b5`](https://github.com/VoltAgent/voltagent/commit/5aa84b5bcf57d19bbe33cc791f0892c96bb3944b)]: + - @voltagent/evals@1.0.0 + - @voltagent/sdk@1.0.0 + +## 0.1.11 + +### Patch Changes + +- [#621](https://github.com/VoltAgent/voltagent/pull/621) [`f4fa7e2`](https://github.com/VoltAgent/voltagent/commit/f4fa7e297fec2f602c9a24a0c77e645aa971f2b9) Thanks [@omeraplak](https://github.com/omeraplak)! - ## @voltagent/core + - Folded the serverless runtime entry point into the main build – importing `@voltagent/core` now auto-detects the runtime and provisions either the Node or serverless observability pipeline. + - Rebuilt serverless observability on top of `BasicTracerProvider`, fetch-based OTLP exporters, and an execution-context `waitUntil` hook. Exports run with exponential backoff, never block the response, and automatically reuse VoltOps credentials (or fall back to the in-memory span/log store) so VoltOps Console transparently swaps to HTTP polling when WebSockets are unavailable. + - Hardened the runtime utilities for Workers/Functions: added universal `randomUUID`, base64, and event-emitter helpers, and taught the default logger to emit OpenTelemetry logs without relying on Node globals. This removes the last Node-only dependencies from the serverless bundle. + + ```ts + import { Agent, VoltAgent } from "@voltagent/core"; + import { serverlessHono } from "@voltagent/serverless-hono"; + import { openai } from "@ai-sdk/openai"; + + import { weatherTool } from "./tools"; + + const assistant = new Agent({ + name: "serverless-assistant", + instructions: "You are a helpful assistant.", + model: openai("gpt-4o-mini"), + }); + + const voltAgent = new VoltAgent({ + agents: { assistant }, + serverless: serverlessHono(), + }); + + export default voltAgent.serverless().toCloudflareWorker(); + ``` + + ## @voltagent/serverless-hono + - Renamed the edge provider to **serverless** and upgraded it to power any fetch-based runtime (Cloudflare Workers, Vercel Edge Functions, Deno Deploy, Netlify Functions). + - Wrapped the Cloudflare adapter in a first-class `HonoServerlessProvider` that installs a scoped `waitUntil` bridge, reuses the shared routing layer, and exposes a `/ws` health stub so VoltOps Console can cleanly fall back to polling. + - Dropped the manual environment merge – Workers should now enable the `nodejs_compat_populate_process_env` flag (documented in the new deployment guide) instead of calling `mergeProcessEnv` themselves. + + ## @voltagent/server-core + - Reworked the observability handlers around the shared storage API, including a new `POST /setup-observability` helper that writes VoltOps keys into `.env` and expanded trace/log queries that match the serverless storage contract. + + ## @voltagent/cli + - Added `volt deploy --target ` to scaffold the right config files. The Cloudflare template now ships with the required compatibility flags (`nodejs_compat`, `nodejs_compat_populate_process_env`, `no_handle_cross_request_promise_resolution`) so new projects run on Workers without extra tweaking. + +## 0.1.10 + +### Patch Changes + +- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements + + This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + + **Key improvements:** + - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs + - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration + - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries + - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup + - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + + These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. + +## 0.1.9 + +### Patch Changes + +- [`00d70cb`](https://github.com/VoltAgent/voltagent/commit/00d70cbb570e4d748ab37e177e4e5df869d52e03) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: update VoltAgent docs MCP configs + +## 0.1.8 + +### Patch Changes + +- [#278](https://github.com/VoltAgent/voltagent/pull/278) [`85d979d`](https://github.com/VoltAgent/voltagent/commit/85d979d5205f23ab6e3a85e68af6c46fa7c0f648) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: introduce VoltAgent MCP Docs Server for IDE integration + + Added comprehensive MCP (Model Context Protocol) Docs Server integration to enable AI assistants in IDEs to access VoltAgent documentation directly. This feature allows developers to ask their AI assistants questions about VoltAgent directly within their development environment. + + **New Features:** + - **`@voltagent/docs-mcp`** package: MCP server that provides access to VoltAgent documentation + - **CLI MCP commands**: Setup, test, status, and remove MCP configurations + - `volt mcp setup` - Interactive setup for Cursor, Windsurf, or VS Code + - `volt mcp test` - Test MCP connection and provide usage examples + - `volt mcp status` - Show current MCP configuration status + - `volt mcp remove` - Remove MCP configuration + - **IDE Configuration**: Automatic configuration file generation for supported IDEs + - **Multi-IDE Support**: Works with Cursor, Windsurf, and VS Code + + **Usage:** + + ```bash + # Setup MCP for your IDE + volt mcp setup + + # Test the connection + volt mcp test + + # Check status + volt mcp status + ``` + + Once configured, developers can ask their AI assistant questions like: + - "How do I create an agent in VoltAgent?" + - "Is there a VoltAgent example with Next.js?" + - "How do I use voice features?" + - "What are the latest updates?" + + The MCP server provides real-time access to VoltAgent documentation, examples, and best practices directly within the IDE environment. + +## 0.1.7 + +### Patch Changes + +- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 + +## 0.1.6 + +### Patch Changes + +- [#155](https://github.com/VoltAgent/voltagent/pull/155) [`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c) Thanks [@baseballyama](https://github.com/baseballyama)! - chore: update `tsconfig.json`'s `target` to `ES2022` + +## 0.1.5 + +### Patch Changes + +- [#102](https://github.com/VoltAgent/voltagent/pull/102) [`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3) Thanks [@omeraplak](https://github.com/omeraplak)! - refactor: use 'instructions' field for Agent definitions in examples - #88 + + Updated documentation examples (READMEs, docs, blogs) and relevant package code examples to use the `instructions` field instead of `description` when defining `Agent` instances. + + This change aligns the examples with the preferred API usage for the `Agent` class, where `instructions` provides behavioral guidance to the agent/LLM. This prepares for the eventual deprecation of the `description` field specifically for `Agent` class definitions. + + **Example Change for Agent Definition:** + + ```diff + const agent = new Agent({ + name: "My Assistant", + - description: "A helpful assistant.", + + instructions: "A helpful assistant.", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + ``` + +## 0.1.4 + +### Patch Changes + +- [#73](https://github.com/VoltAgent/voltagent/pull/73) [`ac6ecbc`](https://github.com/VoltAgent/voltagent/commit/ac6ecbc235a10a947a9f60155b04335761e6ac38) Thanks [@necatiozmen](https://github.com/necatiozmen)! - feat: Add placeholder `add` command + + Introduces the `add ` command. Currently, this command informs users that the feature for adding agents from the marketplace is upcoming and provides a link to the GitHub discussions for early feedback and participation. + +## 0.1.3 + +### Patch Changes + +- [#33](https://github.com/VoltAgent/voltagent/pull/33) [`3ef2eaa`](https://github.com/VoltAgent/voltagent/commit/3ef2eaa9661e8ecfebf17af56b09af41285d0ca9) Thanks [@kwaa](https://github.com/kwaa)! - Update package.json files: + - Remove `src` directory from the `files` array. + - Add explicit `exports` field for better module resolution. + +## 0.1.1 + +- 🚀 **Introducing VoltAgent: TypeScript AI Agent Framework!** + + This initial release marks the beginning of VoltAgent, a powerful toolkit crafted for the JavaScript developer community. We saw the challenges: the complexity of building AI from scratch, the limitations of No-Code tools, and the lack of first-class AI tooling specifically for JS. + + ![VoltAgent Demo](https://cdn.voltagent.dev/readme/demo.gif) + VoltAgent aims to fix that by providing the building blocks you need: + - **`@voltagent/core`**: The foundational engine for agent capabilities. + - **`@voltagent/voice`**: Easily add voice interaction. + - **`@voltagent/vercel-ai`**: Seamless integration with [Vercel AI SDK](https://sdk.vercel.ai/docs/introduction). + - **`@voltagent/xsai`**: A Seamless integration with [xsAI](https://xsai.js.org/). + - **`@voltagent/cli` & `create-voltagent-app`**: Quick start tools to get you building _fast_. + + We're combining the flexibility of code with the clarity of visual tools (like our **currently live [VoltOps LLM Observability Platform](https://console.voltagent.dev/)**) to make AI development easier, clearer, and more powerful. Join us as we build the future of AI in JavaScript! + + Explore the [Docs](https://voltagent.dev/docs/) and join our [Discord community](https://s.voltagent.dev/discord)! + +--- + +## Package: @voltagent/cloudflare-d1 + +## 2.0.4 + +### Patch Changes + +- [#915](https://github.com/VoltAgent/voltagent/pull/915) [`37cc8d3`](https://github.com/VoltAgent/voltagent/commit/37cc8d3d6e49973dff30791f4237878b20c62c24) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Cloudflare D1 memory adapter for Workers + + You can now persist Memory V2 in Cloudflare D1 using `@voltagent/cloudflare-d1`. The adapter accepts a + D1 binding directly, so you can keep Worker bindings inside your `fetch` handler and wire them into + VoltAgent via a small factory. + + Serverless routes still inject Worker `env` into request contexts for ad-hoc access in tools or + workflow steps. The D1 memory adapter does not require this and works with the binding directly. + + Usage: + + ```ts + import { Memory } from "@voltagent/core"; + import { D1MemoryAdapter } from "@voltagent/cloudflare-d1"; + + const memory = new Memory({ + storage: new D1MemoryAdapter({ + binding: env.DB, + }), + }); + ``` + +--- + +## Package: create-voltagent-app + +## 0.2.14 + +### Patch Changes + +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +## 0.2.13 + +### Patch Changes + +- [#857](https://github.com/VoltAgent/voltagent/pull/857) [`056bbda`](https://github.com/VoltAgent/voltagent/commit/056bbdac8502a21bf4d317d05a9492658afc406a) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: use LibSQL for persistent observability in project template + + Previously, projects created with `create-voltagent-app` used in-memory observability storage, which meant traces and spans were lost on restart. + + Now the template uses `LibSQLObservabilityAdapter` to persist observability data to `.voltagent/observability.db`, matching the existing persistent memory setup. This ensures agent traces, spans, and logs are retained across restarts for better debugging and monitoring during development. + +## 0.2.11 + +### Patch Changes + +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` + +## 0.2.10 + +### Patch Changes + +- [#587](https://github.com/VoltAgent/voltagent/pull/587) [`28d4268`](https://github.com/VoltAgent/voltagent/commit/28d42689e1f2c0f1304f0f934bd09ba510e493bc) Thanks [@wayneg123](https://github.com/wayneg123)! - Switch the app template to bundle with tsdown so the production build runs under Node ESM without manual .js extensions or bespoke import mappers. + +## 0.2.9 + +### Patch Changes + +- [`59b4a3e`](https://github.com/VoltAgent/voltagent/commit/59b4a3ecaa5353228bc142f3f175c95a1e4f6d8c) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add VoltAgent v1 support + +## 0.2.9-next.0 + +### Patch Changes + +- [#541](https://github.com/VoltAgent/voltagent/pull/541) [`59b4a3e`](https://github.com/VoltAgent/voltagent/commit/59b4a3ecaa5353228bc142f3f175c95a1e4f6d8c) Thanks [@voltagent-bot](https://github.com/voltagent-bot)! - feat: add VoltAgent v1 support + +## 0.2.8 + +### Patch Changes + +- [#462](https://github.com/VoltAgent/voltagent/pull/462) [`23ecea4`](https://github.com/VoltAgent/voltagent/commit/23ecea421b8c699f5c395dc8aed687f94d558b6c) Thanks [@omeraplak](https://github.com/omeraplak)! - Update Zod to v3.25.0 for compatibility with Vercel AI@5 + - Updated Zod dependency to ^3.25.0 across all packages + - Maintained compatibility with zod-from-json-schema@0.0.5 + - Fixed TypeScript declaration build hanging issue + - Resolved circular dependency issues in the build process + +## 0.2.7 + +### Patch Changes + +- [#463](https://github.com/VoltAgent/voltagent/pull/463) [`760a294`](https://github.com/VoltAgent/voltagent/commit/760a294e4d68742d8701d54dc1c541c87959e5d8) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: update base template to always include VoltOpsClient for observability + + ### What's New + + The create-voltagent-app template now always includes VoltOpsClient configuration, making it easier for users to enable production observability with a single click from the VoltOps Console. + + ### Changes + - **Always Include VoltOpsClient**: The base template now imports and configures VoltOpsClient by default + - **Environment-Based Configuration**: VoltOpsClient reads keys from `VOLTAGENT_PUBLIC_KEY` and `VOLTAGENT_SECRET_KEY` environment variables + - **Seamless Console Integration**: Works with the new one-click observability setup in VoltOps Console + + ### Template Structure + + ```typescript + import { VoltAgent, VoltOpsClient, Agent } from "@voltagent/core"; + + // ... agent configuration ... + + new VoltAgent({ + agents: { agent }, + workflows: { expenseApprovalWorkflow }, + logger, + voltOpsClient: new VoltOpsClient({ + publicKey: process.env.VOLTAGENT_PUBLIC_KEY || "", + secretKey: process.env.VOLTAGENT_SECRET_KEY || "", + }), + }); + ``` + + ### Benefits + - **Zero Configuration**: New projects are ready for observability out of the box + - **Console Integration**: Enable observability with one click from VoltOps Console + - **Production Ready**: Template follows best practices for production deployments + + This change ensures all new VoltAgent projects created with create-voltagent-app are ready for production observability from day one. + +## 0.2.6 + +### Patch Changes + +- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements + + This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + + **Key improvements:** + - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs + - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration + - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries + - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup + - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + + These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. + +## 0.2.3 + +### Patch Changes + +- [#404](https://github.com/VoltAgent/voltagent/pull/404) [`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add @voltagent/logger with createPinoLogger to new project templates + + Enhanced the create-voltagent-app templates to include @voltagent/logger by default in new projects. This provides new VoltAgent applications with production-ready logging capabilities out of the box. + + **Changes:** + - Added `@voltagent/logger` as a dependency in generated projects + - Updated templates to import and use `createPinoLogger` instead of relying on the default ConsoleLogger + - New projects now have pretty-formatted, colored logs in development + - Automatic environment-based configuration (pretty in dev, JSON in production) + + **Generated Code Example:** + + ```typescript + import { createPinoLogger } from "@voltagent/logger"; + + const logger = createPinoLogger({ + level: "info", + name: "my-voltagent-app", + }); + + const voltAgent = new VoltAgent({ + agents: [agent], + logger, + }); + ``` + + This ensures new VoltAgent projects start with professional logging capabilities, improving the developer experience and making applications production-ready from day one. + +## 0.2.0 + +### Minor Changes + +- [`8b143cb`](https://github.com/VoltAgent/voltagent/commit/8b143cbd6f4349fe62158d7e78a5a239fec7a9e2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: modernize create-voltagent-app CLI + - Add AI provider selection (OpenAI, Anthropic, Google, Groq, Mistral, Ollama) + - Add optional API key input with skip option + - Automatic .env file generation based on selected provider + - Package manager detection - only show installed ones + - Auto-install dependencies after project creation + - Full Windows support with cross-platform commands + - Ollama local LLM support with default configuration + - Dynamic template generation based on selected AI provider + +### Patch Changes + +- [`8b143cb`](https://github.com/VoltAgent/voltagent/commit/8b143cbd6f4349fe62158d7e78a5a239fec7a9e2) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: include create-voltagent-app in build:all script + + The create-voltagent-app package was not being built during GitHub Actions release workflow because it doesn't have the @voltagent/ scope prefix. Added explicit scope to build:all command to ensure the CLI tool is properly built before publishing. + +## 0.1.33 + +### Patch Changes + +- [#371](https://github.com/VoltAgent/voltagent/pull/371) [`6ddedc2`](https://github.com/VoltAgent/voltagent/commit/6ddedc2b9be9c3dc4978dc53198a43c2cba74945) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add comprehensive workflow example to new projects + + This change enhances the `create-voltagent-app` template by including a new, comprehensive workflow example. The goal is to provide new users with a practical, out-of-the-box demonstration of VoltAgent's core workflow capabilities. + + The new template now includes: + - A `comprehensive-workflow` that showcases the combined use of `andThen`, `andAgent`, `andAll`, `andRace`, and `andWhen`. + - A dedicated `workflows` directory (`src/workflows`) to promote a modular project structure. + - The workflow uses a self-contained `sentimentAgent`, separating it from the main project agent to ensure clarity and avoid conflicts. + + This provides a much richer starting point for developers, helping them understand and build their own workflows more effectively. + +## 0.1.31 + +### Patch Changes + +- [`00d70cb`](https://github.com/VoltAgent/voltagent/commit/00d70cbb570e4d748ab37e177e4e5df869d52e03) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: update VoltAgent docs MCP configs + +## 0.1.28 + +### Patch Changes + +- [#278](https://github.com/VoltAgent/voltagent/pull/278) [`85d979d`](https://github.com/VoltAgent/voltagent/commit/85d979d5205f23ab6e3a85e68af6c46fa7c0f648) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: introduce VoltAgent MCP Docs Server for IDE integration + + Added comprehensive MCP (Model Context Protocol) Docs Server integration to enable AI assistants in IDEs to access VoltAgent documentation directly. This feature allows developers to ask their AI assistants questions about VoltAgent directly within their development environment. + + **New Features:** + - **`@voltagent/docs-mcp`** package: MCP server that provides access to VoltAgent documentation + - **CLI MCP commands**: Setup, test, status, and remove MCP configurations + - `volt mcp setup` - Interactive setup for Cursor, Windsurf, or VS Code + - `volt mcp test` - Test MCP connection and provide usage examples + - `volt mcp status` - Show current MCP configuration status + - `volt mcp remove` - Remove MCP configuration + - **IDE Configuration**: Automatic configuration file generation for supported IDEs + - **Multi-IDE Support**: Works with Cursor, Windsurf, and VS Code + + **Usage:** + + ```bash + # Setup MCP for your IDE + volt mcp setup + + # Test the connection + volt mcp test + + # Check status + volt mcp status + ``` + + Once configured, developers can ask their AI assistant questions like: + - "How do I create an agent in VoltAgent?" + - "Is there a VoltAgent example with Next.js?" + - "How do I use voice features?" + - "What are the latest updates?" + + The MCP server provides real-time access to VoltAgent documentation, examples, and best practices directly within the IDE environment. + +## 0.1.26 + +### Patch Changes + +- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 + +## 0.1.21 + +### Patch Changes + +- [#155](https://github.com/VoltAgent/voltagent/pull/155) [`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c) Thanks [@baseballyama](https://github.com/baseballyama)! - chore: update `tsconfig.json`'s `target` to `ES2022` + +- [#162](https://github.com/VoltAgent/voltagent/pull/162) [`b164bd0`](https://github.com/VoltAgent/voltagent/commit/b164bd014670452cb162b388f03565db992767af) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: pin zod version to 3.24.2 to avoid "Type instantiation is excessively deep and possibly infinite" error + + Fixed compatibility issues between different zod versions that were causing TypeScript compilation errors. This issue occurs when multiple packages use different patch versions of zod (e.g., 3.23.x vs 3.24.x), leading to type instantiation depth problems. By pinning to 3.24.2, we ensure consistent behavior across all packages. + + See: https://github.com/colinhacks/zod/issues/3435 + +## 0.1.18 + +### Patch Changes + +- [#102](https://github.com/VoltAgent/voltagent/pull/102) [`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3) Thanks [@omeraplak](https://github.com/omeraplak)! - refactor: use 'instructions' field for Agent definitions in examples - #88 + + Updated documentation examples (READMEs, docs, blogs) and relevant package code examples to use the `instructions` field instead of `description` when defining `Agent` instances. + + This change aligns the examples with the preferred API usage for the `Agent` class, where `instructions` provides behavioral guidance to the agent/LLM. This prepares for the eventual deprecation of the `description` field specifically for `Agent` class definitions. + + **Example Change for Agent Definition:** + + ```diff + const agent = new Agent({ + name: "My Assistant", + - description: "A helpful assistant.", + + instructions: "A helpful assistant.", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + ``` + +## 0.1.16 + +### Patch Changes + +- [`13db262`](https://github.com/VoltAgent/voltagent/commit/13db2621ae6b730667f9991d3c2129c85265e925) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: Update Zod to version 3.24.2 to resolve "Type instantiation is excessively deep and possibly infinite" error (related to https://github.com/colinhacks/zod/issues/3435). + +## 0.1.14 + +### Patch Changes + +- [`8e6d2e9`](https://github.com/VoltAgent/voltagent/commit/8e6d2e994398c1a727d4afea39d5e34ffc4a5fca) Thanks [@omeraplak](https://github.com/omeraplak)! - chore: add README + +## 0.1.11 + +### Patch Changes + +- [#33](https://github.com/VoltAgent/voltagent/pull/33) [`3ef2eaa`](https://github.com/VoltAgent/voltagent/commit/3ef2eaa9661e8ecfebf17af56b09af41285d0ca9) Thanks [@kwaa](https://github.com/kwaa)! - Update package.json files: + - Remove `src` directory from the `files` array. + - Add explicit `exports` field for better module resolution. + +--- + +## Package: @voltagent/docs-mcp + +## 2.0.2 + +### Patch Changes + +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +## 2.0.1 + +### Patch Changes + +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +## 2.0.0 + +### Major Changes + +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +## 1.0.21 + +### Patch Changes + +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` + +## 1.0.16 + +### Patch Changes + +- [#627](https://github.com/VoltAgent/voltagent/pull/627) [`0dafbf0`](https://github.com/VoltAgent/voltagent/commit/0dafbf06deb0190de5d865ac522127b2702f42ca) Thanks [@Theadd](https://github.com/Theadd)! - fix(docs-mcp): update JSON Schema target to draft-7 for tool compatibilityfix(docs): update JSON Schema target to draft-7 for tool compatibility + + The MCP tool schemas were using JSON Schema draft-2020-12 features that weren't supported by the current validator. Updated to explicitly use draft-7 format for better compatibility.The MCP tool schemas were using JSON Schema draft-2020-12 features that weren't supported by the current validator. Updated to explicitly use draft-7 format for better compatibility. + - Changed z.toJSONSchema() to use draft-7 target- Changed z.toJSONSchema() to use draft-7 target + - Fixed tool registration failures due to schema validation errors- Fixed tool registration failures due to schema validation errors + - Removed dependency on unsupported $dynamicRef feature- Removed dependency on unsupported $dynamicRef feature + + Fixes #626 + +## 1.0.14 + +### Patch Changes + +- [`9cc4ea4`](https://github.com/VoltAgent/voltagent/commit/9cc4ea4a4985320139e33e8029f299c7ec8329a6) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: @voltagent/core peerDependency version + +## 1.0.2 + +### Patch Changes + +- [#571](https://github.com/VoltAgent/voltagent/pull/571) [`b801a8d`](https://github.com/VoltAgent/voltagent/commit/b801a8da47da5cad15b8637635f83acab5e0d6fc) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Zod v4 support (backwards-compatible with v3) + + What’s new + - Core + server now support `zod` v4 while keeping v3 working. + - Peer ranges expanded to `"zod": "^3.25.0 || ^4.0.0"`. + - JSON Schema → Zod conversion handles both versions: + - Uses `zod-from-json-schema@^0.5.0` when Zod v4 is detected. + - Falls back to `zod-from-json-schema@^0.0.5` via alias `zod-from-json-schema-v3` for Zod v3. + - Implemented in MCP client (core) and object handlers (server-core). + + Why + - Zod v4 introduces changes that require a version-aware conversion path. This update adds seamless compatibility for both major versions. + + Impact + - No breaking changes. Projects on Zod v3 continue to work unchanged. Projects can upgrade to Zod v4 without code changes. + + Notes + - If your bundler disallows npm aliasing, ensure it can resolve `zod-from-json-schema-v3` (alias to `zod-from-json-schema@^0.0.5`). + +## 1.0.2-next.1 + +### Patch Changes + +- [#551](https://github.com/VoltAgent/voltagent/pull/551) [`77a3f64`](https://github.com/VoltAgent/voltagent/commit/77a3f64dea6e8a06fbbd72878711efa9ceb90bc3) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Zod v4 support (backwards-compatible with v3) + + What’s new + - Core + server now support `zod` v4 while keeping v3 working. + - Peer ranges expanded to `"zod": "^3.25.0 || ^4.0.0"`. + - JSON Schema → Zod conversion handles both versions: + - Uses `zod-from-json-schema@^0.5.0` when Zod v4 is detected. + - Falls back to `zod-from-json-schema@^0.0.5` via alias `zod-from-json-schema-v3` for Zod v3. + - Implemented in MCP client (core) and object handlers (server-core). + + Why + - Zod v4 introduces changes that require a version-aware conversion path. This update adds seamless compatibility for both major versions. + + Impact + - No breaking changes. Projects on Zod v3 continue to work unchanged. Projects can upgrade to Zod v4 without code changes. + + Notes + - If your bundler disallows npm aliasing, ensure it can resolve `zod-from-json-schema-v3` (alias to `zod-from-json-schema@^0.0.5`). + +## 1.0.2-next.0 + +### Patch Changes + +- [#551](https://github.com/VoltAgent/voltagent/pull/551) [`77a3f64`](https://github.com/VoltAgent/voltagent/commit/77a3f64dea6e8a06fbbd72878711efa9ceb90bc3) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Zod v4 support (backwards-compatible with v3) + + What’s new + - Core + server now support `zod` v4 while keeping v3 working. + - Peer ranges expanded to `"zod": "^3.25.0 || ^4.0.0"`. + - JSON Schema → Zod conversion handles both versions: + - Uses `zod-from-json-schema@^0.5.0` when Zod v4 is detected. + - Falls back to `zod-from-json-schema@^0.0.5` via alias `zod-from-json-schema-v3` for Zod v3. + - Implemented in MCP client (core) and object handlers (server-core). + + Why + - Zod v4 introduces changes that require a version-aware conversion path. This update adds seamless compatibility for both major versions. + + Impact + - No breaking changes. Projects on Zod v3 continue to work unchanged. Projects can upgrade to Zod v4 without code changes. + + Notes + - If your bundler disallows npm aliasing, ensure it can resolve `zod-from-json-schema-v3` (alias to `zod-from-json-schema@^0.0.5`). + +- Updated dependencies [[`77a3f64`](https://github.com/VoltAgent/voltagent/commit/77a3f64dea6e8a06fbbd72878711efa9ceb90bc3)]: + - @voltagent/core@1.1.7-next.0 + +## 1.0.1 + +### Patch Changes + +- [#546](https://github.com/VoltAgent/voltagent/pull/546) [`f12f344`](https://github.com/VoltAgent/voltagent/commit/f12f34405edf0fcb417ed098deba62570260fb81) Thanks [@omeraplak](https://github.com/omeraplak)! - chore: align Zod to ^3.25.76 and fix type mismatch with AI SDK + + We aligned Zod versions across packages to `^3.25.76` to match AI SDK peer ranges and avoid multiple Zod instances at runtime. + + Why this matters + - Fixes TypeScript narrowing issues in workflows when consuming `@voltagent/core` from npm with a different Zod instance (e.g., `ai` packages pulling newer Zod). + - Prevents errors like "Spread types may only be created from object types" where `data` failed to narrow because `z.ZodTypeAny` checks saw different Zod identities. + + What changed + - `@voltagent/server-core`, `@voltagent/server-hono`: dependencies.zod → `^3.25.76`. + - `@voltagent/docs-mcp`, `@voltagent/core`: devDependencies.zod → `^3.25.76`. + - Examples and templates updated to use `^3.25.76` for consistency (non-publishable). + + Notes for consumers + - Ensure a single Zod version is installed (consider a workspace override to pin Zod to `3.25.76`). + - This improves compatibility with `ai@5.x` packages that require `zod@^3.25.76 || ^4`. + +## 1.0.0 + +### Minor Changes + +- [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: update docs & examples for V1 + +## 1.0.0-next.1 + +### Minor Changes + +- [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: update docs & examples for V1 + +## 1.0.0-next.0 + +### Patch Changes + +- Updated dependencies [[`64a50e6`](https://github.com/VoltAgent/voltagent/commit/64a50e6800dec844fad7b9f3a3b1c2c8d0486229), [`9e8b211`](https://github.com/VoltAgent/voltagent/commit/9e8b2119a783942f114459f0a9b93e645727445e)]: + - @voltagent/core@1.0.0-next.0 + +## 0.2.3 + +### Patch Changes + +- [#462](https://github.com/VoltAgent/voltagent/pull/462) [`23ecea4`](https://github.com/VoltAgent/voltagent/commit/23ecea421b8c699f5c395dc8aed687f94d558b6c) Thanks [@omeraplak](https://github.com/omeraplak)! - Update Zod to v3.25.0 for compatibility with Vercel AI@5 + - Updated Zod dependency to ^3.25.0 across all packages + - Maintained compatibility with zod-from-json-schema@0.0.5 + - Fixed TypeScript declaration build hanging issue + - Resolved circular dependency issues in the build process + +## 0.2.2 + +### Patch Changes + +- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements + + This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + + **Key improvements:** + - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs + - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration + - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries + - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup + - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + + These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. + +## 0.2.1 + +### Patch Changes + +- [#401](https://github.com/VoltAgent/voltagent/pull/401) [`4a7145d`](https://github.com/VoltAgent/voltagent/commit/4a7145debd66c7b1dfb953608e400b6c1ed02db7) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve TypeScript performance issues by fixing Zod dependency configuration (#377) + + Moved Zod from direct dependencies to peer dependencies in @voltagent/vercel-ai to prevent duplicate Zod installations that were causing TypeScript server slowdowns. Also standardized Zod versions across the workspace to ensure consistency. + + Changes: + - @voltagent/vercel-ai: Moved `zod` from dependencies to peerDependencies + - @voltagent/docs-mcp: Updated `zod` from `^3.23.8` to `3.24.2` + - @voltagent/with-postgres: Updated `zod` from `^3.24.2` to `3.24.2` (removed caret) + + This fix significantly improves TypeScript language server performance by ensuring only one Zod version is processed, eliminating the "Type instantiation is excessively deep and possibly infinite" errors that users were experiencing. + +- Updated dependencies [[`57c4874`](https://github.com/VoltAgent/voltagent/commit/57c4874d4d4807c50242b2e34ab9574fc6129888), [`da66f86`](https://github.com/VoltAgent/voltagent/commit/da66f86d92a278007c2d3386d22b482fa70d93ff), [`4a7145d`](https://github.com/VoltAgent/voltagent/commit/4a7145debd66c7b1dfb953608e400b6c1ed02db7)]: + - @voltagent/core@0.1.61 + +## 0.2.0 + +### Minor Changes + +- [#367](https://github.com/VoltAgent/voltagent/pull/367) [`d71efff`](https://github.com/VoltAgent/voltagent/commit/d71efff5d2b9822d787bfed62329e56ee441774a) Thanks [@Theadd](https://github.com/Theadd)! - feat(docs-mcp): dynamically discover example files + + Refactor the getExampleContent function to dynamically discover all relevant files in an example directory instead of relying on a hardcoded list. This introduces a new discoverExampleFiles helper function that recursively scans for .ts files in src, app, and voltagent directories with depth limits, while retaining backward compatibility. This ensures that documentation examples with complex file structures containing voltagent related code are fully captured and displayed. + + Resolves #365 + +## 0.1.8 + +### Patch Changes + +- [`00d70cb`](https://github.com/VoltAgent/voltagent/commit/00d70cbb570e4d748ab37e177e4e5df869d52e03) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: update VoltAgent docs MCP configs + +## 0.1.1 + +### Patch Changes + +- [#278](https://github.com/VoltAgent/voltagent/pull/278) [`85d979d`](https://github.com/VoltAgent/voltagent/commit/85d979d5205f23ab6e3a85e68af6c46fa7c0f648) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: introduce VoltAgent MCP Docs Server for IDE integration + + Added comprehensive MCP (Model Context Protocol) Docs Server integration to enable AI assistants in IDEs to access VoltAgent documentation directly. This feature allows developers to ask their AI assistants questions about VoltAgent directly within their development environment. + + **New Features:** + - **`@voltagent/docs-mcp`** package: MCP server that provides access to VoltAgent documentation + - **CLI MCP commands**: Setup, test, status, and remove MCP configurations + - `volt mcp setup` - Interactive setup for Cursor, Windsurf, or VS Code + - `volt mcp test` - Test MCP connection and provide usage examples + - `volt mcp status` - Show current MCP configuration status + - `volt mcp remove` - Remove MCP configuration + - **IDE Configuration**: Automatic configuration file generation for supported IDEs + - **Multi-IDE Support**: Works with Cursor, Windsurf, and VS Code + + **Usage:** + + ```bash + # Setup MCP for your IDE + volt mcp setup + + # Test the connection + volt mcp test + + # Check status + volt mcp status + ``` + + Once configured, developers can ask their AI assistant questions like: + - "How do I create an agent in VoltAgent?" + - "Is there a VoltAgent example with Next.js?" + - "How do I use voice features?" + - "What are the latest updates?" + + The MCP server provides real-time access to VoltAgent documentation, examples, and best practices directly within the IDE environment. + +- Updated dependencies [[`937ccf8`](https://github.com/VoltAgent/voltagent/commit/937ccf8bf84a4261ee9ed2c94aab9f8c49ab69bd)]: + - @voltagent/core@0.1.39 + +--- + +## Package: @voltagent/evals + +## 2.0.2 + +### Patch Changes + +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505)]: + - @voltagent/internal@1.0.2 + - @voltagent/scorers@2.0.2 + - @voltagent/sdk@2.0.2 + +## 2.0.1 + +### Patch Changes + +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2)]: + - @voltagent/internal@1.0.1 + - @voltagent/scorers@2.0.1 + - @voltagent/sdk@2.0.1 + +## 2.0.0 + +### Major Changes + +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +### Patch Changes + +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/scorers@2.0.0 + - @voltagent/internal@1.0.0 + - @voltagent/sdk@2.0.0 + +## 1.0.4 + +### Patch Changes + +- [#805](https://github.com/VoltAgent/voltagent/pull/805) [`ad4893a`](https://github.com/VoltAgent/voltagent/commit/ad4893a523be60cef93706a5aa6d2e0096cc306b) Thanks [@lzj960515](https://github.com/lzj960515)! - feat: add exports field to package.json for module compatibility + +- Updated dependencies [[`ad4893a`](https://github.com/VoltAgent/voltagent/commit/ad4893a523be60cef93706a5aa6d2e0096cc306b)]: + - @voltagent/scorers@1.0.2 + +## 1.0.3 + +### Patch Changes + +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` +- Updated dependencies [[`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e)]: + - @voltagent/internal@0.0.12 + - @voltagent/scorers@1.0.1 + - @voltagent/sdk@1.0.1 + +## 1.0.2 + +### Patch Changes + +- [`d5170ce`](https://github.com/VoltAgent/voltagent/commit/d5170ced80fbc9fd2de03bb7eaff1cb31424d618) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add runtime payload support for evals + +## 1.0.1 + +### Patch Changes + +- [#690](https://github.com/VoltAgent/voltagent/pull/690) [`c8f9032`](https://github.com/VoltAgent/voltagent/commit/c8f9032fd806efbd22da9c8bd0a10f59a388fb7b) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: allow experiment scorer configs to declare their own `id`, so `passCriteria` entries that target `scorerId` work reliably and scorer summaries use the caller-provided identifiers. + +## 1.0.0 + +### Major Changes + +- [#674](https://github.com/VoltAgent/voltagent/pull/674) [`5aa84b5`](https://github.com/VoltAgent/voltagent/commit/5aa84b5bcf57d19bbe33cc791f0892c96bb3944b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: initial release + +### Patch Changes + +- Updated dependencies [[`5aa84b5`](https://github.com/VoltAgent/voltagent/commit/5aa84b5bcf57d19bbe33cc791f0892c96bb3944b), [`5aa84b5`](https://github.com/VoltAgent/voltagent/commit/5aa84b5bcf57d19bbe33cc791f0892c96bb3944b)]: + - @voltagent/scorers@1.0.0 + - @voltagent/sdk@1.0.0 + +--- + +## Package: @voltagent/internal + +## 1.0.2 + +### Patch Changes + +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +## 1.0.1 + +### Patch Changes + +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +## 1.0.0 + +### Major Changes + +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +## 0.0.12 + +### Patch Changes + +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` + +## 0.0.11 + +### Patch Changes + +- [#596](https://github.com/VoltAgent/voltagent/pull/596) [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7) Thanks [@omeraplak](https://github.com/omeraplak)! - - add `@voltagent/a2a-server`, a JSON-RPC Agent-to-Agent (A2A) server that lets external agents call your VoltAgent instance over HTTP/SSE + - teach `@voltagent/core`, `@voltagent/server-core`, and `@voltagent/server-hono` to auto-register configured A2A servers so adding `{ a2aServers: { ... } }` on `VoltAgent` and opting into `honoServer` instantly exposes discovery and RPC endpoints + - forward request context (`userId`, `sessionId`, metadata) into agent invocations and provide task management hooks, plus allow filtering/augmenting exposed agents by default + - document the setup in `website/docs/agents/a2a/a2a-server.md` and refresh `examples/with-a2a-server` with basic usage and task-store customization + - A2A endpoints are now described in Swagger/OpenAPI and listed in the startup banner whenever an A2A server is registered, making discovery of `/.well-known/...` and `/a2a/:serverId` routes trivial. + + **Getting started** + + ```ts + import { Agent, VoltAgent } from "@voltagent/core"; + import { A2AServer } from "@voltagent/a2a-server"; + import { honoServer } from "@voltagent/server-hono"; + + const assistant = new Agent({ + name: "SupportAgent", + purpose: "Handle support questions from partner agents.", + model: myModel, + }); + + const a2aServer = new A2AServer({ + name: "support-agent", + version: "0.1.0", + }); + + export const voltAgent = new VoltAgent({ + agents: { assistant }, + a2aServers: { a2aServer }, + server: honoServer({ port: 3141 }), + }); + ``` + +- [#596](https://github.com/VoltAgent/voltagent/pull/596) [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7) Thanks [@omeraplak](https://github.com/omeraplak)! - - Ship `@voltagent/mcp-server`, a transport-agnostic MCP provider that surfaces VoltAgent agents, workflows, tools, prompts, and resources over stdio, SSE, and HTTP. + - Wire MCP registration through `@voltagent/core`, `@voltagent/server-core`, and `@voltagent/server-hono` so a single `VoltAgent` constructor opt-in (optionally with `honoServer`) exposes stdio mode immediately and HTTP/SSE endpoints when desired. + - Filter child sub-agents automatically and lift an agent's `purpose` (fallback to `instructions`) into the MCP tool description for cleaner IDE listings out of the box. + - Document the workflow in `website/docs/agents/mcp/mcp-server.md` and refresh `examples/with-mcp-server` with stdio-only and HTTP/SSE configurations. + - When MCP is enabled we now publish REST endpoints in Swagger/OpenAPI and echo them in the startup banner so you can discover `/mcp/*` routes without digging through code. + + **Getting started** + + ```ts + import { Agent, VoltAgent } from "@voltagent/core"; + import { MCPServer } from "@voltagent/mcp-server"; + import { honoServer } from "@voltagent/server-hono"; + + const assistant = new Agent({ + name: "AssistantAgent", + purpose: "Respond to support questions and invoke helper tools when needed.", + model: myModel, + }); + + const mcpServer = new MCPServer({ + name: "support-mcp", + version: "1.0.0", + agents: { assistant }, + protocols: { stdio: true, http: false, sse: false }, + }); + + export const voltAgent = new VoltAgent({ + agents: { assistant }, + mcpServers: { primary: mcpServer }, + server: honoServer({ port: 3141 }), // flip http/sse to true when you need remote clients + }); + ``` + +## 0.0.10 + +### Patch Changes + +- [#559](https://github.com/VoltAgent/voltagent/pull/559) [`134bf9a`](https://github.com/VoltAgent/voltagent/commit/134bf9a2978f0b069f842910fb4fb3e969f70390) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: add deps that the core types rely on, i.e. `type-fest` or they are not installed by default by package managers + +## 0.0.9 + +### Patch Changes + +- [`5968cef`](https://github.com/VoltAgent/voltagent/commit/5968cef5fe417cd118867ac78217dddfbd60493d) Thanks [@omeraplak](https://github.com/omeraplak)! - chore: remove console.warn from deepClone function + + Removed the console.warn statement from the deepClone function's error handling. Since we require Node.js 17+ where structuredClone is always available, this warning is unnecessary and can clutter logs in development environments. + + ## What Changed + - Removed `console.warn("Failed to deep clone object, using shallow clone", { error });` from the catch block + - Kept the fallback logic intact for edge cases + - Maintained the development-only condition check even though the warning is removed + + This change reduces unnecessary console output while maintaining the same fallback behavior for shallow cloning when structuredClone fails. + +## 0.0.8 + +### Patch Changes + +- [#472](https://github.com/VoltAgent/voltagent/pull/472) [`8de5785`](https://github.com/VoltAgent/voltagent/commit/8de5785e385bec632f846bcae44ee5cb22a9022e) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: Migrate to using `safeStringify` to prevent issues using the JSON.stringify/parse method, in addition use structuredClone via Nodejs instead legacy method that errors + +## 0.0.7 + +### Patch Changes + +- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements + + This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + + **Key improvements:** + - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs + - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration + - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries + - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup + - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + + These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. + +## 0.0.6 + +### Patch Changes + +- [#404](https://github.com/VoltAgent/voltagent/pull/404) [`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726) Thanks [@omeraplak](https://github.com/omeraplak)! - refactor: remove devLogger in favor of standardized logging approach + + Removed the internal `devLogger` utility to align with the new standardized logging architecture. This change simplifies the internal package and reduces code duplication by leveraging the comprehensive logging system now available in @voltagent/core and @voltagent/logger. + + **Changes:** + - Removed `devLogger` from exports + - Removed development-only logging utility + - Consumers should use the logger instance provided by VoltAgent or create their own using @voltagent/logger + + This is part of the logging system refactoring to provide a more consistent and powerful logging experience across all VoltAgent packages. + +## 0.0.5 + +### Patch Changes + +- [`6fadbb0`](https://github.com/VoltAgent/voltagent/commit/6fadbb098fe40d8b658aa3386e6126fea155f117) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: createAsyncIterableStream import issue + +## 0.0.4 + +### Patch Changes + +- [#324](https://github.com/VoltAgent/voltagent/pull/324) [`8da1ecc`](https://github.com/VoltAgent/voltagent/commit/8da1eccd0332d1f9037085e16cb0b7d5afaac479) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: improve dev logger environment detection and add debug method + + Enhanced the dev logger to be more intelligent about when to show logs. Previously, the logger only showed logs when `NODE_ENV === "development"`. Now it shows logs unless `NODE_ENV` is explicitly set to `"production"`, `"test"`, or `"ci"`. + + **Changes:** + - **Improved Environment Detection**: Dev logger now shows logs when `NODE_ENV` is undefined, empty string, or any value other than "production", "test", or "ci" + - **Better Developer Experience**: Developers who don't set NODE_ENV will now see logs by default, which is more intuitive + - **Added Debug Method**: Included a placeholder `debug` method for future structured logging with Pino + - **Updated Tests**: Comprehensive test coverage for the new logging behavior + + **Before:** + - Logs only shown when `NODE_ENV === "development"` + - Empty string or undefined NODE_ENV = no logs ❌ + + **After:** + - Logs hidden only when `NODE_ENV === "production"`, `NODE_ENV === "test"`, or `NODE_ENV === "ci"` + - Empty string, undefined, or other values = logs shown ✅ + + This change makes the development experience smoother as most developers don't explicitly set NODE_ENV during local development. + +## 0.0.3 + +### Patch Changes + +- [#311](https://github.com/VoltAgent/voltagent/pull/311) [`1f7fa14`](https://github.com/VoltAgent/voltagent/commit/1f7fa140fcc4062fe85220e61f276e439392b0b4) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix(core, vercel-ui): Currently the `convertToUIMessages` function does not handle tool calls in steps correctly as it does not properly default filter non-tool related steps for sub-agents, same as the `data-stream` functions and in addition in the core the `operationContext` does not have the `subAgent` fields set correctly. + + ### Changes + - deprecated `isSubAgentStreamPart` in favor of `isSubAgent` for universal use + - by default `convertToUIMessages` now filters out non-tool related steps for sub-agents + - now able to exclude specific parts or steps (from OperationContext) in `convertToUIMessages` + + *** + + ### Internals + + New utils were added to the internal package: + - `isObject` + - `isFunction` + - `isPlainObject` + - `isEmptyObject` + - `isNil` + - `hasKey` + +## 0.0.2 + +### Patch Changes + +- [`94de46a`](https://github.com/VoltAgent/voltagent/commit/94de46ab2b7ccead47a539e93c72b357f17168f6) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add `deepClone` function to `object-utils` module + + Added a new `deepClone` utility function to the object-utils module for creating deep copies of complex JavaScript objects. This utility provides safe cloning of nested objects, arrays, and primitive values while handling circular references and special object types. + + Usage: + + ```typescript + import { deepClone } from "@voltagent/core/utils/object-utils"; + + const original = { + nested: { + array: [1, 2, { deep: "value" }], + date: new Date(), + }, + }; + + const cloned = deepClone(original); + // cloned is completely independent from original + ``` + + This utility is particularly useful for agent state management, configuration cloning, and preventing unintended mutations in complex data structures. + +- Updated dependencies []: + - @voltagent/core@0.1.44 + +--- + +## Package: @voltagent/langfuse-exporter + +## 2.0.2 + +### Patch Changes + +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +## 2.0.1 + +### Patch Changes + +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +## 2.0.0 + +### Major Changes + +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +### Patch Changes + +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/core@2.0.0 + +## 1.1.3 + +### Patch Changes + +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` + +## 1.1.2 + +### Patch Changes + +- [`9cc4ea4`](https://github.com/VoltAgent/voltagent/commit/9cc4ea4a4985320139e33e8029f299c7ec8329a6) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: @voltagent/core peerDependency version + +## 1.1.1 + +## 1.1.1-next.0 + +### Patch Changes + +- Updated dependencies [[`77a3f64`](https://github.com/VoltAgent/voltagent/commit/77a3f64dea6e8a06fbbd72878711efa9ceb90bc3)]: + - @voltagent/core@1.1.7-next.0 + +## 1.1.0 + +### Minor Changes + +- [#554](https://github.com/VoltAgent/voltagent/pull/554) [`3a70b05`](https://github.com/VoltAgent/voltagent/commit/3a70b05515d04ea7bc39135d3d399ecd7a59dbe3) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add createLangfuseSpanProcessor helper and robust attribute mappings for new OpenTelemetry observability + + What changed for you + - New helper: `createLangfuseSpanProcessor` to plug Langfuse export directly into VoltAgent’s OpenTelemetry-based observability without touching core. + - Improved attribute mappings with careful fallbacks to align `@voltagent/core` span attributes and Langfuse fields (usage, model params, input/output, user/session, tags, names). + - Updated `examples/with-langfuse` to demonstrate the new integration. + + Quick start + + ```ts + import { Agent, VoltAgent, VoltAgentObservability } from "@voltagent/core"; + import { createLangfuseSpanProcessor } from "@voltagent/langfuse-exporter"; + + // Configure Observability: add Langfuse via SpanProcessor + const observability = new VoltAgentObservability({ + spanProcessors: [ + createLangfuseSpanProcessor({ + publicKey: process.env.LANGFUSE_PUBLIC_KEY, + secretKey: process.env.LANGFUSE_SECRET_KEY, + baseUrl: process.env.LANGFUSE_BASE_URL, // e.g. https://cloud.langfuse.com or self-hosted + debug: true, // optional + // batch: { maxQueueSize, maxExportBatchSize, scheduledDelayMillis, exportTimeoutMillis } + }), + ], + }); + + const agent = new Agent({ + name: "Base Agent", + // ...model, tools, memory + }); + + new VoltAgent({ + agents: { agent }, + observability, + }); + ``` + + Environment variables + - `LANGFUSE_PUBLIC_KEY` + - `LANGFUSE_SECRET_KEY` + - `LANGFUSE_BASE_URL` (optional; defaults to Langfuse cloud if omitted) + + Mapping details (highlights) + - Usage tokens: `gen_ai.usage.*` ← fallbacks to `usage.prompt_tokens`, `usage.completion_tokens`, `usage.total_tokens` from core. + - Model params: prefers `gen_ai.request.*`, falls back to `ai.model.*` from core. + - Input/output (generation): prefers `ai.prompt.messages` / `ai.response.text`, falls back to generic `input` / `output` set by core. + - Input/output (tools): prefers `tool.arguments` / `tool.result`, falls back to `input` / `output`. + - User/session: `enduser.id` ← `user.id`, `session.id` ← `conversation.id`. + - Tags: reads `tags` or parses JSON from `prompt.tags` if present. + - Name: prefers `voltagent.agent.name` then `entity.name` then span name. + + Example updated + - See `examples/with-langfuse` for a complete, working setup using `createLangfuseSpanProcessor`. + +## 1.0.0 + +## 1.0.0-next.0 + +### Patch Changes + +- Updated dependencies [[`64a50e6`](https://github.com/VoltAgent/voltagent/commit/64a50e6800dec844fad7b9f3a3b1c2c8d0486229), [`9e8b211`](https://github.com/VoltAgent/voltagent/commit/9e8b2119a783942f114459f0a9b93e645727445e)]: + - @voltagent/core@1.0.0-next.0 + +## 0.1.5 + +### Patch Changes + +- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements + + This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + + **Key improvements:** + - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs + - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration + - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries + - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup + - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + + These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. + +## 0.1.4 + +### Patch Changes + +- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 + +- Updated dependencies [[`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f), [`80fd3c0`](https://github.com/VoltAgent/voltagent/commit/80fd3c069de4c23116540a55082b891c4b376ce6)]: + - @voltagent/core@0.1.31 + +## 0.1.3 + +### Patch Changes + +- [#155](https://github.com/VoltAgent/voltagent/pull/155) [`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c) Thanks [@baseballyama](https://github.com/baseballyama)! - chore: update `tsconfig.json`'s `target` to `ES2022` + +- Updated dependencies [[`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c), [`b164bd0`](https://github.com/VoltAgent/voltagent/commit/b164bd014670452cb162b388f03565db992767af), [`9412cf0`](https://github.com/VoltAgent/voltagent/commit/9412cf0633f20d6b77c87625fc05e9e216936758)]: + - @voltagent/core@0.1.20 + +## 0.1.2 + +### Patch Changes + +- [#102](https://github.com/VoltAgent/voltagent/pull/102) [`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3) Thanks [@omeraplak](https://github.com/omeraplak)! - refactor: use 'instructions' field for Agent definitions in examples - #88 + + Updated documentation examples (READMEs, docs, blogs) and relevant package code examples to use the `instructions` field instead of `description` when defining `Agent` instances. + + This change aligns the examples with the preferred API usage for the `Agent` class, where `instructions` provides behavioral guidance to the agent/LLM. This prepares for the eventual deprecation of the `description` field specifically for `Agent` class definitions. + + **Example Change for Agent Definition:** + + ```diff + const agent = new Agent({ + name: "My Assistant", + - description: "A helpful assistant.", + + instructions: "A helpful assistant.", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + ``` + +- Updated dependencies [[`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3)]: + - @voltagent/core@0.1.14 + +## 0.1.1 + +### Patch Changes + +- [#94](https://github.com/VoltAgent/voltagent/pull/94) [`004df81`](https://github.com/VoltAgent/voltagent/commit/004df81fa6a23571391e6ddeba0dfe6bfea267e8) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Add Langfuse Observability Exporter + + This introduces a new package `@voltagent/langfuse-exporter` that allows you to export OpenTelemetry traces generated by `@voltagent/core` directly to Langfuse (https://langfuse.com/) for detailed observability into your agent's operations. + + **How to Use:** + + ## Installation + + Install the necessary packages: + + ```bash + npm install @voltagent/langfuse-exporter + ``` + + ## Configuration + + Configure the `LangfuseExporter` and pass it to `VoltAgent`: + + ```typescript + import { Agent, VoltAgent } from "@voltagent/core"; + import { VercelAIProvider } from "@voltagent/vercel-ai"; + import { openai } from "@ai-sdk/openai"; + + import { LangfuseExporter } from "@voltagent/langfuse-exporter"; + + // Ensure LANGFUSE_SECRET_KEY and LANGFUSE_PUBLIC_KEY are set in your environment + + // Define your agent(s) + const agent = new Agent({ + name: "my-voltagent-app", + instructions: "A helpful assistant that answers questions without using tools", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + + // Configure the Langfuse Exporter + const langfuseExporter = new LangfuseExporter({ + publicKey: process.env.LANGFUSE_PUBLIC_KEY, + secretKey: process.env.LANGFUSE_SECRET_KEY, + baseUrl: process.env.LANGFUSE_BASE_URL, // Optional: Defaults to Langfuse Cloud + // debug: true // Optional: Enable exporter logging + }); + + // Initialize VoltAgent with the exporter + // This automatically sets up OpenTelemetry tracing + new VoltAgent({ + agents: { + agent, // Register your agent(s) + }, + telemetryExporter: langfuseExporter, // Pass the exporter instance + }); + + console.log("VoltAgent initialized with Langfuse exporter."); + + // Now, any operations performed by 'agent' (e.g., agent.generateText(...)) + // will automatically generate traces and send them to Langfuse. + ``` + + By providing the `telemetryExporter` to `VoltAgent`, OpenTelemetry is automatically configured, and detailed traces including LLM interactions, tool usage, and agent metadata will appear in your Langfuse project. + +- Updated dependencies [[`004df81`](https://github.com/VoltAgent/voltagent/commit/004df81fa6a23571391e6ddeba0dfe6bfea267e8)]: + - @voltagent/core@0.1.12 + +--- + +## Package: @voltagent/libsql + +## 2.0.2 + +### Patch Changes + +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505)]: + - @voltagent/internal@1.0.2 + +## 2.0.1 + +### Patch Changes + +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2)]: + - @voltagent/internal@1.0.1 + +## 2.0.0 + +### Major Changes + +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +### Patch Changes + +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/core@2.0.0 + - @voltagent/internal@1.0.0 + - @voltagent/logger@2.0.0 + +## 1.1.0 + +### Minor Changes + +- [#887](https://github.com/VoltAgent/voltagent/pull/887) [`25f3859`](https://github.com/VoltAgent/voltagent/commit/25f38592293e77852f0e9e814c6c8548fcbad1a5) Thanks [@nt9142](https://github.com/nt9142)! - Add Edge/Cloudflare Workers support for @voltagent/libsql + - New `@voltagent/libsql/edge` export for edge runtimes + - Refactored adapters into core classes with dependency injection + - Edge adapters use `@libsql/client/web` for fetch-based transport + - Core uses DataView/ArrayBuffer for cross-platform compatibility + - Node.js adapters override with Buffer for better performance + + Usage: + + ```typescript + import { LibSQLMemoryAdapter } from "@voltagent/libsql/edge"; + + const adapter = new LibSQLMemoryAdapter({ + url: "libsql://your-db.turso.io", + authToken: "your-token", + }); + ``` + +## 1.0.14 + +### Patch Changes + +- [#845](https://github.com/VoltAgent/voltagent/pull/845) [`5432f13`](https://github.com/VoltAgent/voltagent/commit/5432f13bddebd869522ebffbedd9843b4476f08b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: workflow execution listing - #844 + + Added a unified way to list workflow runs so teams can audit executions across every storage backend and surface them via the API and console. + + ## What changed + - `queryWorkflowRuns` now exists on all memory adapters (in-memory, libsql, Postgres, Supabase, voltagent-memory) with filters for `workflowId`, `status`, `from`, `to`, `limit`, and `offset`. + - Server routes are consolidated under `/workflows/executions` (no path param needed); `GET /workflows/:id` also returns the workflow result schema for typed clients. Handler naming is standardized to `listWorkflowRuns`. + - VoltOps Console observability panel lists the new endpoint; REST docs updated with query params and sample responses. New unit tests cover handlers and every storage adapter. + + ## Quick fetch + + ```ts + await fetch( + "http://localhost:3141/workflows/executions?workflowId=expense-approval&status=completed&from=2024-01-01&to=2024-01-31&limit=20&offset=0" + ); + ``` + +## 1.0.13 + +### Patch Changes + +- [#820](https://github.com/VoltAgent/voltagent/pull/820) [`c5e0c89`](https://github.com/VoltAgent/voltagent/commit/c5e0c89554d85c895e3d6cbfc83ad47bd53a1b9f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: expose createdAt in memory.getMessages + + ## What Changed + + The `createdAt` timestamp is now exposed in the `metadata` object of messages retrieved via `memory.getMessages()`. This ensures that the creation time of messages is accessible across all storage adapters (`InMemory`, `Supabase`, `LibSQL`, `PostgreSQL`). + + ## Usage + + You can now access the `createdAt` timestamp from the message metadata: + + ```typescript + const messages = await memory.getMessages(userId, conversationId); + + messages.forEach((message) => { + console.log(`Message ID: ${message.id}`); + console.log(`Created At: ${message.metadata?.createdAt}`); + }); + ``` + + This change aligns the behavior of all storage adapters and ensures consistent access to message timestamps. + +## 1.0.12 + +### Patch Changes + +- [#801](https://github.com/VoltAgent/voltagent/pull/801) [`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add triggers DSL improvements and event payload simplification + - Introduce the new `createTriggers` DSL and expose trigger events via sensible provider names (e.g. `on.airtable.recordCreated`) rather than raw catalog IDs. + - Add trigger span metadata propagation so VoltAgent agents receive trigger context automatically without manual mapping. + - Simplify action dispatch payloads: `payload` now contains only the event’s raw data while trigger context lives in the `event`/`metadata` blocks, reducing boilerplate in handlers. + + ```ts + import { VoltAgent, createTriggers } from "@voltagent/core"; + + new VoltAgent({ + // ... + triggers: createTriggers((on) => { + on.airtable.recordCreated(({ payload, event }) => { + console.log("New Airtable row", payload, event.metadata); + }); + + on.gmail.newEmail(({ payload }) => { + console.log("New Gmail message", payload); + }); + }), + }); + ``` + +## 1.0.11 + +### Patch Changes + +- [#787](https://github.com/VoltAgent/voltagent/pull/787) [`5e81d65`](https://github.com/VoltAgent/voltagent/commit/5e81d6568ba3bee26083ca2a8e5d31f158e36fc0) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add full conversation step persistence across the stack: + - Core now exposes managed-memory step APIs, and the VoltAgent managed memory adapter persists/retrieves steps through VoltOps. + - LibSQL, PostgreSQL, Supabase, and server handlers provision the new `_steps` table, wire up DTOs/routes, and surface the data in Observability/Steps UI (including managed-memory backends). + + fixes: #613 + +## 1.0.10 + +### Patch Changes + +- [#738](https://github.com/VoltAgent/voltagent/pull/738) [`d3ed347`](https://github.com/VoltAgent/voltagent/commit/d3ed347e064cb36e04ed1ea98d9305b63fd968ec) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: persist workflow execution timeline events to prevent data loss after completion - #647 + + ## The Problem + + When workflows executed, their timeline events (step-start, step-complete, workflow-complete, etc.) were only visible during streaming. Once the workflow completed, the WebSocket state update would replace the execution object without the events field, causing the timeline UI to reset and lose all execution history. Users couldn't see what happened in completed or suspended workflows. + + **Symptoms:** + - Timeline showed events during execution + - Timeline cleared/reset when workflow completed + - No execution history for completed workflows + - Events were lost after browser refresh + + ## The Solution + + **Backend (Framework)**: + - Added `events`, `output`, and `cancellation` fields to `WorkflowStateEntry` interface + - Modified workflow execution to collect all stream events in memory during execution + - Persist collected events to workflow state when workflow completes, suspends, fails, or is cancelled + - Updated all storage adapters to support the new fields: + - **LibSQL**: Added schema columns + automatic migration method (`addWorkflowStateColumns`) + - **Supabase**: Added schema columns + migration detection + ALTER TABLE migration SQL + - **Postgres**: Added schema columns + INSERT/UPDATE queries + - **In-Memory**: Automatically supported via TypeScript interface + + **Frontend (Console)**: + - Updated `WorkflowPlaygroundProvider` to include events when converting `WorkflowStateEntry` → `WorkflowHistoryEntry` + - Implemented smart merge strategy for WebSocket updates: Use backend persisted events when workflow finishes, keep streaming events during execution + - Events are now preserved across page refreshes and always visible in timeline UI + + ## What Gets Persisted + + ```typescript + // In WorkflowStateEntry (stored in Memory V2): + { + "events": [ + { + "id": "evt_123", + "type": "workflow-start", + "name": "Workflow Started", + "startTime": "2025-01-24T10:00:00Z", + "status": "running", + "input": { "userId": "123" } + }, + { + "id": "evt_124", + "type": "step-complete", + "name": "Step: fetch-user", + "startTime": "2025-01-24T10:00:01Z", + "endTime": "2025-01-24T10:00:02Z", + "status": "success", + "output": { "user": { "name": "John" } } + } + ], + "output": { "result": "success" }, + "cancellation": { + "cancelledAt": "2025-01-24T10:00:05Z", + "reason": "User requested cancellation" + } + } + ``` + + ## Migration Guide + + ### LibSQL Users + + No action required - migrations run automatically on next initialization. + + ### Supabase Users + + When you upgrade and initialize the adapter, you'll see migration SQL in the console. Run it in your Supabase SQL Editor: + + ```sql + -- Add workflow event persistence columns + ALTER TABLE voltagent_workflow_states + ADD COLUMN IF NOT EXISTS events JSONB; + + ALTER TABLE voltagent_workflow_states + ADD COLUMN IF NOT EXISTS output JSONB; + + ALTER TABLE voltagent_workflow_states + ADD COLUMN IF NOT EXISTS cancellation JSONB; + ``` + + ### Postgres Users + + No action required - migrations run automatically on next initialization. + + ### In-Memory Users + + No action required - automatically supported. + + ### VoltAgent Managed Memory Users + + No action required - migrations run automatically on first request per managed memory database after API deployment. The API has been updated to: + - Include new columns in ManagedMemoryProvisioner CREATE TABLE statements (new databases) + - Run automatic column addition migration for existing databases (lazy migration on first request) + - Update PostgreSQL memory adapter to persist and retrieve events, output, and cancellation fields + + **Zero-downtime deployment:** Existing managed memory databases will be migrated lazily when first accessed after the API update. + + ## Impact + - ✅ Workflow execution timeline is now persistent and survives completion + - ✅ Full execution history visible for completed, suspended, and failed workflows + - ✅ Events, output, and cancellation metadata preserved in database + - ✅ Console UI timeline works consistently across all workflow states + - ✅ All storage backends (LibSQL, Supabase, Postgres, In-Memory) behave consistently + - ✅ No data loss on workflow completion or page refresh + +## 1.0.9 + +### Patch Changes + +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` +- Updated dependencies [[`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e)]: + - @voltagent/internal@0.0.12 + +## 1.0.8 + +### Patch Changes + +- [#674](https://github.com/VoltAgent/voltagent/pull/674) [`5aa84b5`](https://github.com/VoltAgent/voltagent/commit/5aa84b5bcf57d19bbe33cc791f0892c96bb3944b) Thanks [@omeraplak](https://github.com/omeraplak)! - ## What Changed + + Removed automatic message pruning functionality from all storage adapters (PostgreSQL, Supabase, LibSQL, and InMemory). Previously, messages were automatically deleted when the count exceeded `storageLimit` (default: 100 messages per conversation). + + ## Why This Change + + Users reported unexpected data loss when their conversation history exceeded the storage limit. Many users expect their conversation history to be preserved indefinitely rather than automatically deleted. This change gives users full control over their data retention policies. + + ## Migration Guide + + ### Before + + ```ts + const memory = new Memory({ + storage: new PostgreSQLMemoryAdapter({ + connection: process.env.DATABASE_URL, + storageLimit: 200, // Messages auto-deleted after 200 + }), + }); + ``` + + ### After + + ```ts + const memory = new Memory({ + storage: new PostgreSQLMemoryAdapter({ + connection: process.env.DATABASE_URL, + // No storageLimit - all messages preserved + }), + }); + ``` + + ### If You Need Message Cleanup + + Implement your own cleanup logic using the `clearMessages()` method: + + ```ts + // Clear all messages for a conversation + await memory.clearMessages(userId, conversationId); + + // Clear all messages for a user + await memory.clearMessages(userId); + ``` + + ## Affected Packages + - `@voltagent/core` - Removed `storageLimit` from types + - `@voltagent/postgres` - Removed from PostgreSQL adapter + - `@voltagent/supabase` - Removed from Supabase adapter + - `@voltagent/libsql` - Removed from LibSQL adapter + + ## Impact + - ✅ No more unexpected data loss + - ✅ Users have full control over message retention + - ⚠️ Databases may grow larger over time (consider implementing manual cleanup) + - ⚠️ Breaking change: `storageLimit` parameter no longer accepted + +## 1.0.7 + +### Patch Changes + +- [#629](https://github.com/VoltAgent/voltagent/pull/629) [`3e64b9c`](https://github.com/VoltAgent/voltagent/commit/3e64b9ce58d0e91bc272f491be2c1932a005ef48) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add memory observability + +## 1.0.6 + +### Patch Changes + +- Updated dependencies [[`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7), [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7)]: + - @voltagent/internal@0.0.11 + +## 1.0.5 + +### Patch Changes + +- [`9cc4ea4`](https://github.com/VoltAgent/voltagent/commit/9cc4ea4a4985320139e33e8029f299c7ec8329a6) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: @voltagent/core peerDependency version + +## 1.0.4 + +### Patch Changes + +- [#573](https://github.com/VoltAgent/voltagent/pull/573) [`51cc774`](https://github.com/VoltAgent/voltagent/commit/51cc774445e5c4e676563b5576868ad45d8ecb9c) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve subagent tracing hierarchy and entity filtering + + ## What Changed + + Fixed OpenTelemetry span hierarchy issues where subagent spans were overriding parent delegate_task spans instead of being properly nested as children. Also resolved entity ID filtering returning incorrect traces for subagent queries. + + ## The Problem + + When a supervisor agent delegated tasks to subagents: + 1. **Span Hierarchy**: Subagent spans appeared to replace delegate_task spans instead of being children + 2. **Entity Filtering**: Querying by subagent entity ID (e.g., `entityId=Formatter`) incorrectly returned traces that should only be associated with the root agent (e.g., `entityId=Supervisor`) + + ## The Solution + + Implemented namespace-based attribute management in trace-context: + - **Root agents** use `entity.id`, `entity.type`, `entity.name` attributes + - **Subagents** use `subagent.id`, `subagent.name`, `subagent.type` namespace + - **Subagents inherit** parent's `entity.id` for correct trace association + - **Span naming** clearly identifies subagents with `subagent:AgentName` prefix + + ## Example + + ```typescript + // Before: Incorrect hierarchy and filtering + // delegate_task span seemed to disappear + // entityId=Formatter returned Supervisor's traces + + // After: Proper hierarchy and filtering + const supervisor = new Agent({ + name: "Supervisor", + subAgents: [formatter, writer], + }); + + // Trace structure now shows: + // - Supervisor (root span) + // - delegate_task: Formatter (tool span) + // - subagent:Formatter (subagent span with proper parent) + // - (formatter's tools and operations) + + // Filtering works correctly: + // entityId=Supervisor ✓ Returns supervisor traces + // entityId=Formatter ✗ Returns no traces (correct - Formatter is a subagent) + ``` + + ## Impact + - Proper parent-child relationships in span hierarchy + - Correct trace filtering by entity ID + - Clear distinction between root agents and subagents in observability data + - Better debugging experience with properly nested spans + +## 1.0.3 + +## 1.0.3-next.0 + +### Patch Changes + +- Updated dependencies [[`77a3f64`](https://github.com/VoltAgent/voltagent/commit/77a3f64dea6e8a06fbbd72878711efa9ceb90bc3)]: + - @voltagent/core@1.1.7-next.0 + +## 1.0.2 + +### Patch Changes + +- [#562](https://github.com/VoltAgent/voltagent/pull/562) [`2886b7a`](https://github.com/VoltAgent/voltagent/commit/2886b7aab5bda296cebc0b8b2bd56d684324d799) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: using `safeStringify` instead of `JSON.stringify` + +## 1.0.1 + +### Patch Changes + +- [`a0d9e84`](https://github.com/VoltAgent/voltagent/commit/a0d9e8404fe3e2cebfc146cd4622b607bd16b462) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: @voltagent/logger dependency version + +- Updated dependencies [[`134bf9a`](https://github.com/VoltAgent/voltagent/commit/134bf9a2978f0b069f842910fb4fb3e969f70390)]: + - @voltagent/internal@0.0.10 + +## 1.0.0 + +### Major Changes + +- [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93) Thanks [@omeraplak](https://github.com/omeraplak)! - # LibSQL 1.x — Memory Adapter + + Replaces `LibSQLStorage` with Memory V2 adapter and adds vector/observability adapters. + + Full migration guide: [Migration Guide](https://voltagent.dev/docs/getting-started/migration-guide/) + + ## Migrate storage + + Before (0.1.x): + + ```ts + import { LibSQLStorage } from "@voltagent/libsql"; + + const agent = new Agent({ + // ... + memory: new LibSQLStorage({ url: "file:./.voltagent/memory.db" }), + }); + ``` + + After (1.x): + + ```ts + import { Memory } from "@voltagent/core"; + import { LibSQLMemoryAdapter } from "@voltagent/libsql"; + + const agent = new Agent({ + // ... + memory: new Memory({ + storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }), + }), + }); + ``` + + ## Optional (new) + + ```ts + import { LibSQLVectorAdapter } from "@voltagent/libsql"; + // Add vector search: new Memory({ vector: new LibSQLVectorAdapter({ ... }) }) + ``` + +### Patch Changes + +- [`c2a6ae1`](https://github.com/VoltAgent/voltagent/commit/c2a6ae125abf9c0b6642927ee78721c6a83dc0f8) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: @voltagent/logger dependency + +## 1.0.0-next.2 + +### Patch Changes + +- [`c2a6ae1`](https://github.com/VoltAgent/voltagent/commit/c2a6ae125abf9c0b6642927ee78721c6a83dc0f8) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: @voltagent/logger dependency + +## 1.0.0-next.1 + +### Major Changes + +- [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93) Thanks [@omeraplak](https://github.com/omeraplak)! - # LibSQL 1.x — Memory Adapter + + Replaces `LibSQLStorage` with Memory V2 adapter and adds vector/observability adapters. + + Full migration guide: [Migration Guide](https://voltagent.dev/docs/getting-started/migration-guide/) + + ## Migrate storage + + Before (0.1.x): + + ```ts + import { LibSQLStorage } from "@voltagent/libsql"; + + const agent = new Agent({ + // ... + memory: new LibSQLStorage({ url: "file:./.voltagent/memory.db" }), + }); + ``` + + After (1.x): + + ```ts + import { Memory } from "@voltagent/core"; + import { LibSQLMemoryAdapter } from "@voltagent/libsql"; + + const agent = new Agent({ + // ... + memory: new Memory({ + storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }), + }), + }); + ``` + + ## Optional (new) + + ```ts + import { LibSQLVectorAdapter } from "@voltagent/libsql"; + // Add vector search: new Memory({ vector: new LibSQLVectorAdapter({ ... }) }) + ``` + +### Patch Changes + +- Updated dependencies [[`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93)]: + - @voltagent/logger@1.0.0-next.0 + +## 1.0.0-next.0 + +### Minor Changes + +- [#485](https://github.com/VoltAgent/voltagent/pull/485) [`64a50e6`](https://github.com/VoltAgent/voltagent/commit/64a50e6800dec844fad7b9f3a3b1c2c8d0486229) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: initial release of @voltagent/libsql package + + ## What's New + + Introducing `@voltagent/libsql` - a dedicated package for LibSQL/Turso database integration with VoltAgent. This package was extracted from `@voltagent/core` to improve modularity and reduce core dependencies. + + ## Key Features + - **Full LibSQL/Turso Support**: Complete implementation of VoltAgent's memory storage interface for LibSQL databases + - **Automatic Migrations**: Built-in schema migrations for conversations, messages, and agent history tables + - **Thread-based Storage**: Support for conversation threads and message history + - **Agent History Tracking**: Store and retrieve agent execution history and timeline events + - **Configurable Logging**: Optional logger injection for debugging and monitoring + + ## Installation + + ```bash + npm install @voltagent/libsql @libsql/client + # or + pnpm add @voltagent/libsql @libsql/client + # or + yarn add @voltagent/libsql @libsql/client + ``` + + ## Usage + + ```typescript + import { LibSQLStorage } from "@voltagent/libsql"; + import { createClient } from "@libsql/client"; + + // Create LibSQL client + const client = createClient({ + url: "file:./memory.db", // or your Turso database URL + authToken: "your-token", // for Turso cloud + }); + + // Initialize storage + const storage = new LibSQLStorage({ + client, + tablePrefix: "company_", // optional, defaults to "conversations" + debug: true, // optional, enables debug logging + }); + + // Use with VoltAgent + import { VoltAgent, Agent } from "@voltagent/core"; + + const agent = new Agent({ + name: "Assistant", + instructions: "You are a helpful assistant", + memory: { + storage: storage, // Use LibSQL storage instead of default InMemoryStorage + }, + // ... other config + }); + ``` + + ## Migration from Core + + If you were previously using LibSQL as the default storage in `@voltagent/core`, you'll need to explicitly install this package and configure it. See the migration guide in the `@voltagent/core` changelog for detailed instructions. + + ## Why This Package? + - **Lambda Compatibility**: Removes native binary dependencies from core, making it Lambda-friendly + - **Modular Architecture**: Use only the storage backends you need + - **Smaller Core Bundle**: Reduces the size of `@voltagent/core` for users who don't need LibSQL + - **Better Maintenance**: Dedicated package allows for independent versioning and updates + +### Patch Changes + +- Updated dependencies [[`64a50e6`](https://github.com/VoltAgent/voltagent/commit/64a50e6800dec844fad7b9f3a3b1c2c8d0486229), [`9e8b211`](https://github.com/VoltAgent/voltagent/commit/9e8b2119a783942f114459f0a9b93e645727445e)]: + - @voltagent/core@1.0.0-next.0 + +--- + +## Package: @voltagent/logger + +## 2.0.2 + +### Patch Changes + +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505)]: + - @voltagent/internal@1.0.2 + +## 2.0.1 + +### Patch Changes + +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2)]: + - @voltagent/internal@1.0.1 + +## 2.0.0 + +### Major Changes + +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +### Patch Changes + +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/internal@1.0.0 + +## 1.0.4 + +### Patch Changes + +- [#736](https://github.com/VoltAgent/voltagent/pull/736) [`348bda0`](https://github.com/VoltAgent/voltagent/commit/348bda0f0fffdcbd75c8a6aa2c2d8bd15195cd22) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: respect configured log levels for console output while sending all logs to OpenTelemetry - #646 + + ## The Problem + + When users configured a custom logger with a specific log level (e.g., `level: "error"`), DEBUG and INFO logs were still appearing in console output, cluttering the development environment. This happened because: + 1. `LoggerProxy` was forwarding all log calls to the underlying logger without checking the configured level + 2. Multiple components (agents, workflows, retrievers, memory adapters, observability) were logging at DEBUG level unconditionally + 3. OpenTelemetry logs were also being filtered by the same level, preventing observability platforms from receiving all logs + + ## The Solution + + **Framework Changes:** + - Updated `LoggerProxy` to check configured log level before forwarding to console/stdout + - Added `shouldLog(level)` method that inspects the underlying logger's level (supports both Pino and ConsoleLogger) + - Separated console output filtering from OpenTelemetry emission: + - **Console/stdout**: Respects configured level (error level → only shows error/fatal) + - **OpenTelemetry**: Always receives all logs (debug, info, warn, error, fatal) + + **What Gets Fixed:** + + ```typescript + const logger = createPinoLogger({ level: "error" }); + + logger.debug("Agent created"); + // Console: ❌ Hidden (keeps dev environment clean) + // OpenTelemetry: ✅ Sent (full observability) + + logger.error("Generation failed"); + // Console: ✅ Shown (important errors visible) + // OpenTelemetry: ✅ Sent (full observability) + ``` + + ## Impact + - **Cleaner Development**: Console output now respects configured log levels + - **Full Observability**: OpenTelemetry platforms receive all logs regardless of console level + - **Better Debugging**: Debug/trace logs available in observability tools even in production + - **No Breaking Changes**: Existing code works as-is with improved behavior + + ## Usage + + No code changes needed - the fix applies automatically: + + ```typescript + // Create logger with error level + const logger = createPinoLogger({ + level: "error", + name: "my-app", + }); + + // Use it with VoltAgent + new VoltAgent({ + agents: { myAgent }, + logger, // Console will be clean, OpenTelemetry gets everything + }); + ``` + + ## Migration Notes + + If you were working around this issue by: + - Filtering console output manually + - Using different loggers for different components + - Avoiding debug logs altogether + + You can now remove those workarounds and use a single logger with your preferred console level while maintaining full observability. + +## 1.0.3 + +### Patch Changes + +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` +- Updated dependencies [[`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e)]: + - @voltagent/internal@0.0.12 + +## 1.0.2 + +### Patch Changes + +- Updated dependencies [[`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7), [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7)]: + - @voltagent/internal@0.0.11 + +## 1.0.1 + +### Patch Changes + +- Updated dependencies [[`134bf9a`](https://github.com/VoltAgent/voltagent/commit/134bf9a2978f0b069f842910fb4fb3e969f70390)]: + - @voltagent/internal@0.0.10 + +## 1.0.0 + +### Major Changes + +- [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93) Thanks [@omeraplak](https://github.com/omeraplak)! - This release adds first‑class OpenTelemetry (OTel) support and seamless integration with VoltAgent 1.x observability. + +## 1.0.0-next.0 + +### Major Changes + +- [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93) Thanks [@omeraplak](https://github.com/omeraplak)! - This release adds first‑class OpenTelemetry (OTel) support and seamless integration with VoltAgent 1.x observability. + +## 0.1.4 + +### Patch Changes + +- Updated dependencies [[`5968cef`](https://github.com/VoltAgent/voltagent/commit/5968cef5fe417cd118867ac78217dddfbd60493d)]: + - @voltagent/internal@0.0.9 + +## 0.1.3 + +### Patch Changes + +- Updated dependencies [[`8de5785`](https://github.com/VoltAgent/voltagent/commit/8de5785e385bec632f846bcae44ee5cb22a9022e)]: + - @voltagent/internal@0.0.8 + +## 0.1.2 + +### Patch Changes + +- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements + + This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + + **Key improvements:** + - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs + - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration + - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries + - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup + - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + + These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. + +- Updated dependencies [[`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5)]: + - @voltagent/internal@0.0.7 + +## 0.1.1 + +### Patch Changes + +- [#404](https://github.com/VoltAgent/voltagent/pull/404) [`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: initial release of @voltagent/logger package + + Introducing a powerful, production-ready logging solution for VoltAgent applications. This package provides a feature-rich logger built on top of Pino with support for pretty formatting, file transports, and advanced logging capabilities. + + **Key Features:** + - **Pino-based Logger**: High-performance logging with minimal overhead + - **Pretty Formatting**: Human-readable output in development with colors and structured formatting + - **Multiple Transports**: Support for console, file, and custom transports + - **Child Logger Support**: Create contextual loggers with inherited configuration + - **Log Buffering**: In-memory buffer for accessing recent logs programmatically + - **Environment-aware Defaults**: Automatic configuration based on NODE_ENV + - **Redaction Support**: Built-in sensitive data redaction + - **Extensible Architecture**: Provider-based design for custom implementations + + **Usage Example:** + + ```typescript + import { createPinoLogger } from "@voltagent/logger"; + + const logger = createPinoLogger({ + level: "info", + name: "my-app", + }); + ``` + + This package replaces the basic ConsoleLogger in @voltagent/core for production use cases, offering significantly improved debugging capabilities and performance. + +- Updated dependencies [[`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726)]: + - @voltagent/internal@0.0.6 + +--- + +## Package: @voltagent/mcp-server + +## 2.0.2 + +### Patch Changes + +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505)]: + - @voltagent/internal@1.0.2 + +## 2.0.1 + +### Patch Changes + +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2)]: + - @voltagent/internal@1.0.1 + +## 2.0.0 + +### Major Changes + +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +### Patch Changes + +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/core@2.0.0 + - @voltagent/internal@1.0.0 + +## 1.0.3 + +### Patch Changes + +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` +- Updated dependencies [[`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e)]: + - @voltagent/internal@0.0.12 + +## 1.0.2 + +### Patch Changes + +- [#659](https://github.com/VoltAgent/voltagent/pull/659) [`c4d13f2`](https://github.com/VoltAgent/voltagent/commit/c4d13f2be129013eed6392990863ae85cdbd8855) Thanks [@marinoska](https://github.com/marinoska)! - Add first-class support for client-side tool calls and Vercel AI hooks integration. + + This enables tools to run in the browser (no execute function) while the model remains on the server. Tool calls are surfaced to the client via Vercel AI hooks (useChat/useAssistant), executed with access to browser APIs, and their results are sent back to the model using addToolResult with the original toolCallId. + + Highlights: + - Define a client-side tool by omitting the execute function. + - Automatic interception of tool calls on the client via onToolCall in useChat/useAssistant. + - Report outputs and errors back to the model via addToolResult(toolCallId, payload), preserving conversation state. + - Example added/updated: examples/with-client-side-tools (Next.js + Vercel AI). + + Docs: + - README: Clarifies client-side tool support and where it fits in the stack. + - website/docs/agents/tools.md: New/updated “Client-Side Tools” section, end-to-end flow with useChat/useAssistant, addToolResult usage, and error handling. + +## 1.0.1 + +### Patch Changes + +- [#596](https://github.com/VoltAgent/voltagent/pull/596) [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7) Thanks [@omeraplak](https://github.com/omeraplak)! - ## ✨ New: first-class Model Context Protocol support + + We shipped a complete MCP integration stack: + - `@voltagent/mcp-server` exposes VoltAgent registries (agents, workflows, tools) over stdio/HTTP/SSE transports. + - `@voltagent/server-core` and `@voltagent/server-hono` gained ready-made route handlers so HTTP servers can proxy MCP traffic with a few lines of glue code. + - `@voltagent/core` exports the shared types that the MCP layers rely on. + + ### Quick start + + ```ts title="src/mcp/server.ts" + import { MCPServer } from "@voltagent/mcp-server"; + import { Agent, createTool } from "@voltagent/core"; + import { openai } from "@ai-sdk/openai"; + import { z } from "zod"; + + const status = createTool({ + name: "status", + description: "Return the current time", + parameters: z.object({}), + async execute() { + return { status: "ok", time: new Date().toISOString() }; + }, + }); + + const assistant = new Agent({ + name: "Support Agent", + instructions: "Route customer tickets to the correct queue.", + model: openai("gpt-4o-mini"), + tools: [status], + }); + + export const mcpServer = new MCPServer({ + name: "voltagent-example", + version: "0.1.0", + description: "Expose VoltAgent over MCP", + agents: { support: assistant }, + tools: { status }, + filterTools: ({ items }) => items.filter((tool) => tool.name !== "debug"), + }); + ``` + + With the server registered on your VoltAgent instance (and the Hono MCP routes enabled), the same agents, workflows, and tools become discoverable from VoltOps Console or any MCP-compatible IDE. + +- [#596](https://github.com/VoltAgent/voltagent/pull/596) [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7) Thanks [@omeraplak](https://github.com/omeraplak)! - - Ship `@voltagent/mcp-server`, a transport-agnostic MCP provider that surfaces VoltAgent agents, workflows, tools, prompts, and resources over stdio, SSE, and HTTP. + - Wire MCP registration through `@voltagent/core`, `@voltagent/server-core`, and `@voltagent/server-hono` so a single `VoltAgent` constructor opt-in (optionally with `honoServer`) exposes stdio mode immediately and HTTP/SSE endpoints when desired. + - Filter child sub-agents automatically and lift an agent's `purpose` (fallback to `instructions`) into the MCP tool description for cleaner IDE listings out of the box. + - Document the workflow in `website/docs/agents/mcp/mcp-server.md` and refresh `examples/with-mcp-server` with stdio-only and HTTP/SSE configurations. + - When MCP is enabled we now publish REST endpoints in Swagger/OpenAPI and echo them in the startup banner so you can discover `/mcp/*` routes without digging through code. + + **Getting started** + + ```ts + import { Agent, VoltAgent } from "@voltagent/core"; + import { MCPServer } from "@voltagent/mcp-server"; + import { honoServer } from "@voltagent/server-hono"; + + const assistant = new Agent({ + name: "AssistantAgent", + purpose: "Respond to support questions and invoke helper tools when needed.", + model: myModel, + }); + + const mcpServer = new MCPServer({ + name: "support-mcp", + version: "1.0.0", + agents: { assistant }, + protocols: { stdio: true, http: false, sse: false }, + }); + + export const voltAgent = new VoltAgent({ + agents: { assistant }, + mcpServers: { primary: mcpServer }, + server: honoServer({ port: 3141 }), // flip http/sse to true when you need remote clients + }); + ``` + +- Updated dependencies [[`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7), [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7)]: + - @voltagent/internal@0.0.11 + +--- + +## Package: @voltagent/postgres + +## 2.0.2 + +### Patch Changes + +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505)]: + - @voltagent/internal@1.0.2 + +## 2.0.1 + +### Patch Changes + +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2)]: + - @voltagent/internal@1.0.1 + +## 2.0.0 + +### Major Changes + +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +### Patch Changes + +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/core@2.0.0 + - @voltagent/internal@1.0.0 + +## 1.1.4 + +### Patch Changes + +- [#845](https://github.com/VoltAgent/voltagent/pull/845) [`5432f13`](https://github.com/VoltAgent/voltagent/commit/5432f13bddebd869522ebffbedd9843b4476f08b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: workflow execution listing - #844 + + Added a unified way to list workflow runs so teams can audit executions across every storage backend and surface them via the API and console. + + ## What changed + - `queryWorkflowRuns` now exists on all memory adapters (in-memory, libsql, Postgres, Supabase, voltagent-memory) with filters for `workflowId`, `status`, `from`, `to`, `limit`, and `offset`. + - Server routes are consolidated under `/workflows/executions` (no path param needed); `GET /workflows/:id` also returns the workflow result schema for typed clients. Handler naming is standardized to `listWorkflowRuns`. + - VoltOps Console observability panel lists the new endpoint; REST docs updated with query params and sample responses. New unit tests cover handlers and every storage adapter. + + ## Quick fetch + + ```ts + await fetch( + "http://localhost:3141/workflows/executions?workflowId=expense-approval&status=completed&from=2024-01-01&to=2024-01-31&limit=20&offset=0" + ); + ``` + +## 1.1.3 + +### Patch Changes + +- [#820](https://github.com/VoltAgent/voltagent/pull/820) [`c5e0c89`](https://github.com/VoltAgent/voltagent/commit/c5e0c89554d85c895e3d6cbfc83ad47bd53a1b9f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: expose createdAt in memory.getMessages + + ## What Changed + + The `createdAt` timestamp is now exposed in the `metadata` object of messages retrieved via `memory.getMessages()`. This ensures that the creation time of messages is accessible across all storage adapters (`InMemory`, `Supabase`, `LibSQL`, `PostgreSQL`). + + ## Usage + + You can now access the `createdAt` timestamp from the message metadata: + + ```typescript + const messages = await memory.getMessages(userId, conversationId); + + messages.forEach((message) => { + console.log(`Message ID: ${message.id}`); + console.log(`Created At: ${message.metadata?.createdAt}`); + }); + ``` + + This change aligns the behavior of all storage adapters and ensures consistent access to message timestamps. + +## 1.1.2 + +### Patch Changes + +- [#801](https://github.com/VoltAgent/voltagent/pull/801) [`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add triggers DSL improvements and event payload simplification + - Introduce the new `createTriggers` DSL and expose trigger events via sensible provider names (e.g. `on.airtable.recordCreated`) rather than raw catalog IDs. + - Add trigger span metadata propagation so VoltAgent agents receive trigger context automatically without manual mapping. + - Simplify action dispatch payloads: `payload` now contains only the event’s raw data while trigger context lives in the `event`/`metadata` blocks, reducing boilerplate in handlers. + + ```ts + import { VoltAgent, createTriggers } from "@voltagent/core"; + + new VoltAgent({ + // ... + triggers: createTriggers((on) => { + on.airtable.recordCreated(({ payload, event }) => { + console.log("New Airtable row", payload, event.metadata); + }); + + on.gmail.newEmail(({ payload }) => { + console.log("New Gmail message", payload); + }); + }), + }); + ``` + +## 1.1.1 + +### Patch Changes + +- [#787](https://github.com/VoltAgent/voltagent/pull/787) [`5e81d65`](https://github.com/VoltAgent/voltagent/commit/5e81d6568ba3bee26083ca2a8e5d31f158e36fc0) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add full conversation step persistence across the stack: + - Core now exposes managed-memory step APIs, and the VoltAgent managed memory adapter persists/retrieves steps through VoltOps. + - LibSQL, PostgreSQL, Supabase, and server handlers provision the new `_steps` table, wire up DTOs/routes, and surface the data in Observability/Steps UI (including managed-memory backends). + + fixes: #613 + +## 1.1.0 + +### Minor Changes + +- [#773](https://github.com/VoltAgent/voltagent/pull/773) [`35290d9`](https://github.com/VoltAgent/voltagent/commit/35290d9331c846f8274325ad698da0c2cda54530) Thanks [@hyperion912](https://github.com/hyperion912)! - feat(postgres-memory-adapter): add schema configuration support + + Add support for defining a custom PostgreSQL schema during adapter initialization. + Defaults to undefined (uses the database’s default schema if not provided). + + Includes tests for schema configuration. + + Resolves #763 + +## 1.0.11 + +### Patch Changes + +- [#738](https://github.com/VoltAgent/voltagent/pull/738) [`d3ed347`](https://github.com/VoltAgent/voltagent/commit/d3ed347e064cb36e04ed1ea98d9305b63fd968ec) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: persist workflow execution timeline events to prevent data loss after completion - #647 + + ## The Problem + + When workflows executed, their timeline events (step-start, step-complete, workflow-complete, etc.) were only visible during streaming. Once the workflow completed, the WebSocket state update would replace the execution object without the events field, causing the timeline UI to reset and lose all execution history. Users couldn't see what happened in completed or suspended workflows. + + **Symptoms:** + - Timeline showed events during execution + - Timeline cleared/reset when workflow completed + - No execution history for completed workflows + - Events were lost after browser refresh + + ## The Solution + + **Backend (Framework)**: + - Added `events`, `output`, and `cancellation` fields to `WorkflowStateEntry` interface + - Modified workflow execution to collect all stream events in memory during execution + - Persist collected events to workflow state when workflow completes, suspends, fails, or is cancelled + - Updated all storage adapters to support the new fields: + - **LibSQL**: Added schema columns + automatic migration method (`addWorkflowStateColumns`) + - **Supabase**: Added schema columns + migration detection + ALTER TABLE migration SQL + - **Postgres**: Added schema columns + INSERT/UPDATE queries + - **In-Memory**: Automatically supported via TypeScript interface + + **Frontend (Console)**: + - Updated `WorkflowPlaygroundProvider` to include events when converting `WorkflowStateEntry` → `WorkflowHistoryEntry` + - Implemented smart merge strategy for WebSocket updates: Use backend persisted events when workflow finishes, keep streaming events during execution + - Events are now preserved across page refreshes and always visible in timeline UI + + ## What Gets Persisted + + ```typescript + // In WorkflowStateEntry (stored in Memory V2): + { + "events": [ + { + "id": "evt_123", + "type": "workflow-start", + "name": "Workflow Started", + "startTime": "2025-01-24T10:00:00Z", + "status": "running", + "input": { "userId": "123" } + }, + { + "id": "evt_124", + "type": "step-complete", + "name": "Step: fetch-user", + "startTime": "2025-01-24T10:00:01Z", + "endTime": "2025-01-24T10:00:02Z", + "status": "success", + "output": { "user": { "name": "John" } } + } + ], + "output": { "result": "success" }, + "cancellation": { + "cancelledAt": "2025-01-24T10:00:05Z", + "reason": "User requested cancellation" + } + } + ``` + + ## Migration Guide + + ### LibSQL Users + + No action required - migrations run automatically on next initialization. + + ### Supabase Users + + When you upgrade and initialize the adapter, you'll see migration SQL in the console. Run it in your Supabase SQL Editor: + + ```sql + -- Add workflow event persistence columns + ALTER TABLE voltagent_workflow_states + ADD COLUMN IF NOT EXISTS events JSONB; + + ALTER TABLE voltagent_workflow_states + ADD COLUMN IF NOT EXISTS output JSONB; + + ALTER TABLE voltagent_workflow_states + ADD COLUMN IF NOT EXISTS cancellation JSONB; + ``` + + ### Postgres Users + + No action required - migrations run automatically on next initialization. + + ### In-Memory Users + + No action required - automatically supported. + + ### VoltAgent Managed Memory Users + + No action required - migrations run automatically on first request per managed memory database after API deployment. The API has been updated to: + - Include new columns in ManagedMemoryProvisioner CREATE TABLE statements (new databases) + - Run automatic column addition migration for existing databases (lazy migration on first request) + - Update PostgreSQL memory adapter to persist and retrieve events, output, and cancellation fields + + **Zero-downtime deployment:** Existing managed memory databases will be migrated lazily when first accessed after the API update. + + ## Impact + - ✅ Workflow execution timeline is now persistent and survives completion + - ✅ Full execution history visible for completed, suspended, and failed workflows + - ✅ Events, output, and cancellation metadata preserved in database + - ✅ Console UI timeline works consistently across all workflow states + - ✅ All storage backends (LibSQL, Supabase, Postgres, In-Memory) behave consistently + - ✅ No data loss on workflow completion or page refresh + +## 1.0.10 + +### Patch Changes + +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` +- Updated dependencies [[`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e)]: + - @voltagent/internal@0.0.12 + +## 1.0.9 + +### Patch Changes + +- [#674](https://github.com/VoltAgent/voltagent/pull/674) [`5aa84b5`](https://github.com/VoltAgent/voltagent/commit/5aa84b5bcf57d19bbe33cc791f0892c96bb3944b) Thanks [@omeraplak](https://github.com/omeraplak)! - ## What Changed + + Removed automatic message pruning functionality from all storage adapters (PostgreSQL, Supabase, LibSQL, and InMemory). Previously, messages were automatically deleted when the count exceeded `storageLimit` (default: 100 messages per conversation). + + ## Why This Change + + Users reported unexpected data loss when their conversation history exceeded the storage limit. Many users expect their conversation history to be preserved indefinitely rather than automatically deleted. This change gives users full control over their data retention policies. + + ## Migration Guide + + ### Before + + ```ts + const memory = new Memory({ + storage: new PostgreSQLMemoryAdapter({ + connection: process.env.DATABASE_URL, + storageLimit: 200, // Messages auto-deleted after 200 + }), + }); + ``` + + ### After + + ```ts + const memory = new Memory({ + storage: new PostgreSQLMemoryAdapter({ + connection: process.env.DATABASE_URL, + // No storageLimit - all messages preserved + }), + }); + ``` + + ### If You Need Message Cleanup + + Implement your own cleanup logic using the `clearMessages()` method: + + ```ts + // Clear all messages for a conversation + await memory.clearMessages(userId, conversationId); + + // Clear all messages for a user + await memory.clearMessages(userId); + ``` + + ## Affected Packages + - `@voltagent/core` - Removed `storageLimit` from types + - `@voltagent/postgres` - Removed from PostgreSQL adapter + - `@voltagent/supabase` - Removed from Supabase adapter + - `@voltagent/libsql` - Removed from LibSQL adapter + + ## Impact + - ✅ No more unexpected data loss + - ✅ Users have full control over message retention + - ⚠️ Databases may grow larger over time (consider implementing manual cleanup) + - ⚠️ Breaking change: `storageLimit` parameter no longer accepted + +## 1.0.8 + +### Patch Changes + +- [#641](https://github.com/VoltAgent/voltagent/pull/641) [`4c42bf7`](https://github.com/VoltAgent/voltagent/commit/4c42bf72834d3cd45ff5246ef65d7b08470d6a8e) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add PostgresVectorAdapter for semantic search with vanilla PostgreSQL + + ## What Changed for You + + The `@voltagent/postgres` package now includes `PostgresVectorAdapter` for storing and querying vector embeddings using vanilla PostgreSQL (no extensions required). This enables semantic search capabilities for conversation history, allowing agents to retrieve contextually relevant messages based on meaning rather than just keywords. + + ## New: PostgresVectorAdapter + + ```typescript + import { Agent, Memory, AiSdkEmbeddingAdapter } from "@voltagent/core"; + import { PostgresMemoryAdapter, PostgresVectorAdapter } from "@voltagent/postgres"; + import { openai } from "@ai-sdk/openai"; + + const memory = new Memory({ + storage: new PostgresMemoryAdapter({ + connectionString: process.env.DATABASE_URL, + }), + embedding: new AiSdkEmbeddingAdapter(openai.embedding("text-embedding-3-small")), + vector: new PostgresVectorAdapter({ + connectionString: process.env.DATABASE_URL, + }), + }); + + const agent = new Agent({ + name: "Assistant", + instructions: "You are a helpful assistant with semantic memory", + model: openai("gpt-4o-mini"), + memory, + }); + + // Semantic search automatically enabled with userId + conversationId + const result = await agent.generateText("What did we discuss about the project?", { + userId: "user-123", + conversationId: "conv-456", + }); + ``` + + ## Key Features + - **No Extensions Required**: Works with vanilla PostgreSQL (no pgvector needed) + - **BYTEA Storage**: Vectors stored efficiently as binary data using PostgreSQL's native BYTEA type + - **In-Memory Similarity**: Cosine similarity computed in-memory for accurate results + - **Automatic Setup**: Creates `voltagent_vectors` table and indexes automatically + - **Configurable**: Customize table name, vector dimensions, cache size, and retry logic + - **Production Ready**: Connection pooling, exponential backoff, LRU caching + + ## Configuration Options + + ```typescript + const vectorAdapter = new PostgresVectorAdapter({ + connectionString: process.env.DATABASE_URL, + + // Optional: customize table name (default: "voltagent_vector") + tablePrefix: "custom_vector", + + // Optional: vector dimensions (default: 1536 for text-embedding-3-small) + maxVectorDimensions: 1536, + + // Optional: LRU cache size (default: 100) + cacheSize: 100, + + // Optional: connection pool size (default: 10) + maxConnections: 10, + }); + ``` + + ## How It Works + 1. **Embedding Generation**: Messages are converted to vector embeddings using your chosen embedding model + 2. **Binary Storage**: Vectors are serialized to binary (BYTEA) and stored in PostgreSQL + 3. **In-Memory Similarity**: When searching, all vectors are loaded and cosine similarity is computed in-memory + 4. **Context Merging**: Relevant messages are merged into conversation context automatically + + ## Why This Matters + - **Better Context Retrieval**: Find relevant past conversations even with different wording + - **Unified Storage**: Keep vectors and messages in the same PostgreSQL database + - **Zero Extensions**: Works with any PostgreSQL instance (12+), no extension installation needed + - **Cost Effective**: No separate vector database needed (Pinecone, Weaviate, etc.) + - **Familiar Tools**: Use standard PostgreSQL management and monitoring tools + - **Framework Parity**: Same `VectorStorageAdapter` interface as other providers + + ## Performance Notes + + This adapter loads all vectors into memory for similarity computation, which works well for: + - **Small to medium datasets** (< 10,000 vectors) + - **Development and prototyping** + - **Applications where extension installation is not possible** + + For large-scale production workloads with millions of vectors, consider specialized vector databases or PostgreSQL with pgvector extension for database-level similarity operations. + + ## Migration Notes + + Existing PostgreSQL memory adapters continue to work without changes. Vector storage is optional and only activates when you configure both `embedding` and `vector` in the Memory constructor. + +## 1.0.7 + +### Patch Changes + +- Updated dependencies [[`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7), [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7)]: + - @voltagent/internal@0.0.11 + +## 1.0.6 + +### Patch Changes + +- [`90ea801`](https://github.com/VoltAgent/voltagent/commit/90ea80121e73e890bb5cea1f970d50d78cd50680) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: migration issue + +## 1.0.5 + +### Patch Changes + +- [`9cc4ea4`](https://github.com/VoltAgent/voltagent/commit/9cc4ea4a4985320139e33e8029f299c7ec8329a6) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: @voltagent/core peerDependency version + +## 1.0.4 + +### Patch Changes + +- [`e268f61`](https://github.com/VoltAgent/voltagent/commit/e268f61dff91691000675222093165e1349831dc) Thanks [@omeraplak](https://github.com/omeraplak)! - chore: add debug logs + +## 1.0.3 + +## 1.0.3-next.0 + +### Patch Changes + +- Updated dependencies [[`77a3f64`](https://github.com/VoltAgent/voltagent/commit/77a3f64dea6e8a06fbbd72878711efa9ceb90bc3)]: + - @voltagent/core@1.1.7-next.0 + +## 1.0.2 + +### Patch Changes + +- [#562](https://github.com/VoltAgent/voltagent/pull/562) [`2886b7a`](https://github.com/VoltAgent/voltagent/commit/2886b7aab5bda296cebc0b8b2bd56d684324d799) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: using `safeStringify` instead of `JSON.stringify` + +## 1.0.1 + +### Patch Changes + +- Updated dependencies [[`134bf9a`](https://github.com/VoltAgent/voltagent/commit/134bf9a2978f0b069f842910fb4fb3e969f70390)]: + - @voltagent/internal@0.0.10 + +## 1.0.0 + +### Major Changes + +- [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93) Thanks [@omeraplak](https://github.com/omeraplak)! - # PostgreSQL 1.x — Memory Adapter + + The old `PostgresStorage` API is replaced by a Memory V2 adapter. + + Full migration guide: [Migration Guide](https://voltagent.dev/docs/getting-started/migration-guide/) + + ## Migrate + + Before (0.1.x): + + ```ts + import { PostgresStorage } from "@voltagent/postgres"; + + const agent = new Agent({ + // ... + memory: new PostgresStorage({ connection: process.env.DATABASE_URL! }), + }); + ``` + + After (1.x): + + ```ts + import { Memory } from "@voltagent/core"; + import { PostgreSQLMemoryAdapter } from "@voltagent/postgres"; + + const agent = new Agent({ + // ... + memory: new Memory({ + storage: new PostgreSQLMemoryAdapter({ + connection: process.env.DATABASE_URL!, + }), + }), + }); + ``` + +## 1.0.0-next.1 + +### Major Changes + +- [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93) Thanks [@omeraplak](https://github.com/omeraplak)! - # PostgreSQL 1.x — Memory Adapter + + The old `PostgresStorage` API is replaced by a Memory V2 adapter. + + Full migration guide: [Migration Guide](https://voltagent.dev/docs/getting-started/migration-guide/) + + ## Migrate + + Before (0.1.x): + + ```ts + import { PostgresStorage } from "@voltagent/postgres"; + + const agent = new Agent({ + // ... + memory: new PostgresStorage({ connection: process.env.DATABASE_URL! }), + }); + ``` + + After (1.x): + + ```ts + import { Memory } from "@voltagent/core"; + import { PostgreSQLMemoryAdapter } from "@voltagent/postgres"; + + const agent = new Agent({ + // ... + memory: new Memory({ + storage: new PostgreSQLMemoryAdapter({ + connection: process.env.DATABASE_URL!, + }), + }), + }); + ``` + +## 1.0.0-next.0 + +### Patch Changes + +- Updated dependencies [[`64a50e6`](https://github.com/VoltAgent/voltagent/commit/64a50e6800dec844fad7b9f3a3b1c2c8d0486229), [`9e8b211`](https://github.com/VoltAgent/voltagent/commit/9e8b2119a783942f114459f0a9b93e645727445e)]: + - @voltagent/core@1.0.0-next.0 + +## 0.1.12 + +### Patch Changes + +- [#466](https://github.com/VoltAgent/voltagent/pull/466) [`730232e`](https://github.com/VoltAgent/voltagent/commit/730232e730cdbd1bb7de6acff8519e8af93f2abf) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: memory messages now return parsed objects instead of JSON strings + + ## What Changed for You + + Memory messages that contain structured content (like tool calls or multi-part messages) now return as **parsed objects** instead of **JSON strings**. This is a breaking change if you were manually parsing these messages. + + ## Before - You Had to Parse JSON Manually + + ```typescript + // ❌ OLD BEHAVIOR: Content came as JSON string + const messages = await memory.getMessages({ conversationId: "123" }); + + // What you got from memory: + console.log(messages[0]); + // { + // role: "user", + // content: '[{"type":"text","text":"Hello"},{"type":"image","image":"data:..."}]', // STRING! + // type: "text" + // } + + // You had to manually parse the JSON string: + const content = JSON.parse(messages[0].content); // Parse required! + console.log(content); + // [ + // { type: "text", text: "Hello" }, + // { type: "image", image: "data:..." } + // ] + + // Tool calls were also JSON strings: + console.log(messages[1].content); + // '[{"type":"tool-call","toolCallId":"123","toolName":"weather"}]' // STRING! + ``` + + ## After - You Get Parsed Objects Automatically + + ```typescript + // ✅ NEW BEHAVIOR: Content comes as proper objects + const messages = await memory.getMessages({ conversationId: "123" }); + + // What you get from memory NOW: + console.log(messages[0]); + // { + // role: "user", + // content: [ + // { type: "text", text: "Hello" }, // OBJECT! + // { type: "image", image: "data:..." } // OBJECT! + // ], + // type: "text" + // } + + // Direct access - no JSON.parse needed! + const content = messages[0].content; // Already parsed! + console.log(content[0].text); // "Hello" + + // Tool calls are proper objects: + console.log(messages[1].content); + // [ + // { type: "tool-call", toolCallId: "123", toolName: "weather" } // OBJECT! + // ] + ``` + + ## Breaking Change Warning ⚠️ + + If your code was doing this: + + ```typescript + // This will now FAIL because content is already parsed + const parsed = JSON.parse(msg.content); // ❌ Error: not a string! + ``` + + Change it to: + + ```typescript + // Just use the content directly + const content = msg.content; // ✅ Already an object/array + ``` + + ## What Gets Auto-Parsed + - **String content** → Stays as string ✅ + - **Structured content** (arrays) → Auto-parsed to objects ✅ + - **Tool calls** → Auto-parsed to objects ✅ + - **Tool results** → Auto-parsed to objects ✅ + - **Metadata fields** → Auto-parsed to objects ✅ + + ## Why This Matters + - **No more JSON.parse errors** in your application + - **Type-safe access** to structured content + - **Cleaner code** without try/catch blocks + - **Consistent behavior** with how agents handle messages + + ## Migration Guide + 1. **Remove JSON.parse calls** for message content + 2. **Remove try/catch** blocks around parsing + 3. **Use content directly** as objects/arrays + + Your memory messages now "just work" without manual parsing! + +## 0.1.11 + +### Patch Changes + +- [#457](https://github.com/VoltAgent/voltagent/pull/457) [`8d89469`](https://github.com/VoltAgent/voltagent/commit/8d8946919820c0298bffea13731ea08660b72c4b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: optimize agent event system and add pagination to agent history API + + Significantly improved agent performance and UI scalability with two major enhancements: + + ## 1. Event System Optimization + + Refactored agent event system to emit events immediately before database writes, matching the workflow event system behavior. This provides real-time event visibility without waiting for persistence operations. + + **Before:** + - Events were queued and only emitted after database write completion + - Real-time monitoring was delayed by persistence operations + + **After:** + - Events emit immediately for real-time updates + - Database persistence happens asynchronously in the background + - Consistent behavior with workflow event system + + ## 2. Agent History Pagination + + Added comprehensive pagination support to agent history API, preventing performance issues when loading large history datasets. + + **New API:** + + ```typescript + // Agent class + const history = await agent.getHistory({ page: 0, limit: 20 }); + // Returns: { entries: AgentHistoryEntry[], pagination: { page, limit, total, totalPages } } + + // REST API + GET /agents/:id/history?page=0&limit=20 + // Returns paginated response format + ``` + + **Implementation Details:** + - Added pagination to all storage backends (LibSQL, PostgreSQL, Supabase, InMemory) + - Updated WebSocket initial load to use pagination + - Maintained backward compatibility (when page/limit not provided, returns first 100 entries) + - Updated all tests to work with new pagination format + + **Storage Changes:** + - LibSQL: Added LIMIT/OFFSET support + - PostgreSQL: Added pagination with proper SQL queries + - Supabase: Used `.range()` method for efficient pagination + - InMemory: Implemented array slicing with total count + + This improves performance for agents with extensive history and provides better UX for viewing agent execution history. + +- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements + + This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + + **Key improvements:** + - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs + - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration + - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries + - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup + - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + + These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. + +## 0.1.10 + +### Patch Changes + +- [#423](https://github.com/VoltAgent/voltagent/pull/423) [`089c039`](https://github.com/VoltAgent/voltagent/commit/089c03993e3b9e05655a1108355e7bee940d33a7) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add message type filtering support to memory storage implementations + + Added the ability to filter messages by type when retrieving conversation history. This enhancement allows the framework to distinguish between different message types (text, tool-call, tool-result) and retrieve only the desired types, improving context preparation for LLMs. + + ## Key Changes + - **MessageFilterOptions**: Added optional `types` parameter to filter messages by type + - **prepareConversationContext**: Now filters to only include text messages, excluding tool-call and tool-result messages for cleaner LLM context + - **All storage implementations**: Added database-level filtering for better performance + + ## Usage + + ```typescript + // Get only text messages + const textMessages = await memory.getMessages({ + userId: "user-123", + conversationId: "conv-456", + types: ["text"], + }); + + // Get tool-related messages + const toolMessages = await memory.getMessages({ + userId: "user-123", + conversationId: "conv-456", + types: ["tool-call", "tool-result"], + }); + + // Get all messages (default behavior - backward compatible) + const allMessages = await memory.getMessages({ + userId: "user-123", + conversationId: "conv-456", + }); + ``` + + ## Implementation Details + - **InMemoryStorage**: Filters messages in memory after retrieval + - **LibSQLStorage**: Adds SQL WHERE clause with IN operator for type filtering + - **PostgreSQL**: Uses parameterized IN clause with proper parameter counting + - **Supabase**: Utilizes query builder's `.in()` method for type filtering + + This change ensures that `prepareConversationContext` provides cleaner, more focused context to LLMs by excluding intermediate tool execution details, while maintaining full backward compatibility for existing code. + +- Updated dependencies [[`089c039`](https://github.com/VoltAgent/voltagent/commit/089c03993e3b9e05655a1108355e7bee940d33a7)]: + - @voltagent/core@0.1.68 + +## 0.1.9 + +### Patch Changes + +- [#418](https://github.com/VoltAgent/voltagent/pull/418) [`aa024c1`](https://github.com/VoltAgent/voltagent/commit/aa024c1a7c643b2aff7a5fd0d150c87f8a9a1858) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: memory storage implementations now correctly return the most recent messages when using context limit + + Fixed an issue where memory storage implementations (LibSQL, PostgreSQL, Supabase) were returning the oldest messages instead of the most recent ones when a context limit was specified. This was causing AI agents to lose important recent context in favor of old conversation history. + + **Before:** + - `contextLimit: 10` returned the first 10 messages (oldest) + - Agents were working with outdated context + + **After:** + - `contextLimit: 10` returns the last 10 messages (most recent) in chronological order + - Agents now have access to the most relevant recent context + - InMemoryStorage was already working correctly and remains unchanged + + Changes: + - LibSQLStorage: Modified query to use `ORDER BY DESC` with `LIMIT`, then reverse results + - PostgreSQL: Modified query to use `ORDER BY DESC` with `LIMIT`, then reverse results + - Supabase: Modified query to use `ascending: false` with `limit`, then reverse results + + This ensures consistent behavior across all storage implementations where context limits provide the most recent messages, improving AI agent response quality and relevance. + +- Updated dependencies [[`67450c3`](https://github.com/VoltAgent/voltagent/commit/67450c3bc4306ab6021ca8feed2afeef6dcc320e), [`aa024c1`](https://github.com/VoltAgent/voltagent/commit/aa024c1a7c643b2aff7a5fd0d150c87f8a9a1858), [`aa024c1`](https://github.com/VoltAgent/voltagent/commit/aa024c1a7c643b2aff7a5fd0d150c87f8a9a1858)]: + - @voltagent/core@0.1.67 + +## 0.1.8 + +### Patch Changes + +- [#371](https://github.com/VoltAgent/voltagent/pull/371) [`6ddedc2`](https://github.com/VoltAgent/voltagent/commit/6ddedc2b9be9c3dc4978dc53198a43c2cba74945) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add workflow history support to postgres + + This update introduces persistence for workflow history when using a PostgreSQL database. This includes storing workflow execution details, individual steps, and timeline events. Database tables are migrated automatically, so no manual action is required. + +- Updated dependencies [[`6ddedc2`](https://github.com/VoltAgent/voltagent/commit/6ddedc2b9be9c3dc4978dc53198a43c2cba74945)]: + - @voltagent/core@0.1.60 + +## 0.1.7 + +### Patch Changes + +- [#317](https://github.com/VoltAgent/voltagent/pull/317) [`16bb8d0`](https://github.com/VoltAgent/voltagent/commit/16bb8d003c17799688e8b70eb9236b46a5c339be) Thanks [@thujee](https://github.com/thujee)! - fix: errors related to missing columns "timestamp" and "utc" in Postgres schema - #316 + +## 0.1.6 + +### Patch Changes + +- [#301](https://github.com/VoltAgent/voltagent/pull/301) [`619e951`](https://github.com/VoltAgent/voltagent/commit/619e9510c05b7e46f8c243db226f220b5fdad824) Thanks [@woutrbe](https://github.com/woutrbe)! - fix(postgres): Fix default value being interpreted as column name + +- Updated dependencies [[`33afe6e`](https://github.com/VoltAgent/voltagent/commit/33afe6ef40ef56c501f7fa69be42da730f87d29d), [`b8529b5`](https://github.com/VoltAgent/voltagent/commit/b8529b53313fa97e941ecacb8c1555205de49c19)]: + - @voltagent/core@0.1.45 + +## 0.1.5 + +### Patch Changes + +- [#252](https://github.com/VoltAgent/voltagent/pull/252) [`88f2d06`](https://github.com/VoltAgent/voltagent/commit/88f2d0682413d27a7ac2d1d8cd502fd9c665e547) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add userId and conversationId support to agent history tables + + This release adds comprehensive support for `userId` and `conversationId` fields in agent history tables across all memory storage implementations, enabling better conversation tracking and user-specific history management. + + ### New Features + - **Agent History Enhancement**: Added `userId` and `conversationId` columns to agent history tables + - **Cross-Implementation Support**: Consistent implementation across PostgreSQL, Supabase, LibSQL, and In-Memory storage + - **Automatic Migration**: Safe schema migrations for existing installations + - **Backward Compatibility**: Existing history entries remain functional + + ### Migration Notes + + **PostgreSQL & Supabase**: Automatic schema migration with user-friendly SQL scripts + **LibSQL**: Seamless column addition with proper indexing + **In-Memory**: No migration required, immediate support + + ### Technical Details + - **Database Schema**: Added `userid TEXT` and `conversationid TEXT` columns (PostgreSQL uses lowercase) + - **Indexing**: Performance-optimized indexes for new columns + - **Migration Safety**: Non-destructive migrations with proper error handling + - **API Consistency**: Unified interface across all storage implementations + +- Updated dependencies [[`88f2d06`](https://github.com/VoltAgent/voltagent/commit/88f2d0682413d27a7ac2d1d8cd502fd9c665e547), [`b63fe67`](https://github.com/VoltAgent/voltagent/commit/b63fe675dfca9121862a9dd67a0fae5d39b9db90)]: + - @voltagent/core@0.1.37 + +## 0.1.4 + +### Patch Changes + +- [#236](https://github.com/VoltAgent/voltagent/pull/236) [`5d39cdc`](https://github.com/VoltAgent/voltagent/commit/5d39cdc68c4ec36ec2f0bf86a29dbf1225644416) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: PostgreSQL string literal syntax error in timeline events table + + Fixed PostgreSQL syntax error where `level TEXT DEFAULT "INFO"` was using double quotes instead of single quotes for string literals. This resolves table creation failures during fresh installations and migrations. + + ### Changes + - **Fixed**: `level TEXT DEFAULT "INFO"` → `level TEXT DEFAULT 'INFO'` + - **Affects**: Timeline events table creation in both fresh installations and migrations + - **Impact**: PostgreSQL database setup now works without syntax errors + + ### Technical Details + + PostgreSQL requires single quotes for string literals and double quotes for identifiers. The timeline events table creation was failing due to incorrect quote usage for the default value. + + **Migration Notes:** + - Existing installations with timeline events table will not be affected + - Fresh installations will now complete successfully + - No manual intervention required + +- Updated dependencies [[`5d39cdc`](https://github.com/VoltAgent/voltagent/commit/5d39cdc68c4ec36ec2f0bf86a29dbf1225644416), [`16c2a86`](https://github.com/VoltAgent/voltagent/commit/16c2a863d3ecdc09f09219bd40f2dbf1d789194d), [`0d85f0e`](https://github.com/VoltAgent/voltagent/commit/0d85f0e960dbc6e8df6a79a16c775ca7a34043bb)]: + - @voltagent/core@0.1.33 + +## 0.1.3 + +### Patch Changes + +- [#215](https://github.com/VoltAgent/voltagent/pull/215) [`f2f4539`](https://github.com/VoltAgent/voltagent/commit/f2f4539af7722f25a5aad9f01c2b7b5e50ba51b8) Thanks [@Ajay-Satish-01](https://github.com/Ajay-Satish-01)! - This release introduces powerful new methods for managing conversations with user-specific access control and improved developer experience. + + ### Simple Usage Example + + ```typescript + // Get all conversations for a user + const conversations = await storage.getUserConversations("user-123").limit(10).execute(); + + console.log(conversations); + + // Get first conversation and its messages + const conversation = conversations[0]; + if (conversation) { + const messages = await storage.getConversationMessages(conversation.id); + console.log(messages); + } + ``` + + ### Pagination Support + + ```typescript + // Get paginated conversations + const result = await storage.getPaginatedUserConversations("user-123", 1, 20); + console.log(result.conversations); // Array of conversations + console.log(result.hasMore); // Boolean indicating if more pages exist + ``` + +- Updated dependencies [[`f2f4539`](https://github.com/VoltAgent/voltagent/commit/f2f4539af7722f25a5aad9f01c2b7b5e50ba51b8), [`0eba8a2`](https://github.com/VoltAgent/voltagent/commit/0eba8a265c35241da74324613e15801402f7b778)]: + - @voltagent/core@0.1.32 + +## 0.1.2 + +### Patch Changes + +- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 + +- Updated dependencies [[`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f), [`80fd3c0`](https://github.com/VoltAgent/voltagent/commit/80fd3c069de4c23116540a55082b891c4b376ce6)]: + - @voltagent/core@0.1.31 + +## 0.1.1 + +### Patch Changes + +- [#176](https://github.com/VoltAgent/voltagent/pull/176) [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275) Thanks [@omeraplak](https://github.com/omeraplak)! - The `error` column has been deprecated and replaced with `statusMessage` column for better consistency and clearer messaging. The old `error` column is still supported for backward compatibility but will be removed in a future major version. + + Changes: + - Deprecated `error` column (still functional) + - Improved error handling and status reporting + +- Updated dependencies [[`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275), [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275)]: + - @voltagent/core@0.1.24 + +--- + +## Package: @voltagent/rag + +## 1.0.2 + +### Patch Changes + +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +## 1.0.1 + +### Patch Changes + +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +## 1.0.0 + +### Major Changes + +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +--- + +## Package: @voltagent/resumable-streams + +## 2.0.1 + +### Patch Changes + +- [#921](https://github.com/VoltAgent/voltagent/pull/921) [`c4591fa`](https://github.com/VoltAgent/voltagent/commit/c4591fa92de6df75a22a758b0232669053bd2b62) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add resumable streaming support via @voltagent/resumable-streams, with server adapters that let clients reconnect to in-flight streams. + + ```ts + import { openai } from "@ai-sdk/openai"; + import { Agent, VoltAgent } from "@voltagent/core"; + import { + createResumableStreamAdapter, + createResumableStreamRedisStore, + } from "@voltagent/resumable-streams"; + import { honoServer } from "@voltagent/server-hono"; + + const streamStore = await createResumableStreamRedisStore(); + const resumableStream = await createResumableStreamAdapter({ streamStore }); + + const agent = new Agent({ + id: "assistant", + name: "Resumable Stream Agent", + instructions: "You are a helpful assistant.", + model: openai("gpt-4o-mini"), + }); + + new VoltAgent({ + agents: { assistant: agent }, + server: honoServer({ + resumableStream: { adapter: resumableStream }, + }), + }); + + await fetch("http://localhost:3141/agents/assistant/chat", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: `{"input":"Hello!","options":{"conversationId":"conv-1","userId":"user-1","resumableStream":true}}`, + }); + + // Resume the same stream after reconnect/refresh + const resumeResponse = await fetch( + "http://localhost:3141/agents/assistant/chat/conv-1/stream?userId=user-1" + ); + + const reader = resumeResponse.body?.getReader(); + const decoder = new TextDecoder(); + while (reader) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value, { stream: true }); + console.log(chunk); + } + ``` + + AI SDK client (resume on refresh): + + ```tsx + import { useChat } from "@ai-sdk/react"; + import { DefaultChatTransport } from "ai"; + + const { messages, sendMessage } = useChat({ + id: chatId, + messages: initialMessages, + resume: true, + transport: new DefaultChatTransport({ + api: "/api/chat", + prepareSendMessagesRequest: ({ id, messages }) => ({ + body: { + message: messages[messages.length - 1], + options: { conversationId: id, userId }, + }, + }), + prepareReconnectToStreamRequest: ({ id }) => ({ + api: `/api/chat/${id}/stream?userId=${encodeURIComponent(userId)}`, + }), + }), + }); + ``` + +- Updated dependencies [[`c4591fa`](https://github.com/VoltAgent/voltagent/commit/c4591fa92de6df75a22a758b0232669053bd2b62)]: + - @voltagent/core@2.0.7 + +--- + +## Package: @voltagent/scorers + +## 2.0.2 + +### Patch Changes + +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505)]: + - @voltagent/core@2.0.2 + - @voltagent/internal@1.0.2 + +## 2.0.1 + +### Patch Changes + +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2)]: + - @voltagent/core@2.0.1 + - @voltagent/internal@1.0.1 + +## 2.0.0 + +### Major Changes + +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +### Patch Changes + +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/core@2.0.0 + - @voltagent/internal@1.0.0 + +## 1.0.2 + +### Patch Changes + +- [#805](https://github.com/VoltAgent/voltagent/pull/805) [`ad4893a`](https://github.com/VoltAgent/voltagent/commit/ad4893a523be60cef93706a5aa6d2e0096cc306b) Thanks [@lzj960515](https://github.com/lzj960515)! - feat: add exports field to package.json for module compatibility + +- Updated dependencies [[`b56e5a0`](https://github.com/VoltAgent/voltagent/commit/b56e5a087378c7ba5ce4a2c1756a0fe3dfb738b5)]: + - @voltagent/core@1.2.7 + +## 1.0.1 + +### Patch Changes + +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` +- Updated dependencies [[`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e)]: + - @voltagent/internal@0.0.12 + - @voltagent/core@1.1.30 + +## 1.0.0 + +### Major Changes + +- [#674](https://github.com/VoltAgent/voltagent/pull/674) [`5aa84b5`](https://github.com/VoltAgent/voltagent/commit/5aa84b5bcf57d19bbe33cc791f0892c96bb3944b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: initial release + +### Patch Changes + +- Updated dependencies [[`5aa84b5`](https://github.com/VoltAgent/voltagent/commit/5aa84b5bcf57d19bbe33cc791f0892c96bb3944b), [`5aa84b5`](https://github.com/VoltAgent/voltagent/commit/5aa84b5bcf57d19bbe33cc791f0892c96bb3944b)]: + - @voltagent/core@1.1.27 + +--- + +## Package: @voltagent/sdk + +## 2.0.2 + +### Patch Changes + +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505)]: + - @voltagent/core@2.0.2 + - @voltagent/internal@1.0.2 + +## 2.0.1 + +### Patch Changes + +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2)]: + - @voltagent/core@2.0.1 + - @voltagent/internal@1.0.1 + +## 2.0.0 + +### Major Changes + +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +### Patch Changes + +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/core@2.0.0 + - @voltagent/internal@1.0.0 + +## 1.0.2 + +### Patch Changes + +- [#801](https://github.com/VoltAgent/voltagent/pull/801) [`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add triggers DSL improvements and event payload simplification + - Introduce the new `createTriggers` DSL and expose trigger events via sensible provider names (e.g. `on.airtable.recordCreated`) rather than raw catalog IDs. + - Add trigger span metadata propagation so VoltAgent agents receive trigger context automatically without manual mapping. + - Simplify action dispatch payloads: `payload` now contains only the event’s raw data while trigger context lives in the `event`/`metadata` blocks, reducing boilerplate in handlers. + + ```ts + import { VoltAgent, createTriggers } from "@voltagent/core"; + + new VoltAgent({ + // ... + triggers: createTriggers((on) => { + on.airtable.recordCreated(({ payload, event }) => { + console.log("New Airtable row", payload, event.metadata); + }); + + on.gmail.newEmail(({ payload }) => { + console.log("New Gmail message", payload); + }); + }), + }); + ``` + +- [#801](https://github.com/VoltAgent/voltagent/pull/801) [`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749) Thanks [@omeraplak](https://github.com/omeraplak)! - Add full Discord action coverage to `VoltOpsActionsClient`, including typed helpers for messaging, reactions, channels, and guild roles. **All VoltOps Actions now require the inline `credential` payload**—pass `{ id: "cred_xyz" }` to reuse a saved credential or provide provider-specific secrets on the fly. Each provider now has explicit credential typing (Airtable ⇒ `{ apiKey }`, Slack ⇒ `{ botToken }`, Discord ⇒ `{ botToken } | { webhookUrl }`), so editors autocomplete only the valid fields. The SDK propagates these types so apps can invoke VoltOps Actions without managing separate credential IDs. + +- Updated dependencies [[`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749), [`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749)]: + - @voltagent/core@1.2.6 + +## 1.0.1 + +### Patch Changes + +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` +- Updated dependencies [[`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e)]: + - @voltagent/internal@0.0.12 + - @voltagent/core@1.1.30 + +## 1.0.0 + +### Major Changes + +- [#674](https://github.com/VoltAgent/voltagent/pull/674) [`5aa84b5`](https://github.com/VoltAgent/voltagent/commit/5aa84b5bcf57d19bbe33cc791f0892c96bb3944b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add dataset/evals/experiments functions + +### Patch Changes + +- Updated dependencies [[`5aa84b5`](https://github.com/VoltAgent/voltagent/commit/5aa84b5bcf57d19bbe33cc791f0892c96bb3944b), [`5aa84b5`](https://github.com/VoltAgent/voltagent/commit/5aa84b5bcf57d19bbe33cc791f0892c96bb3944b)]: + - @voltagent/core@1.1.27 + +## 0.1.7-next.0 + +### Patch Changes + +- Updated dependencies [[`77a3f64`](https://github.com/VoltAgent/voltagent/commit/77a3f64dea6e8a06fbbd72878711efa9ceb90bc3)]: + - @voltagent/core@1.1.7-next.0 + +## 0.1.7-next.0 + +### Patch Changes + +- Updated dependencies [[`64a50e6`](https://github.com/VoltAgent/voltagent/commit/64a50e6800dec844fad7b9f3a3b1c2c8d0486229), [`9e8b211`](https://github.com/VoltAgent/voltagent/commit/9e8b2119a783942f114459f0a9b93e645727445e)]: + - @voltagent/core@1.0.0-next.0 + +## 0.1.6 + +### Patch Changes + +- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements + + This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + + **Key improvements:** + - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs + - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration + - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries + - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup + - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + + These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. + +- Updated dependencies [[`8d89469`](https://github.com/VoltAgent/voltagent/commit/8d8946919820c0298bffea13731ea08660b72c4b), [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5), [`71500c5`](https://github.com/VoltAgent/voltagent/commit/71500c5368cce3ed4aacfb0fb2749752bf71badd), [`6cc552a`](https://github.com/VoltAgent/voltagent/commit/6cc552ada896b1a8344976c46a08b53d2b3a5743)]: + - @voltagent/core@0.1.73 + +## 0.1.5 + +### Patch Changes + +- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 + +- Updated dependencies [[`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f), [`80fd3c0`](https://github.com/VoltAgent/voltagent/commit/80fd3c069de4c23116540a55082b891c4b376ce6)]: + - @voltagent/core@0.1.31 + +## 0.1.4 + +### Patch Changes + +- [#176](https://github.com/VoltAgent/voltagent/pull/176) [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: initial release of VoltAgent Observability SDK + + A TypeScript SDK for monitoring AI agents and conversations with automatic event batching and structured tracing. + + **Basic Usage:** + + ```typescript + const sdk = new VoltAgentObservabilitySDK({ + baseUrl: "https://api.voltagent.dev", + publicKey: "your-public-key", + secretKey: "your-secret-key", + autoFlush: true, + flushInterval: 3000, + }); + + const trace = await sdk.trace({ + name: "Customer Support Query", + agentId: "support-agent-v1", + input: { query: "How to reset password?" }, + userId: "user-123", + conversationId: "conv-456", + }); + + const agent = await trace.addAgent({ + name: "Support Agent", + model: "gpt-4", + input: { query: "User needs password reset help" }, + }); + ``` + + Supports nested agent workflows, custom metadata, and automatic performance metrics collection. + +- Updated dependencies [[`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275), [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275)]: + - @voltagent/core@0.1.24 + +## 0.1.3 + +### Patch Changes + +- [#171](https://github.com/VoltAgent/voltagent/pull/171) [`1cd2a93`](https://github.com/VoltAgent/voltagent/commit/1cd2a9307d10bf5c90083138655aca9614d8053b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: initial release of Vercel AI SDK integration + + Add support for Vercel AI SDK observability with automated tracing and monitoring capabilities. + + Documentation: https://voltagent.dev/voltops-llm-observability-docs/vercel-ai/ + +## 0.1.1 + +### Patch Changes + +- [#160](https://github.com/VoltAgent/voltagent/pull/160) [`03ed437`](https://github.com/VoltAgent/voltagent/commit/03ed43723cd56f29ac67088f0624a88632a14a1b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: introduce new VoltAgent SDK package + - Add new `@voltagent/sdk` package for client-side interactions with VoltAgent API + - Includes VoltAgentClient for managing agents, conversations, and telemetry + - Provides wrapper utilities for enhanced agent functionality + - Supports TypeScript with complete type definitions + +- Updated dependencies [[`03ed437`](https://github.com/VoltAgent/voltagent/commit/03ed43723cd56f29ac67088f0624a88632a14a1b)]: + - @voltagent/core@0.1.21 + +--- + +## Package: @voltagent/server-core + +## 2.1.2 + +### Patch Changes + +- [#921](https://github.com/VoltAgent/voltagent/pull/921) [`c4591fa`](https://github.com/VoltAgent/voltagent/commit/c4591fa92de6df75a22a758b0232669053bd2b62) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add resumable streaming support via @voltagent/resumable-streams, with server adapters that let clients reconnect to in-flight streams. + + ```ts + import { openai } from "@ai-sdk/openai"; + import { Agent, VoltAgent } from "@voltagent/core"; + import { + createResumableStreamAdapter, + createResumableStreamRedisStore, + } from "@voltagent/resumable-streams"; + import { honoServer } from "@voltagent/server-hono"; + + const streamStore = await createResumableStreamRedisStore(); + const resumableStream = await createResumableStreamAdapter({ streamStore }); + + const agent = new Agent({ + id: "assistant", + name: "Resumable Stream Agent", + instructions: "You are a helpful assistant.", + model: openai("gpt-4o-mini"), + }); + + new VoltAgent({ + agents: { assistant: agent }, + server: honoServer({ + resumableStream: { adapter: resumableStream }, + }), + }); + + await fetch("http://localhost:3141/agents/assistant/chat", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: `{"input":"Hello!","options":{"conversationId":"conv-1","userId":"user-1","resumableStream":true}}`, + }); + + // Resume the same stream after reconnect/refresh + const resumeResponse = await fetch( + "http://localhost:3141/agents/assistant/chat/conv-1/stream?userId=user-1" + ); + + const reader = resumeResponse.body?.getReader(); + const decoder = new TextDecoder(); + while (reader) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value, { stream: true }); + console.log(chunk); + } + ``` + + AI SDK client (resume on refresh): + + ```tsx + import { useChat } from "@ai-sdk/react"; + import { DefaultChatTransport } from "ai"; + + const { messages, sendMessage } = useChat({ + id: chatId, + messages: initialMessages, + resume: true, + transport: new DefaultChatTransport({ + api: "/api/chat", + prepareSendMessagesRequest: ({ id, messages }) => ({ + body: { + message: messages[messages.length - 1], + options: { conversationId: id, userId }, + }, + }), + prepareReconnectToStreamRequest: ({ id }) => ({ + api: `/api/chat/${id}/stream?userId=${encodeURIComponent(userId)}`, + }), + }), + }); + ``` + +- Updated dependencies [[`c4591fa`](https://github.com/VoltAgent/voltagent/commit/c4591fa92de6df75a22a758b0232669053bd2b62)]: + - @voltagent/core@2.0.7 + +## 2.1.1 + +### Patch Changes + +- [#911](https://github.com/VoltAgent/voltagent/pull/911) [`975831a`](https://github.com/VoltAgent/voltagent/commit/975831a852ea471adb621a1d87990a8ffbc5ed31) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: expose Cloudflare Workers `env` bindings in serverless contexts + + When using `@voltagent/serverless-hono` on Cloudflare Workers, the runtime `env` is now injected into the + context map for agent requests, workflow runs, and tool executions. `@voltagent/core` exports + `SERVERLESS_ENV_CONTEXT_KEY` so you can access bindings like D1 from `options.context` (tools) or + `state.context` (workflow steps). Tool execution also accepts `context` as a `Map`, preserving + `userId`/`conversationId` when provided that way. + + `@voltagent/core` is also marked as side-effect free so edge bundlers can tree-shake the PlanAgent + filesystem backend, avoiding Node-only dependency loading when it is not used. + + Usage: + + ```ts + import { createTool, SERVERLESS_ENV_CONTEXT_KEY } from "@voltagent/core"; + import type { D1Database } from "@cloudflare/workers-types"; + import { z } from "zod"; + + type Env = { DB: D1Database }; + + export const listUsers = createTool({ + name: "list-users", + description: "Fetch users from D1", + parameters: z.object({}), + execute: async (_args, options) => { + const env = options?.context?.get(SERVERLESS_ENV_CONTEXT_KEY) as Env | undefined; + const db = env?.DB; + if (!db) { + throw new Error("D1 binding is missing (env.DB)"); + } + + const { results } = await db.prepare("SELECT id, name FROM users").all(); + return results; + }, + }); + ``` + +- Updated dependencies [[`975831a`](https://github.com/VoltAgent/voltagent/commit/975831a852ea471adb621a1d87990a8ffbc5ed31)]: + - @voltagent/core@2.0.4 + +## 2.1.0 + +### Minor Changes + +- [#898](https://github.com/VoltAgent/voltagent/pull/898) [`b322cf4`](https://github.com/VoltAgent/voltagent/commit/b322cf4c511c64872c178e51f9ddccb869385dee) Thanks [@MGrin](https://github.com/MGrin)! - feat: Initial release of @voltagent/server-elysia + + # @voltagent/server-elysia + + ## 1.0.0 + + ### Major Changes + - Initial release of Elysia server implementation for VoltAgent + - Full feature parity with server-hono including: + - Agent execution endpoints (text, stream, chat, object) + - Workflow execution and lifecycle management + - Tool execution and discovery + - MCP (Model Context Protocol) support + - A2A (Agent-to-Agent) communication + - Observability and tracing + - Logging endpoints + - Authentication with authNext support + - Custom endpoint configuration + - CORS configuration + - WebSocket support + + ### Features + - **High Performance**: Built on Elysia, optimized for speed and low latency + - **Type Safety**: Full TypeScript support with strict typing + - **Flexible Configuration**: Support for both `configureApp` and `configureFullApp` patterns + - **Auth Support**: JWT authentication with public route configuration via `authNext` + - **Extensible**: Easy to add custom routes, middleware, and plugins + - **OpenAPI/Swagger**: Built-in API documentation via @elysiajs/swagger + - **MCP Support**: Full Model Context Protocol implementation with SSE streaming + - **WebSocket Support**: Real-time updates and streaming capabilities + + ### Dependencies + - `@voltagent/core`: ^1.5.1 + - `@voltagent/server-core`: ^1.0.36 + - `@voltagent/mcp-server`: ^1.0.3 + - `@voltagent/a2a-server`: ^1.0.2 + - `elysia`: ^1.1.29 + + ### Peer Dependencies + - `@voltagent/core`: ^1.x + - `elysia`: ^1.x + +## 2.0.2 + +### Patch Changes + +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505)]: + - @voltagent/core@2.0.2 + - @voltagent/internal@1.0.2 + +## 2.0.1 + +### Patch Changes + +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +- Updated dependencies [[`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2)]: + - @voltagent/core@2.0.1 + - @voltagent/internal@1.0.1 + +## 2.0.0 + +### Major Changes + +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) + + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. + + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` + + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +### Patch Changes + +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/core@2.0.0 + - @voltagent/internal@1.0.0 + +## 1.0.36 + +### Patch Changes + +- [#883](https://github.com/VoltAgent/voltagent/pull/883) [`9320326`](https://github.com/VoltAgent/voltagent/commit/93203262bf3ebcbc38fe4663c4b0cea27dd9ea16) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add authNext and deprecate legacy auth + + Add a new `authNext` policy that splits routes into public, console, and user access. All routes are protected by default; use `publicRoutes` to opt out. + + AuthNext example: + + ```ts + import { jwtAuth } from "@voltagent/server-core"; + import { honoServer } from "@voltagent/server-hono"; + + const server = honoServer({ + authNext: { + provider: jwtAuth({ secret: process.env.JWT_SECRET! }), + publicRoutes: ["GET /health"], + }, + }); + ``` + + Behavior summary: + - When `authNext` is set, all routes are private by default. + - Console endpoints (agents, workflows, tools, docs, observability, updates) require a Console Access Key. + - Execution endpoints require a user token (JWT). + + Console access uses `VOLTAGENT_CONSOLE_ACCESS_KEY`: + + ```bash + VOLTAGENT_CONSOLE_ACCESS_KEY=your-console-key + ``` + + ```bash + curl http://localhost:3141/agents \ + -H "x-console-access-key: your-console-key" + ``` + + Legacy `auth` remains supported but is deprecated. Use `authNext` for new integrations. + +## 1.0.35 + +### Patch Changes + +- [`b663dce`](https://github.com/VoltAgent/voltagent/commit/b663dceb57542d1b85475777f32ceb3671cc1237) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: dedupe MCP endpoints in server startup output and include MCP transport paths (streamable HTTP/SSE) so the actual server endpoint is visible. + +- Updated dependencies [[`b663dce`](https://github.com/VoltAgent/voltagent/commit/b663dceb57542d1b85475777f32ceb3671cc1237)]: + - @voltagent/core@1.5.1 + +## 1.0.34 + +### Patch Changes + +- [#865](https://github.com/VoltAgent/voltagent/pull/865) [`77833b8`](https://github.com/VoltAgent/voltagent/commit/77833b848fbb1ae99e79c955e25442f9ebdd162f) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: make GET /tools endpoint public when auth is enabled + + Previously, `GET /tools` was listed in `PROTECTED_ROUTES`, requiring authentication even though it only returns tool metadata (name, description, parameters). This was inconsistent with `GET /agents` and `GET /workflows` which are publicly accessible for discovery. + + ## Changes + - Moved `GET /tools` from `PROTECTED_ROUTES` to `DEFAULT_PUBLIC_ROUTES` + - Tool execution (`POST /tools/:name/execute`) remains protected and requires authentication + + This allows VoltOps Console and other clients to discover available tools without authentication, while still requiring auth to actually execute them. + +## 1.0.33 + +### Patch Changes + +- [#847](https://github.com/VoltAgent/voltagent/pull/847) [`d861c17`](https://github.com/VoltAgent/voltagent/commit/d861c17e72f2fb6368778970a56411fadabaf9a5) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add first-class REST tool endpoints and UI support - #638 + - Server: list and execute registered tools over HTTP (`GET /tools`, `POST /tools/:name/execute`) with zod-validated inputs and OpenAPI docs. + - Auth: Both GET and POST tool endpoints are behind the same auth middleware as agent/workflow execution (protected by default). + - Multi-agent tools: tools now report all owning agents via `agents[]` (no more single `agentId`), including tags when provided. + - Safer handlers: input validation via safeParse guard, tag extraction without `any`, and better error shaping. + - Serverless: update install route handles empty bodies and `/updates/:packageName` variant. + - Console: Unified list surfaces tools, tool tester drawer with Monaco editors and default context, Observability page adds a Tools tab with direct execution. + - Docs: New tools endpoint page and API reference entries for listing/executing tools. + +## 1.0.32 + +### Patch Changes + +- [#845](https://github.com/VoltAgent/voltagent/pull/845) [`5432f13`](https://github.com/VoltAgent/voltagent/commit/5432f13bddebd869522ebffbedd9843b4476f08b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: workflow execution listing - #844 + + Added a unified way to list workflow runs so teams can audit executions across every storage backend and surface them via the API and console. + + ## What changed + - `queryWorkflowRuns` now exists on all memory adapters (in-memory, libsql, Postgres, Supabase, voltagent-memory) with filters for `workflowId`, `status`, `from`, `to`, `limit`, and `offset`. + - Server routes are consolidated under `/workflows/executions` (no path param needed); `GET /workflows/:id` also returns the workflow result schema for typed clients. Handler naming is standardized to `listWorkflowRuns`. + - VoltOps Console observability panel lists the new endpoint; REST docs updated with query params and sample responses. New unit tests cover handlers and every storage adapter. + + ## Quick fetch + + ```ts + await fetch( + "http://localhost:3141/workflows/executions?workflowId=expense-approval&status=completed&from=2024-01-01&to=2024-01-31&limit=20&offset=0" + ); + ``` + +- Updated dependencies [[`5432f13`](https://github.com/VoltAgent/voltagent/commit/5432f13bddebd869522ebffbedd9843b4476f08b)]: + - @voltagent/core@1.2.17 + +## 1.0.31 + +### Patch Changes + +- [`d3e0995`](https://github.com/VoltAgent/voltagent/commit/d3e09950fb8708db8beb9db2f1b8eafbe47686ea) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add CLI announcements system for server startup + + VoltAgent server now displays announcements during startup, keeping developers informed about new features and updates. + + ## How It Works + + When the server starts, it fetches announcements from a centralized GitHub-hosted JSON file and displays them in a minimal, non-intrusive format: + + ``` + ⚡ Introducing VoltOps Deployments → https://console.voltagent.dev/deployments + ``` + + ## Key Features + - **Dynamic updates**: Announcements are fetched from GitHub at runtime, so new announcements appear without requiring a package update + - **Non-blocking**: Uses a 3-second timeout and fails silently to never delay server startup + - **Minimal footprint**: Single-line format inspired by Next.js, doesn't clutter the console + - **Toggle support**: Each announcement has an `enabled` flag for easy control + + ## Technical Details + - Announcements source: `https://raw.githubusercontent.com/VoltAgent/voltagent/main/announcements.json` + - New `showAnnouncements()` function exported from `@voltagent/server-core` + - Integrated into both `BaseServerProvider` and `HonoServerProvider` startup flow + +## 1.0.30 + +### Patch Changes + +- [#840](https://github.com/VoltAgent/voltagent/pull/840) [`9e88658`](https://github.com/VoltAgent/voltagent/commit/9e88658c2c26aff972bdd2da6e7ac2e34958c47d) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: webSocket authentication now uses same logic as HTTP routes + + ## The Problem + + WebSocket endpoints were using a different authentication logic than HTTP endpoints: + - HTTP routes used `requiresAuth()` function which respects `publicRoutes`, `DEFAULT_PUBLIC_ROUTES`, `PROTECTED_ROUTES`, and `defaultPrivate` configuration + - WebSocket routes only checked for console access key or JWT token, ignoring the `publicRoutes` configuration entirely + + This meant that setting `publicRoutes: ["/ws/**"]` in your auth configuration had no effect on WebSocket connections. + + ## The Solution + + Updated `setupWebSocketUpgrade` in `packages/server-core/src/websocket/setup.ts` to: + 1. Check console access first (console always has access via `VOLTAGENT_CONSOLE_ACCESS_KEY`) + 2. Use the same `requiresAuth()` function that HTTP routes use + 3. Respect `publicRoutes`, `PROTECTED_ROUTES`, and `defaultPrivate` configuration - **🤝 Help Shape Workflows:** - We need your feedback to make Workflows awesome! The API will evolve based on real-world usage and community input. - - 💬 **[Join our Discord](https://s.voltagent.dev/discord)**: Share ideas, discuss use cases, and get help - - 🐛 **[GitHub Issues](https://github.com/VoltAgent/voltagent/issues)**: Report bugs, request features, or suggest improvements - - 🚀 **Early Adopters**: Build experimental projects and share your learnings - - 📝 **API Feedback**: Tell us what's missing, confusing, or could be better + ## Impact + - **Consistent auth behavior:** WebSocket and HTTP routes now follow the same authentication rules + - **publicRoutes works for WebSocket:** You can now make WebSocket paths public using the `publicRoutes` configuration + - **Console access preserved:** Console with `VOLTAGENT_CONSOLE_ACCESS_KEY` continues to work on all WebSocket paths - **🔄 Future Plans:** - - React Flow integration for visual workflow editor - - Advanced error handling and retry mechanisms - - Workflow templates and presets - - Real-time execution monitoring - - Comprehensive documentation and tutorials + ## Example -## 0.1.57 + ```typescript + const server = new VoltAgent({ + auth: { + defaultPrivate: true, + publicRoutes: ["/ws/public/**"], // Now works for WebSocket too! + }, + }); + ``` + +- Updated dependencies [[`93e5a8e`](https://github.com/VoltAgent/voltagent/commit/93e5a8ed03d2335d845436752b476881c24931ba)]: + - @voltagent/core@1.2.16 + +## 1.0.29 ### Patch Changes -- [`894be7f`](https://github.com/VoltAgent/voltagent/commit/894be7feb97630c10e036cf3691974a5e351472c) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: export PromptContent type to resolve "cannot be named" TypeScript error +- [#824](https://github.com/VoltAgent/voltagent/pull/824) [`92f8d46`](https://github.com/VoltAgent/voltagent/commit/92f8d466db683f5c8bc000d034c441fc3b9e3ad5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: ensure `jwtAuth` respects `defaultPrivate` option -## 0.1.56 + The `jwtAuth` helper function was ignoring the `defaultPrivate` option, causing custom routes to remain public even when `defaultPrivate: true` was set. This change ensures that the option is correctly passed to the authentication provider, enforcing security on all routes by default when enabled. + + ## Example + + ```typescript + // Custom routes are now properly secured + server: honoServer({ + auth: jwtAuth({ + secret: "...", + defaultPrivate: true, // Now correctly enforces auth on all routes + publicRoutes: ["GET /health"], + }), + configureApp: (app) => { + // This route is now protected (returns 401 without token) + app.get("/api/protected", (c) => c.json({ message: "Protected" })); + }, + }), + ``` + +- Updated dependencies [[`fd1428b`](https://github.com/VoltAgent/voltagent/commit/fd1428b73abfcac29c238e0cee5229ff227cb72b)]: + - @voltagent/core@1.2.13 + +## 1.0.28 ### Patch Changes -- [#351](https://github.com/VoltAgent/voltagent/pull/351) [`f8f8d04`](https://github.com/VoltAgent/voltagent/commit/f8f8d04340d6f9609450f6ae000c9fe1d71072d7) Thanks [@alasano](https://github.com/alasano)! - fix: add historyMemory option to Agent configuration +- [`28661fc`](https://github.com/VoltAgent/voltagent/commit/28661fc24f945b0e52c12703a5a09a033317d8fa) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: enable persistence for live evaluations -## 0.1.55 +- Updated dependencies [[`28661fc`](https://github.com/VoltAgent/voltagent/commit/28661fc24f945b0e52c12703a5a09a033317d8fa)]: + - @voltagent/core@1.2.12 + +## 1.0.27 ### Patch Changes -- [#352](https://github.com/VoltAgent/voltagent/pull/352) [`b7dcded`](https://github.com/VoltAgent/voltagent/commit/b7dcdedfbbdda5bfb1885317b59b4d4e2495c956) Thanks [@alasano](https://github.com/alasano)! - fix(core): store and use userContext from Agent constructor +- [`2cb5464`](https://github.com/VoltAgent/voltagent/commit/2cb5464f15a6e2b2e7b5649c1db3ed7298b633eb) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: trigger duplicate span issue -- [#345](https://github.com/VoltAgent/voltagent/pull/345) [`822739c`](https://github.com/VoltAgent/voltagent/commit/822739c901bbc679cd11dd2c9df99cd041fc40c7) Thanks [@thujee](https://github.com/thujee)! - fix: moves zod from direct to dev dependency to avoid version conflicts in consuming app +- Updated dependencies [[`148f550`](https://github.com/VoltAgent/voltagent/commit/148f550ceafa412534fd2d1c4cfb44c8255636ab)]: + - @voltagent/core@1.2.10 -## 0.1.54 +## 1.0.26 ### Patch Changes -- [#346](https://github.com/VoltAgent/voltagent/pull/346) [`5100f7f`](https://github.com/VoltAgent/voltagent/commit/5100f7f9419db7e26aa18681b0ad3c09c0957b10) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: export PromptContent type to resolve "cannot be named" TypeScript error +- [#812](https://github.com/VoltAgent/voltagent/pull/812) [`0f64363`](https://github.com/VoltAgent/voltagent/commit/0f64363a2b577e025fae41276cc0d85ef7fc0644) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: comprehensive authentication system with JWT, Console Access, and WebSocket support + + ## The Problem + + VoltAgent's authentication system had several critical gaps that made it difficult to secure production deployments: + 1. **No Authentication Support:** The framework lacked built-in authentication, forcing developers to implement their own security + 2. **WebSocket Security:** WebSocket connections for observability had no authentication, exposing sensitive telemetry data + 3. **Browser Limitations:** Browsers cannot send custom headers during WebSocket handshake, making authentication impossible + 4. **Development vs Production:** No clear separation between development convenience and production security + 5. **Console Access:** No secure way for the VoltAgent Console to access observability endpoints in production + + ## The Solution + + **JWT Authentication (`@voltagent/server-core`, `@voltagent/server-hono`):** + - Added pluggable `jwtAuth` provider with configurable secret and options + - Implemented `mapUser` function to transform JWT payloads into user objects + - Created flexible route protection with `defaultPrivate` mode (opt-out vs opt-in) + - Added `publicRoutes` configuration for fine-grained control + + **WebSocket Authentication:** + - Implemented query parameter authentication for browser WebSocket connections + - Added dual authentication support (headers for servers, query params for browsers) + - Created WebSocket-specific authentication helpers for observability endpoints + - Preserved user context throughout WebSocket connection lifecycle + + **Console Access System:** + - Introduced `VOLTAGENT_CONSOLE_ACCESS_KEY` environment variable for production Console access + - Added `x-console-access-key` header support for HTTP requests + - Implemented query parameter `?key=` for WebSocket connections + - Created `hasConsoleAccess()` utility for unified access checking + + **Development Experience:** + - Enhanced `x-voltagent-dev` header to work with both HTTP and WebSocket + - Added `isDevRequest()` helper that requires both header AND non-production environment + - Implemented query parameter `?dev=true` for browser WebSocket connections + - Maintained zero-config development mode while ensuring production security + + **Route Matching Improvements:** + - Added wildcard support with `/observability/*` pattern for all observability endpoints + - Implemented double-star pattern `/api/**` for path and all children + - Enhanced `pathMatches()` function with proper segment matching + - Protected all observability, workflow control, and system update endpoints by default + + ## Impact + - ✅ **Production Ready:** Complete authentication system for securing VoltAgent deployments + - ✅ **WebSocket Security:** Browser-compatible authentication for real-time observability + - ✅ **Console Integration:** Secure access for VoltAgent Console in production environments + - ✅ **Developer Friendly:** Zero-config development with automatic authentication bypass + - ✅ **Flexible Security:** Choose between opt-in (default) or opt-out authentication modes + - ✅ **User Context:** Automatic user injection into agent and workflow execution context + + ## Technical Details + + **Protected Routes (Default):** - Fixed a TypeScript compilation error where users would get "cannot be named" errors when exporting variables that use `InstructionsDynamicValue` type. This occurred because `InstructionsDynamicValue` references `PromptContent` type, but `PromptContent` was not being re-exported from the public API. + ```typescript + // Agent/Workflow Execution + POST /agents/:id/text + POST /agents/:id/stream + POST /workflows/:id/run - **Before:** + // All Observability Endpoints + /observability/* // Traces, logs, memory - all methods + + // Workflow Control + POST /workflows/:id/executions/:executionId/suspend + POST /workflows/:id/executions/:executionId/resume + + // System Updates + GET /updates + POST /updates/:packageName + ``` + + **Authentication Modes:** ```typescript - export type { DynamicValueOptions, DynamicValue, PromptHelper }; + // Opt-in mode (default) - Only execution endpoints protected + auth: jwtAuth({ + secret: process.env.JWT_SECRET, + }); + + // Opt-out mode - Everything protected except specified routes + auth: jwtAuth({ + secret: process.env.JWT_SECRET, + defaultPrivate: true, + publicRoutes: ["GET /health", "POST /webhooks/*"], + }); ``` - **After:** + **WebSocket Authentication Flow:** ```typescript - export type { DynamicValueOptions, DynamicValue, PromptHelper, PromptContent }; + // Browser WebSocket with query params + new WebSocket("ws://localhost:3000/ws/observability?key=console-key"); + new WebSocket("ws://localhost:3000/ws/observability?dev=true"); + + // Server WebSocket with headers + ws.connect({ + headers: { + "x-console-access-key": "console-key", + "x-voltagent-dev": "true", + }, + }); ``` - This ensures that all types referenced by public API types are properly exported, preventing TypeScript compilation errors when users export agents or variables that use dynamic instructions. + ## Migration Notes -## 0.1.53 + **For Existing Users:** + 1. **No Breaking Changes:** Authentication is optional. Existing deployments continue to work without configuration. + 2. **To Enable Authentication:** + + ```typescript + import { jwtAuth } from "@voltagent/server-hono"; + + new VoltAgent({ + server: honoServer({ + auth: jwtAuth({ + secret: process.env.JWT_SECRET, + }), + }), + }); + ``` + + 3. **For Production Console:** + + ```bash + # .env + VOLTAGENT_CONSOLE_ACCESS_KEY=your-secure-key + NODE_ENV=production + ``` + + 4. **Generate Secrets:** + + ```bash + # JWT Secret + openssl rand -hex 32 + + # Console Access Key + openssl rand -hex 32 + ``` + + 5. **Test Token Generation:** + ```javascript + // generate-token.js + import jwt from "jsonwebtoken"; + const token = jwt.sign({ id: "user-1", email: "test@example.com" }, process.env.JWT_SECRET, { + expiresIn: "24h", + }); + console.log(token); + ``` + + ## Documentation + + Comprehensive authentication documentation has been added to `/website/docs/api/authentication.md` covering: + - Getting started with three authentication options + - Common use cases with code examples + - Advanced configuration with `mapUser` function + - Console and observability authentication + - Security best practices + - Troubleshooting guide + +- Updated dependencies [[`0f64363`](https://github.com/VoltAgent/voltagent/commit/0f64363a2b577e025fae41276cc0d85ef7fc0644)]: + - @voltagent/core@1.2.9 + +## 1.0.25 ### Patch Changes -- [#343](https://github.com/VoltAgent/voltagent/pull/343) [`096bda4`](https://github.com/VoltAgent/voltagent/commit/096bda41d5333e110da2c034e57f60b4ce7b9076) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: extend SubAgent functionality with support for multiple execution methods and flexible configuration API +- [#801](https://github.com/VoltAgent/voltagent/pull/801) [`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add triggers DSL improvements and event payload simplification + - Introduce the new `createTriggers` DSL and expose trigger events via sensible provider names (e.g. `on.airtable.recordCreated`) rather than raw catalog IDs. + - Add trigger span metadata propagation so VoltAgent agents receive trigger context automatically without manual mapping. + - Simplify action dispatch payloads: `payload` now contains only the event’s raw data while trigger context lives in the `event`/`metadata` blocks, reducing boilerplate in handlers. - **SubAgent functionality has been significantly enhanced to support all four agent execution methods (generateText, streamText, generateObject, streamObject) with flexible per-subagent configuration.** Previously, SubAgents only supported `streamText` method. Now you can configure each SubAgent to use different execution methods with custom options and schemas. + ```ts + import { VoltAgent, createTriggers } from "@voltagent/core"; - ## 📋 Usage + new VoltAgent({ + // ... + triggers: createTriggers((on) => { + on.airtable.recordCreated(({ payload, event }) => { + console.log("New Airtable row", payload, event.metadata); + }); - **New SubAgent API with createSubagent():** + on.gmail.newEmail(({ payload }) => { + console.log("New Gmail message", payload); + }); + }), + }); + ``` + +- Updated dependencies [[`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749), [`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749)]: + - @voltagent/core@1.2.6 + +## 1.0.24 + +### Patch Changes + +- [`b4e98f5`](https://github.com/VoltAgent/voltagent/commit/b4e98f5220f3beab08d8a1abad5e05a1f8166c3e) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: prevent NoOutputSpecifiedError when experimental_output is not provided + + ## The Problem + + When `experimental_output` parameter was added to HTTP text endpoints but not provided in requests, accessing `result.experimental_output` would throw `AI_NoOutputSpecifiedError`. This happened because AI SDK's `experimental_output` getter throws an error when the output schema is not defined. + + ## The Solution + + Wrapped `experimental_output` access in a try-catch block in `handleGenerateText()` to safely handle cases where the parameter is not provided: ```typescript - import { Agent, createSubagent } from "@voltagent/core"; - import { VercelAIProvider } from "@voltagent/vercel-ai"; - import { openai } from "@ai-sdk/openai"; - import { z } from "zod"; + // Safe access pattern + ...(() => { + try { + return result.experimental_output ? { experimental_output: result.experimental_output } : {}; + } catch { + return {}; + } + })() + ``` - // Define schemas for structured output - const analysisSchema = z.object({ - summary: z.string(), - keyFindings: z.array(z.string()), - confidence: z.number().min(0).max(1), - }); + ## Impact + - **No Breaking Changes:** Endpoints work correctly both with and without `experimental_output` + - **Better Error Handling:** Gracefully handles missing output schemas instead of throwing errors + - **Backward Compatible:** Existing API calls continue to work without modification - const reportSchema = z.object({ - title: z.string(), - sections: z.array( - z.object({ - heading: z.string(), - content: z.string(), - priority: z.enum(["high", "medium", "low"]), - }) - ), - }); +## 1.0.23 - // Create specialized subagents - const dataAnalyst = new Agent({ - name: "DataAnalyst", - instructions: "Analyze data and provide structured insights", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - }); +### Patch Changes - const reportGenerator = new Agent({ - name: "ReportGenerator", - instructions: "Generate comprehensive reports", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - }); +- [#791](https://github.com/VoltAgent/voltagent/pull/791) [`57bff8b`](https://github.com/VoltAgent/voltagent/commit/57bff8bef675d9d1b9f60a7aea8d11cbf4fb7a15) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add experimental_output support to HTTP text endpoints - #790 - const summaryWriter = new Agent({ - name: "SummaryWriter", - instructions: "Create concise summaries", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - }); + ## What Changed - // Supervisor with enhanced SubAgent configuration - const supervisor = new Agent({ - name: "AdvancedSupervisor", - instructions: "Coordinate specialized agents with different methods", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - subAgents: [ - // ✅ OLD STYLE: Direct agent (defaults to streamText) - still supported - summaryWriter, + The HTTP API now supports AI SDK's `experimental_output` feature for structured generation! You can now use `/agents/{id}/text`, `/agents/{id}/stream`, and `/agents/{id}/chat` endpoints to generate type-safe structured data while maintaining full tool calling capabilities. - // ✅ NEW STYLE: generateObject with schema - createSubagent({ - agent: dataAnalyst, - method: "generateObject", - schema: analysisSchema, - options: { - temperature: 0.3, // Precise analysis - maxTokens: 1500, - }, - }), + ## The Problem - // ✅ NEW STYLE: streamObject with schema - createSubagent({ - agent: reportGenerator, - method: "streamObject", - schema: reportSchema, - options: { - temperature: 0.5, - maxTokens: 2000, - }, - }), + Previously, to get structured output from VoltAgent's HTTP API, you had two options: + 1. Use `/agents/{id}/object` endpoint - BUT this doesn't support tool calling + 2. Use direct method calls with `experimental_output` - BUT this requires running code in the same process - // ✅ NEW STYLE: generateText with custom options - createSubagent({ - agent: summaryWriter, - method: "generateText", - options: { - temperature: 0.7, // Creative writing - maxTokens: 800, - }, - }), - ], - }); + Users couldn't get structured output with tool calling through the HTTP API. + + ## The Solution + + **HTTP API (server-core):** + - Added `experimental_output` field to `GenerateOptionsSchema` (accepts `{ type: "object"|"text", schema?: {...} }`) + - Updated `processAgentOptions` to convert JSON schema → Zod schema → `Output.object()` or `Output.text()` + - Modified `handleGenerateText` to return `experimental_output` in response + - Moved `BasicJsonSchema` definition to be reused across object and experimental_output endpoints + - All existing endpoints (`/text`, `/stream`, `/chat`) now support this feature + + **What Gets Sent:** + + ```json + { + "input": "Create a recipe", + "options": { + "experimental_output": { + "type": "object", + "schema": { + "type": "object", + "properties": { ... }, + "required": [...] + } + } + } + } ``` - **Backward Compatibility:** + **What You Get Back:** + + ```json + { + "success": true, + "data": { + "text": "Here's a recipe...", + "experimental_output": { + "name": "Pasta Carbonara", + "ingredients": ["eggs", "bacon", "pasta"], + "steps": ["Boil pasta", "Cook bacon", ...], + "prepTime": 20 + }, + "usage": { ... } + } + } + ``` + + ## Usage Examples + + ### Object Type - Structured JSON Output + + **Request:** + + ```bash + curl -X POST http://localhost:3141/agents/my-agent/text \ + -H "Content-Type: application/json" \ + -d '{ + "input": "Create a recipe for pasta carbonara", + "options": { + "experimental_output": { + "type": "object", + "schema": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "ingredients": { + "type": "array", + "items": { "type": "string" } + }, + "steps": { + "type": "array", + "items": { "type": "string" } + }, + "prepTime": { "type": "number" } + }, + "required": ["name", "ingredients", "steps"] + } + } + } + }' + ``` + + **Response:** + + ```json + { + "success": true, + "data": { + "text": "Here is a classic pasta carbonara recipe...", + "experimental_output": { + "name": "Classic Pasta Carbonara", + "ingredients": [ + "400g spaghetti", + "200g guanciale or pancetta", + "4 large eggs", + "100g Pecorino Romano cheese", + "Black pepper" + ], + "steps": [ + "Bring a large pot of salted water to boil", + "Cook pasta according to package directions", + "While pasta cooks, dice guanciale and cook until crispy", + "Beat eggs with grated cheese and black pepper", + "Drain pasta, reserving 1 cup pasta water", + "Off heat, toss pasta with guanciale and fat", + "Add egg mixture, tossing quickly with pasta water" + ], + "prepTime": 20 + }, + "usage": { + "promptTokens": 145, + "completionTokens": 238, + "totalTokens": 383 + }, + "finishReason": "stop", + "toolCalls": [], + "toolResults": [] + } + } + ``` + + ### Text Type - Constrained Text Output + + **Request:** + + ```bash + curl -X POST http://localhost:3141/agents/my-agent/text \ + -H "Content-Type: application/json" \ + -d '{ + "input": "Write a short poem about coding", + "options": { + "experimental_output": { + "type": "text" + } + } + }' + ``` + + **Response:** + + ```json + { + "success": true, + "data": { + "text": "Lines of code dance on the screen...", + "experimental_output": "Lines of code dance on the screen,\nLogic flows like streams pristine,\nBugs debug with patience keen,\nCreating worlds we've never seen.", + "usage": { ... }, + "finishReason": "stop" + } + } + ``` + + ### With Streaming (SSE) + + The `/agents/{id}/stream` and `/agents/{id}/chat` endpoints also support `experimental_output`: + + **Request:** + + ```bash + curl -X POST http://localhost:3141/agents/my-agent/stream \ + -H "Content-Type: application/json" \ + -d '{ + "input": "Create a recipe", + "options": { + "experimental_output": { + "type": "object", + "schema": { ... } + } + } + }' + ``` + + **Response (Server-Sent Events):** + + ``` + data: {"type":"text-delta","textDelta":"Here"} + data: {"type":"text-delta","textDelta":" is"} + data: {"type":"text-delta","textDelta":" a recipe..."} + data: {"type":"finish","finishReason":"stop","experimental_output":{...}} + ``` + + ## Comparison: generateObject vs experimental_output + + | Feature | `/agents/{id}/object` | `/agents/{id}/text` + `experimental_output` | + | ----------------- | ---------------------- | ------------------------------------------- | + | Structured output | ✅ | ✅ | + | Tool calling | ❌ | ✅ | + | Streaming | Partial objects | Partial objects | + | Use case | Simple data extraction | Complex workflows with tools | + + **When to use which:** + - Use `/object` for simple schema validation without tool calling + - Use `/text` with `experimental_output` when you need structured output **and** tool calling + + ## Important Notes + - **Backward Compatible:** `experimental_output` is optional - existing API calls work unchanged + - **Tool Calling:** Unlike `/object` endpoint, this supports full tool calling capabilities + - **Type Safety:** JSON schema is automatically converted to Zod schema for validation + - **Zod Version:** Supports both Zod v3 and v4 (automatic detection) + - **Experimental:** This uses AI SDK's experimental features and may change in future versions + + ## Technical Details + + **Files Changed:** + - `packages/server-core/src/schemas/agent.schemas.ts` - Added `experimental_output` schema + - `packages/server-core/src/utils/options.ts` - Added JSON→Zod conversion logic + - `packages/server-core/src/handlers/agent.handlers.ts` - Added response field + + **Schema Format:** ```typescript - // ✅ OLD STYLE: Still works (defaults to streamText) - const supervisor = new Agent({ - name: "Supervisor", - subAgents: [agent1, agent2, agent3], // Direct Agent instances - // ... other config - }); + experimental_output: z.object({ + type: z.enum(["object", "text"]), + schema: BasicJsonSchema.optional(), // for type: "object" + }).optional(); ``` -- [#344](https://github.com/VoltAgent/voltagent/pull/344) [`5d908c5`](https://github.com/VoltAgent/voltagent/commit/5d908c5a83569848c91d86c5ecfcd3d4d4ffae42) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add supervisorConfig API for customizing supervisor agent behavior + ## Impact + - ✅ **HTTP API Parity:** HTTP endpoints now have feature parity with direct method calls + - ✅ **Tool Calling + Structure:** Combine structured output with tool execution + - ✅ **Better DX:** Type-safe outputs through HTTP API + - ✅ **Backward Compatible:** No breaking changes + + ## Related + + This feature complements the `experimental_output` support added to `@voltagent/core` in v1.1.6, bringing the same capabilities to HTTP endpoints. + +## 1.0.22 + +### Patch Changes + +- [#787](https://github.com/VoltAgent/voltagent/pull/787) [`5e81d65`](https://github.com/VoltAgent/voltagent/commit/5e81d6568ba3bee26083ca2a8e5d31f158e36fc0) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add full conversation step persistence across the stack: + - Core now exposes managed-memory step APIs, and the VoltAgent managed memory adapter persists/retrieves steps through VoltOps. + - LibSQL, PostgreSQL, Supabase, and server handlers provision the new `_steps` table, wire up DTOs/routes, and surface the data in Observability/Steps UI (including managed-memory backends). + + fixes: #613 - **SupervisorConfig API enables complete control over supervisor agent system messages and behavior** when working with SubAgents, allowing users to customize guidelines, override system messages, and control memory inclusion. +- Updated dependencies [[`5e81d65`](https://github.com/VoltAgent/voltagent/commit/5e81d6568ba3bee26083ca2a8e5d31f158e36fc0)]: + - @voltagent/core@1.2.3 - ## 🎯 What's New +## 1.0.21 - **🚀 SupervisorConfig API:** +### Patch Changes - ```typescript - const supervisor = new Agent({ - name: "Custom Supervisor", - instructions: "Coordinate specialized tasks", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - subAgents: [writerAgent, editorAgent], +- [#767](https://github.com/VoltAgent/voltagent/pull/767) [`cc1f5c0`](https://github.com/VoltAgent/voltagent/commit/cc1f5c032cd891ed4df0b718885f70853c344690) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add tunnel command - supervisorConfig: { - // Complete system message override - systemMessage: "You are TaskBot. Use delegate_task to assign work.", + ## New: `volt tunnel` - // Add custom rules to default guidelines - customGuidelines: ["Always verify sources", "Include confidence levels"], + Expose your local VoltAgent server over a secure public URL with a single command: - // Control memory inclusion (default: true) - includeAgentsMemory: false, - }, - }); + ```bash + pnpm volt tunnel 3141 ``` - ## 🔧 Configuration Options - - **`systemMessage`**: Complete system message override - replaces default template - - **`customGuidelines`**: Add custom rules to default supervisor guidelines - - **`includeAgentsMemory`**: Control whether previous agent interactions are included + The CLI handles tunnel creation for `localhost:3141` and keeps the connection alive until you press `Ctrl+C`. You can omit the port argument to use the default. -- [#340](https://github.com/VoltAgent/voltagent/pull/340) [`ef778c5`](https://github.com/VoltAgent/voltagent/commit/ef778c543acb229edd049da2e7bbed2ae5fe40cf) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: separate conversation memory from history storage when memory: false +## 1.0.20 - When `memory: false` is set, conversation memory and user messages should be disabled, but history storage and timeline events should continue working. Previously, both conversation memory and history storage were being disabled together. +### Patch Changes - **Before:** +- [#734](https://github.com/VoltAgent/voltagent/pull/734) [`2084fd4`](https://github.com/VoltAgent/voltagent/commit/2084fd491db4dbc89c432d1e72a633ec0c42d92b) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: add URL path support for single package updates and resolve 404 errors - ```typescript - const agent = new Agent({ - name: "TestAgent", - instructions: "You are a helpful assistant", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - memory: false, // ❌ Disabled both conversation memory AND history storage - }); + ## The Problem - // Result: No conversation context + No history/events tracking - ``` + The update endpoint only accepted package names via request body (`POST /updates` with `{ "packageName": "@voltagent/core" }`), but users expected to be able to specify the package name directly in the URL path (`POST /updates/@voltagent/core`). This caused 404 errors when trying to update individual packages using the more intuitive URL-based approach. - **After:** + ## The Solution + + Added a new route `POST /updates/:packageName` that accepts the package name as a URL parameter, providing a more RESTful API design while maintaining backward compatibility with the existing body-based approach. + + **New Routes Available:** + - `POST /updates/@voltagent/core` - Update single package (package name in URL path) + - `POST /updates` with body `{ "packageName": "@voltagent/core" }` - Update single package (package name in body) + - `POST /updates` with no body - Update all VoltAgent packages + + **Package Manager Detection:** + The system automatically detects your package manager based on lock files: + - `pnpm-lock.yaml` → uses `pnpm add` + - `yarn.lock` → uses `yarn add` + - `package-lock.json` → uses `npm install` + - `bun.lockb` → uses `bun add` + + ## Usage Example ```typescript - const agent = new Agent({ - name: "TestAgent", - instructions: "You are a helpful assistant", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - memory: false, // ✅ Disables only conversation memory, history storage remains active + // Update a single package using URL path + fetch("http://localhost:3141/updates/@voltagent/core", { + method: "POST", }); - // Result: No conversation context + History/events tracking still works - ``` - - **What this means for users:** - - ✅ `memory: false` now only disables conversation memory (user messages and context) - - ✅ History storage and timeline events continue to work for debugging and observability - - ✅ Agent interactions are still tracked in VoltAgent Console - - ✅ Tools and sub-agents can still access operation context and history + // Or using the body parameter (backward compatible) + fetch("http://localhost:3141/updates", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ packageName: "@voltagent/core" }), + }); - This change improves the observability experience while maintaining the expected behavior of disabling conversation memory when `memory: false` is set. + // Update all packages + fetch("http://localhost:3141/updates", { + method: "POST", + }); + ``` - Fixes the issue where setting `memory: false` would prevent history and events from being tracked in the VoltAgent Console. +- Updated dependencies [[`348bda0`](https://github.com/VoltAgent/voltagent/commit/348bda0f0fffdcbd75c8a6aa2c2d8bd15195cd22)]: + - @voltagent/core@1.1.36 -## 0.1.52 +## 1.0.19 ### Patch Changes -- [#338](https://github.com/VoltAgent/voltagent/pull/338) [`3e9a863`](https://github.com/VoltAgent/voltagent/commit/3e9a8631c0e4774d0623825263040ad3a14c23d0) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: implement configurable maxSteps parameter with parent-child agent inheritance +- [`907cc30`](https://github.com/VoltAgent/voltagent/commit/907cc30b8cbe655ae6e79fd25494f246663fd8ad) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: @voltagent/core dependency - **Agents now support configurable maxSteps parameter at the API level, allowing fine-grained control over computational resources. Parent agents automatically pass their effective maxSteps to subagents, ensuring consistent resource management across the agent hierarchy.** +## 1.0.18 - ## 🎯 What's New +### Patch Changes - **🚀 Configurable MaxSteps System** - - **API-Level Configuration**: Set maxSteps dynamically for any agent call - - **Agent-Level Defaults**: Configure default maxSteps when creating agents - - **Automatic Inheritance**: SubAgents automatically inherit parent's effective maxSteps - - **Configurable Supervisor**: Enhanced supervisor system message generation with agent memory +- Updated dependencies [[`461ecec`](https://github.com/VoltAgent/voltagent/commit/461ecec60aa90b56a413713070b6e9f43efbd74b)]: + - @voltagent/core@1.1.31 - ## 📋 Usage Examples +## 1.0.17 - **API-Level MaxSteps Configuration:** +### Patch Changes - ```typescript - import { Agent, VoltAgent } from "@voltagent/core"; - import { VercelAIProvider } from "@voltagent/vercel-ai"; - import { openai } from "@ai-sdk/openai"; +- [#709](https://github.com/VoltAgent/voltagent/pull/709) [`8b838ec`](https://github.com/VoltAgent/voltagent/commit/8b838ecf085f13efacb94897063de5e7087861e6) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add defaultPrivate option to AuthProvider for protecting all routes by default - // Create agent with default maxSteps - const agent = new Agent({ - name: "AssistantAgent", - instructions: "Help users with their questions", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - maxSteps: 10, // Default maxSteps for this agent - }); + ## The Problem - // Usage examples: + When using VoltAgent with third-party auth providers (like Clerk, Auth0, or custom providers), custom routes added via `configureApp` were public by default. This meant: + - Only routes explicitly in `PROTECTED_ROUTES` required authentication + - Custom endpoints needed manual middleware to be protected + - The `publicRoutes` property couldn't make all routes private by default - // 1. Use agent's default maxSteps (10) - const result1 = await agent.generateText("Simple question"); + This was especially problematic when integrating with enterprise auth systems where security-by-default is expected. - // 2. Override with API-level maxSteps - const result2 = await agent.generateText("Complex question", { - maxSteps: 25, // Override agent's default (10) with API-level (25) - }); + ## The Solution - // 3. Stream with custom maxSteps - const stream = await agent.streamText("Long conversation", { - maxSteps: 50, // Allow more steps for complex interactions - }); + Added `defaultPrivate` option to `AuthProvider` interface, enabling two authentication modes: + - **Opt-In Mode** (default, `defaultPrivate: false`): Only specific routes require auth + - **Opt-Out Mode** (`defaultPrivate: true`): All routes require auth unless explicitly listed in `publicRoutes` - // 4. Generate object with specific maxSteps - const objectResult = await agent.generateObject("Create structure", schema, { - maxSteps: 5, // Limit steps for simple object generation - }); - ``` + ## Usage Example - **Parent-Child Agent Inheritance:** + ### Protecting All Routes with Clerk ```typescript - // Create specialized subagents - const contentCreator = new Agent({ - name: "ContentCreator", - instructions: "Create engaging content", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - }); - - const formatter = new Agent({ - name: "Formatter", - instructions: "Format and style content", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - }); + import { VoltAgent } from "@voltagent/core"; + import { honoServer, jwtAuth } from "@voltagent/server-hono"; - // Create supervisor with subagents - const supervisor = new Agent({ - name: "Supervisor", - instructions: "Coordinate content creation and formatting", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - subAgents: [contentCreator, formatter], - maxSteps: 15, // Agent limit + new VoltAgent({ + agents: { myAgent }, + server: honoServer({ + auth: jwtAuth({ + secret: process.env.CLERK_JWT_KEY, + defaultPrivate: true, // 🔒 Protect all routes by default + publicRoutes: ["GET /health", "POST /webhooks/clerk"], + mapUser: (payload) => ({ + id: payload.sub, + email: payload.email, + }), + }), + configureApp: (app) => { + // ✅ Public (in publicRoutes) + app.get("/health", (c) => c.json({ status: "ok" })); + + // 🔒 Protected automatically (defaultPrivate: true) + app.get("/api/user/data", (c) => { + const user = c.get("authenticatedUser"); + return c.json({ user }); + }); + }, + }), }); + ``` - // Parent-child inheritance examples: - - // 1. Use supervisor's default maxSteps - const result1 = await supervisor.generateText("Create a blog post"); - // Supervisor uses: maxSteps: 15 - // SubAgents inherit: maxSteps: 15 + ### Default Behavior (Backward Compatible) - // 2. Override with API-level maxSteps - const result2 = await supervisor.generateText("Create a blog post", { - maxSteps: 8, // API-level override + ```typescript + // Without defaultPrivate, behavior is unchanged + auth: jwtAuth({ + secret: process.env.JWT_SECRET, + // defaultPrivate: false (default) }); - // Supervisor uses: maxSteps: 8 - // SubAgents inherit: maxSteps: 8 - // 3. Direct subagent calls use their own defaults - const directResult = await contentCreator.generateText("Create content"); - // Uses contentCreator's own maxSteps or default calculation + // Custom routes are public unless you add your own middleware + configureApp: (app) => { + app.get("/api/data", (c) => { + // This is PUBLIC by default + return c.json({ data: "anyone can access" }); + }); + }; ``` - **REST API Usage:** + ## Benefits + - ✅ **Fail-safe security**: Routes are protected by default when enabled + - ✅ **No manual middleware**: Custom endpoints automatically protected + - ✅ **Perfect for third-party auth**: Ideal for Clerk, Auth0, Supabase + - ✅ **Backward compatible**: No breaking changes, opt-in feature + - ✅ **Fine-grained control**: Use `publicRoutes` to selectively allow access - ```bash - # with generateText - curl -X POST http://localhost:3141/agents/my-agent-id/generate \ - -H "Content-Type: application/json" \ - -d '{ - "input": "Explain quantum physics", - "options": { - "maxSteps": 10, - } - }' +## 1.0.16 - # with streamText - curl -N -X POST http://localhost:3141/agents/supervisor-agent-id/stream \ - -H "Content-Type: application/json" \ - -d '{ - "input": "Coordinate research and writing workflow", - "options": { - "maxSteps": 15, - } - }' - ``` +### Patch Changes - This enhancement provides fine-grained control over agent computational resources while maintaining backward compatibility with existing agent configurations. +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` +- Updated dependencies [[`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e)]: + - @voltagent/internal@0.0.12 + - @voltagent/core@1.1.30 -## 0.1.51 +## 1.0.15 ### Patch Changes -- [#333](https://github.com/VoltAgent/voltagent/pull/333) [`721372a`](https://github.com/VoltAgent/voltagent/commit/721372a59edab1095ee608488ca96b81326fd1cc) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add abort signal support for operation cancellation - - **Abort Signal Support enables graceful cancellation of agent operations.** Users can now cancel expensive operations when they navigate away or change their minds. - - ## 🎯 Key Features - - **Stream API Cancellation**: `/stream` and `/stream-object` endpoints now handle client disconnection automatically - - **Agent Method Support**: All agent methods (`generateText`, `streamText`, `generateObject`, `streamObject`) support abort signals - - **SubAgent Propagation**: Abort signals cascade through sub-agent hierarchies +- [#637](https://github.com/VoltAgent/voltagent/pull/637) [`b7ee693`](https://github.com/VoltAgent/voltagent/commit/b7ee6936280b5d09b893db6500ad58b4ac80eaf2) Thanks [@marinoska](https://github.com/marinoska)! - - Introduced tests and documentation for the `ToolDeniedError`. + - Added a feature to terminate the process flow when the `onToolStart` hook triggers a `ToolDeniedError`. + - Enhanced error handling mechanisms to ensure proper flow termination in specific error scenarios. +- Updated dependencies [[`4c42bf7`](https://github.com/VoltAgent/voltagent/commit/4c42bf72834d3cd45ff5246ef65d7b08470d6a8e), [`b7ee693`](https://github.com/VoltAgent/voltagent/commit/b7ee6936280b5d09b893db6500ad58b4ac80eaf2)]: + - @voltagent/core@1.1.24 - ## 📋 Usage +## 1.0.14 - ```typescript - // Create AbortController - const abortController = new AbortController(); +### Patch Changes - // Cancel when user navigates away or clicks stop - window.addEventListener("beforeunload", () => abortController.abort()); +- [`ca6160a`](https://github.com/VoltAgent/voltagent/commit/ca6160a2f5098f296729dcd842a013558d14eeb8) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: updates endpoint - // Stream request with abort signal - const response = await fetch("http://localhost:3141/agents/my-agent/stream", { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({ - input: "Write a very long story...", - options: { maxTokens: 4000 }, - }), - signal: abortController.signal, // ✅ Automatic cancellation - }); +## 1.0.13 - // Manual cancellation after 10 seconds - setTimeout(() => abortController.abort(), 10000); - ``` +### Patch Changes - This prevents unnecessary computation and improves resource efficiency. +- [#629](https://github.com/VoltAgent/voltagent/pull/629) [`3e64b9c`](https://github.com/VoltAgent/voltagent/commit/3e64b9ce58d0e91bc272f491be2c1932a005ef48) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add memory observability -## 0.1.50 +## 1.0.12 ### Patch Changes -- [#329](https://github.com/VoltAgent/voltagent/pull/329) [`9406552`](https://github.com/VoltAgent/voltagent/commit/94065520f51a1743be91c3b5be9ab5370d47f666) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: userContext changes in onEnd hook now properly reflected in final response +- [#621](https://github.com/VoltAgent/voltagent/pull/621) [`f4fa7e2`](https://github.com/VoltAgent/voltagent/commit/f4fa7e297fec2f602c9a24a0c77e645aa971f2b9) Thanks [@omeraplak](https://github.com/omeraplak)! - ## @voltagent/core + - Folded the serverless runtime entry point into the main build – importing `@voltagent/core` now auto-detects the runtime and provisions either the Node or serverless observability pipeline. + - Rebuilt serverless observability on top of `BasicTracerProvider`, fetch-based OTLP exporters, and an execution-context `waitUntil` hook. Exports run with exponential backoff, never block the response, and automatically reuse VoltOps credentials (or fall back to the in-memory span/log store) so VoltOps Console transparently swaps to HTTP polling when WebSockets are unavailable. + - Hardened the runtime utilities for Workers/Functions: added universal `randomUUID`, base64, and event-emitter helpers, and taught the default logger to emit OpenTelemetry logs without relying on Node globals. This removes the last Node-only dependencies from the serverless bundle. - The `userContext` changes made in the `onEnd` hook were not being reflected in the final response from `.generateText()` and `.generateObject()` methods. This was because the userContext snapshot was taken before the `onEnd` hook execution, causing any modifications made within the hook to be lost. + ```ts + import { Agent, VoltAgent } from "@voltagent/core"; + import { serverlessHono } from "@voltagent/serverless-hono"; + import { openai } from "@ai-sdk/openai"; - **Before**: + import { weatherTool } from "./tools"; - ```typescript - const agent = new Agent({ - name: "TestAgent", - llm: new VercelAIProvider(), + const assistant = new Agent({ + name: "serverless-assistant", + instructions: "You are a helpful assistant.", model: openai("gpt-4o-mini"), - hooks: createHooks({ - onEnd: ({ context }) => { - // This change was lost in the final response - context.userContext.set("agent_response", "bye"); - }, - }), }); - const response = await agent.generateText("Hello", { - userContext: new Map([["agent_response", "hi"]]), + const voltAgent = new VoltAgent({ + agents: { assistant }, + serverless: serverlessHono(), }); - console.log(response.userContext?.get("agent_response")); // ❌ "hi" (old value) + export default voltAgent.serverless().toCloudflareWorker(); ``` - **After**: + ## @voltagent/serverless-hono + - Renamed the edge provider to **serverless** and upgraded it to power any fetch-based runtime (Cloudflare Workers, Vercel Edge Functions, Deno Deploy, Netlify Functions). + - Wrapped the Cloudflare adapter in a first-class `HonoServerlessProvider` that installs a scoped `waitUntil` bridge, reuses the shared routing layer, and exposes a `/ws` health stub so VoltOps Console can cleanly fall back to polling. + - Dropped the manual environment merge – Workers should now enable the `nodejs_compat_populate_process_env` flag (documented in the new deployment guide) instead of calling `mergeProcessEnv` themselves. - ```typescript - const agent = new Agent({ - name: "TestAgent", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - hooks: createHooks({ - onEnd: ({ context }) => { - // This change is now preserved in the final response - context.userContext.set("agent_response", "bye"); - }, - }), - }); + ## @voltagent/server-core + - Reworked the observability handlers around the shared storage API, including a new `POST /setup-observability` helper that writes VoltOps keys into `.env` and expanded trace/log queries that match the serverless storage contract. - const response = await agent.generateText("Hello", { - userContext: new Map([["agent_response", "hi"]]), - }); + ## @voltagent/cli + - Added `volt deploy --target ` to scaffold the right config files. The Cloudflare template now ships with the required compatibility flags (`nodejs_compat`, `nodejs_compat_populate_process_env`, `no_handle_cross_request_promise_resolution`) so new projects run on Workers without extra tweaking. - console.log(response.userContext?.get("agent_response")); // ✅ "bye" (updated value) - ``` +## 1.0.11 + +### Patch Changes + +- [`c738241`](https://github.com/VoltAgent/voltagent/commit/c738241fea017eeb3c6e3ceb27436ab2f027c48d) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: zod@4 swagger doc issue -## 0.1.49 +## 1.0.10 ### Patch Changes -- [#324](https://github.com/VoltAgent/voltagent/pull/324) [`8da1ecc`](https://github.com/VoltAgent/voltagent/commit/8da1eccd0332d1f9037085e16cb0b7d5afaac479) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add enterprise-grade VoltOps Prompt Management platform with team collaboration and analytics +- [#609](https://github.com/VoltAgent/voltagent/pull/609) [`942663f`](https://github.com/VoltAgent/voltagent/commit/942663f74dca0df70cdac323102acb18c050fa65) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add workflow cancellation support, including cancellation metadata, default controller updates, and a new API endpoint for cancelling executions - #608 - **VoltOps Prompt Management transforms VoltAgent from a simple framework into an enterprise-grade platform for managing AI prompts at scale.** Think "GitHub for prompts" with built-in team collaboration, version control, environment management, and performance analytics. + ## Usage Example - ## 🎯 What's New + ```ts + import { createSuspendController } from "@voltagent/core"; - **🚀 VoltOps Prompt Management Platform** - - **Team Collaboration**: Non-technical team members can edit prompts via web console - - **Version Control**: Full prompt versioning with commit messages and rollback capabilities - - **Environment Management**: Promote prompts from development → staging → production with labels - - **Template Variables**: Dynamic `{{variable}}` substitution with validation - - **Performance Analytics**: Track prompt effectiveness, costs, and usage patterns + const controller = createSuspendController(); + const stream = workflow.stream(input, { suspendController: controller }); - ## 📋 Usage Examples + // Cancel from application code + controller.cancel("User stopped the workflow"); - **Basic VoltOps Setup:** + // Or via HTTP + await fetch(`/api/workflows/${workflowId}/executions/${executionId}/cancel`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ reason: "User stopped the workflow" }), + }); + ``` - ```typescript - import { Agent, VoltAgent, VoltOpsClient } from "@voltagent/core"; - import { VercelAIProvider } from "@voltagent/vercel-ai"; - import { openai } from "@ai-sdk/openai"; +## 1.0.9 - // 1. Initialize VoltOps client - const voltOpsClient = new VoltOpsClient({ - publicKey: process.env.VOLTOPS_PUBLIC_KEY, - secretKey: process.env.VOLTOPS_SECRET_KEY, - }); +### Patch Changes - // 2. Create agent with VoltOps prompts - const supportAgent = new Agent({ +- [#596](https://github.com/VoltAgent/voltagent/pull/596) [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7) Thanks [@omeraplak](https://github.com/omeraplak)! - - add `@voltagent/a2a-server`, a JSON-RPC Agent-to-Agent (A2A) server that lets external agents call your VoltAgent instance over HTTP/SSE + - teach `@voltagent/core`, `@voltagent/server-core`, and `@voltagent/server-hono` to auto-register configured A2A servers so adding `{ a2aServers: { ... } }` on `VoltAgent` and opting into `honoServer` instantly exposes discovery and RPC endpoints + - forward request context (`userId`, `sessionId`, metadata) into agent invocations and provide task management hooks, plus allow filtering/augmenting exposed agents by default + - document the setup in `website/docs/agents/a2a/a2a-server.md` and refresh `examples/with-a2a-server` with basic usage and task-store customization + - A2A endpoints are now described in Swagger/OpenAPI and listed in the startup banner whenever an A2A server is registered, making discovery of `/.well-known/...` and `/a2a/:serverId` routes trivial. + + **Getting started** + + ```ts + import { Agent, VoltAgent } from "@voltagent/core"; + import { A2AServer } from "@voltagent/a2a-server"; + import { honoServer } from "@voltagent/server-hono"; + + const assistant = new Agent({ name: "SupportAgent", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - instructions: async ({ prompts }) => { - return await prompts.getPrompt({ - promptName: "customer-support-prompt", - label: process.env.NODE_ENV === "production" ? "production" : "development", - variables: { - companyName: "VoltAgent Corp", - tone: "friendly and professional", - supportLevel: "premium", - }, - }); - }, + purpose: "Handle support questions from partner agents.", + model: myModel, }); - // 3. Initialize VoltAgent with global VoltOps client - const voltAgent = new VoltAgent({ - agents: { supportAgent }, - voltOpsClient: voltOpsClient, + const a2aServer = new A2AServer({ + name: "support-agent", + version: "0.1.0", + }); + + export const voltAgent = new VoltAgent({ + agents: { assistant }, + a2aServers: { a2aServer }, + server: honoServer({ port: 3141 }), }); ``` -- [#324](https://github.com/VoltAgent/voltagent/pull/324) [`8da1ecc`](https://github.com/VoltAgent/voltagent/commit/8da1eccd0332d1f9037085e16cb0b7d5afaac479) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: introduce VoltOpsClient as unified replacement for deprecated telemetryExporter +- [#596](https://github.com/VoltAgent/voltagent/pull/596) [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7) Thanks [@omeraplak](https://github.com/omeraplak)! - ## ✨ New: first-class Model Context Protocol support - **VoltOpsClient** is the new unified platform client for VoltAgent that replaces the deprecated `telemetryExporter`. + We shipped a complete MCP integration stack: + - `@voltagent/mcp-server` exposes VoltAgent registries (agents, workflows, tools) over stdio/HTTP/SSE transports. + - `@voltagent/server-core` and `@voltagent/server-hono` gained ready-made route handlers so HTTP servers can proxy MCP traffic with a few lines of glue code. + - `@voltagent/core` exports the shared types that the MCP layers rely on. - ## 📋 Usage + ### Quick start - ```typescript - import { Agent, VoltAgent, VoltOpsClient } from "@voltagent/core"; + ```ts title="src/mcp/server.ts" + import { MCPServer } from "@voltagent/mcp-server"; + import { Agent, createTool } from "@voltagent/core"; + import { openai } from "@ai-sdk/openai"; + import { z } from "zod"; - const voltOpsClient = new VoltOpsClient({ - publicKey: process.env.VOLTOPS_PUBLIC_KEY, - secretKey: process.env.VOLTOPS_SECRET_KEY, - observability: true, // Enable observability - default is true - prompts: true, // Enable prompt management - default is true + const status = createTool({ + name: "status", + description: "Return the current time", + parameters: z.object({}), + async execute() { + return { status: "ok", time: new Date().toISOString() }; + }, }); - const voltAgent = new VoltAgent({ - agents: { myAgent }, - voltOpsClient: voltOpsClient, // ✅ New approach + const assistant = new Agent({ + name: "Support Agent", + instructions: "Route customer tickets to the correct queue.", + model: openai("gpt-4o-mini"), + tools: [status], + }); + + export const mcpServer = new MCPServer({ + name: "voltagent-example", + version: "0.1.0", + description: "Expose VoltAgent over MCP", + agents: { support: assistant }, + tools: { status }, + filterTools: ({ items }) => items.filter((tool) => tool.name !== "debug"), }); ``` - ## 🔄 Migration from telemetryExporter + With the server registered on your VoltAgent instance (and the Hono MCP routes enabled), the same agents, workflows, and tools become discoverable from VoltOps Console or any MCP-compatible IDE. - Replace the deprecated `telemetryExporter` with the new `VoltOpsClient`: +- [#596](https://github.com/VoltAgent/voltagent/pull/596) [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7) Thanks [@omeraplak](https://github.com/omeraplak)! - - Ship `@voltagent/mcp-server`, a transport-agnostic MCP provider that surfaces VoltAgent agents, workflows, tools, prompts, and resources over stdio, SSE, and HTTP. + - Wire MCP registration through `@voltagent/core`, `@voltagent/server-core`, and `@voltagent/server-hono` so a single `VoltAgent` constructor opt-in (optionally with `honoServer`) exposes stdio mode immediately and HTTP/SSE endpoints when desired. + - Filter child sub-agents automatically and lift an agent's `purpose` (fallback to `instructions`) into the MCP tool description for cleaner IDE listings out of the box. + - Document the workflow in `website/docs/agents/mcp/mcp-server.md` and refresh `examples/with-mcp-server` with stdio-only and HTTP/SSE configurations. + - When MCP is enabled we now publish REST endpoints in Swagger/OpenAPI and echo them in the startup banner so you can discover `/mcp/*` routes without digging through code. - ```diff + **Getting started** + + ```ts import { Agent, VoltAgent } from "@voltagent/core"; - - import { VoltAgentExporter } from "@voltagent/core"; - + import { VoltOpsClient } from "@voltagent/core"; + import { MCPServer } from "@voltagent/mcp-server"; + import { honoServer } from "@voltagent/server-hono"; - const voltAgent = new VoltAgent({ - agents: { myAgent }, - - telemetryExporter: new VoltAgentExporter({ - + voltOpsClient: new VoltOpsClient({ - publicKey: process.env.VOLTOPS_PUBLIC_KEY, - secretKey: process.env.VOLTOPS_SECRET_KEY, - - baseUrl: "https://api.voltagent.dev", - }), + const assistant = new Agent({ + name: "AssistantAgent", + purpose: "Respond to support questions and invoke helper tools when needed.", + model: myModel, }); - ``` - - ## ⚠️ Deprecation Notice - - `telemetryExporter` is now **deprecated** and will be removed in future versions: - ```typescript - // ❌ Deprecated - Don't use - new VoltAgent({ - agents: { myAgent }, - telemetryExporter: new VoltAgentExporter({...}), // Deprecated! + const mcpServer = new MCPServer({ + name: "support-mcp", + version: "1.0.0", + agents: { assistant }, + protocols: { stdio: true, http: false, sse: false }, }); - // ✅ Correct approach - new VoltAgent({ - agents: { myAgent }, - voltOpsClient: new VoltOpsClient({...}), + export const voltAgent = new VoltAgent({ + agents: { assistant }, + mcpServers: { primary: mcpServer }, + server: honoServer({ port: 3141 }), // flip http/sse to true when you need remote clients }); ``` - **For migration guide, see:** `/docs/observability/developer-console#migration-guide` +- Updated dependencies [[`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7), [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7)]: + - @voltagent/internal@0.0.11 - ## 🔧 Advanced Configuration +## 1.0.8 - ```typescript - const voltOpsClient = new VoltOpsClient({ - publicKey: process.env.VOLTOPS_PUBLIC_KEY, - secretKey: process.env.VOLTOPS_SECRET_KEY, - baseUrl: "https://api.voltagent.dev", // Default - observability: true, // Enable observability export - default is true - prompts: false, // Observability only - default is true - promptCache: { - enabled: true, // Enable prompt cache - default is true - ttl: 300, // 5 minute cache - default is 300 - maxSize: 100, // Max size of the cache - default is 100 - }, - }); - ``` +### Patch Changes -- Updated dependencies [[`8da1ecc`](https://github.com/VoltAgent/voltagent/commit/8da1eccd0332d1f9037085e16cb0b7d5afaac479)]: - - @voltagent/internal@0.0.4 +- [#581](https://github.com/VoltAgent/voltagent/pull/581) [`05ddac1`](https://github.com/VoltAgent/voltagent/commit/05ddac1ac9404cd6062d2e448b0ce4df90ecd748) Thanks [@wayneg123](https://github.com/wayneg123)! - fix(server-core): add missing /chat endpoint to protected routes for JWT auth -## 0.1.48 + The /agents/:id/chat endpoint was missing from PROTECTED_ROUTES, causing it to bypass JWT authentication while other execution endpoints (/text, /stream, /object, /stream-object) correctly required authentication. -### Patch Changes + This fix ensures all agent execution endpoints consistently require JWT authentication when jwtAuth is configured. -- [#296](https://github.com/VoltAgent/voltagent/pull/296) [`4621e09`](https://github.com/VoltAgent/voltagent/commit/4621e09118fc652d8a05f40758b02d5108e38967) Thanks [@Ajay-Satish-01](https://github.com/Ajay-Satish-01)! - The `UserContext` was properly propagated through tools and hooks, but was not being returned in the final response from `.generateText()` and `.generateObject()` methods. This prevented post-processing logic from accessing the UserContext data. + Fixes authentication bypass vulnerability on chat endpoint. - **Before**: +- [`9cc4ea4`](https://github.com/VoltAgent/voltagent/commit/9cc4ea4a4985320139e33e8029f299c7ec8329a6) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: @voltagent/core peerDependency version - ```typescript - const result = await agent.generateText(...); +## 1.0.7 - result.userContext; // ❌ Missing userContext - ``` +### Patch Changes - **After**: +- [#571](https://github.com/VoltAgent/voltagent/pull/571) [`b801a8d`](https://github.com/VoltAgent/voltagent/commit/b801a8da47da5cad15b8637635f83acab5e0d6fc) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Zod v4 support (backwards-compatible with v3) - ```typescript - const result = await agent.generateText(...); + What’s new + - Core + server now support `zod` v4 while keeping v3 working. + - Peer ranges expanded to `"zod": "^3.25.0 || ^4.0.0"`. + - JSON Schema → Zod conversion handles both versions: + - Uses `zod-from-json-schema@^0.5.0` when Zod v4 is detected. + - Falls back to `zod-from-json-schema@^0.0.5` via alias `zod-from-json-schema-v3` for Zod v3. + - Implemented in MCP client (core) and object handlers (server-core). - return result.userContext; // ✅ Includes userContext + Why + - Zod v4 introduces changes that require a version-aware conversion path. This update adds seamless compatibility for both major versions. - **How users can see the changes**: + Impact + - No breaking changes. Projects on Zod v3 continue to work unchanged. Projects can upgrade to Zod v4 without code changes. - Now users can access the `userContext` in the response from all agent methods: + Notes + - If your bundler disallows npm aliasing, ensure it can resolve `zod-from-json-schema-v3` (alias to `zod-from-json-schema@^0.0.5`). - // Set custom context before calling the agent - const customContext = new Map(); - customContext.set("sessionId", "user-123"); - customContext.set("requestId", "req-456"); +## 1.0.7-next.1 - // generateText now returns userContext - const result = await agent.generateText("Hello", { - userContext: customContext, - }); +### Patch Changes - // Access the userContext from the response - console.log(result.userContext.get("sessionId")); // 'user-123' - console.log(result.userContext.get("requestId")); // 'req-456' +- [`78a5046`](https://github.com/VoltAgent/voltagent/commit/78a5046ca4d768a96650ebee63ae1630b0dff7a7) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Zod v4 support (backwards-compatible with v3) - // GenerateObject - const objectResult = await agent.generateObject("Create a summary", schema, { - userContext: customContext, - }); - console.log(objectResult.userContext.get("sessionId")); // 'user-123' + What’s new + - Core + server now support `zod` v4 while keeping v3 working. + - Peer ranges expanded to `"zod": "^3.25.0 || ^4.0.0"`. + - JSON Schema → Zod conversion handles both versions: + - Uses `zod-from-json-schema@^0.5.0` when Zod v4 is detected. + - Falls back to `zod-from-json-schema@^0.0.5` via alias `zod-from-json-schema-v3` for Zod v3. + - Implemented in MCP client (core) and object handlers (server-core). - // Streaming methods - const streamResult = await agent.streamText("Hello", { - userContext: customContext, - }); - console.log(streamResult.userContext?.get("sessionId")); // 'user-123' - ``` + Why + - Zod v4 introduces changes that require a version-aware conversion path. This update adds seamless compatibility for both major versions. - Fixes: [#283](https://github.com/VoltAgent/voltagent/issues/283) + Impact + - No breaking changes. Projects on Zod v3 continue to work unchanged. Projects can upgrade to Zod v4 without code changes. -## 0.1.47 + Notes + - If your bundler disallows npm aliasing, ensure it can resolve `zod-from-json-schema-v3` (alias to `zod-from-json-schema@^0.0.5`). + +## 1.0.7-next.0 ### Patch Changes -- [#311](https://github.com/VoltAgent/voltagent/pull/311) [`1f7fa14`](https://github.com/VoltAgent/voltagent/commit/1f7fa140fcc4062fe85220e61f276e439392b0b4) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix(core, vercel-ui): Currently the `convertToUIMessages` function does not handle tool calls in steps correctly as it does not properly default filter non-tool related steps for sub-agents, same as the `data-stream` functions and in addition in the core the `operationContext` does not have the `subAgent` fields set correctly. +- [#551](https://github.com/VoltAgent/voltagent/pull/551) [`77a3f64`](https://github.com/VoltAgent/voltagent/commit/77a3f64dea6e8a06fbbd72878711efa9ceb90bc3) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Zod v4 support (backwards-compatible with v3) - ### Changes - - deprecated `isSubAgentStreamPart` in favor of `isSubAgent` for universal use - - by default `convertToUIMessages` now filters out non-tool related steps for sub-agents - - now able to exclude specific parts or steps (from OperationContext) in `convertToUIMessages` + What’s new + - Core + server now support `zod` v4 while keeping v3 working. + - Peer ranges expanded to `"zod": "^3.25.0 || ^4.0.0"`. + - JSON Schema → Zod conversion handles both versions: + - Uses `zod-from-json-schema@^0.5.0` when Zod v4 is detected. + - Falls back to `zod-from-json-schema@^0.0.5` via alias `zod-from-json-schema-v3` for Zod v3. + - Implemented in MCP client (core) and object handlers (server-core). - *** + Why + - Zod v4 introduces changes that require a version-aware conversion path. This update adds seamless compatibility for both major versions. - ### Internals + Impact + - No breaking changes. Projects on Zod v3 continue to work unchanged. Projects can upgrade to Zod v4 without code changes. - New utils were added to the internal package: - - `isObject` - - `isFunction` - - `isPlainObject` - - `isEmptyObject` - - `isNil` - - `hasKey` + Notes + - If your bundler disallows npm aliasing, ensure it can resolve `zod-from-json-schema-v3` (alias to `zod-from-json-schema@^0.0.5`). -- Updated dependencies [[`1f7fa14`](https://github.com/VoltAgent/voltagent/commit/1f7fa140fcc4062fe85220e61f276e439392b0b4)]: - - @voltagent/internal@0.0.3 +- Updated dependencies [[`77a3f64`](https://github.com/VoltAgent/voltagent/commit/77a3f64dea6e8a06fbbd72878711efa9ceb90bc3)]: + - @voltagent/core@1.1.7-next.0 -## 0.1.46 +## 1.0.6 ### Patch Changes -- [#309](https://github.com/VoltAgent/voltagent/pull/309) [`b81a6b0`](https://github.com/VoltAgent/voltagent/commit/b81a6b09c33d95f7e586501cc058ae8381c854c4) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix(core): Default to filtering `error` types from the `fullStream` to allow for error handling to happen properly +- [#562](https://github.com/VoltAgent/voltagent/pull/562) [`2886b7a`](https://github.com/VoltAgent/voltagent/commit/2886b7aab5bda296cebc0b8b2bd56d684324d799) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: using `safeStringify` instead of `JSON.stringify` -## 0.1.45 +## 1.0.5 ### Patch Changes -- [#308](https://github.com/VoltAgent/voltagent/pull/308) [`33afe6e`](https://github.com/VoltAgent/voltagent/commit/33afe6ef40ef56c501f7fa69be42da730f87d29d) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: subAgents now share conversation steps and context with parent agents +- Updated dependencies [[`134bf9a`](https://github.com/VoltAgent/voltagent/commit/134bf9a2978f0b069f842910fb4fb3e969f70390)]: + - @voltagent/internal@0.0.10 - SubAgents automatically inherit and contribute to their parent agent's operation context, including `userContext` and conversation history. This creates a unified workflow where all agents (supervisor + subagents) add steps to the same `conversationSteps` array, providing complete visibility and traceability across the entire agent hierarchy. +## 1.0.4 - ## Usage +### Patch Changes + +- [`78658de`](https://github.com/VoltAgent/voltagent/commit/78658de30e71c586df7391d52b4fe657fe4dc2b0) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add ModelMessage format support to server API endpoints + + Server endpoints now accept ModelMessage format (messages with `role` and `content` fields) in addition to UIMessage format and plain strings. This allows clients to send messages in either format: + - **String**: Direct text input + - **UIMessage[]**: AI SDK UIMessage format with `parts` structure + - **ModelMessage[]**: AI SDK ModelMessage format with `role` and `content` structure + + The change adopts a flexible validation, where the server handlers pass input directly to agents which handle the conversion. API schemas and documentation have been updated to reflect this support. + + Example: ```typescript - import { Agent, createHooks } from "@voltagent/core"; - import { VercelAIProvider } from "@voltagent/vercel-ai"; - import { openai } from "@ai-sdk/openai"; + // All three formats are now supported + await fetch("/agents/assistant/text", { + method: "POST", + body: JSON.stringify({ + // Option 1: String + input: "Hello", - // SubAgent automatically receives parent's context - const translatorAgent = new Agent({ - name: "Translator Agent", - hooks: createHooks({ - onStart: ({ context }) => { - // Access parent's userContext automatically - const projectId = context.userContext.get("projectId"); - const language = context.userContext.get("language"); - console.log(`Translating for project ${projectId} to ${language}`); - }, + // Option 2: UIMessage format + input: [{ role: "user", parts: [{ type: "text", text: "Hello" }] }], + + // Option 3: ModelMessage format + input: [{ role: "user", content: "Hello" }], }), - instructions: "You are a skilled translator", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), }); + ``` - // Supervisor agent with context - const supervisorAgent = new Agent({ - name: "Supervisor Agent", - subAgents: [translatorAgent], - hooks: createHooks({ - onEnd: ({ context }) => { - // Access complete workflow history from all agents - const allSteps = context.conversationSteps; - console.log(`Total workflow steps: ${allSteps.length}`); - // Includes supervisor's delegate_task calls + subagent's processing steps +## 1.0.3 + +### Patch Changes + +- [`3177a60`](https://github.com/VoltAgent/voltagent/commit/3177a60a2632c200150e8a71d706b44df508cc66) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: version bump + +## 2.0.0 + +### Patch Changes + +- Updated dependencies [[`63d4787`](https://github.com/VoltAgent/voltagent/commit/63d4787bd92135fa2d6edffb3b610889ddc0e3f5)]: + - @voltagent/core@1.1.0 + +## 1.0.2 + +### Patch Changes + +- [`c27b260`](https://github.com/VoltAgent/voltagent/commit/c27b260bfca007da5201eb2967e089790cab3b97) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: zod dependency moved from dependencies to devDependencies + +## 1.0.1 + +### Patch Changes + +- [#545](https://github.com/VoltAgent/voltagent/pull/545) [`5d7c8e7`](https://github.com/VoltAgent/voltagent/commit/5d7c8e7f3898fe84066d0dd9be7f573fca66f185) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve EADDRINUSE error on server startup by fixing race condition in port availability check - #544 + + Fixed a critical issue where users would encounter "EADDRINUSE: address already in use" errors when starting VoltAgent servers. The problem was caused by a race condition in the port availability check where the test server wasn't fully closed before the actual server tried to bind to the same port. + + ## What was happening + + When checking if a port was available, the port manager would: + 1. Create a test server and bind to the port + 2. On successful binding, immediately close the server + 3. Return `true` indicating the port was available + 4. But the test server wasn't fully closed yet when `serve()` tried to bind to the same port + + ## The fix + + Modified the port availability check in `port-manager.ts` to: + - Wait for the server's close callback before returning + - Add a small delay (50ms) to ensure the OS has fully released the port + - This prevents the race condition between test server closure and actual server startup + + ## Changes + - **port-manager.ts**: Fixed race condition by properly waiting for test server to close + - **hono-server-provider.ts**: Added proper error handling for server startup failures + + This ensures reliable server startup without port conflicts. + +- [#546](https://github.com/VoltAgent/voltagent/pull/546) [`f12f344`](https://github.com/VoltAgent/voltagent/commit/f12f34405edf0fcb417ed098deba62570260fb81) Thanks [@omeraplak](https://github.com/omeraplak)! - chore: align Zod to ^3.25.76 and fix type mismatch with AI SDK + + We aligned Zod versions across packages to `^3.25.76` to match AI SDK peer ranges and avoid multiple Zod instances at runtime. + + Why this matters + - Fixes TypeScript narrowing issues in workflows when consuming `@voltagent/core` from npm with a different Zod instance (e.g., `ai` packages pulling newer Zod). + - Prevents errors like "Spread types may only be created from object types" where `data` failed to narrow because `z.ZodTypeAny` checks saw different Zod identities. + + What changed + - `@voltagent/server-core`, `@voltagent/server-hono`: dependencies.zod → `^3.25.76`. + - `@voltagent/docs-mcp`, `@voltagent/core`: devDependencies.zod → `^3.25.76`. + - Examples and templates updated to use `^3.25.76` for consistency (non-publishable). + + Notes for consumers + - Ensure a single Zod version is installed (consider a workspace override to pin Zod to `3.25.76`). + - This improves compatibility with `ai@5.x` packages that require `zod@^3.25.76 || ^4`. + +- Updated dependencies [[`f12f344`](https://github.com/VoltAgent/voltagent/commit/f12f34405edf0fcb417ed098deba62570260fb81)]: + - @voltagent/core@1.0.1 + +## 1.0.0 + +### Major Changes + +- [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93) Thanks [@omeraplak](https://github.com/omeraplak)! - # Server Core 1.x — typed routes, schemas, utilities + + Server functionality lives outside core. Use `@voltagent/server-core` types/schemas with `@voltagent/server-hono`. + + Full migration guide: [Migration Guide](https://voltagent.dev/docs/getting-started/migration-guide/) + + ## Example: extend the app + + ```ts + import { VoltAgent } from "@voltagent/core"; + import { honoServer } from "@voltagent/server-hono"; + import { AgentRoutes } from "@voltagent/server-core"; // typed route defs (optional) + + new VoltAgent({ + agents: { agent }, + server: honoServer({ + configureApp: (app) => { + // Add custom endpoints alongside the built‑ins + app.get("/api/health", (c) => c.json({ status: "ok" })); }, }), - instructions: "Coordinate translation workflow", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), }); + ``` - // Usage - context automatically flows to subagents - const response = await supervisorAgent.streamText("Translate this text", { - userContext: new Map([ - ["projectId", "proj-123"], - ["language", "Spanish"], - ]), - }); +### Patch Changes - // Final context includes data from both supervisor and subagents - console.log("Project:", response.userContext?.get("projectId")); - ``` +- Updated dependencies [[`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93)]: + - @voltagent/core@1.0.0 -- [#306](https://github.com/VoltAgent/voltagent/pull/306) [`b8529b5`](https://github.com/VoltAgent/voltagent/commit/b8529b53313fa97e941ecacb8c1555205de49c19) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix(core): Revert original fix by @omeraplak to pass the task role as "user" instead of prompt to prevent errors in providers such as Anthropic, Grok, etc. +## 1.0.0-next.2 -## 0.1.44 +### Major Changes + +- [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93) Thanks [@omeraplak](https://github.com/omeraplak)! - # Server Core 1.x — typed routes, schemas, utilities + + Server functionality lives outside core. Use `@voltagent/server-core` types/schemas with `@voltagent/server-hono`. + + Full migration guide: [Migration Guide](https://voltagent.dev/docs/getting-started/migration-guide/) + + ## Example: extend the app + + ```ts + import { VoltAgent } from "@voltagent/core"; + import { honoServer } from "@voltagent/server-hono"; + import { AgentRoutes } from "@voltagent/server-core"; // typed route defs (optional) + + new VoltAgent({ + agents: { agent }, + server: honoServer({ + configureApp: (app) => { + // Add custom endpoints alongside the built‑ins + app.get("/api/health", (c) => c.json({ status: "ok" })); + }, + }), + }); + ``` ### Patch Changes -- Updated dependencies [[`94de46a`](https://github.com/VoltAgent/voltagent/commit/94de46ab2b7ccead47a539e93c72b357f17168f6)]: - - @voltagent/internal@0.0.2 +- Updated dependencies [[`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93)]: + - @voltagent/core@1.0.0-next.2 -## 0.1.43 +## 1.0.0-next.1 ### Patch Changes -- [#287](https://github.com/VoltAgent/voltagent/pull/287) [`4136a9b`](https://github.com/VoltAgent/voltagent/commit/4136a9bd1a2f687bf009858dda4e56a50574c9c2) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: optimize streamText/generateText/genereteObject/streamObject performance with background event publishing and memory operations +- Updated dependencies [[`e86cadb`](https://github.com/VoltAgent/voltagent/commit/e86cadb5ae9ee9719bfd1f12e7116d95224699ce), [`e86cadb`](https://github.com/VoltAgent/voltagent/commit/e86cadb5ae9ee9719bfd1f12e7116d95224699ce)]: + - @voltagent/core@1.0.0-next.1 - Significantly improved agent response times by optimizing blocking operations during stream initialization. Stream start time reduced by 70-80% while maintaining full conversation context quality. +--- - ## What's Fixed - - **Background Event Publishing**: Timeline events now publish asynchronously, eliminating blocking delays - - **Memory Operations**: Context loading optimized with background conversation setup and input saving +## Package: @voltagent/server-elysia + +## 2.0.0 + +### Major Changes + +- [#898](https://github.com/VoltAgent/voltagent/pull/898) [`b322cf4`](https://github.com/VoltAgent/voltagent/commit/b322cf4c511c64872c178e51f9ddccb869385dee) Thanks [@MGrin](https://github.com/MGrin)! - feat: Initial release of @voltagent/server-elysia + + # @voltagent/server-elysia + + ## 1.0.0 + + ### Major Changes + - Initial release of Elysia server implementation for VoltAgent + - Full feature parity with server-hono including: + - Agent execution endpoints (text, stream, chat, object) + - Workflow execution and lifecycle management + - Tool execution and discovery + - MCP (Model Context Protocol) support + - A2A (Agent-to-Agent) communication + - Observability and tracing + - Logging endpoints + - Authentication with authNext support + - Custom endpoint configuration + - CORS configuration + - WebSocket support + + ### Features + - **High Performance**: Built on Elysia, optimized for speed and low latency + - **Type Safety**: Full TypeScript support with strict typing + - **Flexible Configuration**: Support for both `configureApp` and `configureFullApp` patterns + - **Auth Support**: JWT authentication with public route configuration via `authNext` + - **Extensible**: Easy to add custom routes, middleware, and plugins + - **OpenAPI/Swagger**: Built-in API documentation via @elysiajs/swagger + - **MCP Support**: Full Model Context Protocol implementation with SSE streaming + - **WebSocket Support**: Real-time updates and streaming capabilities + + ### Dependencies + - `@voltagent/core`: ^1.5.1 + - `@voltagent/server-core`: ^1.0.36 + - `@voltagent/mcp-server`: ^1.0.3 + - `@voltagent/a2a-server`: ^1.0.2 + - `elysia`: ^1.1.29 + + ### Peer Dependencies + - `@voltagent/core`: ^1.x + - `elysia`: ^1.x - ## Performance Impact - - Stream initialization: ~300-500ms → ~150-200ms - - 70-80% faster response start times - - Zero impact on conversation quality or history tracking +### Patch Changes - Perfect for production applications requiring fast AI interactions. +- Updated dependencies [[`b322cf4`](https://github.com/VoltAgent/voltagent/commit/b322cf4c511c64872c178e51f9ddccb869385dee)]: + - @voltagent/server-core@2.1.0 -- [#287](https://github.com/VoltAgent/voltagent/pull/287) [`4136a9b`](https://github.com/VoltAgent/voltagent/commit/4136a9bd1a2f687bf009858dda4e56a50574c9c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add `deepClone` function to `object-utils` module +--- - Added a new `deepClone` utility function to the object-utils module for creating deep copies of complex JavaScript objects. This utility provides safe cloning of nested objects, arrays, and primitive values while handling circular references and special object types. +## Package: @voltagent/server-hono - Usage: +## 2.0.3 - ```typescript - import { deepClone } from "@voltagent/core/utils/object-utils"; +### Patch Changes - const original = { - nested: { - array: [1, 2, { deep: "value" }], - date: new Date(), - }, - }; +- [#921](https://github.com/VoltAgent/voltagent/pull/921) [`c4591fa`](https://github.com/VoltAgent/voltagent/commit/c4591fa92de6df75a22a758b0232669053bd2b62) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add resumable streaming support via @voltagent/resumable-streams, with server adapters that let clients reconnect to in-flight streams. - const cloned = deepClone(original); - // cloned is completely independent from original - ``` + ```ts + import { openai } from "@ai-sdk/openai"; + import { Agent, VoltAgent } from "@voltagent/core"; + import { + createResumableStreamAdapter, + createResumableStreamRedisStore, + } from "@voltagent/resumable-streams"; + import { honoServer } from "@voltagent/server-hono"; - This utility is particularly useful for agent state management, configuration cloning, and preventing unintended mutations in complex data structures. + const streamStore = await createResumableStreamRedisStore(); + const resumableStream = await createResumableStreamAdapter({ streamStore }); -- [#287](https://github.com/VoltAgent/voltagent/pull/287) [`4136a9b`](https://github.com/VoltAgent/voltagent/commit/4136a9bd1a2f687bf009858dda4e56a50574c9c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: optimize performance with new `BackgroundQueue` utility class and non-blocking background operations + const agent = new Agent({ + id: "assistant", + name: "Resumable Stream Agent", + instructions: "You are a helpful assistant.", + model: openai("gpt-4o-mini"), + }); - Added a new `BackgroundQueue` utility class for managing background operations with enhanced reliability, performance, and order preservation. Significantly improved agent response times by optimizing blocking operations during stream initialization and agent interactions. + new VoltAgent({ + agents: { assistant: agent }, + server: honoServer({ + resumableStream: { adapter: resumableStream }, + }), + }); - ## Performance Improvements + await fetch("http://localhost:3141/agents/assistant/chat", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: `{"input":"Hello!","options":{"conversationId":"conv-1","userId":"user-1","resumableStream":true}}`, + }); - **All blocking operations have been moved to background jobs**, resulting in significant performance gains: - - **Agent execution is no longer blocked** by history persistence, memory operations, or telemetry exports - - **3-5x faster response times** for agent interactions due to non-blocking background processing - - **Zero blocking delays** during agent conversations and tool executions + // Resume the same stream after reconnect/refresh + const resumeResponse = await fetch( + "http://localhost:3141/agents/assistant/chat/conv-1/stream?userId=user-1" + ); - ## Stream Operations Optimized - - **Background Event Publishing**: Timeline events now publish asynchronously, eliminating blocking delays - - **Memory Operations**: Context loading optimized with background conversation setup and input saving - - **Stream initialization**: ~300-500ms → ~150-200ms (70-80% faster response start times) - - **Zero impact on conversation quality or history tracking** + const reader = resumeResponse.body?.getReader(); + const decoder = new TextDecoder(); + while (reader) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value, { stream: true }); + console.log(chunk); + } + ``` - Perfect for production applications requiring fast AI interactions with enhanced reliability and order preservation. + AI SDK client (resume on refresh): -## 0.1.42 + ```tsx + import { useChat } from "@ai-sdk/react"; + import { DefaultChatTransport } from "ai"; + + const { messages, sendMessage } = useChat({ + id: chatId, + messages: initialMessages, + resume: true, + transport: new DefaultChatTransport({ + api: "/api/chat", + prepareSendMessagesRequest: ({ id, messages }) => ({ + body: { + message: messages[messages.length - 1], + options: { conversationId: id, userId }, + }, + }), + prepareReconnectToStreamRequest: ({ id }) => ({ + api: `/api/chat/${id}/stream?userId=${encodeURIComponent(userId)}`, + }), + }), + }); + ``` + +- Updated dependencies [[`c4591fa`](https://github.com/VoltAgent/voltagent/commit/c4591fa92de6df75a22a758b0232669053bd2b62)]: + - @voltagent/resumable-streams@2.0.1 + - @voltagent/server-core@2.1.2 + - @voltagent/core@2.0.7 + +## 2.0.2 ### Patch Changes -- [#286](https://github.com/VoltAgent/voltagent/pull/286) [`73632ea`](https://github.com/VoltAgent/voltagent/commit/73632ea229917ab4042bb58b61d5e6dbd9b72804) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - Fixed issue where fullStream processing was erroring due to inability to access a Nil value +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) -## 0.1.41 + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. -### Patch Changes + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` -- [`7705108`](https://github.com/VoltAgent/voltagent/commit/7705108317a8166bb1324838f99691ad8879b94d) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: reverted subagent handoff message role from `user` back to `system`. + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ -## 0.1.40 +- Updated dependencies [[`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505)]: + - @voltagent/a2a-server@2.0.2 + - @voltagent/core@2.0.2 + - @voltagent/internal@1.0.2 + - @voltagent/mcp-server@2.0.2 + - @voltagent/server-core@2.0.2 -### Patch Changes +## 2.0.1 -- [#284](https://github.com/VoltAgent/voltagent/pull/284) [`003ea5e`](https://github.com/VoltAgent/voltagent/commit/003ea5e0aab1e3e4a1398ed5ebf54b20fc9e27f3) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: subagent task delegation system message handling for Google Gemini compatibility +### Patch Changes - Fixed an issue where subagent task delegation was sending tasks as system messages, which caused errors with certain AI models like Google Gemini that have strict system message requirements. The task delegation now properly sends tasks as user messages instead of system messages. +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) - This change improves compatibility across different AI providers, particularly Google Gemini, which expects a specific system message format and doesn't handle multiple or dynamic system messages well during task delegation workflows. + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. -- [#284](https://github.com/VoltAgent/voltagent/pull/284) [`003ea5e`](https://github.com/VoltAgent/voltagent/commit/003ea5e0aab1e3e4a1398ed5ebf54b20fc9e27f3) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: userContext reference preservation in agent history initialization + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` -## 0.1.39 + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ -### Patch Changes +- Updated dependencies [[`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2)]: + - @voltagent/a2a-server@2.0.1 + - @voltagent/core@2.0.1 + - @voltagent/internal@1.0.1 + - @voltagent/mcp-server@2.0.1 + - @voltagent/server-core@2.0.1 -- [#276](https://github.com/VoltAgent/voltagent/pull/276) [`937ccf8`](https://github.com/VoltAgent/voltagent/commit/937ccf8bf84a4261ee9ed2c94aab9f8c49ab69bd) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add dynamic agent parameters with userContext support - #272 +## 2.0.0 - Added dynamic agent parameters functionality that allows agents to adapt their behavior, models, and tools based on runtime context. This enables personalized, multi-tenant, and role-based AI experiences. +### Major Changes - ## Features - - **Dynamic Instructions**: Agent instructions that change based on user context - - **Dynamic Models**: Different AI models based on subscription tiers or user roles - - **Dynamic Tools**: Role-based tool access and permissions - - **REST API Integration**: Full userContext support via REST endpoints - - **VoltOps Integration**: Visual testing interface for dynamic agents +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) - ## Usage + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. - ```typescript - import { Agent } from "@voltagent/core"; - import { VercelAIProvider } from "@voltagent/vercel-ai"; - import { openai } from "@ai-sdk/openai"; + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` - const dynamicAgent = new Agent({ - name: "Adaptive Assistant", + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ - // Dynamic instructions based on user context - instructions: ({ userContext }) => { - const role = (userContext.get("role") as string) || "user"; - const language = (userContext.get("language") as string) || "English"; +### Patch Changes - if (role === "admin") { - return `You are an admin assistant with special privileges. Respond in ${language}.`; - } else { - return `You are a helpful assistant. Respond in ${language}.`; - } - }, +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/server-core@2.0.0 + - @voltagent/core@2.0.0 + - @voltagent/a2a-server@2.0.0 + - @voltagent/internal@1.0.0 + - @voltagent/mcp-server@2.0.0 - // Dynamic model selection based on subscription tier - model: ({ userContext }) => { - const tier = (userContext.get("tier") as string) || "free"; +## 1.2.11 - switch (tier) { - case "premium": - return openai("gpt-4o"); - case "pro": - return openai("gpt-4o-mini"); - default: - return openai("gpt-3.5-turbo"); - } - }, +### Patch Changes - // Dynamic tools based on user role - tools: ({ userContext }) => { - const role = (userContext.get("role") as string) || "user"; +- [#883](https://github.com/VoltAgent/voltagent/pull/883) [`9320326`](https://github.com/VoltAgent/voltagent/commit/93203262bf3ebcbc38fe4663c4b0cea27dd9ea16) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add authNext and deprecate legacy auth - if (role === "admin") { - return [basicTool, adminTool]; - } else { - return [basicTool]; - } - }, + Add a new `authNext` policy that splits routes into public, console, and user access. All routes are protected by default; use `publicRoutes` to opt out. - llm: new VercelAIProvider(), - }); + AuthNext example: - // Usage with userContext - const userContext = new Map([ - ["role", "admin"], - ["language", "Spanish"], - ["tier", "premium"], - ]); + ```ts + import { jwtAuth } from "@voltagent/server-core"; + import { honoServer } from "@voltagent/server-hono"; - const response = await dynamicAgent.generateText("Help me manage the system", { userContext }); + const server = honoServer({ + authNext: { + provider: jwtAuth({ secret: process.env.JWT_SECRET! }), + publicRoutes: ["GET /health"], + }, + }); ``` - ## REST API Integration + Behavior summary: + - When `authNext` is set, all routes are private by default. + - Console endpoints (agents, workflows, tools, docs, observability, updates) require a Console Access Key. + - Execution endpoints require a user token (JWT). - Dynamic agents work seamlessly with REST API endpoints: + Console access uses `VOLTAGENT_CONSOLE_ACCESS_KEY`: ```bash - # POST /agents/my-agent/text - curl -X POST http://localhost:3141/agents/my-agent/text \ - -H "Content-Type: application/json" \ - -d '{ - "input": "I need admin access", - "options": { - "userContext": { - "role": "admin", - "language": "Spanish", - "tier": "premium" - } - } - }' + VOLTAGENT_CONSOLE_ACCESS_KEY=your-console-key ``` - Perfect for multi-tenant applications, role-based access control, subscription tiers, internationalization, and A/B testing scenarios. - -## 0.1.38 - -### Patch Changes + ```bash + curl http://localhost:3141/agents \ + -H "x-console-access-key: your-console-key" + ``` -- [#267](https://github.com/VoltAgent/voltagent/pull/267) [`f7e5a34`](https://github.com/VoltAgent/voltagent/commit/f7e5a344a5bcb63d1a225e580f01dfa5886b6a01) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: subagent event ordering and stream injection + Legacy `auth` remains supported but is deprecated. Use `authNext` for new integrations. - Fixed an issue where subagent events were not being properly included in the main agent's stream before subagent completion. Previously, subagent events (text-delta, tool-call, tool-result, etc.) would sometimes miss being included in the parent agent's real-time stream, causing incomplete event visibility for monitoring and debugging. +- Updated dependencies [[`9320326`](https://github.com/VoltAgent/voltagent/commit/93203262bf3ebcbc38fe4663c4b0cea27dd9ea16)]: + - @voltagent/server-core@1.0.36 -## 0.1.37 +## 1.2.10 ### Patch Changes -- [#252](https://github.com/VoltAgent/voltagent/pull/252) [`88f2d06`](https://github.com/VoltAgent/voltagent/commit/88f2d0682413d27a7ac2d1d8cd502fd9c665e547) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add userId and conversationId support to agent history tables +- [`b663dce`](https://github.com/VoltAgent/voltagent/commit/b663dceb57542d1b85475777f32ceb3671cc1237) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: dedupe MCP endpoints in server startup output and include MCP transport paths (streamable HTTP/SSE) so the actual server endpoint is visible. - This release adds comprehensive support for `userId` and `conversationId` fields in agent history tables across all memory storage implementations, enabling better conversation tracking and user-specific history management. +- Updated dependencies [[`b663dce`](https://github.com/VoltAgent/voltagent/commit/b663dceb57542d1b85475777f32ceb3671cc1237)]: + - @voltagent/server-core@1.0.35 + - @voltagent/core@1.5.1 - ### New Features - - **Agent History Enhancement**: Added `userId` and `conversationId` columns to agent history tables - - **Cross-Implementation Support**: Consistent implementation across PostgreSQL, Supabase, LibSQL, and In-Memory storage - - **Automatic Migration**: Safe schema migrations for existing installations - - **Backward Compatibility**: Existing history entries remain functional +## 1.2.9 - ### Migration Notes +### Patch Changes - **PostgreSQL & Supabase**: Automatic schema migration with user-friendly SQL scripts - **LibSQL**: Seamless column addition with proper indexing - **In-Memory**: No migration required, immediate support +- [`37be1ed`](https://github.com/VoltAgent/voltagent/commit/37be1ed67f833add6a3cce5cb47a8f0774236956) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: bump @voltagent/server-core dep - ### Technical Details - - **Database Schema**: Added `userid TEXT` and `conversationid TEXT` columns (PostgreSQL uses lowercase) - - **Indexing**: Performance-optimized indexes for new columns - - **Migration Safety**: Non-destructive migrations with proper error handling - - **API Consistency**: Unified interface across all storage implementations +## 1.2.8 -- [#261](https://github.com/VoltAgent/voltagent/pull/261) [`b63fe67`](https://github.com/VoltAgent/voltagent/commit/b63fe675dfca9121862a9dd67a0fae5d39b9db90) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: subAgent event propagation in fullStream for enhanced streaming experience +### Patch Changes - Fixed an issue where SubAgent events (text-delta, tool-call, tool-result, reasoning, source, finish) were not being properly forwarded to the parent agent's fullStream. This enhancement improves the streaming experience by ensuring all SubAgent activities are visible in the parent stream with proper metadata (subAgentId, subAgentName) for UI filtering and display. +- [#847](https://github.com/VoltAgent/voltagent/pull/847) [`d861c17`](https://github.com/VoltAgent/voltagent/commit/d861c17e72f2fb6368778970a56411fadabaf9a5) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add first-class REST tool endpoints and UI support - #638 + - Server: list and execute registered tools over HTTP (`GET /tools`, `POST /tools/:name/execute`) with zod-validated inputs and OpenAPI docs. + - Auth: Both GET and POST tool endpoints are behind the same auth middleware as agent/workflow execution (protected by default). + - Multi-agent tools: tools now report all owning agents via `agents[]` (no more single `agentId`), including tags when provided. + - Safer handlers: input validation via safeParse guard, tag extraction without `any`, and better error shaping. + - Serverless: update install route handles empty bodies and `/updates/:packageName` variant. + - Console: Unified list surfaces tools, tool tester drawer with Monaco editors and default context, Observability page adds a Tools tab with direct execution. + - Docs: New tools endpoint page and API reference entries for listing/executing tools. -## 0.1.36 +- Updated dependencies [[`d861c17`](https://github.com/VoltAgent/voltagent/commit/d861c17e72f2fb6368778970a56411fadabaf9a5)]: + - @voltagent/server-core@1.0.33 -### Patch Changes +## 1.2.7 -- [#251](https://github.com/VoltAgent/voltagent/pull/251) [`be0cf47`](https://github.com/VoltAgent/voltagent/commit/be0cf47ec6e9640119d752dd6b608097d06bf69d) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add fullStream support and subagent event forwarding +### Patch Changes - Added `fullStream` support to the core agent system for enhanced streaming with detailed chunk types (text-delta, tool-call, tool-result, reasoning, finish, error). Also improved event forwarding between subagents for better multi-agent workflows. SubAgent events are now fully forwarded to parent agents, with filtering moved to the client side for better flexibility. +- [#845](https://github.com/VoltAgent/voltagent/pull/845) [`5432f13`](https://github.com/VoltAgent/voltagent/commit/5432f13bddebd869522ebffbedd9843b4476f08b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: workflow execution listing - #844 - Real-world example: + Added a unified way to list workflow runs so teams can audit executions across every storage backend and surface them via the API and console. - ```typescript - const response = await agent.streamText("What's the weather in Istanbul?"); + ## What changed + - `queryWorkflowRuns` now exists on all memory adapters (in-memory, libsql, Postgres, Supabase, voltagent-memory) with filters for `workflowId`, `status`, `from`, `to`, `limit`, and `offset`. + - Server routes are consolidated under `/workflows/executions` (no path param needed); `GET /workflows/:id` also returns the workflow result schema for typed clients. Handler naming is standardized to `listWorkflowRuns`. + - VoltOps Console observability panel lists the new endpoint; REST docs updated with query params and sample responses. New unit tests cover handlers and every storage adapter. - if (response.fullStream) { - for await (const chunk of response.fullStream) { - // Filter out SubAgent text, reasoning, and source events for cleaner UI - if (chunk.subAgentId && chunk.subAgentName) { - if (chunk.type === "text" || chunk.type === "reasoning" || chunk.type === "source") { - continue; // Skip these events from sub-agents - } - } + ## Quick fetch - switch (chunk.type) { - case "text-delta": - process.stdout.write(chunk.textDelta); // Stream text in real-time - break; - case "tool-call": - console.log(`🔧 Using tool: ${chunk.toolName}`); - break; - case "tool-result": - console.log(`✅ Tool completed: ${chunk.toolName}`); - break; - case "reasoning": - console.log(`🤔 AI thinking: ${chunk.reasoning}`); - break; - case "finish": - console.log(`\n✨ Done! Tokens used: ${chunk.usage?.totalTokens}`); - break; - } - } - } + ```ts + await fetch( + "http://localhost:3141/workflows/executions?workflowId=expense-approval&status=completed&from=2024-01-01&to=2024-01-31&limit=20&offset=0" + ); ``` -- [#248](https://github.com/VoltAgent/voltagent/pull/248) [`a3b4e60`](https://github.com/VoltAgent/voltagent/commit/a3b4e604e6f79281903ff0c28422e6ee2863b340) Thanks [@alasano](https://github.com/alasano)! - feat(core): add streamable HTTP transport support for MCP - - Upgrade @modelcontextprotocol/sdk from 1.10.1 to 1.12.1 - - Add support for streamable HTTP transport (the newer MCP protocol) - - Modified existing `type: "http"` to use automatic selection with streamable HTTP → SSE fallback - - Added two new transport types: - - `type: "sse"` - Force SSE transport only (legacy) - - `type: "streamable-http"` - Force streamable HTTP only (no fallback) - - Maintain full backward compatibility - existing `type: "http"` configurations continue to work via automatic fallback +- Updated dependencies [[`5432f13`](https://github.com/VoltAgent/voltagent/commit/5432f13bddebd869522ebffbedd9843b4476f08b)]: + - @voltagent/server-core@1.0.32 + - @voltagent/core@1.2.17 - Fixes #246 +## 1.2.6 -- [#247](https://github.com/VoltAgent/voltagent/pull/247) [`20119ad`](https://github.com/VoltAgent/voltagent/commit/20119ada182ec5f313a7f46956218d593180e096) Thanks [@Ajay-Satish-01](https://github.com/Ajay-Satish-01)! - feat(core): Enhanced server configuration with unified `server` object and Swagger UI control +### Patch Changes - Server configuration options have been enhanced with a new unified `server` object for better organization and flexibility while maintaining full backward compatibility. +- [`d3e0995`](https://github.com/VoltAgent/voltagent/commit/d3e09950fb8708db8beb9db2f1b8eafbe47686ea) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add CLI announcements system for server startup - **What's New:** - - **Unified Server Configuration:** All server-related options (`autoStart`, `port`, `enableSwaggerUI`, `customEndpoints`) are now grouped under a single `server` object. - - **Swagger UI Control:** Fine-grained control over Swagger UI availability with environment-specific defaults. - - **Backward Compatibility:** Legacy individual options are still supported but deprecated. - - **Override Logic:** New `server` object takes precedence over deprecated individual options. + VoltAgent server now displays announcements during startup, keeping developers informed about new features and updates. - **Migration Guide:** + ## How It Works - **New Recommended Usage:** + When the server starts, it fetches announcements from a centralized GitHub-hosted JSON file and displays them in a minimal, non-intrusive format: + + ``` + ⚡ Introducing VoltOps Deployments → https://console.voltagent.dev/deployments + ``` + + ## Key Features + - **Dynamic updates**: Announcements are fetched from GitHub at runtime, so new announcements appear without requiring a package update + - **Non-blocking**: Uses a 3-second timeout and fails silently to never delay server startup + - **Minimal footprint**: Single-line format inspired by Next.js, doesn't clutter the console + - **Toggle support**: Each announcement has an `enabled` flag for easy control + + ## Technical Details + - Announcements source: `https://raw.githubusercontent.com/VoltAgent/voltagent/main/announcements.json` + - New `showAnnouncements()` function exported from `@voltagent/server-core` + - Integrated into both `BaseServerProvider` and `HonoServerProvider` startup flow + +- [#837](https://github.com/VoltAgent/voltagent/pull/837) [`3bdb4ad`](https://github.com/VoltAgent/voltagent/commit/3bdb4ad24d0c9cb5eb9143b303752b22b4727457) Thanks [@venatir](https://github.com/venatir)! - feat: enhance app configuration - adding `configureFullApp` + +- Updated dependencies [[`d3e0995`](https://github.com/VoltAgent/voltagent/commit/d3e09950fb8708db8beb9db2f1b8eafbe47686ea)]: + - @voltagent/server-core@1.0.31 + +## 1.2.5 + +### Patch Changes + +- [#812](https://github.com/VoltAgent/voltagent/pull/812) [`0f64363`](https://github.com/VoltAgent/voltagent/commit/0f64363a2b577e025fae41276cc0d85ef7fc0644) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: comprehensive authentication system with JWT, Console Access, and WebSocket support + + ## The Problem + + VoltAgent's authentication system had several critical gaps that made it difficult to secure production deployments: + 1. **No Authentication Support:** The framework lacked built-in authentication, forcing developers to implement their own security + 2. **WebSocket Security:** WebSocket connections for observability had no authentication, exposing sensitive telemetry data + 3. **Browser Limitations:** Browsers cannot send custom headers during WebSocket handshake, making authentication impossible + 4. **Development vs Production:** No clear separation between development convenience and production security + 5. **Console Access:** No secure way for the VoltAgent Console to access observability endpoints in production + + ## The Solution + + **JWT Authentication (`@voltagent/server-core`, `@voltagent/server-hono`):** + - Added pluggable `jwtAuth` provider with configurable secret and options + - Implemented `mapUser` function to transform JWT payloads into user objects + - Created flexible route protection with `defaultPrivate` mode (opt-out vs opt-in) + - Added `publicRoutes` configuration for fine-grained control + + **WebSocket Authentication:** + - Implemented query parameter authentication for browser WebSocket connections + - Added dual authentication support (headers for servers, query params for browsers) + - Created WebSocket-specific authentication helpers for observability endpoints + - Preserved user context throughout WebSocket connection lifecycle + + **Console Access System:** + - Introduced `VOLTAGENT_CONSOLE_ACCESS_KEY` environment variable for production Console access + - Added `x-console-access-key` header support for HTTP requests + - Implemented query parameter `?key=` for WebSocket connections + - Created `hasConsoleAccess()` utility for unified access checking + + **Development Experience:** + - Enhanced `x-voltagent-dev` header to work with both HTTP and WebSocket + - Added `isDevRequest()` helper that requires both header AND non-production environment + - Implemented query parameter `?dev=true` for browser WebSocket connections + - Maintained zero-config development mode while ensuring production security + + **Route Matching Improvements:** + - Added wildcard support with `/observability/*` pattern for all observability endpoints + - Implemented double-star pattern `/api/**` for path and all children + - Enhanced `pathMatches()` function with proper segment matching + - Protected all observability, workflow control, and system update endpoints by default + + ## Impact + - ✅ **Production Ready:** Complete authentication system for securing VoltAgent deployments + - ✅ **WebSocket Security:** Browser-compatible authentication for real-time observability + - ✅ **Console Integration:** Secure access for VoltAgent Console in production environments + - ✅ **Developer Friendly:** Zero-config development with automatic authentication bypass + - ✅ **Flexible Security:** Choose between opt-in (default) or opt-out authentication modes + - ✅ **User Context:** Automatic user injection into agent and workflow execution context + + ## Technical Details + + **Protected Routes (Default):** ```typescript - import { Agent, VoltAgent } from "@voltagent/core"; - import { VercelAIProvider } from "@voltagent/vercel-ai"; - import { openai } from "@ai-sdk/openai"; + // Agent/Workflow Execution + POST /agents/:id/text + POST /agents/:id/stream + POST /workflows/:id/run - const agent = new Agent({ - name: "My Assistant", - instructions: "A helpful assistant", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - }); + // All Observability Endpoints + /observability/* // Traces, logs, memory - all methods - new VoltAgent({ - agents: { agent }, - server: { - autoStart: true, - port: 3000, - enableSwaggerUI: true, - customEndpoints: [ - { - path: "/health", - method: "get", - handler: async (c) => c.json({ status: "ok" }), - }, - ], - }, - }); + // Workflow Control + POST /workflows/:id/executions/:executionId/suspend + POST /workflows/:id/executions/:executionId/resume + + // System Updates + GET /updates + POST /updates/:packageName ``` - **Legacy Usage (Deprecated but Still Works):** + **Authentication Modes:** ```typescript - new VoltAgent({ - agents: { agent }, - autoStart: true, // @deprecated - use server.autoStart - port: 3000, // @deprecated - use server.port - customEndpoints: [], // @deprecated - use server.customEndpoints + // Opt-in mode (default) - Only execution endpoints protected + auth: jwtAuth({ + secret: process.env.JWT_SECRET, + }); + + // Opt-out mode - Everything protected except specified routes + auth: jwtAuth({ + secret: process.env.JWT_SECRET, + defaultPrivate: true, + publicRoutes: ["GET /health", "POST /webhooks/*"], }); ``` - **Mixed Usage (Server Object Overrides):** + **WebSocket Authentication Flow:** ```typescript - new VoltAgent({ - agents: { agent }, - autoStart: false, // This will be overridden - server: { - autoStart: true, // This takes precedence + // Browser WebSocket with query params + new WebSocket("ws://localhost:3000/ws/observability?key=console-key"); + new WebSocket("ws://localhost:3000/ws/observability?dev=true"); + + // Server WebSocket with headers + ws.connect({ + headers: { + "x-console-access-key": "console-key", + "x-voltagent-dev": "true", }, }); ``` - **Swagger UI Defaults:** - - Development (`NODE_ENV !== 'production'`): Swagger UI enabled - - Production (`NODE_ENV === 'production'`): Swagger UI disabled - - Override with `server.enableSwaggerUI: true/false` + ## Migration Notes - Resolves [#241](https://github.com/VoltAgent/voltagent/issues/241) + **For Existing Users:** + 1. **No Breaking Changes:** Authentication is optional. Existing deployments continue to work without configuration. + 2. **To Enable Authentication:** -## 0.1.35 + ```typescript + import { jwtAuth } from "@voltagent/server-hono"; -### Patch Changes + new VoltAgent({ + server: honoServer({ + auth: jwtAuth({ + secret: process.env.JWT_SECRET, + }), + }), + }); + ``` -- [#240](https://github.com/VoltAgent/voltagent/pull/240) [`8605863`](https://github.com/VoltAgent/voltagent/commit/860586377bff11b9e7ba80e06fd26b0098bd334a) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - trim the system prompt so we don't have extra newlines and offset text + 3. **For Production Console:** -## 0.1.34 + ```bash + # .env + VOLTAGENT_CONSOLE_ACCESS_KEY=your-secure-key + NODE_ENV=production + ``` -### Patch Changes + 4. **Generate Secrets:** -- [#238](https://github.com/VoltAgent/voltagent/pull/238) [`ccdba7a`](https://github.com/VoltAgent/voltagent/commit/ccdba7ac58e284dcda9f6b7bec2c8d2e69892940) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: user messages saving with proper content serialization + ```bash + # JWT Secret + openssl rand -hex 32 - Fixed an issue where user messages were not being saved correctly to storage due to improper content formatting. The message content is now properly stringified when it's not already a string, ensuring consistent storage format across PostgreSQL and LibSQL implementations. + # Console Access Key + openssl rand -hex 32 + ``` -## 0.1.33 + 5. **Test Token Generation:** + ```javascript + // generate-token.js + import jwt from "jsonwebtoken"; + const token = jwt.sign({ id: "user-1", email: "test@example.com" }, process.env.JWT_SECRET, { + expiresIn: "24h", + }); + console.log(token); + ``` -### Patch Changes + ## Documentation -- [#236](https://github.com/VoltAgent/voltagent/pull/236) [`5d39cdc`](https://github.com/VoltAgent/voltagent/commit/5d39cdc68c4ec36ec2f0bf86a29dbf1225644416) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: Remove userId parameter from addMessage method + Comprehensive authentication documentation has been added to `/website/docs/api/authentication.md` covering: + - Getting started with three authentication options + - Common use cases with code examples + - Advanced configuration with `mapUser` function + - Console and observability authentication + - Security best practices + - Troubleshooting guide - Simplified the `addMessage` method signature by removing the `userId` parameter. This change makes the API cleaner and more consistent with the conversation-based approach where user context is handled at the conversation level. +- Updated dependencies [[`0f64363`](https://github.com/VoltAgent/voltagent/commit/0f64363a2b577e025fae41276cc0d85ef7fc0644)]: + - @voltagent/server-core@1.0.26 + - @voltagent/core@1.2.9 - ### Changes - - **Removed**: `userId` parameter from `addMessage` method - - **Before**: `addMessage(message: MemoryMessage, userId: string, conversationId: string)` - - **After**: `addMessage(message: MemoryMessage, conversationId: string)` +## 1.2.4 - ### Migration Guide +### Patch Changes - If you were calling `addMessage` with a `userId` parameter, simply remove it: +- [#801](https://github.com/VoltAgent/voltagent/pull/801) [`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add triggers DSL improvements and event payload simplification + - Introduce the new `createTriggers` DSL and expose trigger events via sensible provider names (e.g. `on.airtable.recordCreated`) rather than raw catalog IDs. + - Add trigger span metadata propagation so VoltAgent agents receive trigger context automatically without manual mapping. + - Simplify action dispatch payloads: `payload` now contains only the event’s raw data while trigger context lives in the `event`/`metadata` blocks, reducing boilerplate in handlers. - ```typescript - // Before - await memory.addMessage(message, conversationId, userId); + ```ts + import { VoltAgent, createTriggers } from "@voltagent/core"; - // After - await memory.addMessage(message, conversationId); + new VoltAgent({ + // ... + triggers: createTriggers((on) => { + on.airtable.recordCreated(({ payload, event }) => { + console.log("New Airtable row", payload, event.metadata); + }); + + on.gmail.newEmail(({ payload }) => { + console.log("New Gmail message", payload); + }); + }), + }); ``` - ### Rationale +- Updated dependencies [[`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749), [`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749)]: + - @voltagent/server-core@1.0.25 + - @voltagent/core@1.2.6 - User context is now properly managed at the conversation level, making the API more intuitive and reducing parameter complexity. The user association is handled through the conversation's `userId` property instead of requiring it on every message operation. +## 1.2.3 - **Breaking Change:** +### Patch Changes - This is a minor breaking change. Update your `addMessage` calls to remove the `userId` parameter. +- [#787](https://github.com/VoltAgent/voltagent/pull/787) [`5e81d65`](https://github.com/VoltAgent/voltagent/commit/5e81d6568ba3bee26083ca2a8e5d31f158e36fc0) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add full conversation step persistence across the stack: + - Core now exposes managed-memory step APIs, and the VoltAgent managed memory adapter persists/retrieves steps through VoltOps. + - LibSQL, PostgreSQL, Supabase, and server handlers provision the new `_steps` table, wire up DTOs/routes, and surface the data in Observability/Steps UI (including managed-memory backends). -- [#235](https://github.com/VoltAgent/voltagent/pull/235) [`16c2a86`](https://github.com/VoltAgent/voltagent/commit/16c2a863d3ecdc09f09219bd40f2dbf1d789194d) Thanks [@alasano](https://github.com/alasano)! - fix: onHandoff hook invocation to pass arguments as object instead of positional parameters + fixes: #613 -- [#233](https://github.com/VoltAgent/voltagent/pull/233) [`0d85f0e`](https://github.com/VoltAgent/voltagent/commit/0d85f0e960dbc6e8df6a79a16c775ca7a34043bb) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: adding in missing changeset from [PR #226](https://github.com/VoltAgent/voltagent/pull/226) +- Updated dependencies [[`5e81d65`](https://github.com/VoltAgent/voltagent/commit/5e81d6568ba3bee26083ca2a8e5d31f158e36fc0)]: + - @voltagent/server-core@1.0.22 + - @voltagent/core@1.2.3 -## 0.1.32 +## 1.2.2 ### Patch Changes -- [#215](https://github.com/VoltAgent/voltagent/pull/215) [`f2f4539`](https://github.com/VoltAgent/voltagent/commit/f2f4539af7722f25a5aad9f01c2b7b5e50ba51b8) Thanks [@Ajay-Satish-01](https://github.com/Ajay-Satish-01)! - This release introduces powerful new methods for managing conversations with user-specific access control and improved developer experience. - - ### Simple Usage Example +- [#734](https://github.com/VoltAgent/voltagent/pull/734) [`2084fd4`](https://github.com/VoltAgent/voltagent/commit/2084fd491db4dbc89c432d1e72a633ec0c42d92b) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: add URL path support for single package updates and resolve 404 errors - ```typescript - // Get all conversations for a user - const conversations = await storage.getUserConversations("user-123").limit(10).execute(); + ## The Problem - console.log(conversations); + The update endpoint only accepted package names via request body (`POST /updates` with `{ "packageName": "@voltagent/core" }`), but users expected to be able to specify the package name directly in the URL path (`POST /updates/@voltagent/core`). This caused 404 errors when trying to update individual packages using the more intuitive URL-based approach. - // Get first conversation and its messages - const conversation = conversations[0]; - if (conversation) { - const messages = await storage.getConversationMessages(conversation.id); - console.log(messages); - } - ``` + ## The Solution - ### Pagination Support + Added a new route `POST /updates/:packageName` that accepts the package name as a URL parameter, providing a more RESTful API design while maintaining backward compatibility with the existing body-based approach. - ```typescript - // Get paginated conversations - const result = await storage.getPaginatedUserConversations("user-123", 1, 20); - console.log(result.conversations); // Array of conversations - console.log(result.hasMore); // Boolean indicating if more pages exist - ``` + **New Routes Available:** + - `POST /updates/@voltagent/core` - Update single package (package name in URL path) + - `POST /updates` with body `{ "packageName": "@voltagent/core" }` - Update single package (package name in body) + - `POST /updates` with no body - Update all VoltAgent packages -- [#229](https://github.com/VoltAgent/voltagent/pull/229) [`0eba8a2`](https://github.com/VoltAgent/voltagent/commit/0eba8a265c35241da74324613e15801402f7b778) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: migrate the provider streams to `AsyncIterableStream` + **Package Manager Detection:** + The system automatically detects your package manager based on lock files: + - `pnpm-lock.yaml` → uses `pnpm add` + - `yarn.lock` → uses `yarn add` + - `package-lock.json` → uses `npm install` + - `bun.lockb` → uses `bun add` - Example: + ## Usage Example ```typescript - const stream = createAsyncIterableStream( - new ReadableStream({ - start(controller) { - controller.enqueue("Hello"); - controller.enqueue(", "); - controller.enqueue("world!"); - controller.close(); - }, - }) - ); - - for await (const chunk of stream) { - console.log(chunk); - } + // Update a single package using URL path + fetch("http://localhost:3141/updates/@voltagent/core", { + method: "POST", + }); - // in the agent - const result = await agent.streamObject({ - messages, - model: "test-model", - schema, + // Or using the body parameter (backward compatible) + fetch("http://localhost:3141/updates", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ packageName: "@voltagent/core" }), }); - for await (const chunk of result.objectStream) { - console.log(chunk); - } + // Update all packages + fetch("http://localhost:3141/updates", { + method: "POST", + }); ``` - New exports: - - `createAsyncIterableStream` - - `type AsyncIterableStream` - -## 0.1.31 +- [#736](https://github.com/VoltAgent/voltagent/pull/736) [`348bda0`](https://github.com/VoltAgent/voltagent/commit/348bda0f0fffdcbd75c8a6aa2c2d8bd15195cd22) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: respect configured log levels for console output while sending all logs to OpenTelemetry - #646 -### Patch Changes + ## The Problem -- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 + When users configured a custom logger with a specific log level (e.g., `level: "error"`), DEBUG and INFO logs were still appearing in console output, cluttering the development environment. This happened because: + 1. `LoggerProxy` was forwarding all log calls to the underlying logger without checking the configured level + 2. Multiple components (agents, workflows, retrievers, memory adapters, observability) were logging at DEBUG level unconditionally + 3. OpenTelemetry logs were also being filtered by the same level, preventing observability platforms from receiving all logs -- [#223](https://github.com/VoltAgent/voltagent/pull/223) [`80fd3c0`](https://github.com/VoltAgent/voltagent/commit/80fd3c069de4c23116540a55082b891c4b376ce6) Thanks [@omeraplak](https://github.com/omeraplak)! - Add userContext support to retrievers for tracking references and metadata + ## The Solution - Retrievers can now store additional information (like references, sources, citations) in userContext that can be accessed from agent responses. This enables tracking which documents were used to generate responses, perfect for citation systems and audit trails. + **Framework Changes:** + - Updated `LoggerProxy` to check configured log level before forwarding to console/stdout + - Added `shouldLog(level)` method that inspects the underlying logger's level (supports both Pino and ConsoleLogger) + - Separated console output filtering from OpenTelemetry emission: + - **Console/stdout**: Respects configured level (error level → only shows error/fatal) + - **OpenTelemetry**: Always receives all logs (debug, info, warn, error, fatal) - ```ts - class MyRetriever extends BaseRetriever { - async retrieve(input: string, options: RetrieveOptions): Promise { - // Find relevant documents - const docs = this.findRelevantDocs(input); + **What Gets Fixed:** - const references = docs.map((doc) => ({ - id: doc.id, - title: doc.title, - source: doc.source, - })); - options.userContext.set("references", references); + ```typescript + const logger = createPinoLogger({ level: "error" }); - return docs.map((doc) => doc.content).join("\n"); - } - } + logger.debug("Agent created"); + // Console: ❌ Hidden (keeps dev environment clean) + // OpenTelemetry: ✅ Sent (full observability) - // Access references from response - const response = await agent.generateText("What is VoltAgent?"); - const references = response.userContext?.get("references"); + logger.error("Generation failed"); + // Console: ✅ Shown (important errors visible) + // OpenTelemetry: ✅ Sent (full observability) ``` -## 0.1.30 + ## Impact + - **Cleaner Development**: Console output now respects configured log levels + - **Full Observability**: OpenTelemetry platforms receive all logs regardless of console level + - **Better Debugging**: Debug/trace logs available in observability tools even in production + - **No Breaking Changes**: Existing code works as-is with improved behavior -### Patch Changes + ## Usage -- [#201](https://github.com/VoltAgent/voltagent/pull/201) [`04dd320`](https://github.com/VoltAgent/voltagent/commit/04dd3204455b09dc490d1bdfbd0cfeea13c3c409) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: include modelParameters in agent event metadata + No code changes needed - the fix applies automatically: - This adds the `modelParameters` field to agent event metadata to improve observability and debugging of model-specific behavior during agent execution. + ```typescript + // Create logger with error level + const logger = createPinoLogger({ + level: "error", + name: "my-app", + }); -## 0.1.29 + // Use it with VoltAgent + new VoltAgent({ + agents: { myAgent }, + logger, // Console will be clean, OpenTelemetry gets everything + }); + ``` -### Patch Changes + ## Migration Notes -- [#191](https://github.com/VoltAgent/voltagent/pull/191) [`07d99d1`](https://github.com/VoltAgent/voltagent/commit/07d99d133232babf78ba4e1c32fe235d5b3c9944) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - Remove console based logging in favor of a dev-only logger that will not output logs in production environments by leveraging the NODE_ENV + If you were working around this issue by: + - Filtering console output manually + - Using different loggers for different components + - Avoiding debug logs altogether -- [#196](https://github.com/VoltAgent/voltagent/pull/196) [`67b0e7e`](https://github.com/VoltAgent/voltagent/commit/67b0e7ea704d23bf9efb722c0b0b4971d0974153) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add `systemPrompt` and `messages` array to metadata for display on VoltOps Platform + You can now remove those workarounds and use a single logger with your preferred console level while maintaining full observability. -## 0.1.28 +- Updated dependencies [[`2084fd4`](https://github.com/VoltAgent/voltagent/commit/2084fd491db4dbc89c432d1e72a633ec0c42d92b), [`348bda0`](https://github.com/VoltAgent/voltagent/commit/348bda0f0fffdcbd75c8a6aa2c2d8bd15195cd22)]: + - @voltagent/server-core@1.0.20 + - @voltagent/core@1.1.36 -### Patch Changes +## 1.2.1 -- [#189](https://github.com/VoltAgent/voltagent/pull/189) [`07138fc`](https://github.com/VoltAgent/voltagent/commit/07138fc85ef27c9136d303233559f6b358ad86de) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - Added the 'purpose' field to agents (subagents) to provide a limited description of the purpose of the agent to the supervisor instead of passing the instructions for the subagent directly to the supervisor +### Patch Changes - ```ts - const storyAgent = new Agent({ - name: "Story Agent", - purpose: "A story writer agent that creates original, engaging short stories.", - instructions: "You are a creative story writer. Create original, engaging short stories.", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - }); - ``` +- [#728](https://github.com/VoltAgent/voltagent/pull/728) [`3952b4b`](https://github.com/VoltAgent/voltagent/commit/3952b4b2f4315eba80a06ba2596b74e00bf57735) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: automatic detection and display of custom routes in console logs and Swagger UI - > The supervisor agent's system prompt is automatically modified to include instructions on how to manage its subagents effectively. It lists the available subagents and their `purpose` and provides guidelines for delegation, communication, and response aggregation. + Custom routes added via `configureApp` callback are now automatically detected and displayed in both server startup logs and Swagger UI documentation. -- [#186](https://github.com/VoltAgent/voltagent/pull/186) [`adad41a`](https://github.com/VoltAgent/voltagent/commit/adad41a930e338c4683306b9dbffec22096eba5c) Thanks [@necatiozmen](https://github.com/necatiozmen)! - chore: update "VoltAgent Console" -> "VoltOps Platform" + ## What Changed -## 0.1.27 + Previously, only OpenAPI-registered routes were visible in: + - Server startup console logs + - Swagger UI documentation (`/ui`) -### Patch Changes + Now **all custom routes** are automatically detected, including: + - Regular Hono routes (`app.get()`, `app.post()`, etc.) + - OpenAPI routes with full documentation + - Routes with path parameters (`:id`, `{id}`) -- [#126](https://github.com/VoltAgent/voltagent/pull/126) [`2c47bc1`](https://github.com/VoltAgent/voltagent/commit/2c47bc1e9cd845cc60e6e9d7e86df40c98b82614) Thanks [@fav-devs](https://github.com/fav-devs)! - feat: add custom endpoints feature to VoltAgent API server, allowing developers to extend the API with their own endpoints + ## Usage Example ```typescript - import { VoltAgent } from "@voltagent/core"; + import { honoServer } from "@voltagent/server-hono"; new VoltAgent({ agents: { myAgent }, - customEndpoints: [ - { - path: "/api/health", - method: "get", - handler: async (c) => { - return c.json({ - success: true, - data: { status: "healthy" }, - }); - }, + server: honoServer({ + configureApp: (app) => { + // These routes are now automatically detected! + app.get("/api/health", (c) => c.json({ status: "ok" })); + app.post("/api/calculate", async (c) => { + const { a, b } = await c.req.json(); + return c.json({ result: a + b }); + }); }, - ], + }), }); ``` -## 0.1.26 - -### Patch Changes + ## Console Output -- [#181](https://github.com/VoltAgent/voltagent/pull/181) [`1b4a9fd`](https://github.com/VoltAgent/voltagent/commit/1b4a9fd78b84d9b758120380cb80a940c2354020) Thanks [@omeraplak](https://github.com/omeraplak)! - Implement comprehensive error handling for streaming endpoints - #170 - - **Backend**: Added error handling to `streamRoute` and `streamObjectRoute` with onError callbacks, safe stream operations, and multiple error layers (setup, iteration, stream errors) - - **Documentation**: Added detailed error handling guide with examples for fetch-based SSE streaming + ``` + ══════════════════════════════════════════════════ + VOLTAGENT SERVER STARTED SUCCESSFULLY + ══════════════════════════════════════════════════ + ✓ HTTP Server: http://localhost:3141 + ✓ Swagger UI: http://localhost:3141/ui + + ✓ Registered Endpoints: 2 total + + Custom Endpoints + GET /api/health + POST /api/calculate + ══════════════════════════════════════════════════ + ``` - Fixes issue where streaming errors weren't being communicated to frontend users, leaving them without feedback when API calls failed during streaming operations. + ## Improvements + - ✅ Extracts routes from `app.routes` array (includes all Hono routes) + - ✅ Merges with OpenAPI document routes for descriptions + - ✅ Filters out built-in VoltAgent paths using exact matching (not regex) + - ✅ Custom routes like `/agents-dashboard` or `/workflows-manager` are now correctly detected + - ✅ Normalizes path formatting (removes duplicate slashes) + - ✅ Handles both `:param` and `{param}` path parameter formats + - ✅ Adds custom routes to Swagger UI with auto-generated schemas + - ✅ Comprehensive test coverage (44 unit tests) -## 0.1.25 + ## Implementation Details -### Patch Changes + The `extractCustomEndpoints()` function now: + 1. Extracts all routes from `app.routes` (regular Hono routes) + 2. Merges with OpenAPI document routes (for descriptions) + 3. Deduplicates and filters built-in VoltAgent routes + 4. Returns a complete list of custom endpoints -- [`13d25b4`](https://github.com/VoltAgent/voltagent/commit/13d25b4033c3a4b41d501e954e2893b50553d8d4) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: update zod-from-json-schema dependency version to resolve MCP tools compatibility issues + The `getEnhancedOpenApiDoc()` function: + 1. Adds custom routes to OpenAPI document for Swagger UI + 2. Generates response schemas for undocumented routes + 3. Preserves existing OpenAPI documentation + 4. Supports path parameters and request bodies -## 0.1.24 +- Updated dependencies [[`59da0b5`](https://github.com/VoltAgent/voltagent/commit/59da0b587cd72ff6065fa7fde9fcaecf0a92d830)]: + - @voltagent/core@1.1.34 -### Patch Changes +## 1.2.0 -- [#176](https://github.com/VoltAgent/voltagent/pull/176) [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: removed `@n8n/json-schema-to-zod` dependency - #177 +### Minor Changes -- [#176](https://github.com/VoltAgent/voltagent/pull/176) [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275) Thanks [@omeraplak](https://github.com/omeraplak)! - The `error` column has been deprecated and replaced with `statusMessage` column for better consistency and clearer messaging. The old `error` column is still supported for backward compatibility but will be removed in a future major version. +- [#720](https://github.com/VoltAgent/voltagent/pull/720) [`91c7269`](https://github.com/VoltAgent/voltagent/commit/91c7269bb703e4e0786d6afe179b2fd986e9d95a) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: simplify CORS configuration and ensure custom routes are auth-protected - Changes: - - Deprecated `error` column (still functional) - - Improved error handling and status reporting + ## Breaking Changes -## 0.1.23 + ### CORS Configuration -### Patch Changes + CORS configuration has been simplified. Instead of configuring CORS in `configureApp`, use the new `cors` field: -- [`b2f423d`](https://github.com/VoltAgent/voltagent/commit/b2f423d55ee031fc02b0e8eda5175cfe15e38a42) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: zod import issue - #161 + **Before:** - Fixed incorrect zod import that was causing OpenAPI type safety errors. Updated to use proper import from @hono/zod-openapi package. + ```typescript + server: honoServer({ + configureApp: (app) => { + app.use( + "*", + cors({ + origin: "https://your-domain.com", + credentials: true, + }) + ); -## 0.1.22 + app.get("/api/health", (c) => c.json({ status: "ok" })); + }, + }); + ``` -### Patch Changes + **After (Simple global CORS):** -- [#149](https://github.com/VoltAgent/voltagent/pull/149) [`0137a4e`](https://github.com/VoltAgent/voltagent/commit/0137a4e67deaa2490b4a07f9de5f13633f2c473c) Thanks [@VenomHare](https://github.com/VenomHare)! - Added JSON schema support for REST API `generateObject` and `streamObject` functions. The system now accepts JSON schemas which are internally converted to Zod schemas for validation. This enables REST API usage where Zod schemas cannot be directly passed. #87 + ```typescript + server: honoServer({ + cors: { + origin: "https://your-domain.com", + credentials: true, + }, + configureApp: (app) => { + app.get("/api/health", (c) => c.json({ status: "ok" })); + }, + }); + ``` - Additional Changes: - - Included the JSON schema from `options.schema` in the system message for the `generateObject` and `streamObject` functions in both `anthropic-ai` and `groq-ai` providers. - - Enhanced schema handling to convert JSON schemas to Zod internally for seamless REST API compatibility. + **After (Route-specific CORS):** -- [#151](https://github.com/VoltAgent/voltagent/pull/151) [`4308b85`](https://github.com/VoltAgent/voltagent/commit/4308b857ab2133f6ca60f22271dcf30bad8b4c08) Thanks [@process.env.POSTGRES_USER](https://github.com/process.env.POSTGRES_USER)! - feat: Agent memory can now be stored in PostgreSQL database. This feature enables agents to persistently store conversation history in PostgreSQL. - #16 + ```typescript + import { cors } from "hono/cors"; - ## Usage + server: honoServer({ + cors: false, // Disable default CORS for route-specific control - ```tsx - import { openai } from "@ai-sdk/openai"; - import { Agent, VoltAgent } from "@voltagent/core"; - import { PostgresStorage } from "@voltagent/postgres"; - import { VercelAIProvider } from "@voltagent/vercel-ai"; + configureApp: (app) => { + // Different CORS for different routes + app.use("/agents/*", cors({ origin: "https://agents.com" })); + app.use("/api/public/*", cors({ origin: "*" })); - // Configure PostgreSQL Memory Storage - const memoryStorage = new PostgresStorage({ - // Read connection details from environment variables - connection: { - host: process.env.POSTGRES_HOST || "localhost", - port: Number.parseInt(process.env.POSTGRES_PORT || "5432"), - database: process.env.POSTGRES_DB || "voltagent", - || "postgres", - password: process.env.POSTGRES_PASSWORD || "password", - ssl: process.env.POSTGRES_SSL === "true", + app.get("/api/health", (c) => c.json({ status: "ok" })); }, + }); + ``` - // Alternative: Use connection string - // connection: process.env.DATABASE_URL || "postgresql://postgres:password@localhost:5432/voltagent", + ### Custom Routes Authentication - // Optional: Customize table names - tablePrefix: "voltagent_memory", + Custom routes added via `configureApp` are now registered AFTER authentication middleware. This means: + - **Opt-in mode** (default): Custom routes follow the same auth rules as built-in routes + - **Opt-out mode** (`defaultPrivate: true`): Custom routes are automatically protected - // Optional: Configure connection pool - maxConnections: 10, + **Before:** Custom routes bypassed authentication unless you manually added auth middleware. - // Optional: Set storage limit for messages - storageLimit: 100, + **After:** Custom routes inherit authentication behavior automatically. - // Optional: Enable debug logging for development - debug: process.env.NODE_ENV === "development", - }); + **Example with opt-out mode:** - // Create agent with PostgreSQL memory - const agent = new Agent({ - name: "PostgreSQL Memory Agent", - description: "A helpful assistant that remembers conversations using PostgreSQL.", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - memory: memoryStorage, // Use the configured PostgreSQL storage + ```typescript + server: honoServer({ + auth: jwtAuth({ + secret: process.env.JWT_SECRET, + defaultPrivate: true, // Protect all routes by default + publicRoutes: ["GET /api/health"], + }), + configureApp: (app) => { + // This is now automatically protected + app.get("/api/user/profile", (c) => { + const user = c.get("authenticatedUser"); + return c.json({ user }); // user is guaranteed to exist + }); + }, }); ``` -## 0.1.21 + ## Why This Change? + 1. **Security**: Custom routes are no longer accidentally left unprotected + 2. **Simplicity**: CORS configuration is now a simple config field for common cases + 3. **Flexibility**: Advanced users can still use route-specific CORS with `cors: false` + 4. **Consistency**: Custom routes follow the same authentication rules as built-in routes ### Patch Changes -- [#160](https://github.com/VoltAgent/voltagent/pull/160) [`03ed437`](https://github.com/VoltAgent/voltagent/commit/03ed43723cd56f29ac67088f0624a88632a14a1b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: improved event system architecture for better observability - - We've updated the event system architecture to improve observability capabilities. The system includes automatic migrations to maintain backward compatibility, though some events may not display perfectly due to the architectural changes. Overall functionality remains stable and most features work as expected. - - No action required - the system will automatically handle the migration process. If you encounter any issues, feel free to reach out on [Discord](https://s.voltagent.dev/discord) for support. - - **What's Changed:** - - Enhanced event system for better observability and monitoring - - Automatic database migrations for seamless upgrades - - Improved agent history tracking and management +- Updated dependencies [[`efe4be6`](https://github.com/VoltAgent/voltagent/commit/efe4be634f52aaef00d6b188a9146b1ad00b5968)]: + - @voltagent/core@1.1.33 - **Migration Notes:** - - Backward compatibility is maintained through automatic migrations - - Some legacy events may display differently but core functionality is preserved - - No manual intervention needed - migrations run automatically +## 1.1.0 - **Note:** - Some events may not display perfectly due to architecture changes, but the system will automatically migrate and most functionality will work as expected. +### Minor Changes -## 0.1.20 +- [#681](https://github.com/VoltAgent/voltagent/pull/681) [`683318f`](https://github.com/VoltAgent/voltagent/commit/683318f8671d7c5028d51169650555d2694afd05) Thanks [@ekas-7](https://github.com/ekas-7)! - feat: add support for custom endpoints ### Patch Changes -- [#155](https://github.com/VoltAgent/voltagent/pull/155) [`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c) Thanks [@baseballyama](https://github.com/baseballyama)! - chore: update `tsconfig.json`'s `target` to `ES2022` +- Updated dependencies [[`3a1d214`](https://github.com/VoltAgent/voltagent/commit/3a1d214790cf49c5020eac3e9155a6daab2ff1db)]: + - @voltagent/core@1.1.32 -- [#162](https://github.com/VoltAgent/voltagent/pull/162) [`b164bd0`](https://github.com/VoltAgent/voltagent/commit/b164bd014670452cb162b388f03565db992767af) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: pin zod version to 3.24.2 to avoid "Type instantiation is excessively deep and possibly infinite" error +## 1.0.26 - Fixed compatibility issues between different zod versions that were causing TypeScript compilation errors. This issue occurs when multiple packages use different patch versions of zod (e.g., 3.23.x vs 3.24.x), leading to type instantiation depth problems. By pinning to 3.24.2, we ensure consistent behavior across all packages. +### Patch Changes - See: https://github.com/colinhacks/zod/issues/3435 +- [`907cc30`](https://github.com/VoltAgent/voltagent/commit/907cc30b8cbe655ae6e79fd25494f246663fd8ad) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: @voltagent/core dependency -- [#158](https://github.com/VoltAgent/voltagent/pull/158) [`9412cf0`](https://github.com/VoltAgent/voltagent/commit/9412cf0633f20d6b77c87625fc05e9e216936758) Thanks [@baseballyama](https://github.com/baseballyama)! - chore(core): fixed a type error that occurred in src/server/api.ts +- Updated dependencies [[`907cc30`](https://github.com/VoltAgent/voltagent/commit/907cc30b8cbe655ae6e79fd25494f246663fd8ad)]: + - @voltagent/server-core@1.0.19 -## 0.1.19 +## 1.0.25 ### Patch Changes -- [#128](https://github.com/VoltAgent/voltagent/pull/128) [`d6cf2e1`](https://github.com/VoltAgent/voltagent/commit/d6cf2e194d47352565314c93f1a4e477701563c1) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add VoltAgentExporter for production observability 🚀 - - VoltAgentExporter enables persistent storage and monitoring of AI agents in production environments: - - Send agent telemetry data to the VoltAgent cloud platform - - Access historical execution data through your project dashboard - - Monitor deployed agents over time - - Debug production issues with comprehensive tracing +- [#714](https://github.com/VoltAgent/voltagent/pull/714) [`f20cdf1`](https://github.com/VoltAgent/voltagent/commit/f20cdf1c9cc84daa6c4002c1dfa2c2085f2ed2ca) Thanks [@{...}](https://github.com/{...})! - fix: auth middleware now preserves conversationId and all client options - To configure your project with VoltAgentExporter, visit the new tracing setup page at [`https://console.voltagent.dev/tracing-setup`](https://console.voltagent.dev/tracing-setup). + ## The Problem - For more information about production tracing with VoltAgentExporter, see our [developer documentation](https://voltagent.dev/docs/observability/developer-console/#production-tracing-with-voltagentexporter). + When using custom auth providers with VoltAgent, the auth middleware was completely replacing the `body.options` object instead of merging with it. This caused critical client-provided options to be lost, including: + - `conversationId` - essential for conversation continuity and hooks + - `temperature`, `maxSteps`, `topP` - LLM configuration parameters + - Any other options sent by the client in the request body -## 0.1.18 + This happened because the middleware created a brand new `options` object containing only auth-related fields (`context.user` and `userId`), completely discarding the original `body.options`. -### Patch Changes + **Example of the bug:** -- [#113](https://github.com/VoltAgent/voltagent/pull/113) [`0a120f4`](https://github.com/VoltAgent/voltagent/commit/0a120f4bf1b71575a4b6c67c94104633c58e1410) Thanks [@nhc](https://github.com/nhc)! - export createTool from toolkit + ```typescript + // Client sends: + { + input: "Hello", + options: { + conversationId: "conv-abc-123", + temperature: 0.7 + } + } -## 0.1.17 + // After auth middleware (BEFORE FIX): + { + input: "Hello", + options: { + // ❌ conversationId LOST! + // ❌ temperature LOST! + context: { user: {...} }, + userId: "user-123" + } + } -### Patch Changes + // Result: conversationId missing in onStart hook's context + ``` -- [#106](https://github.com/VoltAgent/voltagent/pull/106) [`b31c8f2`](https://github.com/VoltAgent/voltagent/commit/b31c8f2ad1b4bf242b197a094300cb3397109a94) Thanks [@omeraplak](https://github.com/omeraplak)! - Enabled `userContext` to be passed from supervisor agents to their sub-agents, allowing for consistent contextual data across delegated tasks. This ensures that sub-agents can operate with the necessary shared information provided by their parent agent. + This was especially problematic when: + - Using hooks that depend on `conversationId` (like `onStart`, `onEnd`) + - Configuring LLM parameters from the client side + - Tracking conversations across multiple agent calls - ```typescript - // Supervisor Agent initiates an operation with userContext: - const supervisorContext = new Map(); - supervisorContext.set("globalTransactionId", "tx-supervisor-12345"); + ## The Solution - await supervisorAgent.generateText( - "Delegate analysis of transaction tx-supervisor-12345 to the financial sub-agent.", - { userContext: supervisorContext } - ); + Changed the auth middleware to **merge** auth data into the existing `body.options` instead of replacing it. Now all client options are preserved while auth context is properly added. - // In your sub-agent's hook definition (e.g., within createHooks): - onStart: ({ agent, context }: OnStartHookArgs) => { - const inheritedUserContext = context.userContext; // Access the OperationContext's userContext - const transactionId = inheritedUserContext.get("globalTransactionId"); - console.log(`[${agent.name}] Hook: Operating with Transaction ID: ${transactionId}`); - // Expected log: [FinancialSubAgent] Hook: Operating with Transaction ID: tx-supervisor-12345 - }; + **After the fix:** - // Example: Inside a Tool executed by the Sub-Agent - // In your sub-agent tool's execute function: - execute: async (params: { someParam: string }, options?: ToolExecutionContext) => { - if (options?.operationContext?.userContext) { - const inheritedUserContext = options.operationContext.userContext; - const transactionId = inheritedUserContext.get("globalTransactionId"); - console.log(`[SubAgentTool] Tool: Processing with Transaction ID: ${transactionId}`); - // Expected log: [SubAgentTool] Tool: Processing with Transaction ID: tx-supervisor-12345 - return `Processed ${params.someParam} for transaction ${transactionId}`; + ```typescript + // Client sends: + { + input: "Hello", + options: { + conversationId: "conv-abc-123", + temperature: 0.7 } - return "Error: OperationContext not available for tool"; - }; - ``` + } -## 0.1.14 + // After auth middleware (AFTER FIX): + { + input: "Hello", + options: { + ...body.options, // ✅ All original options preserved + conversationId: "conv-abc-123", // ✅ Preserved + temperature: 0.7, // ✅ Preserved + context: { + ...body.options?.context, // ✅ Existing context merged + // ✅ Auth user added + }, + userId: "user-123" // ✅ Auth userId added + } + } -### Patch Changes + // Result: conversationId properly available in hooks! + ``` -- [#102](https://github.com/VoltAgent/voltagent/pull/102) [`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3) Thanks [@omeraplak](https://github.com/omeraplak)! - refactor: use 'instructions' field for Agent definitions in examples - #88 + ## Technical Changes - Updated documentation examples (READMEs, docs, blogs) and relevant package code examples to use the `instructions` field instead of `description` when defining `Agent` instances. + **Before (packages/server-hono/src/auth/middleware.ts:82-90):** - This change aligns the examples with the preferred API usage for the `Agent` class, where `instructions` provides behavioral guidance to the agent/LLM. This prepares for the eventual deprecation of the `description` field specifically for `Agent` class definitions. + ```typescript + options: { + context: { + ...body.context, + user, + }, + userId: user.id || user.sub, + } + // ❌ Creates NEW options object, loses body.options + ``` - **Example Change for Agent Definition:** + **After:** - ```diff - const agent = new Agent({ - name: "My Assistant", - - description: "A helpful assistant.", - + instructions: "A helpful assistant.", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - }); + ```typescript + options: { + ...body.options, // ✅ Preserve all existing options + context: { + ...body.options?.context, // ✅ Merge existing context + ...body.context, + user, + }, + userId: user.id || user.sub, + } + // ✅ Merges auth data into existing options ``` -## 0.1.13 + ## Impact + - ✅ **Fixes missing conversationId in hooks**: `onStart`, `onEnd`, and other hooks now receive the correct `conversationId` from client + - ✅ **Preserves LLM configuration**: Client-side `temperature`, `maxSteps`, `topP`, etc. are no longer lost + - ✅ **Context merging works correctly**: Both custom context and auth user context coexist + - ✅ **Backward compatible**: Existing code continues to work, only fixes the broken behavior + - ✅ **Proper fallback chain**: `userId` uses `user.id` → `user.sub` → `body.options.userId` -### Patch Changes + ## Testing -- [`f7de864`](https://github.com/VoltAgent/voltagent/commit/f7de864503d598cf7131cc01afa3779639190107) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: add `toolName` to event metadata to ensure `delegate_task` name is visible in VoltOps LLM Observability Platform + Added comprehensive test suite (`packages/server-hono/src/auth/middleware.spec.ts`) with 12 test cases covering: + - conversationId preservation + - Multiple options preservation + - Context merging + - userId priority logic + - Empty options handling + - Public routes + - Authentication failures -- [`13db262`](https://github.com/VoltAgent/voltagent/commit/13db2621ae6b730667f9991d3c2129c85265e925) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: Update Zod to version 3.24.2 to resolve "Type instantiation is excessively deep and possibly infinite" error (related to https://github.com/colinhacks/zod/issues/3435). + All tests passing ✅ -## 0.1.12 +## 1.0.24 ### Patch Changes -- [#94](https://github.com/VoltAgent/voltagent/pull/94) [`004df81`](https://github.com/VoltAgent/voltagent/commit/004df81fa6a23571391e6ddeba0dfe6bfea267e8) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Add Langfuse Observability Exporter - - This introduces a new package `@voltagent/langfuse-exporter` that allows you to export OpenTelemetry traces generated by `@voltagent/core` directly to Langfuse (https://langfuse.com/) for detailed observability into your agent's operations. +- Updated dependencies [[`461ecec`](https://github.com/VoltAgent/voltagent/commit/461ecec60aa90b56a413713070b6e9f43efbd74b)]: + - @voltagent/core@1.1.31 + - @voltagent/server-core@1.0.18 - **How to Use:** +## 1.0.23 - ## Installation +### Patch Changes - Install the necessary packages: +- [#709](https://github.com/VoltAgent/voltagent/pull/709) [`8b838ec`](https://github.com/VoltAgent/voltagent/commit/8b838ecf085f13efacb94897063de5e7087861e6) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add defaultPrivate option to AuthProvider for protecting all routes by default - ```bash - npm install @voltagent/langfuse-exporter - ``` + ## The Problem - ## Configuration + When using VoltAgent with third-party auth providers (like Clerk, Auth0, or custom providers), custom routes added via `configureApp` were public by default. This meant: + - Only routes explicitly in `PROTECTED_ROUTES` required authentication + - Custom endpoints needed manual middleware to be protected + - The `publicRoutes` property couldn't make all routes private by default - Configure the `LangfuseExporter` and pass it to `VoltAgent`: + This was especially problematic when integrating with enterprise auth systems where security-by-default is expected. - ```typescript - import { Agent, VoltAgent } from "@voltagent/core"; - import { VercelAIProvider } from "@voltagent/vercel-ai"; - import { openai } from "@ai-sdk/openai"; + ## The Solution - import { LangfuseExporter } from "@voltagent/langfuse-exporter"; + Added `defaultPrivate` option to `AuthProvider` interface, enabling two authentication modes: + - **Opt-In Mode** (default, `defaultPrivate: false`): Only specific routes require auth + - **Opt-Out Mode** (`defaultPrivate: true`): All routes require auth unless explicitly listed in `publicRoutes` - // Ensure LANGFUSE_SECRET_KEY and LANGFUSE_PUBLIC_KEY are set in your environment + ## Usage Example - // Define your agent(s) - const agent = new Agent({ - name: "my-voltagent-app", - instructions: "A helpful assistant that answers questions without using tools", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - }); + ### Protecting All Routes with Clerk - // Configure the Langfuse Exporter - const langfuseExporter = new LangfuseExporter({ - publicKey: process.env.LANGFUSE_PUBLIC_KEY, - secretKey: process.env.LANGFUSE_SECRET_KEY, - baseUrl: process.env.LANGFUSE_BASE_URL, // Optional: Defaults to Langfuse Cloud - // debug: true // Optional: Enable exporter logging - }); + ```typescript + import { VoltAgent } from "@voltagent/core"; + import { honoServer, jwtAuth } from "@voltagent/server-hono"; - // Initialize VoltAgent with the exporter - // This automatically sets up OpenTelemetry tracing new VoltAgent({ - agents: { - agent, // Register your agent(s) - }, - telemetryExporter: langfuseExporter, // Pass the exporter instance + agents: { myAgent }, + server: honoServer({ + auth: jwtAuth({ + secret: process.env.CLERK_JWT_KEY, + defaultPrivate: true, // 🔒 Protect all routes by default + publicRoutes: ["GET /health", "POST /webhooks/clerk"], + mapUser: (payload) => ({ + id: payload.sub, + email: payload.email, + }), + }), + configureApp: (app) => { + // ✅ Public (in publicRoutes) + app.get("/health", (c) => c.json({ status: "ok" })); + + // 🔒 Protected automatically (defaultPrivate: true) + app.get("/api/user/data", (c) => { + const user = c.get("authenticatedUser"); + return c.json({ user }); + }); + }, + }), }); + ``` - console.log("VoltAgent initialized with Langfuse exporter."); + ### Default Behavior (Backward Compatible) - // Now, any operations performed by 'agent' (e.g., agent.generateText(...)) - // will automatically generate traces and send them to Langfuse. - ``` + ```typescript + // Without defaultPrivate, behavior is unchanged + auth: jwtAuth({ + secret: process.env.JWT_SECRET, + // defaultPrivate: false (default) + }); - By providing the `telemetryExporter` to `VoltAgent`, OpenTelemetry is automatically configured, and detailed traces including LLM interactions, tool usage, and agent metadata will appear in your Langfuse project. + // Custom routes are public unless you add your own middleware + configureApp: (app) => { + app.get("/api/data", (c) => { + // This is PUBLIC by default + return c.json({ data: "anyone can access" }); + }); + }; + ``` -## 0.1.11 + ## Benefits + - ✅ **Fail-safe security**: Routes are protected by default when enabled + - ✅ **No manual middleware**: Custom endpoints automatically protected + - ✅ **Perfect for third-party auth**: Ideal for Clerk, Auth0, Supabase + - ✅ **Backward compatible**: No breaking changes, opt-in feature + - ✅ **Fine-grained control**: Use `publicRoutes` to selectively allow access -### Patch Changes +- [`5a0728d`](https://github.com/VoltAgent/voltagent/commit/5a0728d888b48169cdadabb62641cdcf437f4ee4) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: correct CORS middleware detection to use actual function name 'cors2' -- [`e5b3a46`](https://github.com/VoltAgent/voltagent/commit/e5b3a46e2e61f366fa3c67f9a37d4e4d9e0fe426) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: enhance API Overview documentation - - Added `curl` examples for all key generation endpoints (`/text`, `/stream`, `/object`, `/stream-object`). - - Clarified that `userId` and `conversationId` options are optional. - - Provided separate `curl` examples demonstrating usage both with and without optional parameters (`userId`, `conversationId`). - - Added a new "Common Generation Options" section with a detailed table explaining parameters like `temperature`, `maxTokens`, `contextLimit`, etc., including their types and default values. + Fixed a critical bug where custom CORS middleware was not being properly detected, causing both custom and default CORS to be applied simultaneously. This resulted in the default CORS (`origin: "*"`) overwriting custom CORS headers on actual POST/GET requests, while OPTIONS (preflight) requests worked correctly. -- [`4649c3c`](https://github.com/VoltAgent/voltagent/commit/4649c3ccb9e56a7fcabfe6a0bcef2383ff6506ef) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve agent event handling and error processing - - Enhanced start event emission in agent operations - - Fixed timeline event creation for agent operations + ## The Problem -- [`8e6d2e9`](https://github.com/VoltAgent/voltagent/commit/8e6d2e994398c1a727d4afea39d5e34ffc4a5fca) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Allow passing arbitrary provider-specific options via the `provider` object in agent generation methods (`generateText`, `streamText`, etc.). + The middleware detection logic was checking for `middleware.name === "cors"`, but Hono's cors middleware function is actually named `"cors2"`. This caused: + - Detection to always fail → `userConfiguredCors` stayed `false` + - Default CORS (`app.use("*", cors())`) was applied even when users configured custom CORS + - **Both** middlewares executed: custom CORS on specific paths + default CORS on `"*"` + - OPTIONS requests returned correct custom CORS headers ✅ + - POST/GET requests had custom headers **overwritten** by default CORS (`*`) ❌ - Added an index signature `[key: string]: unknown;` to the `ProviderOptions` type (`voltagent/packages/core/src/agent/types.ts`). This allows users to pass any provider-specific parameters directly through the `provider` object, enhancing flexibility and enabling the use of features not covered by the standard options. + ## The Solution - Example using a Vercel AI SDK option: + Updated the detection logic to check for the actual function name: ```typescript - import { Agent } from "@voltagent/core"; - import { VercelProvider } from "@voltagent/vercel-ai"; - import { openai } from "@ai-sdk/openai"; + // Before: middleware.name === "cors" + // After: middleware.name === "cors2" + ``` - const agent = new Agent({ - name: "Example Agent", - llm: new VercelProvider(), - model: openai("gpt-4o-mini"), - }); + Now when users configure custom CORS in `configureApp`, it's properly detected and default CORS is skipped entirely. - await agent.streamText("Tell me a joke", { - provider: { - // Standard options can still be used - temperature: 0.7, - // Provider-specific options are now allowed by the type - experimental_activeTools: ["tool1", "tool2"], - anotherProviderOption: "someValue", - }, + ## Impact + - Custom CORS configurations now work correctly for **all** request types (OPTIONS, POST, GET, etc.) + - No more default CORS overwriting custom CORS headers + - Fixes browser CORS errors when using custom origins with credentials + - Maintains backward compatibility - default CORS still applies when no custom CORS is configured + + ## Example + + This now works as expected: + + ```typescript + import { VoltAgent } from "@voltagent/core"; + import { honoServer } from "@voltagent/server-hono"; + import { cors } from "hono/cors"; + + new VoltAgent({ + agents: { myAgent }, + server: honoServer({ + configureApp: (app) => { + app.use( + "/agents/*", + cors({ + origin: "http://localhost:3001", + credentials: true, + }) + ); + }, + }), }); ``` -## 0.1.10 + Both OPTIONS and POST requests now return: + - `Access-Control-Allow-Origin: http://localhost:3001` ✅ + - `Access-Control-Allow-Credentials: true` ✅ -### Patch Changes +- Updated dependencies [[`8b838ec`](https://github.com/VoltAgent/voltagent/commit/8b838ecf085f13efacb94897063de5e7087861e6)]: + - @voltagent/server-core@1.0.17 -- [#77](https://github.com/VoltAgent/voltagent/pull/77) [`beaa8fb`](https://github.com/VoltAgent/voltagent/commit/beaa8fb1f1bc6351f1bede0b65a6a189cc1b6ea2) Thanks [@omeraplak](https://github.com/omeraplak)! - **API & Providers:** Standardized message content format for array inputs. - - The API (`/text`, `/stream`, `/object`, `/stream-object` endpoints) now strictly expects the `content` field within message objects (when `input` is an array) to be either a `string` or an `Array` of content parts (e.g., `[{ type: 'text', text: '...' }]`). - - The previous behavior of allowing a single content object (e.g., `{ type: 'text', ... }`) directly as the value for `content` in message arrays is no longer supported in the API schema. Raw string inputs remain unchanged. - - Provider logic (`google-ai`, `groq-ai`, `xsai`) updated to align with this stricter definition. +## 1.0.22 - **Console:** - - **Added file and image upload functionality to the Assistant Chat.** Users can now attach multiple files/images via a button, preview attachments, and send them along with text messages. - - Improved the Assistant Chat resizing: Replaced size toggle buttons with a draggable handle (top-left corner). - - Chat window dimensions are now saved to local storage and restored on reload. +### Patch Changes - **Internal:** - - Added comprehensive test suites for Groq and XsAI providers. +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` +- Updated dependencies [[`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e)]: + - @voltagent/server-core@1.0.16 + - @voltagent/a2a-server@1.0.2 + - @voltagent/mcp-server@1.0.3 + - @voltagent/internal@0.0.12 + - @voltagent/core@1.1.30 -## 0.1.9 +## 1.0.21 ### Patch Changes -- [#71](https://github.com/VoltAgent/voltagent/pull/71) [`1f20509`](https://github.com/VoltAgent/voltagent/commit/1f20509528fc2cb2ba00f86d649848afae34af04) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Introduce `userContext` for passing custom data through agent operations +- [#703](https://github.com/VoltAgent/voltagent/pull/703) [`fbbb349`](https://github.com/VoltAgent/voltagent/commit/fbbb34932aeeaf6cede30228ded03df43df415ad) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve CORS middleware execution order issue preventing custom CORS configuration - Introduced `userContext`, a `Map` within the `OperationContext`. This allows developers to store and retrieve custom data across agent lifecycle hooks (`onStart`, `onEnd`) and tool executions for a specific agent operation (like a `generateText` call). This context is isolated per operation, providing a way to manage state specific to a single request or task. + Fixed a critical issue where custom CORS middleware configured in `configureApp` was not being applied because the default CORS middleware was registered before user configuration. - **Usage Example:** + ## The Problem - ```typescript - import { - Agent, - createHooks, - createTool, - type OperationContext, - type ToolExecutionContext, - } from "@voltagent/core"; - import { z } from "zod"; + When users configured custom CORS settings in `configureApp`, their configuration was ignored: + - Default CORS middleware (`origin: "*"`) was applied before `configureApp` was called + - Hono middleware executes in registration order, so default CORS handled OPTIONS requests first + - Custom CORS middleware never executed, causing incorrect CORS headers in responses - // Define hooks that set and retrieve data - const hooks = createHooks({ - onStart: (agent: Agent, context: OperationContext) => { - // Set data needed throughout the operation and potentially by tools - const requestId = `req-${Date.now()}`; - const traceId = `trace-${Math.random().toString(16).substring(2, 8)}`; - context.userContext.set("requestId", requestId); - context.userContext.set("traceId", traceId); - console.log( - `[${agent.name}] Operation started. RequestID: ${requestId}, TraceID: ${traceId}` - ); - }, - onEnd: (agent: Agent, result: any, context: OperationContext) => { - // Retrieve data at the end of the operation - const requestId = context.userContext.get("requestId"); - const traceId = context.userContext.get("traceId"); // Can retrieve traceId here too - console.log( - `[${agent.name}] Operation finished. RequestID: ${requestId}, TraceID: ${traceId}` - ); - // Use these IDs for logging, metrics, cleanup, etc. - }, - }); + ## The Solution + - Restructured middleware execution order to call `configureApp` **first** + - Added detection logic to identify when users configure custom CORS + - Default CORS now only applies if user hasn't configured custom CORS + - Custom CORS configuration takes full control when present - // Define a tool that uses the context data set in onStart - const customContextTool = createTool({ - name: "custom_context_logger", - description: "Logs a message using trace ID from the user context.", - parameters: z.object({ - message: z.string().describe("The message to log."), + ## Impact + - Custom CORS configurations in `configureApp` now work correctly + - Users can specify custom origins, headers, methods, and credentials + - Maintains backward compatibility - default CORS still applies when no custom CORS is configured + - Updated documentation with middleware execution order and CORS configuration examples + + ## Example Usage + + ```typescript + import { VoltAgent } from "@voltagent/core"; + import { honoServer } from "@voltagent/server-hono"; + import { cors } from "hono/cors"; + + new VoltAgent({ + agents: { myAgent }, + server: honoServer({ + configureApp: (app) => { + // Custom CORS configuration now works correctly + app.use( + "*", + cors({ + origin: "https://your-domain.com", + allowHeaders: ["X-Custom-Header", "Content-Type"], + allowMethods: ["POST", "GET", "OPTIONS"], + credentials: true, + }) + ); + }, }), - execute: async (params: { message: string }, options?: ToolExecutionContext) => { - // Access userContext via options.operationContext - const traceId = options?.operationContext?.userContext?.get("traceId") || "unknown-trace"; - const requestId = - options?.operationContext?.userContext?.get("requestId") || "unknown-request"; // Can access requestId too - const logMessage = `[RequestID: ${requestId}, TraceID: ${traceId}] Tool Log: ${params.message}`; - console.log(logMessage); - // In a real scenario, you might interact with external systems using these IDs - return `Logged message with RequestID: ${requestId} and TraceID: ${traceId}`; - }, }); + ``` - // Create an agent with the tool and hooks - const agent = new Agent({ - name: "MyCombinedAgent", - llm: myLlmProvider, // Your LLM provider instance - model: myModel, // Your model instance - tools: [customContextTool], - hooks: hooks, - }); +## 1.0.20 - // Trigger the agent. The LLM might decide to use the tool. - await agent.generateText( - "Log the following information using the custom logger: 'User feedback received.'" - ); +### Patch Changes - // Console output will show logs from onStart, the tool (if called), and onEnd, - // demonstrating context data flow. - ``` +- [#696](https://github.com/VoltAgent/voltagent/pull/696) [`69bc5bf`](https://github.com/VoltAgent/voltagent/commit/69bc5bf1c0ccedd65964f9b878cc57318b82a8a4) Thanks [@fav-devs](https://github.com/fav-devs)! - Add hostname configuration option to honoServer() to support IPv6 and dual-stack networking. -- [#71](https://github.com/VoltAgent/voltagent/pull/71) [`1f20509`](https://github.com/VoltAgent/voltagent/commit/1f20509528fc2cb2ba00f86d649848afae34af04) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Standardize Agent Error and Finish Handling + The honoServer() function now accepts a `hostname` option that allows configuring which network interface the server binds to. This fixes deployment issues on platforms like Railway that require IPv6 binding for private networking. - This change introduces a more robust and consistent way errors and successful finishes are handled across the `@voltagent/core` Agent and LLM provider implementations (like `@voltagent/vercel-ai`). + **Example usage:** - **Key Improvements:** - - **Standardized Errors (`VoltAgentError`):** - - Introduced `VoltAgentError`, `ToolErrorInfo`, and `StreamOnErrorCallback` types in `@voltagent/core`. - - LLM Providers (e.g., Vercel) now wrap underlying SDK/API errors into a structured `VoltAgentError` before passing them to `onError` callbacks or throwing them. - - Agent methods (`generateText`, `streamText`, `generateObject`, `streamObject`) now consistently handle `VoltAgentError`, enabling richer context (stage, code, tool details) in history events and logs. + ```typescript + import { honoServer } from "@voltagent/server-hono"; - - **Standardized Stream Finish Results:** - - Introduced `StreamTextFinishResult`, `StreamTextOnFinishCallback`, `StreamObjectFinishResult`, and `StreamObjectOnFinishCallback` types in `@voltagent/core`. - - LLM Providers (e.g., Vercel) now construct these standardized result objects upon successful stream completion. - - Agent streaming methods (`streamText`, `streamObject`) now receive these standardized results in their `onFinish` handlers, ensuring consistent access to final output (`text` or `object`), `usage`, `finishReason`, etc., for history, events, and hooks. + new VoltAgent({ + agents, + server: honoServer({ + port: 8080, + hostname: "::", // Binds to IPv6/dual-stack + }), + }); + ``` - - **Updated Interfaces:** The `LLMProvider` interface and related options types (`StreamTextOptions`, `StreamObjectOptions`) have been updated to reflect these new standardized callback types and error-throwing expectations. + **Options:** + - `"0.0.0.0"` - Binds to all IPv4 interfaces (default, maintains backward compatibility) + - `"::"` - Binds to all IPv6 interfaces (dual-stack on most systems) + - `"localhost"` or `"127.0.0.1"` - Only localhost access - These changes lead to more predictable behavior, improved debugging capabilities through structured errors, and a more consistent experience when working with different LLM providers. + Fixes #694 -- [`7a7a0f6`](https://github.com/VoltAgent/voltagent/commit/7a7a0f672adbe42635c3edc5f0a7f282575d0932) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Refactor Agent Hooks Signature to Use Single Argument Object - #57 +## 1.0.19 - This change refactors the signature for all agent hooks (`onStart`, `onEnd`, `onToolStart`, `onToolEnd`, `onHandoff`) in `@voltagent/core` to improve usability, readability, and extensibility. +### Patch Changes - **Key Changes:** - - **Single Argument Object:** All hooks now accept a single argument object containing named properties (e.g., `{ agent, context, output, error }`) instead of positional arguments. - - **`onEnd` / `onToolEnd` Refinement:** The `onEnd` and `onToolEnd` hooks no longer use an `isError` flag or a combined `outputOrError` parameter. They now have distinct `output: | undefined` and `error: VoltAgentError | undefined` properties, making it explicit whether the operation or tool execution succeeded or failed. - - **Unified `onEnd` Output:** The `output` type for the `onEnd` hook (`AgentOperationOutput`) is now a standardized union type, providing a consistent structure regardless of which agent method (`generateText`, `streamText`, etc.) completed successfully. +- [#695](https://github.com/VoltAgent/voltagent/pull/695) [`66a1bff`](https://github.com/VoltAgent/voltagent/commit/66a1bfff1c7258c79935af4e4361b2fc043d2d1f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add hostname configuration support to honoServer - #694 - **Migration Guide:** + ## The Problem - If you have implemented custom agent hooks, you will need to update their signatures: + The `honoServer()` function hardcoded `hostname: "0.0.0.0"` which prevented binding to IPv6 addresses. This caused deployment issues on platforms like Railway that require IPv6 or dual-stack binding for private networking. - **Before:** + ## The Solution + + Added a `hostname` configuration option to `HonoServerConfig` that allows users to specify which network interface to bind to. The default remains `"0.0.0.0"` for backward compatibility. + + ## Usage Examples + + **Default behavior (IPv4 only):** ```typescript - const myHooks = { - onStart: async (agent, context) => { - /* ... */ - }, - onEnd: async (agent, outputOrError, context, isError) => { - if (isError) { - // Handle error (outputOrError is the error) - } else { - // Handle success (outputOrError is the output) - } - }, - onToolStart: async (agent, tool, context) => { - /* ... */ - }, - onToolEnd: async (agent, tool, result, context) => { - // Assuming result might contain an error or be the success output - }, - // ... - }; + new VoltAgent({ + agents: { myAgent }, + server: honoServer({ + port: 3141, + }), + }); + // Binds to 0.0.0.0 (all IPv4 interfaces) ``` - **After:** + **IPv6 dual-stack (recommended for Railway, Fly.io):** ```typescript - import type { - OnStartHookArgs, - OnEndHookArgs, - OnToolStartHookArgs, - OnToolEndHookArgs, - // ... other needed types - } from "@voltagent/core"; - - const myHooks = { - onStart: async (args: OnStartHookArgs) => { - const { agent, context } = args; - /* ... */ - }, - onEnd: async (args: OnEndHookArgs) => { - const { agent, output, error, context } = args; - if (error) { - // Handle error (error is VoltAgentError) - } else if (output) { - // Handle success (output is AgentOperationOutput) - } - }, - onToolStart: async (args: OnToolStartHookArgs) => { - const { agent, tool, context } = args; - /* ... */ - }, - onToolEnd: async (args: OnToolEndHookArgs) => { - const { agent, tool, output, error, context } = args; - if (error) { - // Handle tool error (error is VoltAgentError) - } else { - // Handle tool success (output is the result) - } - }, - // ... - }; + new VoltAgent({ + agents: { myAgent }, + server: honoServer({ + port: 3141, + hostname: "::", // Binds to both IPv4 and IPv6 + }), + }); ``` - Update your hook function definitions to accept the single argument object and use destructuring or direct property access (`args.propertyName`) to get the required data. - -## 0.1.8 + **Localhost only:** -### Patch Changes + ```typescript + new VoltAgent({ + agents: { myAgent }, + server: honoServer({ + port: 3141, + hostname: "127.0.0.1", // Local development only + }), + }); + ``` -- [#51](https://github.com/VoltAgent/voltagent/pull/51) [`55c58b0`](https://github.com/VoltAgent/voltagent/commit/55c58b0da12dd94a3095aad4bc74c90757c98db4) Thanks [@kwaa](https://github.com/kwaa)! - Use the latest Hono to avoid duplicate dependencies + **Environment-based configuration:** -- [#59](https://github.com/VoltAgent/voltagent/pull/59) [`d40cb14`](https://github.com/VoltAgent/voltagent/commit/d40cb14860a5abe8771e0b91200d10f522c62881) Thanks [@kwaa](https://github.com/kwaa)! - fix: add package exports + ```typescript + new VoltAgent({ + agents: { myAgent }, + server: honoServer({ + port: parseInt(process.env.PORT || "3141"), + hostname: process.env.HOSTNAME || "::", // Default to dual-stack + }), + }); + ``` -- [`e88cb12`](https://github.com/VoltAgent/voltagent/commit/e88cb1249c4189ced9e245069bed5eab71cdd894) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Enhance `createPrompt` with Template Literal Type Inference + This change is fully backward compatible and enables VoltAgent to work seamlessly on modern cloud platforms with IPv6 networking. - Improved the `createPrompt` utility to leverage TypeScript's template literal types. This provides strong type safety by: - - Automatically inferring required variable names directly from `{{variable}}` placeholders in the template string. - - Enforcing the provision of all required variables with the correct types at compile time when calling `createPrompt`. +## 1.0.18 - This significantly reduces the risk of runtime errors caused by missing or misspelled prompt variables. +### Patch Changes -- [#65](https://github.com/VoltAgent/voltagent/pull/65) [`0651d35`](https://github.com/VoltAgent/voltagent/commit/0651d35442cda32b6057f8b7daf7fd8655a9a2a4) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Add OpenAPI (Swagger) Documentation for Core API - #64 - - Integrated `@hono/zod-openapi` and `@hono/swagger-ui` to provide interactive API documentation. - - Documented the following core endpoints with request/response schemas, parameters, and examples: - - `GET /agents`: List all registered agents. - - `POST /agents/{id}/text`: Generate text response. - - `POST /agents/{id}/stream`: Stream text response (SSE). - - `POST /agents/{id}/object`: Generate object response (Note: Requires backend update to fully support JSON Schema input). - - `POST /agents/{id}/stream-object`: Stream object response (SSE) (Note: Requires backend update to fully support JSON Schema input). - - Added `/doc` endpoint serving the OpenAPI 3.1 specification in JSON format. - - Added `/ui` endpoint serving the interactive Swagger UI. - - Improved API discoverability: - - Added links to Swagger UI and OpenAPI Spec on the root (`/`) endpoint. - - Added links to Swagger UI in the server startup console logs. - - Refactored API schemas and route definitions into `api.routes.ts` for better organization. - - Standardized generation options (like `userId`, `temperature`, `maxTokens`) in the API schema with descriptions, examples, and sensible defaults. +- [#676](https://github.com/VoltAgent/voltagent/pull/676) [`8781956`](https://github.com/VoltAgent/voltagent/commit/8781956ad86ec731684f0ca92ef28c65f26e1229) Thanks [@venatir](https://github.com/venatir)! - fix(auth-context): retain context in response body and options for user authentication -## 0.1.7 +- Updated dependencies [[`78b9727`](https://github.com/VoltAgent/voltagent/commit/78b9727e85a31fd8eaa9c333de373d982f58b04f), [`6d00793`](https://github.com/VoltAgent/voltagent/commit/6d007938d31c6d928185153834661c50227af326), [`7fef3a7`](https://github.com/VoltAgent/voltagent/commit/7fef3a7ea1b3f7f8c780a528d3c3abce312f3be9), [`c4d13f2`](https://github.com/VoltAgent/voltagent/commit/c4d13f2be129013eed6392990863ae85cdbd8855)]: + - @voltagent/core@1.1.26 + - @voltagent/mcp-server@1.0.2 + +## 1.0.17 ### Patch Changes -- [`e328613`](https://github.com/VoltAgent/voltagent/commit/e32861366852f4bb7ad8854527b2bb6525703a25) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: prevent `ReferenceError: module is not defined` in ES module environments by adding guards around the CommonJS-specific `require.main === module` check in the main entry point. +- [#664](https://github.com/VoltAgent/voltagent/pull/664) [`f46aae9`](https://github.com/VoltAgent/voltagent/commit/f46aae9784b6a7e86a33b55d59d90a8f4f1489f4) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: vendored Hono OpenAPI adapters to eliminate pnpm alias requirement and auto-select Zod v3/v4 support; docs now clarify that installing `zod` is sufficient. #651 -## 0.1.6 +## 1.0.16 ### Patch Changes -- [#41](https://github.com/VoltAgent/voltagent/pull/41) [`52d5fa9`](https://github.com/VoltAgent/voltagent/commit/52d5fa94045481dc43dc260a40b701606190585c) Thanks [@omeraplak](https://github.com/omeraplak)! - ## Introducing Toolkits for Better Tool Management +- [#637](https://github.com/VoltAgent/voltagent/pull/637) [`b7ee693`](https://github.com/VoltAgent/voltagent/commit/b7ee6936280b5d09b893db6500ad58b4ac80eaf2) Thanks [@marinoska](https://github.com/marinoska)! - - Introduced tests and documentation for the `ToolDeniedError`. + - Added a feature to terminate the process flow when the `onToolStart` hook triggers a `ToolDeniedError`. + - Enhanced error handling mechanisms to ensure proper flow termination in specific error scenarios. +- Updated dependencies [[`4c42bf7`](https://github.com/VoltAgent/voltagent/commit/4c42bf72834d3cd45ff5246ef65d7b08470d6a8e), [`b7ee693`](https://github.com/VoltAgent/voltagent/commit/b7ee6936280b5d09b893db6500ad58b4ac80eaf2)]: + - @voltagent/core@1.1.24 + - @voltagent/server-core@1.0.15 - Managing related tools and their instructions is now simpler with `Toolkit`s. +## 1.0.15 - **Motivation:** - - Defining shared instructions for multiple related tools was cumbersome. - - The logic for deciding which instructions to add to the agent's system prompt could become complex. - - We wanted a cleaner way to group tools logically. +### Patch Changes - **What's New: The `Toolkit`** +- [`ca6160a`](https://github.com/VoltAgent/voltagent/commit/ca6160a2f5098f296729dcd842a013558d14eeb8) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: updates endpoint - A `Toolkit` bundles related tools and allows defining shared `instructions` and an `addInstructions` flag _at the toolkit level_. +- Updated dependencies [[`ca6160a`](https://github.com/VoltAgent/voltagent/commit/ca6160a2f5098f296729dcd842a013558d14eeb8)]: + - @voltagent/server-core@1.0.14 - ```typescript - // packages/core/src/tool/toolkit.ts - export type Toolkit = { - /** - * Unique identifier name for the toolkit. - */ - name: string; - /** - * A brief description of what the toolkit does. Optional. - */ - description?: string; - /** - * Shared instructions for the LLM on how to use the tools within this toolkit. - * Optional. - */ - instructions?: string; - /** - * Whether to automatically add the toolkit's `instructions` to the agent's system prompt. - * Defaults to false. - */ - addInstructions?: boolean; - /** - * An array of Tool instances that belong to this toolkit. - */ - tools: Tool[]; - }; - ``` +## 1.0.14 - **Key Changes to Core:** - 1. **`ToolManager` Upgrade:** Now manages both `Tool` and `Toolkit` objects. - 2. **`AgentOptions` Update:** The `tools` option accepts `(Tool | Toolkit)[]`. - 3. **Simplified Instruction Handling:** `Agent` now only adds instructions from `Toolkit`s where `addInstructions` is true. +### Patch Changes - This change leads to a clearer separation of concerns, simplifies the agent's internal logic, and makes managing tool instructions more predictable and powerful. +- [#629](https://github.com/VoltAgent/voltagent/pull/629) [`3e64b9c`](https://github.com/VoltAgent/voltagent/commit/3e64b9ce58d0e91bc272f491be2c1932a005ef48) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add memory observability - ### New `createToolkit` Helper +- Updated dependencies [[`3e64b9c`](https://github.com/VoltAgent/voltagent/commit/3e64b9ce58d0e91bc272f491be2c1932a005ef48)]: + - @voltagent/server-core@1.0.13 + - @voltagent/core@1.1.22 - We've also added a helper function, `createToolkit`, to simplify the creation of toolkits. It provides default values and basic validation: +## 1.0.13 - ```typescript - // packages/core/src/tool/toolkit.ts - export const createToolkit = (options: Toolkit): Toolkit => { - if (!options.name) { - throw new Error("Toolkit name is required"); - } - if (!options.tools || options.tools.length === 0) { - console.warn(`Toolkit '${options.name}' created without any tools.`); - } +### Patch Changes - return { - name: options.name, - description: options.description || "", // Default empty description - instructions: options.instructions, - addInstructions: options.addInstructions || false, // Default to false - tools: options.tools || [], // Default to empty array - }; - }; - ``` +- [`d000689`](https://github.com/VoltAgent/voltagent/commit/d00068907428c407757e35f426746924e1617b61) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: zod@4 and zod@3 compability - **Example Usage:** +## 1.0.12 - ```typescript - import { createTool, createToolkit } from "@voltagent/core"; - import { z } from "zod"; +### Patch Changes - // Define some tools first - const getWeather = createTool({ - name: "getWeather", - description: "Gets the weather for a location.", - schema: z.object({ location: z.string() }), - run: async ({ location }) => ({ temperature: "25C", condition: "Sunny" }), - }); +- [`c738241`](https://github.com/VoltAgent/voltagent/commit/c738241fea017eeb3c6e3ceb27436ab2f027c48d) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: zod@4 swagger doc issue - const searchWeb = createTool({ - name: "searchWeb", - description: "Searches the web for a query.", - schema: z.object({ query: z.string() }), - run: async ({ query }) => ({ results: ["Result 1", "Result 2"] }), - }); +- Updated dependencies [[`c738241`](https://github.com/VoltAgent/voltagent/commit/c738241fea017eeb3c6e3ceb27436ab2f027c48d)]: + - @voltagent/server-core@1.0.11 - // Create a toolkit using the helper - const webInfoToolkit = createToolkit({ - name: "web_information", - description: "Tools for getting information from the web.", - addInstructions: true, // Add the instructions to the system prompt - tools: [getWeather, searchWeb], - }); +## 1.0.11 - console.log(webInfoToolkit); - /* - Output: - { - name: 'web_information', - description: 'Tools for getting information from the web.', - instructions: 'Use these tools to find current information online.', - addInstructions: true, - tools: [ [Object Tool: getWeather], [Object Tool: searchWeb] ] - } - */ - ``` +### Patch Changes -- [#33](https://github.com/VoltAgent/voltagent/pull/33) [`3ef2eaa`](https://github.com/VoltAgent/voltagent/commit/3ef2eaa9661e8ecfebf17af56b09af41285d0ca9) Thanks [@kwaa](https://github.com/kwaa)! - Update package.json files: - - Remove `src` directory from the `files` array. - - Add explicit `exports` field for better module resolution. +- [#609](https://github.com/VoltAgent/voltagent/pull/609) [`942663f`](https://github.com/VoltAgent/voltagent/commit/942663f74dca0df70cdac323102acb18c050fa65) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add workflow cancellation support, including cancellation metadata, default controller updates, and a new API endpoint for cancelling executions - #608 -- [#41](https://github.com/VoltAgent/voltagent/pull/41) [`52d5fa9`](https://github.com/VoltAgent/voltagent/commit/52d5fa94045481dc43dc260a40b701606190585c) Thanks [@omeraplak](https://github.com/omeraplak)! - ## Introducing Reasoning Tools Helper + ## Usage Example - This update introduces a new helper function, `createReasoningTools`, to easily add step-by-step reasoning capabilities to your agents. #24 + ```ts + import { createSuspendController } from "@voltagent/core"; - ### New `createReasoningTools` Helper + const controller = createSuspendController(); + const stream = workflow.stream(input, { suspendController: controller }); - **Feature:** Easily add `think` and `analyze` tools for step-by-step reasoning. + // Cancel from application code + controller.cancel("User stopped the workflow"); - We've added a new helper function, `createReasoningTools`, which makes it trivial to equip your agents with structured thinking capabilities, similar to patterns seen in advanced AI systems. - - **What it does:** Returns a pre-configured `Toolkit` named `reasoning_tools`. - - **Tools included:** Contains the `think` tool (for internal monologue/planning) and the `analyze` tool (for evaluating results and deciding next steps). - - **Instructions:** Includes detailed instructions explaining how the agent should use these tools iteratively to solve problems. You can choose whether these instructions are automatically added to the system prompt via the `addInstructions` option. + // Or via HTTP + await fetch(`/api/workflows/${workflowId}/executions/${executionId}/cancel`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ reason: "User stopped the workflow" }), + }); + ``` - ```typescript - import { createReasoningTools, type Toolkit } from "@voltagent/core"; +- Updated dependencies [[`942663f`](https://github.com/VoltAgent/voltagent/commit/942663f74dca0df70cdac323102acb18c050fa65)]: + - @voltagent/core@1.1.16 + - @voltagent/server-core@1.0.10 - // Get the reasoning toolkit (with instructions included in the system prompt) - const reasoningToolkit: Toolkit = createReasoningTools({ addInstructions: true }); +## 1.0.10 - // Get the toolkit without automatically adding instructions - const reasoningToolkitManual: Toolkit = createReasoningTools({ addInstructions: false }); - ``` +### Patch Changes - ### How to Use Reasoning Tools +- [`8997e35`](https://github.com/VoltAgent/voltagent/commit/8997e3572113ebdab21ce4ccd7a15c4333f7e915) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: zod@4 compability - Pass the `Toolkit` object returned by `createReasoningTools` directly to the agent's `tools` array. +## 1.0.9 - ```typescript - // Example: Using the new reasoning tools helper - import { Agent, createReasoningTools, type Toolkit } from "@voltagent/core"; - import { VercelAIProvider } from "@voltagent/vercel-ai"; - import { openai } from "@ai-sdk/openai"; +### Patch Changes - const reasoningToolkit: Toolkit = createReasoningTools({ - addInstructions: true, - }); +- [`325bc30`](https://github.com/VoltAgent/voltagent/commit/325bc303bd8e99b8f3e8ecd6ea011dcff3500809) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: prevent Swagger/OpenAPI from registering MCP and A2A endpoints when no servers are configured and ensure path parameters declare required metadata, avoiding `/doc` errors in projects that omit those optional packages. - const agent = new Agent({ - name: "MyThinkingAgent", - instructions: "An agent equipped with reasoning tools.", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - tools: [reasoningToolkit], // Pass the toolkit - }); +## 1.0.8 - // Agent's system message will include reasoning instructions. - ``` +### Patch Changes - This change simplifies adding reasoning capabilities to your agents. +- [`e4d51da`](https://github.com/VoltAgent/voltagent/commit/e4d51da4161b69cbe0ac737aeca6842a48a4568c) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: prevent Swagger/OpenAPI from registering MCP and A2A endpoints when no servers are configured, avoiding `/doc` errors in projects that omit those optional packages. -## 0.1.5 +## 1.0.7 ### Patch Changes -- [#35](https://github.com/VoltAgent/voltagent/pull/35) [`9acbbb8`](https://github.com/VoltAgent/voltagent/commit/9acbbb898a517902cbdcb7ae7a8460e9d35f3dbe) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: Prevent potential error when accessing debug option in LibSQLStorage - #34 - - Modified the `debug` method within the `LibSQLStorage` class. - - Changed the access to `this.options.debug` to use optional chaining (`this.options?.debug`). +- [#596](https://github.com/VoltAgent/voltagent/pull/596) [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7) Thanks [@omeraplak](https://github.com/omeraplak)! - - add `@voltagent/a2a-server`, a JSON-RPC Agent-to-Agent (A2A) server that lets external agents call your VoltAgent instance over HTTP/SSE + - teach `@voltagent/core`, `@voltagent/server-core`, and `@voltagent/server-hono` to auto-register configured A2A servers so adding `{ a2aServers: { ... } }` on `VoltAgent` and opting into `honoServer` instantly exposes discovery and RPC endpoints + - forward request context (`userId`, `sessionId`, metadata) into agent invocations and provide task management hooks, plus allow filtering/augmenting exposed agents by default + - document the setup in `website/docs/agents/a2a/a2a-server.md` and refresh `examples/with-a2a-server` with basic usage and task-store customization + - A2A endpoints are now described in Swagger/OpenAPI and listed in the startup banner whenever an A2A server is registered, making discovery of `/.well-known/...` and `/a2a/:serverId` routes trivial. - This change prevents runtime errors that could occur in specific environments, such as Next.js, if the `debug` method is invoked before the `options` object is fully initialized or if `options` becomes unexpectedly `null` or `undefined`. It ensures the debug logging mechanism is more robust. + **Getting started** -## 0.1.4 + ```ts + import { Agent, VoltAgent } from "@voltagent/core"; + import { A2AServer } from "@voltagent/a2a-server"; + import { honoServer } from "@voltagent/server-hono"; -### Patch Changes + const assistant = new Agent({ + name: "SupportAgent", + purpose: "Handle support questions from partner agents.", + model: myModel, + }); -- [#27](https://github.com/VoltAgent/voltagent/pull/27) [`3c0829d`](https://github.com/VoltAgent/voltagent/commit/3c0829dcec4db9596147b583a9cf2d4448bc30f1) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve sub-agent context sharing for sequential task execution - #30 + const a2aServer = new A2AServer({ + name: "support-agent", + version: "0.1.0", + }); - Enhanced the Agent system to properly handle context sharing between sub-agents, enabling reliable sequential task execution. The changes include: - - Adding `contextMessages` parameter to `getSystemMessage` method - - Refactoring `prepareAgentsMemory` to properly format conversation history - - Ensuring conversation context is correctly passed between delegated tasks - - Enhancing system prompts to better handle sequential workflows + export const voltAgent = new VoltAgent({ + agents: { assistant }, + a2aServers: { a2aServer }, + server: honoServer({ port: 3141 }), + }); + ``` - This fixes issues where the second agent in a sequence would not have access to the first agent's output, causing failures in multi-step workflows. +- [#596](https://github.com/VoltAgent/voltagent/pull/596) [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7) Thanks [@omeraplak](https://github.com/omeraplak)! - ## ✨ New: first-class Model Context Protocol support -## 0.1.1 + We shipped a complete MCP integration stack: + - `@voltagent/mcp-server` exposes VoltAgent registries (agents, workflows, tools) over stdio/HTTP/SSE transports. + - `@voltagent/server-core` and `@voltagent/server-hono` gained ready-made route handlers so HTTP servers can proxy MCP traffic with a few lines of glue code. + - `@voltagent/core` exports the shared types that the MCP layers rely on. -- 🚀 **Introducing VoltAgent: TypeScript AI Agent Framework!** + ### Quick start - This initial release marks the beginning of VoltAgent, a powerful toolkit crafted for the JavaScript developer community. We saw the challenges: the complexity of building AI from scratch, the limitations of No-Code tools, and the lack of first-class AI tooling specifically for JS. + ```ts title="src/mcp/server.ts" + import { MCPServer } from "@voltagent/mcp-server"; + import { Agent, createTool } from "@voltagent/core"; + import { openai } from "@ai-sdk/openai"; + import { z } from "zod"; - ![VoltAgent Demo](https://cdn.voltagent.dev/readme/demo.gif) - VoltAgent aims to fix that by providing the building blocks you need: - - **`@voltagent/core`**: The foundational engine for agent capabilities. - - **`@voltagent/voice`**: Easily add voice interaction. - - **`@voltagent/vercel-ai`**: Seamless integration with [Vercel AI SDK](https://sdk.vercel.ai/docs/introduction). - - **`@voltagent/xsai`**: A Seamless integration with [xsAI](https://xsai.js.org/). - - **`@voltagent/cli` & `create-voltagent-app`**: Quick start tools to get you building _fast_. + const status = createTool({ + name: "status", + description: "Return the current time", + parameters: z.object({}), + async execute() { + return { status: "ok", time: new Date().toISOString() }; + }, + }); - We're combining the flexibility of code with the clarity of visual tools (like our **currently live [VoltOps LLM Observability Platform](https://console.voltagent.dev/)**) to make AI development easier, clearer, and more powerful. Join us as we build the future of AI in JavaScript! + const assistant = new Agent({ + name: "Support Agent", + instructions: "Route customer tickets to the correct queue.", + model: openai("gpt-4o-mini"), + tools: [status], + }); - Explore the [Docs](https://voltagent.dev/docs/) and join our [Discord community](https://s.voltagent.dev/discord)! + export const mcpServer = new MCPServer({ + name: "voltagent-example", + version: "0.1.0", + description: "Expose VoltAgent over MCP", + agents: { support: assistant }, + tools: { status }, + filterTools: ({ items }) => items.filter((tool) => tool.name !== "debug"), + }); + ``` ---- + With the server registered on your VoltAgent instance (and the Hono MCP routes enabled), the same agents, workflows, and tools become discoverable from VoltOps Console or any MCP-compatible IDE. -## Package: @voltagent/cli +- [#596](https://github.com/VoltAgent/voltagent/pull/596) [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7) Thanks [@omeraplak](https://github.com/omeraplak)! - - Ship `@voltagent/mcp-server`, a transport-agnostic MCP provider that surfaces VoltAgent agents, workflows, tools, prompts, and resources over stdio, SSE, and HTTP. + - Wire MCP registration through `@voltagent/core`, `@voltagent/server-core`, and `@voltagent/server-hono` so a single `VoltAgent` constructor opt-in (optionally with `honoServer`) exposes stdio mode immediately and HTTP/SSE endpoints when desired. + - Filter child sub-agents automatically and lift an agent's `purpose` (fallback to `instructions`) into the MCP tool description for cleaner IDE listings out of the box. + - Document the workflow in `website/docs/agents/mcp/mcp-server.md` and refresh `examples/with-mcp-server` with stdio-only and HTTP/SSE configurations. + - When MCP is enabled we now publish REST endpoints in Swagger/OpenAPI and echo them in the startup banner so you can discover `/mcp/*` routes without digging through code. -## 0.1.10 + **Getting started** -### Patch Changes + ```ts + import { Agent, VoltAgent } from "@voltagent/core"; + import { MCPServer } from "@voltagent/mcp-server"; + import { honoServer } from "@voltagent/server-hono"; -- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements + const assistant = new Agent({ + name: "AssistantAgent", + purpose: "Respond to support questions and invoke helper tools when needed.", + model: myModel, + }); - This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + const mcpServer = new MCPServer({ + name: "support-mcp", + version: "1.0.0", + agents: { assistant }, + protocols: { stdio: true, http: false, sse: false }, + }); - **Key improvements:** - - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs - - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration - - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries - - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup - - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + export const voltAgent = new VoltAgent({ + agents: { assistant }, + mcpServers: { primary: mcpServer }, + server: honoServer({ port: 3141 }), // flip http/sse to true when you need remote clients + }); + ``` - These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. +- Updated dependencies [[`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7), [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7), [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7)]: + - @voltagent/server-core@1.0.9 + - @voltagent/a2a-server@1.0.1 + - @voltagent/internal@0.0.11 + - @voltagent/core@1.1.13 + - @voltagent/mcp-server@1.0.1 -## 0.1.9 +## 1.0.6 ### Patch Changes -- [`00d70cb`](https://github.com/VoltAgent/voltagent/commit/00d70cbb570e4d748ab37e177e4e5df869d52e03) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: update VoltAgent docs MCP configs +- [`9cc4ea4`](https://github.com/VoltAgent/voltagent/commit/9cc4ea4a4985320139e33e8029f299c7ec8329a6) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: @voltagent/core peerDependency version -## 0.1.8 +- Updated dependencies [[`05ddac1`](https://github.com/VoltAgent/voltagent/commit/05ddac1ac9404cd6062d2e448b0ce4df90ecd748), [`9cc4ea4`](https://github.com/VoltAgent/voltagent/commit/9cc4ea4a4985320139e33e8029f299c7ec8329a6)]: + - @voltagent/server-core@1.0.8 + +## 1.0.5 ### Patch Changes -- [#278](https://github.com/VoltAgent/voltagent/pull/278) [`85d979d`](https://github.com/VoltAgent/voltagent/commit/85d979d5205f23ab6e3a85e68af6c46fa7c0f648) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: introduce VoltAgent MCP Docs Server for IDE integration +- [#571](https://github.com/VoltAgent/voltagent/pull/571) [`b801a8d`](https://github.com/VoltAgent/voltagent/commit/b801a8da47da5cad15b8637635f83acab5e0d6fc) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: add Zod v3/v4 compatibility layer for @hono/zod-openapi + - Added dynamic detection of Zod version using `toJSONSchema` method check + - Conditionally loads correct @hono/zod-openapi version based on installed Zod + - Fixed route definitions to use enhanced `z` from zod-openapi-compat instead of extending base schemas + - Resolves `.openapi()` method not found errors when using Zod v4 - Added comprehensive MCP (Model Context Protocol) Docs Server integration to enable AI assistants in IDEs to access VoltAgent documentation directly. This feature allows developers to ask their AI assistants questions about VoltAgent directly within their development environment. +- [#571](https://github.com/VoltAgent/voltagent/pull/571) [`b801a8d`](https://github.com/VoltAgent/voltagent/commit/b801a8da47da5cad15b8637635f83acab5e0d6fc) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Zod v4 support (backwards-compatible with v3) - **New Features:** - - **`@voltagent/docs-mcp`** package: MCP server that provides access to VoltAgent documentation - - **CLI MCP commands**: Setup, test, status, and remove MCP configurations - - `volt mcp setup` - Interactive setup for Cursor, Windsurf, or VS Code - - `volt mcp test` - Test MCP connection and provide usage examples - - `volt mcp status` - Show current MCP configuration status - - `volt mcp remove` - Remove MCP configuration - - **IDE Configuration**: Automatic configuration file generation for supported IDEs - - **Multi-IDE Support**: Works with Cursor, Windsurf, and VS Code + What’s new + - Core + server now support `zod` v4 while keeping v3 working. + - Peer ranges expanded to `"zod": "^3.25.0 || ^4.0.0"`. + - JSON Schema → Zod conversion handles both versions: + - Uses `zod-from-json-schema@^0.5.0` when Zod v4 is detected. + - Falls back to `zod-from-json-schema@^0.0.5` via alias `zod-from-json-schema-v3` for Zod v3. + - Implemented in MCP client (core) and object handlers (server-core). - **Usage:** + Why + - Zod v4 introduces changes that require a version-aware conversion path. This update adds seamless compatibility for both major versions. - ```bash - # Setup MCP for your IDE - volt mcp setup + Impact + - No breaking changes. Projects on Zod v3 continue to work unchanged. Projects can upgrade to Zod v4 without code changes. - # Test the connection - volt mcp test + Notes + - If your bundler disallows npm aliasing, ensure it can resolve `zod-from-json-schema-v3` (alias to `zod-from-json-schema@^0.0.5`). - # Check status - volt mcp status - ``` +- Updated dependencies [[`b801a8d`](https://github.com/VoltAgent/voltagent/commit/b801a8da47da5cad15b8637635f83acab5e0d6fc)]: + - @voltagent/server-core@1.0.7 - Once configured, developers can ask their AI assistant questions like: - - "How do I create an agent in VoltAgent?" - - "Is there a VoltAgent example with Next.js?" - - "How do I use voice features?" - - "What are the latest updates?" +## 1.0.5-next.2 - The MCP server provides real-time access to VoltAgent documentation, examples, and best practices directly within the IDE environment. +### Patch Changes -## 0.1.7 +- [`7d05717`](https://github.com/VoltAgent/voltagent/commit/7d057172029e594b8fe7c77e7fe49fdb3c937ac3) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: add Zod v3/v4 compatibility layer for @hono/zod-openapi + - Added dynamic detection of Zod version using `toJSONSchema` method check + - Conditionally loads correct @hono/zod-openapi version based on installed Zod + - Fixed route definitions to use enhanced `z` from zod-openapi-compat instead of extending base schemas + - Resolves `.openapi()` method not found errors when using Zod v4 + +## 1.0.5-next.1 ### Patch Changes -- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 +- [#551](https://github.com/VoltAgent/voltagent/pull/551) [`77a3f64`](https://github.com/VoltAgent/voltagent/commit/77a3f64dea6e8a06fbbd72878711efa9ceb90bc3) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Zod v4 support (backwards-compatible with v3) -## 0.1.6 + What’s new + - Core + server now support `zod` v4 while keeping v3 working. + - Peer ranges expanded to `"zod": "^3.25.0 || ^4.0.0"`. + - JSON Schema → Zod conversion handles both versions: + - Uses `zod-from-json-schema@^0.5.0` when Zod v4 is detected. + - Falls back to `zod-from-json-schema@^0.0.5` via alias `zod-from-json-schema-v3` for Zod v3. + - Implemented in MCP client (core) and object handlers (server-core). -### Patch Changes + Why + - Zod v4 introduces changes that require a version-aware conversion path. This update adds seamless compatibility for both major versions. -- [#155](https://github.com/VoltAgent/voltagent/pull/155) [`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c) Thanks [@baseballyama](https://github.com/baseballyama)! - chore: update `tsconfig.json`'s `target` to `ES2022` + Impact + - No breaking changes. Projects on Zod v3 continue to work unchanged. Projects can upgrade to Zod v4 without code changes. -## 0.1.5 + Notes + - If your bundler disallows npm aliasing, ensure it can resolve `zod-from-json-schema-v3` (alias to `zod-from-json-schema@^0.0.5`). + +- Updated dependencies [[`78a5046`](https://github.com/VoltAgent/voltagent/commit/78a5046ca4d768a96650ebee63ae1630b0dff7a7)]: + - @voltagent/server-core@1.0.7-next.1 + +## 1.0.5-next.0 ### Patch Changes -- [#102](https://github.com/VoltAgent/voltagent/pull/102) [`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3) Thanks [@omeraplak](https://github.com/omeraplak)! - refactor: use 'instructions' field for Agent definitions in examples - #88 +- [#551](https://github.com/VoltAgent/voltagent/pull/551) [`77a3f64`](https://github.com/VoltAgent/voltagent/commit/77a3f64dea6e8a06fbbd72878711efa9ceb90bc3) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Zod v4 support (backwards-compatible with v3) - Updated documentation examples (READMEs, docs, blogs) and relevant package code examples to use the `instructions` field instead of `description` when defining `Agent` instances. + What’s new + - Core + server now support `zod` v4 while keeping v3 working. + - Peer ranges expanded to `"zod": "^3.25.0 || ^4.0.0"`. + - JSON Schema → Zod conversion handles both versions: + - Uses `zod-from-json-schema@^0.5.0` when Zod v4 is detected. + - Falls back to `zod-from-json-schema@^0.0.5` via alias `zod-from-json-schema-v3` for Zod v3. + - Implemented in MCP client (core) and object handlers (server-core). - This change aligns the examples with the preferred API usage for the `Agent` class, where `instructions` provides behavioral guidance to the agent/LLM. This prepares for the eventual deprecation of the `description` field specifically for `Agent` class definitions. + Why + - Zod v4 introduces changes that require a version-aware conversion path. This update adds seamless compatibility for both major versions. - **Example Change for Agent Definition:** + Impact + - No breaking changes. Projects on Zod v3 continue to work unchanged. Projects can upgrade to Zod v4 without code changes. - ```diff - const agent = new Agent({ - name: "My Assistant", - - description: "A helpful assistant.", - + instructions: "A helpful assistant.", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - }); - ``` + Notes + - If your bundler disallows npm aliasing, ensure it can resolve `zod-from-json-schema-v3` (alias to `zod-from-json-schema@^0.0.5`). -## 0.1.4 +- Updated dependencies [[`77a3f64`](https://github.com/VoltAgent/voltagent/commit/77a3f64dea6e8a06fbbd72878711efa9ceb90bc3)]: + - @voltagent/core@1.1.7-next.0 + - @voltagent/server-core@1.0.7-next.0 -### Patch Changes +## 1.0.4 -- [#73](https://github.com/VoltAgent/voltagent/pull/73) [`ac6ecbc`](https://github.com/VoltAgent/voltagent/commit/ac6ecbc235a10a947a9f60155b04335761e6ac38) Thanks [@necatiozmen](https://github.com/necatiozmen)! - feat: Add placeholder `add` command +### Patch Changes - Introduces the `add ` command. Currently, this command informs users that the feature for adding agents from the marketplace is upcoming and provides a link to the GitHub discussions for early feedback and participation. +- Updated dependencies [[`134bf9a`](https://github.com/VoltAgent/voltagent/commit/134bf9a2978f0b069f842910fb4fb3e969f70390)]: + - @voltagent/internal@0.0.10 + - @voltagent/server-core@1.0.5 -## 0.1.3 +## 1.0.3 ### Patch Changes -- [#33](https://github.com/VoltAgent/voltagent/pull/33) [`3ef2eaa`](https://github.com/VoltAgent/voltagent/commit/3ef2eaa9661e8ecfebf17af56b09af41285d0ca9) Thanks [@kwaa](https://github.com/kwaa)! - Update package.json files: - - Remove `src` directory from the `files` array. - - Add explicit `exports` field for better module resolution. +- [`3177a60`](https://github.com/VoltAgent/voltagent/commit/3177a60a2632c200150e8a71d706b44df508cc66) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: version bump -## 0.1.1 +- Updated dependencies [[`3177a60`](https://github.com/VoltAgent/voltagent/commit/3177a60a2632c200150e8a71d706b44df508cc66)]: + - @voltagent/server-core@1.0.3 -- 🚀 **Introducing VoltAgent: TypeScript AI Agent Framework!** +## 2.0.0 - This initial release marks the beginning of VoltAgent, a powerful toolkit crafted for the JavaScript developer community. We saw the challenges: the complexity of building AI from scratch, the limitations of No-Code tools, and the lack of first-class AI tooling specifically for JS. +### Patch Changes - ![VoltAgent Demo](https://cdn.voltagent.dev/readme/demo.gif) - VoltAgent aims to fix that by providing the building blocks you need: - - **`@voltagent/core`**: The foundational engine for agent capabilities. - - **`@voltagent/voice`**: Easily add voice interaction. - - **`@voltagent/vercel-ai`**: Seamless integration with [Vercel AI SDK](https://sdk.vercel.ai/docs/introduction). - - **`@voltagent/xsai`**: A Seamless integration with [xsAI](https://xsai.js.org/). - - **`@voltagent/cli` & `create-voltagent-app`**: Quick start tools to get you building _fast_. +- Updated dependencies [[`63d4787`](https://github.com/VoltAgent/voltagent/commit/63d4787bd92135fa2d6edffb3b610889ddc0e3f5)]: + - @voltagent/core@1.1.0 + - @voltagent/server-core@2.0.0 - We're combining the flexibility of code with the clarity of visual tools (like our **currently live [VoltOps LLM Observability Platform](https://console.voltagent.dev/)**) to make AI development easier, clearer, and more powerful. Join us as we build the future of AI in JavaScript! +## 1.0.2 - Explore the [Docs](https://voltagent.dev/docs/) and join our [Discord community](https://s.voltagent.dev/discord)! +### Patch Changes ---- +- [`c27b260`](https://github.com/VoltAgent/voltagent/commit/c27b260bfca007da5201eb2967e089790cab3b97) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: zod dependency moved from dependencies to devDependencies -## Package: create-voltagent-app +- Updated dependencies [[`c27b260`](https://github.com/VoltAgent/voltagent/commit/c27b260bfca007da5201eb2967e089790cab3b97)]: + - @voltagent/server-core@1.0.2 -## 0.2.7 +## 1.0.1 ### Patch Changes -- [#463](https://github.com/VoltAgent/voltagent/pull/463) [`760a294`](https://github.com/VoltAgent/voltagent/commit/760a294e4d68742d8701d54dc1c541c87959e5d8) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: update base template to always include VoltOpsClient for observability +- [#545](https://github.com/VoltAgent/voltagent/pull/545) [`5d7c8e7`](https://github.com/VoltAgent/voltagent/commit/5d7c8e7f3898fe84066d0dd9be7f573fca66f185) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve EADDRINUSE error on server startup by fixing race condition in port availability check - #544 - ### What's New + Fixed a critical issue where users would encounter "EADDRINUSE: address already in use" errors when starting VoltAgent servers. The problem was caused by a race condition in the port availability check where the test server wasn't fully closed before the actual server tried to bind to the same port. - The create-voltagent-app template now always includes VoltOpsClient configuration, making it easier for users to enable production observability with a single click from the VoltOps Console. + ## What was happening - ### Changes - - **Always Include VoltOpsClient**: The base template now imports and configures VoltOpsClient by default - - **Environment-Based Configuration**: VoltOpsClient reads keys from `VOLTAGENT_PUBLIC_KEY` and `VOLTAGENT_SECRET_KEY` environment variables - - **Seamless Console Integration**: Works with the new one-click observability setup in VoltOps Console + When checking if a port was available, the port manager would: + 1. Create a test server and bind to the port + 2. On successful binding, immediately close the server + 3. Return `true` indicating the port was available + 4. But the test server wasn't fully closed yet when `serve()` tried to bind to the same port - ### Template Structure + ## The fix - ```typescript - import { VoltAgent, VoltOpsClient, Agent } from "@voltagent/core"; + Modified the port availability check in `port-manager.ts` to: + - Wait for the server's close callback before returning + - Add a small delay (50ms) to ensure the OS has fully released the port + - This prevents the race condition between test server closure and actual server startup - // ... agent configuration ... + ## Changes + - **port-manager.ts**: Fixed race condition by properly waiting for test server to close + - **hono-server-provider.ts**: Added proper error handling for server startup failures - new VoltAgent({ - agents: { agent }, - workflows: { expenseApprovalWorkflow }, - logger, - voltOpsClient: new VoltOpsClient({ - publicKey: process.env.VOLTAGENT_PUBLIC_KEY || "", - secretKey: process.env.VOLTAGENT_SECRET_KEY || "", - }), - }); - ``` + This ensures reliable server startup without port conflicts. - ### Benefits - - **Zero Configuration**: New projects are ready for observability out of the box - - **Console Integration**: Enable observability with one click from VoltOps Console - - **Production Ready**: Template follows best practices for production deployments +- [#546](https://github.com/VoltAgent/voltagent/pull/546) [`f12f344`](https://github.com/VoltAgent/voltagent/commit/f12f34405edf0fcb417ed098deba62570260fb81) Thanks [@omeraplak](https://github.com/omeraplak)! - chore: align Zod to ^3.25.76 and fix type mismatch with AI SDK - This change ensures all new VoltAgent projects created with create-voltagent-app are ready for production observability from day one. + We aligned Zod versions across packages to `^3.25.76` to match AI SDK peer ranges and avoid multiple Zod instances at runtime. -## 0.2.6 + Why this matters + - Fixes TypeScript narrowing issues in workflows when consuming `@voltagent/core` from npm with a different Zod instance (e.g., `ai` packages pulling newer Zod). + - Prevents errors like "Spread types may only be created from object types" where `data` failed to narrow because `z.ZodTypeAny` checks saw different Zod identities. -### Patch Changes + What changed + - `@voltagent/server-core`, `@voltagent/server-hono`: dependencies.zod → `^3.25.76`. + - `@voltagent/docs-mcp`, `@voltagent/core`: devDependencies.zod → `^3.25.76`. + - Examples and templates updated to use `^3.25.76` for consistency (non-publishable). -- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements + Notes for consumers + - Ensure a single Zod version is installed (consider a workspace override to pin Zod to `3.25.76`). + - This improves compatibility with `ai@5.x` packages that require `zod@^3.25.76 || ^4`. - This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: +- Updated dependencies [[`5d7c8e7`](https://github.com/VoltAgent/voltagent/commit/5d7c8e7f3898fe84066d0dd9be7f573fca66f185), [`f12f344`](https://github.com/VoltAgent/voltagent/commit/f12f34405edf0fcb417ed098deba62570260fb81)]: + - @voltagent/server-core@1.0.1 + - @voltagent/core@1.0.1 - **Key improvements:** - - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs - - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration - - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries - - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup - - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported +## 1.0.0 - These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. +### Major Changes -## 0.2.3 +- [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93) Thanks [@omeraplak](https://github.com/omeraplak)! - # Server Hono 1.x — pluggable HTTP server -### Patch Changes + Core no longer embeds an HTTP server. Use the Hono provider. -- [#404](https://github.com/VoltAgent/voltagent/pull/404) [`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add @voltagent/logger with createPinoLogger to new project templates + Full migration guide: [Migration Guide](https://voltagent.dev/docs/getting-started/migration-guide/) - Enhanced the create-voltagent-app templates to include @voltagent/logger by default in new projects. This provides new VoltAgent applications with production-ready logging capabilities out of the box. + ## Basic setup - **Changes:** - - Added `@voltagent/logger` as a dependency in generated projects - - Updated templates to import and use `createPinoLogger` instead of relying on the default ConsoleLogger - - New projects now have pretty-formatted, colored logs in development - - Automatic environment-based configuration (pretty in dev, JSON in production) + ```ts + import { VoltAgent } from "@voltagent/core"; + import { honoServer } from "@voltagent/server-hono"; - **Generated Code Example:** + new VoltAgent({ + agents: { agent }, + server: honoServer({ port: 3141, enableSwaggerUI: true }), + }); + ``` - ```typescript - import { createPinoLogger } from "@voltagent/logger"; + ## Custom routes and auth - const logger = createPinoLogger({ - level: "info", - name: "my-voltagent-app", - }); + ```ts + import { honoServer, jwtAuth } from "@voltagent/server-hono"; - const voltAgent = new VoltAgent({ - agents: [agent], - logger, + new VoltAgent({ + agents: { agent }, + server: honoServer({ + configureApp: (app) => { + app.get("/api/health", (c) => c.json({ status: "ok" })); + }, + auth: jwtAuth({ + secret: process.env.JWT_SECRET!, + publicRoutes: ["/health", "/metrics"], + }), + }), }); ``` - This ensures new VoltAgent projects start with professional logging capabilities, improving the developer experience and making applications production-ready from day one. - -## 0.2.0 +### Patch Changes -### Minor Changes +- Updated dependencies [[`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93), [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93)]: + - @voltagent/core@1.0.0 + - @voltagent/server-core@1.0.0 -- [`8b143cb`](https://github.com/VoltAgent/voltagent/commit/8b143cbd6f4349fe62158d7e78a5a239fec7a9e2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: modernize create-voltagent-app CLI - - Add AI provider selection (OpenAI, Anthropic, Google, Groq, Mistral, Ollama) - - Add optional API key input with skip option - - Automatic .env file generation based on selected provider - - Package manager detection - only show installed ones - - Auto-install dependencies after project creation - - Full Windows support with cross-platform commands - - Ollama local LLM support with default configuration - - Dynamic template generation based on selected AI provider +## 1.0.0-next.2 -### Patch Changes +### Major Changes -- [`8b143cb`](https://github.com/VoltAgent/voltagent/commit/8b143cbd6f4349fe62158d7e78a5a239fec7a9e2) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: include create-voltagent-app in build:all script +- [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93) Thanks [@omeraplak](https://github.com/omeraplak)! - # Server Hono 1.x — pluggable HTTP server - The create-voltagent-app package was not being built during GitHub Actions release workflow because it doesn't have the @voltagent/ scope prefix. Added explicit scope to build:all command to ensure the CLI tool is properly built before publishing. + Core no longer embeds an HTTP server. Use the Hono provider. -## 0.1.33 + Full migration guide: [Migration Guide](https://voltagent.dev/docs/getting-started/migration-guide/) -### Patch Changes + ## Basic setup -- [#371](https://github.com/VoltAgent/voltagent/pull/371) [`6ddedc2`](https://github.com/VoltAgent/voltagent/commit/6ddedc2b9be9c3dc4978dc53198a43c2cba74945) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add comprehensive workflow example to new projects + ```ts + import { VoltAgent } from "@voltagent/core"; + import { honoServer } from "@voltagent/server-hono"; - This change enhances the `create-voltagent-app` template by including a new, comprehensive workflow example. The goal is to provide new users with a practical, out-of-the-box demonstration of VoltAgent's core workflow capabilities. + new VoltAgent({ + agents: { agent }, + server: honoServer({ port: 3141, enableSwaggerUI: true }), + }); + ``` - The new template now includes: - - A `comprehensive-workflow` that showcases the combined use of `andThen`, `andAgent`, `andAll`, `andRace`, and `andWhen`. - - A dedicated `workflows` directory (`src/workflows`) to promote a modular project structure. - - The workflow uses a self-contained `sentimentAgent`, separating it from the main project agent to ensure clarity and avoid conflicts. + ## Custom routes and auth - This provides a much richer starting point for developers, helping them understand and build their own workflows more effectively. + ```ts + import { honoServer, jwtAuth } from "@voltagent/server-hono"; -## 0.1.31 + new VoltAgent({ + agents: { agent }, + server: honoServer({ + configureApp: (app) => { + app.get("/api/health", (c) => c.json({ status: "ok" })); + }, + auth: jwtAuth({ + secret: process.env.JWT_SECRET!, + publicRoutes: ["/health", "/metrics"], + }), + }), + }); + ``` ### Patch Changes -- [`00d70cb`](https://github.com/VoltAgent/voltagent/commit/00d70cbb570e4d748ab37e177e4e5df869d52e03) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: update VoltAgent docs MCP configs +- Updated dependencies [[`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93), [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93)]: + - @voltagent/core@1.0.0-next.2 + - @voltagent/server-core@1.0.0-next.2 -## 0.1.28 +## 1.0.0-next.1 -### Patch Changes +### Minor Changes -- [#278](https://github.com/VoltAgent/voltagent/pull/278) [`85d979d`](https://github.com/VoltAgent/voltagent/commit/85d979d5205f23ab6e3a85e68af6c46fa7c0f648) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: introduce VoltAgent MCP Docs Server for IDE integration +- [#514](https://github.com/VoltAgent/voltagent/pull/514) [`e86cadb`](https://github.com/VoltAgent/voltagent/commit/e86cadb5ae9ee9719bfd1f12e7116d95224699ce) Thanks [@omeraplak](https://github.com/omeraplak)! - # VoltAgent Server Architecture - Pluggable Server Providers - Added comprehensive MCP (Model Context Protocol) Docs Server integration to enable AI assistants in IDEs to access VoltAgent documentation directly. This feature allows developers to ask their AI assistants questions about VoltAgent directly within their development environment. + VoltAgent's server architecture has been completely redesigned with a pluggable server provider pattern, removing the built-in server in favor of optional server packages. - **New Features:** - - **`@voltagent/docs-mcp`** package: MCP server that provides access to VoltAgent documentation - - **CLI MCP commands**: Setup, test, status, and remove MCP configurations - - `volt mcp setup` - Interactive setup for Cursor, Windsurf, or VS Code - - `volt mcp test` - Test MCP connection and provide usage examples - - `volt mcp status` - Show current MCP configuration status - - `volt mcp remove` - Remove MCP configuration - - **IDE Configuration**: Automatic configuration file generation for supported IDEs - - **Multi-IDE Support**: Works with Cursor, Windsurf, and VS Code + ## Breaking Changes - **Usage:** + ### Built-in Server Removed - ```bash - # Setup MCP for your IDE - volt mcp setup + The built-in server has been removed from the core package. Server functionality is now provided through separate server packages. - # Test the connection - volt mcp test + **Before:** - # Check status - volt mcp status + ```typescript + import { VoltAgent } from "@voltagent/core"; + + // Server was built-in and auto-started + const voltAgent = new VoltAgent({ + agents: { myAgent }, + port: 3000, + enableSwaggerUI: true, + autoStart: true, // Server auto-started + }); ``` - Once configured, developers can ask their AI assistant questions like: - - "How do I create an agent in VoltAgent?" - - "Is there a VoltAgent example with Next.js?" - - "How do I use voice features?" - - "What are the latest updates?" + **After:** - The MCP server provides real-time access to VoltAgent documentation, examples, and best practices directly within the IDE environment. + ```typescript + import { VoltAgent } from "@voltagent/core"; + import { honoServer } from "@voltagent/server-hono"; -## 0.1.26 + // Server is now optional and explicitly configured + const voltAgent = new VoltAgent({ + agents: { myAgent }, + server: honoServer({ + port: 3000, + enableSwaggerUI: true, + }), + }); + ``` -### Patch Changes + ### Custom Endpoints Removed -- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 + Custom endpoint registration methods have been removed. Custom routes should now be added through the server provider's `configureApp` option. -## 0.1.21 + **Before:** -### Patch Changes + ```typescript + voltAgent.registerCustomEndpoint({ + path: "/custom", + method: "GET", + handler: async (req) => { + return { message: "Hello" }; + }, + }); + ``` -- [#155](https://github.com/VoltAgent/voltagent/pull/155) [`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c) Thanks [@baseballyama](https://github.com/baseballyama)! - chore: update `tsconfig.json`'s `target` to `ES2022` + **After:** -- [#162](https://github.com/VoltAgent/voltagent/pull/162) [`b164bd0`](https://github.com/VoltAgent/voltagent/commit/b164bd014670452cb162b388f03565db992767af) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: pin zod version to 3.24.2 to avoid "Type instantiation is excessively deep and possibly infinite" error + ```typescript + import { honoServer } from "@voltagent/server-hono"; - Fixed compatibility issues between different zod versions that were causing TypeScript compilation errors. This issue occurs when multiple packages use different patch versions of zod (e.g., 3.23.x vs 3.24.x), leading to type instantiation depth problems. By pinning to 3.24.2, we ensure consistent behavior across all packages. + new VoltAgent({ + agents: { myAgent }, + server: honoServer({ + port: 3000, + // Configure custom routes via configureApp callback + configureApp: (app) => { + app.get("/api/custom", (c) => { + return c.json({ message: "Hello" }); + }); - See: https://github.com/colinhacks/zod/issues/3435 + app.post("/api/calculate", async (c) => { + const { a, b } = await c.req.json(); + return c.json({ result: a + b }); + }); + }, + }), + }); + ``` -## 0.1.18 + ### Server Management Methods Changed -### Patch Changes + **Before:** -- [#102](https://github.com/VoltAgent/voltagent/pull/102) [`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3) Thanks [@omeraplak](https://github.com/omeraplak)! - refactor: use 'instructions' field for Agent definitions in examples - #88 + ```typescript + // Server started automatically or with: + voltAgent.startServer(); + // No stop method available + ``` - Updated documentation examples (READMEs, docs, blogs) and relevant package code examples to use the `instructions` field instead of `description` when defining `Agent` instances. + **After:** - This change aligns the examples with the preferred API usage for the `Agent` class, where `instructions` provides behavioral guidance to the agent/LLM. This prepares for the eventual deprecation of the `description` field specifically for `Agent` class definitions. + ```typescript + // Server starts automatically if provider is configured + voltAgent.startServer(); // Still available + voltAgent.stopServer(); // New method for graceful shutdown + ``` - **Example Change for Agent Definition:** + ## New Server Provider Pattern - ```diff - const agent = new Agent({ - name: "My Assistant", - - description: "A helpful assistant.", - + instructions: "A helpful assistant.", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - }); + ### IServerProvider Interface + + Server providers must implement the `IServerProvider` interface: + + ```typescript + interface IServerProvider { + start(): Promise<{ port: number }>; + stop(): Promise; + isRunning(): boolean; + } ``` -## 0.1.16 + ### Available Server Providers -### Patch Changes + #### @voltagent/server-hono (Recommended) -- [`13db262`](https://github.com/VoltAgent/voltagent/commit/13db2621ae6b730667f9991d3c2129c85265e925) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: Update Zod to version 3.24.2 to resolve "Type instantiation is excessively deep and possibly infinite" error (related to https://github.com/colinhacks/zod/issues/3435). + Edge-optimized server using Hono framework: -## 0.1.14 + ```typescript + import { honoServer } from "@voltagent/server-hono"; -### Patch Changes + new VoltAgent({ + agents: { myAgent }, + server: honoServer({ + port: 3141, + enableSwaggerUI: true, + auth: { + provider: "jwt", + secret: "your-secret", + }, + configureApp: (app) => { + // Add custom routes + app.get("/api/health", (c) => { + return c.json({ status: "healthy" }); + }); + }, + }), + }); + ``` -- [`8e6d2e9`](https://github.com/VoltAgent/voltagent/commit/8e6d2e994398c1a727d4afea39d5e34ffc4a5fca) Thanks [@omeraplak](https://github.com/omeraplak)! - chore: add README + Features: + - **Built-in JWT Authentication**: Secure your API with JWT tokens + - **Swagger UI Support**: Interactive API documentation + - **WebSocket Support**: Real-time streaming capabilities + - **Edge Runtime Compatible**: Deploy to Vercel Edge, Cloudflare Workers, etc. + - **Fast and Lightweight**: Optimized for performance -## 0.1.11 + #### Authentication & Authorization -### Patch Changes + The server-hono package includes comprehensive JWT authentication support: -- [#33](https://github.com/VoltAgent/voltagent/pull/33) [`3ef2eaa`](https://github.com/VoltAgent/voltagent/commit/3ef2eaa9661e8ecfebf17af56b09af41285d0ca9) Thanks [@kwaa](https://github.com/kwaa)! - Update package.json files: - - Remove `src` directory from the `files` array. - - Add explicit `exports` field for better module resolution. + ```typescript + import { honoServer, jwtAuth } from "@voltagent/server-hono"; ---- + new VoltAgent({ + agents: { myAgent }, + server: honoServer({ + port: 3141, + + // Configure JWT authentication + auth: jwtAuth({ + secret: process.env.JWT_SECRET, + + // Map JWT payload to user object + mapUser: (payload) => ({ + id: payload.sub, + email: payload.email, + role: payload.role, + permissions: payload.permissions || [], + }), -## Package: @voltagent/docs-mcp + // Define public routes (no auth required) + publicRoutes: ["/health", "/metrics"], -## 0.2.2 + // JWT verification options + verifyOptions: { + algorithms: ["HS256"], + audience: "your-app", + issuer: "your-auth-server", + }, + }), + }), + }); + ``` -### Patch Changes + **Accessing User Context in Agents:** -- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements + ```typescript + const agent = new Agent({ + name: "SecureAgent", + instructions: "You are a secure assistant", + model: openai("gpt-4o-mini"), - This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + // Access authenticated user in hooks + hooks: { + onStart: async ({ context }) => { + const user = context.get("user"); + if (user?.role === "admin") { + // Admin-specific logic + } + }, + }, + }); + ``` - **Key improvements:** - - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs - - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration - - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries - - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup - - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + **Making Authenticated Requests:** - These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. + ```bash + # Include JWT token in Authorization header + curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + http://localhost:3141/api/agent/chat + ``` -## 0.2.1 + ### No Server Configuration -### Patch Changes + For serverless or custom deployments: -- [#401](https://github.com/VoltAgent/voltagent/pull/401) [`4a7145d`](https://github.com/VoltAgent/voltagent/commit/4a7145debd66c7b1dfb953608e400b6c1ed02db7) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve TypeScript performance issues by fixing Zod dependency configuration (#377) + ```typescript + new VoltAgent({ + agents: { myAgent }, + // No server property - runs without HTTP server + }); + ``` - Moved Zod from direct dependencies to peer dependencies in @voltagent/vercel-ai to prevent duplicate Zod installations that were causing TypeScript server slowdowns. Also standardized Zod versions across the workspace to ensure consistency. + ## Migration Guide + 1. **Install server package**: - Changes: - - @voltagent/vercel-ai: Moved `zod` from dependencies to peerDependencies - - @voltagent/docs-mcp: Updated `zod` from `^3.23.8` to `3.24.2` - - @voltagent/with-postgres: Updated `zod` from `^3.24.2` to `3.24.2` (removed caret) + ```bash + npm install @voltagent/server-hono + ``` - This fix significantly improves TypeScript language server performance by ensuring only one Zod version is processed, eliminating the "Type instantiation is excessively deep and possibly infinite" errors that users were experiencing. + 2. **Update imports**: -- Updated dependencies [[`57c4874`](https://github.com/VoltAgent/voltagent/commit/57c4874d4d4807c50242b2e34ab9574fc6129888), [`da66f86`](https://github.com/VoltAgent/voltagent/commit/da66f86d92a278007c2d3386d22b482fa70d93ff), [`4a7145d`](https://github.com/VoltAgent/voltagent/commit/4a7145debd66c7b1dfb953608e400b6c1ed02db7)]: - - @voltagent/core@0.1.61 + ```typescript + import { honoServer } from "@voltagent/server-hono"; + ``` -## 0.2.0 + 3. **Update VoltAgent configuration**: + - Remove: `port`, `enableSwaggerUI`, `autoStart`, `customEndpoints` + - Add: `server: honoServer({ /* config */ })` + 4. **Handle custom routes**: + - Use `configureApp` callback in server config + - Access full Hono app instance for custom routes -### Minor Changes +### Patch Changes -- [#367](https://github.com/VoltAgent/voltagent/pull/367) [`d71efff`](https://github.com/VoltAgent/voltagent/commit/d71efff5d2b9822d787bfed62329e56ee441774a) Thanks [@Theadd](https://github.com/Theadd)! - feat(docs-mcp): dynamically discover example files +- Updated dependencies [[`e86cadb`](https://github.com/VoltAgent/voltagent/commit/e86cadb5ae9ee9719bfd1f12e7116d95224699ce), [`e86cadb`](https://github.com/VoltAgent/voltagent/commit/e86cadb5ae9ee9719bfd1f12e7116d95224699ce)]: + - @voltagent/core@1.0.0-next.1 + - @voltagent/server-core@1.0.0-next.1 - Refactor the getExampleContent function to dynamically discover all relevant files in an example directory instead of relying on a hardcoded list. This introduces a new discoverExampleFiles helper function that recursively scans for .ts files in src, app, and voltagent directories with depth limits, while retaining backward compatibility. This ensures that documentation examples with complex file structures containing voltagent related code are fully captured and displayed. +--- - Resolves #365 +## Package: @voltagent/serverless-hono -## 0.1.8 +## 2.0.5 ### Patch Changes -- [`00d70cb`](https://github.com/VoltAgent/voltagent/commit/00d70cbb570e4d748ab37e177e4e5df869d52e03) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: update VoltAgent docs MCP configs +- [#921](https://github.com/VoltAgent/voltagent/pull/921) [`c4591fa`](https://github.com/VoltAgent/voltagent/commit/c4591fa92de6df75a22a758b0232669053bd2b62) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add resumable streaming support via @voltagent/resumable-streams, with server adapters that let clients reconnect to in-flight streams. -## 0.1.1 + ```ts + import { openai } from "@ai-sdk/openai"; + import { Agent, VoltAgent } from "@voltagent/core"; + import { + createResumableStreamAdapter, + createResumableStreamRedisStore, + } from "@voltagent/resumable-streams"; + import { honoServer } from "@voltagent/server-hono"; -### Patch Changes + const streamStore = await createResumableStreamRedisStore(); + const resumableStream = await createResumableStreamAdapter({ streamStore }); -- [#278](https://github.com/VoltAgent/voltagent/pull/278) [`85d979d`](https://github.com/VoltAgent/voltagent/commit/85d979d5205f23ab6e3a85e68af6c46fa7c0f648) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: introduce VoltAgent MCP Docs Server for IDE integration + const agent = new Agent({ + id: "assistant", + name: "Resumable Stream Agent", + instructions: "You are a helpful assistant.", + model: openai("gpt-4o-mini"), + }); - Added comprehensive MCP (Model Context Protocol) Docs Server integration to enable AI assistants in IDEs to access VoltAgent documentation directly. This feature allows developers to ask their AI assistants questions about VoltAgent directly within their development environment. + new VoltAgent({ + agents: { assistant: agent }, + server: honoServer({ + resumableStream: { adapter: resumableStream }, + }), + }); - **New Features:** - - **`@voltagent/docs-mcp`** package: MCP server that provides access to VoltAgent documentation - - **CLI MCP commands**: Setup, test, status, and remove MCP configurations - - `volt mcp setup` - Interactive setup for Cursor, Windsurf, or VS Code - - `volt mcp test` - Test MCP connection and provide usage examples - - `volt mcp status` - Show current MCP configuration status - - `volt mcp remove` - Remove MCP configuration - - **IDE Configuration**: Automatic configuration file generation for supported IDEs - - **Multi-IDE Support**: Works with Cursor, Windsurf, and VS Code + await fetch("http://localhost:3141/agents/assistant/chat", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: `{"input":"Hello!","options":{"conversationId":"conv-1","userId":"user-1","resumableStream":true}}`, + }); - **Usage:** + // Resume the same stream after reconnect/refresh + const resumeResponse = await fetch( + "http://localhost:3141/agents/assistant/chat/conv-1/stream?userId=user-1" + ); - ```bash - # Setup MCP for your IDE - volt mcp setup + const reader = resumeResponse.body?.getReader(); + const decoder = new TextDecoder(); + while (reader) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value, { stream: true }); + console.log(chunk); + } + ``` - # Test the connection - volt mcp test + AI SDK client (resume on refresh): - # Check status - volt mcp status + ```tsx + import { useChat } from "@ai-sdk/react"; + import { DefaultChatTransport } from "ai"; + + const { messages, sendMessage } = useChat({ + id: chatId, + messages: initialMessages, + resume: true, + transport: new DefaultChatTransport({ + api: "/api/chat", + prepareSendMessagesRequest: ({ id, messages }) => ({ + body: { + message: messages[messages.length - 1], + options: { conversationId: id, userId }, + }, + }), + prepareReconnectToStreamRequest: ({ id }) => ({ + api: `/api/chat/${id}/stream?userId=${encodeURIComponent(userId)}`, + }), + }), + }); ``` - Once configured, developers can ask their AI assistant questions like: - - "How do I create an agent in VoltAgent?" - - "Is there a VoltAgent example with Next.js?" - - "How do I use voice features?" - - "What are the latest updates?" +- Updated dependencies [[`c4591fa`](https://github.com/VoltAgent/voltagent/commit/c4591fa92de6df75a22a758b0232669053bd2b62)]: + - @voltagent/resumable-streams@2.0.1 + - @voltagent/server-core@2.1.2 - The MCP server provides real-time access to VoltAgent documentation, examples, and best practices directly within the IDE environment. +## 2.0.4 -- Updated dependencies [[`937ccf8`](https://github.com/VoltAgent/voltagent/commit/937ccf8bf84a4261ee9ed2c94aab9f8c49ab69bd)]: - - @voltagent/core@0.1.39 +### Patch Changes ---- +- [#911](https://github.com/VoltAgent/voltagent/pull/911) [`975831a`](https://github.com/VoltAgent/voltagent/commit/975831a852ea471adb621a1d87990a8ffbc5ed31) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: expose Cloudflare Workers `env` bindings in serverless contexts -## Package: @voltagent/internal + When using `@voltagent/serverless-hono` on Cloudflare Workers, the runtime `env` is now injected into the + context map for agent requests, workflow runs, and tool executions. `@voltagent/core` exports + `SERVERLESS_ENV_CONTEXT_KEY` so you can access bindings like D1 from `options.context` (tools) or + `state.context` (workflow steps). Tool execution also accepts `context` as a `Map`, preserving + `userId`/`conversationId` when provided that way. -## 0.0.8 + `@voltagent/core` is also marked as side-effect free so edge bundlers can tree-shake the PlanAgent + filesystem backend, avoiding Node-only dependency loading when it is not used. -### Patch Changes + Usage: -- [#472](https://github.com/VoltAgent/voltagent/pull/472) [`8de5785`](https://github.com/VoltAgent/voltagent/commit/8de5785e385bec632f846bcae44ee5cb22a9022e) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: Migrate to using `safeStringify` to prevent issues using the JSON.stringify/parse method, in addition use structuredClone via Nodejs instead legacy method that errors + ```ts + import { createTool, SERVERLESS_ENV_CONTEXT_KEY } from "@voltagent/core"; + import type { D1Database } from "@cloudflare/workers-types"; + import { z } from "zod"; -## 0.0.7 + type Env = { DB: D1Database }; + + export const listUsers = createTool({ + name: "list-users", + description: "Fetch users from D1", + parameters: z.object({}), + execute: async (_args, options) => { + const env = options?.context?.get(SERVERLESS_ENV_CONTEXT_KEY) as Env | undefined; + const db = env?.DB; + if (!db) { + throw new Error("D1 binding is missing (env.DB)"); + } -### Patch Changes + const { results } = await db.prepare("SELECT id, name FROM users").all(); + return results; + }, + }); + ``` -- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements +- Updated dependencies [[`975831a`](https://github.com/VoltAgent/voltagent/commit/975831a852ea471adb621a1d87990a8ffbc5ed31)]: + - @voltagent/server-core@2.1.1 - This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: +## 2.0.3 - **Key improvements:** - - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs - - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration - - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries - - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup - - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported +### Patch Changes - These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. +- [`c9bd810`](https://github.com/VoltAgent/voltagent/commit/c9bd810ac71972eb7e9e6e01c9ca15b6e9cfc9f0) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: allow Console dev headers in CORS and add a /ws probe response for serverless runtimes without WebSocket support -## 0.0.6 +## 2.0.2 ### Patch Changes -- [#404](https://github.com/VoltAgent/voltagent/pull/404) [`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726) Thanks [@omeraplak](https://github.com/omeraplak)! - refactor: remove devLogger in favor of standardized logging approach - - Removed the internal `devLogger` utility to align with the new standardized logging architecture. This change simplifies the internal package and reduces code duplication by leveraging the comprehensive logging system now available in @voltagent/core and @voltagent/logger. - - **Changes:** - - Removed `devLogger` from exports - - Removed development-only logging utility - - Consumers should use the logger instance provided by VoltAgent or create their own using @voltagent/logger +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) - This is part of the logging system refactoring to provide a more consistent and powerful logging experience across all VoltAgent packages. + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. -## 0.0.5 + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` -### Patch Changes + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ -- [`6fadbb0`](https://github.com/VoltAgent/voltagent/commit/6fadbb098fe40d8b658aa3386e6126fea155f117) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: createAsyncIterableStream import issue +- Updated dependencies [[`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505)]: + - @voltagent/internal@1.0.2 + - @voltagent/server-core@2.0.2 -## 0.0.4 +## 2.0.1 ### Patch Changes -- [#324](https://github.com/VoltAgent/voltagent/pull/324) [`8da1ecc`](https://github.com/VoltAgent/voltagent/commit/8da1eccd0332d1f9037085e16cb0b7d5afaac479) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: improve dev logger environment detection and add debug method +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) - Enhanced the dev logger to be more intelligent about when to show logs. Previously, the logger only showed logs when `NODE_ENV === "development"`. Now it shows logs unless `NODE_ENV` is explicitly set to `"production"`, `"test"`, or `"ci"`. + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. - **Changes:** - - **Improved Environment Detection**: Dev logger now shows logs when `NODE_ENV` is undefined, empty string, or any value other than "production", "test", or "ci" - - **Better Developer Experience**: Developers who don't set NODE_ENV will now see logs by default, which is more intuitive - - **Added Debug Method**: Included a placeholder `debug` method for future structured logging with Pino - - **Updated Tests**: Comprehensive test coverage for the new logging behavior + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` - **Before:** - - Logs only shown when `NODE_ENV === "development"` - - Empty string or undefined NODE_ENV = no logs ❌ + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ - **After:** - - Logs hidden only when `NODE_ENV === "production"`, `NODE_ENV === "test"`, or `NODE_ENV === "ci"` - - Empty string, undefined, or other values = logs shown ✅ +- Updated dependencies [[`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2)]: + - @voltagent/internal@1.0.1 + - @voltagent/server-core@2.0.1 - This change makes the development experience smoother as most developers don't explicitly set NODE_ENV during local development. +## 2.0.0 -## 0.0.3 +### Major Changes -### Patch Changes +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) -- [#311](https://github.com/VoltAgent/voltagent/pull/311) [`1f7fa14`](https://github.com/VoltAgent/voltagent/commit/1f7fa140fcc4062fe85220e61f276e439392b0b4) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix(core, vercel-ui): Currently the `convertToUIMessages` function does not handle tool calls in steps correctly as it does not properly default filter non-tool related steps for sub-agents, same as the `data-stream` functions and in addition in the core the `operationContext` does not have the `subAgent` fields set correctly. + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. - ### Changes - - deprecated `isSubAgentStreamPart` in favor of `isSubAgent` for universal use - - by default `convertToUIMessages` now filters out non-tool related steps for sub-agents - - now able to exclude specific parts or steps (from OperationContext) in `convertToUIMessages` + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` - *** + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ - ### Internals +### Patch Changes - New utils were added to the internal package: - - `isObject` - - `isFunction` - - `isPlainObject` - - `isEmptyObject` - - `isNil` - - `hasKey` +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/server-core@2.0.0 + - @voltagent/core@2.0.0 + - @voltagent/internal@1.0.0 -## 0.0.2 +## 1.0.10 ### Patch Changes -- [`94de46a`](https://github.com/VoltAgent/voltagent/commit/94de46ab2b7ccead47a539e93c72b357f17168f6) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add `deepClone` function to `object-utils` module +- [#847](https://github.com/VoltAgent/voltagent/pull/847) [`d861c17`](https://github.com/VoltAgent/voltagent/commit/d861c17e72f2fb6368778970a56411fadabaf9a5) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add first-class REST tool endpoints and UI support - #638 + - Server: list and execute registered tools over HTTP (`GET /tools`, `POST /tools/:name/execute`) with zod-validated inputs and OpenAPI docs. + - Auth: Both GET and POST tool endpoints are behind the same auth middleware as agent/workflow execution (protected by default). + - Multi-agent tools: tools now report all owning agents via `agents[]` (no more single `agentId`), including tags when provided. + - Safer handlers: input validation via safeParse guard, tag extraction without `any`, and better error shaping. + - Serverless: update install route handles empty bodies and `/updates/:packageName` variant. + - Console: Unified list surfaces tools, tool tester drawer with Monaco editors and default context, Observability page adds a Tools tab with direct execution. + - Docs: New tools endpoint page and API reference entries for listing/executing tools. - Added a new `deepClone` utility function to the object-utils module for creating deep copies of complex JavaScript objects. This utility provides safe cloning of nested objects, arrays, and primitive values while handling circular references and special object types. +- Updated dependencies [[`d861c17`](https://github.com/VoltAgent/voltagent/commit/d861c17e72f2fb6368778970a56411fadabaf9a5)]: + - @voltagent/server-core@1.0.33 - Usage: +## 1.0.9 - ```typescript - import { deepClone } from "@voltagent/core/utils/object-utils"; +### Patch Changes - const original = { - nested: { - array: [1, 2, { deep: "value" }], - date: new Date(), - }, - }; +- [#845](https://github.com/VoltAgent/voltagent/pull/845) [`5432f13`](https://github.com/VoltAgent/voltagent/commit/5432f13bddebd869522ebffbedd9843b4476f08b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: workflow execution listing - #844 - const cloned = deepClone(original); - // cloned is completely independent from original - ``` + Added a unified way to list workflow runs so teams can audit executions across every storage backend and surface them via the API and console. - This utility is particularly useful for agent state management, configuration cloning, and preventing unintended mutations in complex data structures. + ## What changed + - `queryWorkflowRuns` now exists on all memory adapters (in-memory, libsql, Postgres, Supabase, voltagent-memory) with filters for `workflowId`, `status`, `from`, `to`, `limit`, and `offset`. + - Server routes are consolidated under `/workflows/executions` (no path param needed); `GET /workflows/:id` also returns the workflow result schema for typed clients. Handler naming is standardized to `listWorkflowRuns`. + - VoltOps Console observability panel lists the new endpoint; REST docs updated with query params and sample responses. New unit tests cover handlers and every storage adapter. -- Updated dependencies []: - - @voltagent/core@0.1.44 + ## Quick fetch ---- + ```ts + await fetch( + "http://localhost:3141/workflows/executions?workflowId=expense-approval&status=completed&from=2024-01-01&to=2024-01-31&limit=20&offset=0" + ); + ``` -## Package: @voltagent/langfuse-exporter +- Updated dependencies [[`5432f13`](https://github.com/VoltAgent/voltagent/commit/5432f13bddebd869522ebffbedd9843b4476f08b)]: + - @voltagent/server-core@1.0.32 -## 0.1.5 +## 1.0.8 ### Patch Changes -- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements +- [#810](https://github.com/VoltAgent/voltagent/pull/810) [`efcfe52`](https://github.com/VoltAgent/voltagent/commit/efcfe52dbe2c095057ce08a5e053d1defafd4e62) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: ensure reliable trace export and context propagation in serverless environments - This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + ## The Problem - **Key improvements:** - - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs - - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration - - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries - - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup - - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + Trigger-initiated agent executions in serverless environments (Cloudflare Workers, Vercel Edge Functions) were experiencing inconsistent trace exports and missing parent-child span relationships. This manifested as: + 1. Agent traces not appearing in observability tools despite successful execution + 2. Trigger and agent spans appearing as separate, disconnected traces instead of a single coherent trace tree + 3. Spans being lost due to serverless functions terminating before export completion - These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. + ## The Solution -## 0.1.4 + **Serverless Trace Export (`@voltagent/serverless-hono`):** + - Implemented reliable span flushing using Cloudflare's `waitUntil` API to ensure spans are exported before function termination + - Switched from `SimpleSpanProcessor` to `BatchSpanProcessor` with serverless-optimized configuration (immediate export, small batch sizes) + - Added automatic flush on trigger completion with graceful fallback to `forceFlush` when `waitUntil` is unavailable -### Patch Changes + **Context Propagation (`@voltagent/core`):** + - Integrated official `@opentelemetry/context-async-hooks` package to replace custom context manager implementation + - Ensured `AsyncHooksContextManager` is registered in both Node.js and serverless environments for consistent async context tracking + - Fixed `resolveParentSpan` logic to correctly identify scorer spans while avoiding framework-generated ambient spans + - Exported `propagation` and `ROOT_CONTEXT` from `@opentelemetry/api` for HTTP header-based trace context injection/extraction -- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 + **Node.js Reliability:** + - Updated `NodeVoltAgentObservability.flushOnFinish()` to call `forceFlush()` instead of being a no-op, ensuring spans are exported in short-lived processes -- Updated dependencies [[`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f), [`80fd3c0`](https://github.com/VoltAgent/voltagent/commit/80fd3c069de4c23116540a55082b891c4b376ce6)]: - - @voltagent/core@0.1.31 + ## Impact + - ✅ Serverless traces are now reliably exported and visible in observability tools + - ✅ Trigger and agent spans form a single, coherent trace tree with proper parent-child relationships + - ✅ Consistent tracing behavior across Node.js and serverless runtimes + - ✅ No more missing or orphaned spans in Cloudflare Workers, Vercel Edge Functions, or similar platforms -## 0.1.3 + ## Technical Details + - Uses `BatchSpanProcessor` with `maxExportBatchSize: 32` and `scheduledDelayMillis: 100` for serverless + - Leverages `globalThis.___voltagent_wait_until` for non-blocking span export in Cloudflare Workers + - Implements `AsyncHooksContextManager` for robust async context tracking across `Promise` chains and `async/await` + - Maintains backward compatibility with existing Node.js deployments -### Patch Changes + ## Migration Notes -- [#155](https://github.com/VoltAgent/voltagent/pull/155) [`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c) Thanks [@baseballyama](https://github.com/baseballyama)! - chore: update `tsconfig.json`'s `target` to `ES2022` + No breaking changes. Existing deployments will automatically benefit from improved trace reliability. Ensure your `wrangler.toml` includes `nodejs_compat` flag for Cloudflare Workers: -- Updated dependencies [[`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c), [`b164bd0`](https://github.com/VoltAgent/voltagent/commit/b164bd014670452cb162b388f03565db992767af), [`9412cf0`](https://github.com/VoltAgent/voltagent/commit/9412cf0633f20d6b77c87625fc05e9e216936758)]: - - @voltagent/core@0.1.20 + ```toml + compatibility_flags = ["nodejs_compat"] + ``` -## 0.1.2 +## 1.0.7 ### Patch Changes -- [#102](https://github.com/VoltAgent/voltagent/pull/102) [`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3) Thanks [@omeraplak](https://github.com/omeraplak)! - refactor: use 'instructions' field for Agent definitions in examples - #88 - - Updated documentation examples (READMEs, docs, blogs) and relevant package code examples to use the `instructions` field instead of `description` when defining `Agent` instances. +- [#801](https://github.com/VoltAgent/voltagent/pull/801) [`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add triggers DSL improvements and event payload simplification + - Introduce the new `createTriggers` DSL and expose trigger events via sensible provider names (e.g. `on.airtable.recordCreated`) rather than raw catalog IDs. + - Add trigger span metadata propagation so VoltAgent agents receive trigger context automatically without manual mapping. + - Simplify action dispatch payloads: `payload` now contains only the event’s raw data while trigger context lives in the `event`/`metadata` blocks, reducing boilerplate in handlers. - This change aligns the examples with the preferred API usage for the `Agent` class, where `instructions` provides behavioral guidance to the agent/LLM. This prepares for the eventual deprecation of the `description` field specifically for `Agent` class definitions. + ```ts + import { VoltAgent, createTriggers } from "@voltagent/core"; - **Example Change for Agent Definition:** + new VoltAgent({ + // ... + triggers: createTriggers((on) => { + on.airtable.recordCreated(({ payload, event }) => { + console.log("New Airtable row", payload, event.metadata); + }); - ```diff - const agent = new Agent({ - name: "My Assistant", - - description: "A helpful assistant.", - + instructions: "A helpful assistant.", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - }); + on.gmail.newEmail(({ payload }) => { + console.log("New Gmail message", payload); + }); + }), + }); ``` -- Updated dependencies [[`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3)]: - - @voltagent/core@0.1.14 +- Updated dependencies [[`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749)]: + - @voltagent/server-core@1.0.25 -## 0.1.1 +## 1.0.6 ### Patch Changes -- [#94](https://github.com/VoltAgent/voltagent/pull/94) [`004df81`](https://github.com/VoltAgent/voltagent/commit/004df81fa6a23571391e6ddeba0dfe6bfea267e8) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Add Langfuse Observability Exporter +- [#787](https://github.com/VoltAgent/voltagent/pull/787) [`5e81d65`](https://github.com/VoltAgent/voltagent/commit/5e81d6568ba3bee26083ca2a8e5d31f158e36fc0) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add full conversation step persistence across the stack: + - Core now exposes managed-memory step APIs, and the VoltAgent managed memory adapter persists/retrieves steps through VoltOps. + - LibSQL, PostgreSQL, Supabase, and server handlers provision the new `_steps` table, wire up DTOs/routes, and surface the data in Observability/Steps UI (including managed-memory backends). - This introduces a new package `@voltagent/langfuse-exporter` that allows you to export OpenTelemetry traces generated by `@voltagent/core` directly to Langfuse (https://langfuse.com/) for detailed observability into your agent's operations. + fixes: #613 - **How to Use:** +- Updated dependencies [[`5e81d65`](https://github.com/VoltAgent/voltagent/commit/5e81d6568ba3bee26083ca2a8e5d31f158e36fc0)]: + - @voltagent/server-core@1.0.22 - ## Installation +## 1.0.5 - Install the necessary packages: +### Patch Changes - ```bash - npm install @voltagent/langfuse-exporter - ``` +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` +- Updated dependencies [[`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e)]: + - @voltagent/server-core@1.0.16 + - @voltagent/internal@0.0.12 - ## Configuration +## 1.0.4 - Configure the `LangfuseExporter` and pass it to `VoltAgent`: +### Patch Changes - ```typescript - import { Agent, VoltAgent } from "@voltagent/core"; - import { VercelAIProvider } from "@voltagent/vercel-ai"; - import { openai } from "@ai-sdk/openai"; +- [#701](https://github.com/VoltAgent/voltagent/pull/701) [`c4f01e6`](https://github.com/VoltAgent/voltagent/commit/c4f01e6691b4841c11d4127525011bb2edbe1e26) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: observability spans terminating prematurely on Vercel Edge and Deno Deploy - import { LangfuseExporter } from "@voltagent/langfuse-exporter"; + ## The Problem - // Ensure LANGFUSE_SECRET_KEY and LANGFUSE_PUBLIC_KEY are set in your environment + Observability spans were being cut short on Vercel Edge and Deno Deploy runtimes because the `toVercelEdge()` and `toDeno()` adapters didn't implement `waitUntil` support. Unlike `toCloudflareWorker()`, which properly extracted and set up `waitUntil` from the execution context, these adapters would terminate async operations (like span exports) as soon as the response was returned. - // Define your agent(s) - const agent = new Agent({ - name: "my-voltagent-app", - instructions: "A helpful assistant that answers questions without using tools", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - }); + This caused the observability pipeline's `FetchTraceExporter` and `FetchLogExporter` to have their export promises cancelled mid-flight, resulting in incomplete or missing observability data. - // Configure the Langfuse Exporter - const langfuseExporter = new LangfuseExporter({ - publicKey: process.env.LANGFUSE_PUBLIC_KEY, - secretKey: process.env.LANGFUSE_SECRET_KEY, - baseUrl: process.env.LANGFUSE_BASE_URL, // Optional: Defaults to Langfuse Cloud - // debug: true // Optional: Enable exporter logging - }); + ## The Solution - // Initialize VoltAgent with the exporter - // This automatically sets up OpenTelemetry tracing - new VoltAgent({ - agents: { - agent, // Register your agent(s) - }, - telemetryExporter: langfuseExporter, // Pass the exporter instance - }); + Refactored all serverless adapters to use a new `withWaitUntil()` helper utility that: + - Extracts `waitUntil` from the runtime context (Cloudflare's `executionCtx`, Vercel's `context`, or Deno's `info`) + - Sets it as `globalThis.___voltagent_wait_until` for the observability exporters to use + - Returns a cleanup function that properly restores previous state + - Handles errors gracefully and supports nested calls - console.log("VoltAgent initialized with Langfuse exporter."); + Now all three adapters (`toCloudflareWorker`, `toVercelEdge`, `toDeno`) use the same battle-tested pattern: - // Now, any operations performed by 'agent' (e.g., agent.generateText(...)) - // will automatically generate traces and send them to Langfuse. + ```ts + const cleanup = withWaitUntil(context); + try { + return await processRequest(request); + } finally { + cleanup(); + } ``` - By providing the `telemetryExporter` to `VoltAgent`, OpenTelemetry is automatically configured, and detailed traces including LLM interactions, tool usage, and agent metadata will appear in your Langfuse project. - -- Updated dependencies [[`004df81`](https://github.com/VoltAgent/voltagent/commit/004df81fa6a23571391e6ddeba0dfe6bfea267e8)]: - - @voltagent/core@0.1.12 + ## Impact + - ✅ Observability spans now export successfully on Vercel Edge Runtime + - ✅ Observability spans now export successfully on Deno Deploy + - ✅ Consistent `waitUntil` behavior across all serverless platforms + - ✅ DRY principle: eliminated duplicate code across adapters + - ✅ Comprehensive test coverage with 11 unit tests covering edge cases, nested calls, and error scenarios ---- + ## Technical Details -## Package: @voltagent/logger + The fix introduces: + - `utils/wait-until-wrapper.ts`: Reusable `withWaitUntil()` helper + - `utils/wait-until-wrapper.spec.ts`: Complete test suite (11/11 passing) + - Updated `toCloudflareWorker()`: Simplified using helper + - **Fixed** `toVercelEdge()`: Now properly supports `waitUntil` + - **Fixed** `toDeno()`: Now properly supports `waitUntil` -## 0.1.3 +## 1.0.3 ### Patch Changes -- Updated dependencies [[`8de5785`](https://github.com/VoltAgent/voltagent/commit/8de5785e385bec632f846bcae44ee5cb22a9022e)]: - - @voltagent/internal@0.0.8 - -## 0.1.2 - -### Patch Changes +- [`ca6160a`](https://github.com/VoltAgent/voltagent/commit/ca6160a2f5098f296729dcd842a013558d14eeb8) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: updates endpoint -- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements +- Updated dependencies [[`ca6160a`](https://github.com/VoltAgent/voltagent/commit/ca6160a2f5098f296729dcd842a013558d14eeb8)]: + - @voltagent/server-core@1.0.14 - This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: +## 1.0.2 - **Key improvements:** - - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs - - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration - - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries - - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup - - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported +### Patch Changes - These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. +- [#629](https://github.com/VoltAgent/voltagent/pull/629) [`3e64b9c`](https://github.com/VoltAgent/voltagent/commit/3e64b9ce58d0e91bc272f491be2c1932a005ef48) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add memory observability -- Updated dependencies [[`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5)]: - - @voltagent/internal@0.0.7 +- Updated dependencies [[`3e64b9c`](https://github.com/VoltAgent/voltagent/commit/3e64b9ce58d0e91bc272f491be2c1932a005ef48)]: + - @voltagent/server-core@1.0.13 -## 0.1.1 +## 1.0.1 ### Patch Changes -- [#404](https://github.com/VoltAgent/voltagent/pull/404) [`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: initial release of @voltagent/logger package - - Introducing a powerful, production-ready logging solution for VoltAgent applications. This package provides a feature-rich logger built on top of Pino with support for pretty formatting, file transports, and advanced logging capabilities. +- [#621](https://github.com/VoltAgent/voltagent/pull/621) [`f4fa7e2`](https://github.com/VoltAgent/voltagent/commit/f4fa7e297fec2f602c9a24a0c77e645aa971f2b9) Thanks [@omeraplak](https://github.com/omeraplak)! - ## @voltagent/core + - Folded the serverless runtime entry point into the main build – importing `@voltagent/core` now auto-detects the runtime and provisions either the Node or serverless observability pipeline. + - Rebuilt serverless observability on top of `BasicTracerProvider`, fetch-based OTLP exporters, and an execution-context `waitUntil` hook. Exports run with exponential backoff, never block the response, and automatically reuse VoltOps credentials (or fall back to the in-memory span/log store) so VoltOps Console transparently swaps to HTTP polling when WebSockets are unavailable. + - Hardened the runtime utilities for Workers/Functions: added universal `randomUUID`, base64, and event-emitter helpers, and taught the default logger to emit OpenTelemetry logs without relying on Node globals. This removes the last Node-only dependencies from the serverless bundle. - **Key Features:** - - **Pino-based Logger**: High-performance logging with minimal overhead - - **Pretty Formatting**: Human-readable output in development with colors and structured formatting - - **Multiple Transports**: Support for console, file, and custom transports - - **Child Logger Support**: Create contextual loggers with inherited configuration - - **Log Buffering**: In-memory buffer for accessing recent logs programmatically - - **Environment-aware Defaults**: Automatic configuration based on NODE_ENV - - **Redaction Support**: Built-in sensitive data redaction - - **Extensible Architecture**: Provider-based design for custom implementations + ```ts + import { Agent, VoltAgent } from "@voltagent/core"; + import { serverlessHono } from "@voltagent/serverless-hono"; + import { openai } from "@ai-sdk/openai"; - **Usage Example:** + import { weatherTool } from "./tools"; - ```typescript - import { createPinoLogger } from "@voltagent/logger"; + const assistant = new Agent({ + name: "serverless-assistant", + instructions: "You are a helpful assistant.", + model: openai("gpt-4o-mini"), + }); - const logger = createPinoLogger({ - level: "info", - name: "my-app", + const voltAgent = new VoltAgent({ + agents: { assistant }, + serverless: serverlessHono(), }); + + export default voltAgent.serverless().toCloudflareWorker(); ``` - This package replaces the basic ConsoleLogger in @voltagent/core for production use cases, offering significantly improved debugging capabilities and performance. + ## @voltagent/serverless-hono + - Renamed the edge provider to **serverless** and upgraded it to power any fetch-based runtime (Cloudflare Workers, Vercel Edge Functions, Deno Deploy, Netlify Functions). + - Wrapped the Cloudflare adapter in a first-class `HonoServerlessProvider` that installs a scoped `waitUntil` bridge, reuses the shared routing layer, and exposes a `/ws` health stub so VoltOps Console can cleanly fall back to polling. + - Dropped the manual environment merge – Workers should now enable the `nodejs_compat_populate_process_env` flag (documented in the new deployment guide) instead of calling `mergeProcessEnv` themselves. -- Updated dependencies [[`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726)]: - - @voltagent/internal@0.0.6 + ## @voltagent/server-core + - Reworked the observability handlers around the shared storage API, including a new `POST /setup-observability` helper that writes VoltOps keys into `.env` and expanded trace/log queries that match the serverless storage contract. + + ## @voltagent/cli + - Added `volt deploy --target ` to scaffold the right config files. The Cloudflare template now ships with the required compatibility flags (`nodejs_compat`, `nodejs_compat_populate_process_env`, `no_handle_cross_request_promise_resolution`) so new projects run on Workers without extra tweaking. + +- Updated dependencies [[`f4fa7e2`](https://github.com/VoltAgent/voltagent/commit/f4fa7e297fec2f602c9a24a0c77e645aa971f2b9)]: + - @voltagent/server-core@1.0.12 --- -## Package: @voltagent/postgres +## Package: @voltagent/supabase -## 0.1.12 +## 2.0.2 ### Patch Changes -- [#466](https://github.com/VoltAgent/voltagent/pull/466) [`730232e`](https://github.com/VoltAgent/voltagent/commit/730232e730cdbd1bb7de6acff8519e8af93f2abf) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: memory messages now return parsed objects instead of JSON strings +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) - ## What Changed for You + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. - Memory messages that contain structured content (like tool calls or multi-part messages) now return as **parsed objects** instead of **JSON strings**. This is a breaking change if you were manually parsing these messages. + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` - ## Before - You Had to Parse JSON Manually + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ - ```typescript - // ❌ OLD BEHAVIOR: Content came as JSON string - const messages = await memory.getMessages({ conversationId: "123" }); +- Updated dependencies [[`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505)]: + - @voltagent/internal@1.0.2 - // What you got from memory: - console.log(messages[0]); - // { - // role: "user", - // content: '[{"type":"text","text":"Hello"},{"type":"image","image":"data:..."}]', // STRING! - // type: "text" - // } +## 2.0.1 - // You had to manually parse the JSON string: - const content = JSON.parse(messages[0].content); // Parse required! - console.log(content); - // [ - // { type: "text", text: "Hello" }, - // { type: "image", image: "data:..." } - // ] +### Patch Changes - // Tool calls were also JSON strings: - console.log(messages[1].content); - // '[{"type":"tool-call","toolCallId":"123","toolName":"weather"}]' // STRING! - ``` +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) - ## After - You Get Parsed Objects Automatically + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. - ```typescript - // ✅ NEW BEHAVIOR: Content comes as proper objects - const messages = await memory.getMessages({ conversationId: "123" }); + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` - // What you get from memory NOW: - console.log(messages[0]); - // { - // role: "user", - // content: [ - // { type: "text", text: "Hello" }, // OBJECT! - // { type: "image", image: "data:..." } // OBJECT! - // ], - // type: "text" - // } + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ - // Direct access - no JSON.parse needed! - const content = messages[0].content; // Already parsed! - console.log(content[0].text); // "Hello" +- Updated dependencies [[`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2)]: + - @voltagent/internal@1.0.1 - // Tool calls are proper objects: - console.log(messages[1].content); - // [ - // { type: "tool-call", toolCallId: "123", toolName: "weather" } // OBJECT! - // ] - ``` +## 2.0.0 - ## Breaking Change Warning ⚠️ +### Major Changes - If your code was doing this: +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) - ```typescript - // This will now FAIL because content is already parsed - const parsed = JSON.parse(msg.content); // ❌ Error: not a string! - ``` + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. - Change it to: + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` - ```typescript - // Just use the content directly - const content = msg.content; // ✅ Already an object/array - ``` + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ - ## What Gets Auto-Parsed - - **String content** → Stays as string ✅ - - **Structured content** (arrays) → Auto-parsed to objects ✅ - - **Tool calls** → Auto-parsed to objects ✅ - - **Tool results** → Auto-parsed to objects ✅ - - **Metadata fields** → Auto-parsed to objects ✅ +### Patch Changes - ## Why This Matters - - **No more JSON.parse errors** in your application - - **Type-safe access** to structured content - - **Cleaner code** without try/catch blocks - - **Consistent behavior** with how agents handle messages +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/core@2.0.0 + - @voltagent/internal@1.0.0 + - @voltagent/logger@2.0.0 - ## Migration Guide - 1. **Remove JSON.parse calls** for message content - 2. **Remove try/catch** blocks around parsing - 3. **Use content directly** as objects/arrays +## 1.0.11 - Your memory messages now "just work" without manual parsing! +### Patch Changes -## 0.1.11 +- [#845](https://github.com/VoltAgent/voltagent/pull/845) [`5432f13`](https://github.com/VoltAgent/voltagent/commit/5432f13bddebd869522ebffbedd9843b4476f08b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: workflow execution listing - #844 -### Patch Changes + Added a unified way to list workflow runs so teams can audit executions across every storage backend and surface them via the API and console. -- [#457](https://github.com/VoltAgent/voltagent/pull/457) [`8d89469`](https://github.com/VoltAgent/voltagent/commit/8d8946919820c0298bffea13731ea08660b72c4b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: optimize agent event system and add pagination to agent history API + ## What changed + - `queryWorkflowRuns` now exists on all memory adapters (in-memory, libsql, Postgres, Supabase, voltagent-memory) with filters for `workflowId`, `status`, `from`, `to`, `limit`, and `offset`. + - Server routes are consolidated under `/workflows/executions` (no path param needed); `GET /workflows/:id` also returns the workflow result schema for typed clients. Handler naming is standardized to `listWorkflowRuns`. + - VoltOps Console observability panel lists the new endpoint; REST docs updated with query params and sample responses. New unit tests cover handlers and every storage adapter. - Significantly improved agent performance and UI scalability with two major enhancements: + ## Quick fetch - ## 1. Event System Optimization + ```ts + await fetch( + "http://localhost:3141/workflows/executions?workflowId=expense-approval&status=completed&from=2024-01-01&to=2024-01-31&limit=20&offset=0" + ); + ``` - Refactored agent event system to emit events immediately before database writes, matching the workflow event system behavior. This provides real-time event visibility without waiting for persistence operations. +## 1.0.10 - **Before:** - - Events were queued and only emitted after database write completion - - Real-time monitoring was delayed by persistence operations +### Patch Changes - **After:** - - Events emit immediately for real-time updates - - Database persistence happens asynchronously in the background - - Consistent behavior with workflow event system +- [#820](https://github.com/VoltAgent/voltagent/pull/820) [`c5e0c89`](https://github.com/VoltAgent/voltagent/commit/c5e0c89554d85c895e3d6cbfc83ad47bd53a1b9f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: expose createdAt in memory.getMessages - ## 2. Agent History Pagination + ## What Changed - Added comprehensive pagination support to agent history API, preventing performance issues when loading large history datasets. + The `createdAt` timestamp is now exposed in the `metadata` object of messages retrieved via `memory.getMessages()`. This ensures that the creation time of messages is accessible across all storage adapters (`InMemory`, `Supabase`, `LibSQL`, `PostgreSQL`). - **New API:** + ## Usage + + You can now access the `createdAt` timestamp from the message metadata: ```typescript - // Agent class - const history = await agent.getHistory({ page: 0, limit: 20 }); - // Returns: { entries: AgentHistoryEntry[], pagination: { page, limit, total, totalPages } } + const messages = await memory.getMessages(userId, conversationId); - // REST API - GET /agents/:id/history?page=0&limit=20 - // Returns paginated response format + messages.forEach((message) => { + console.log(`Message ID: ${message.id}`); + console.log(`Created At: ${message.metadata?.createdAt}`); + }); ``` - **Implementation Details:** - - Added pagination to all storage backends (LibSQL, PostgreSQL, Supabase, InMemory) - - Updated WebSocket initial load to use pagination - - Maintained backward compatibility (when page/limit not provided, returns first 100 entries) - - Updated all tests to work with new pagination format + This change aligns the behavior of all storage adapters and ensures consistent access to message timestamps. - **Storage Changes:** - - LibSQL: Added LIMIT/OFFSET support - - PostgreSQL: Added pagination with proper SQL queries - - Supabase: Used `.range()` method for efficient pagination - - InMemory: Implemented array slicing with total count +## 1.0.9 - This improves performance for agents with extensive history and provides better UX for viewing agent execution history. +### Patch Changes -- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements +- [#801](https://github.com/VoltAgent/voltagent/pull/801) [`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add triggers DSL improvements and event payload simplification + - Introduce the new `createTriggers` DSL and expose trigger events via sensible provider names (e.g. `on.airtable.recordCreated`) rather than raw catalog IDs. + - Add trigger span metadata propagation so VoltAgent agents receive trigger context automatically without manual mapping. + - Simplify action dispatch payloads: `payload` now contains only the event’s raw data while trigger context lives in the `event`/`metadata` blocks, reducing boilerplate in handlers. - This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + ```ts + import { VoltAgent, createTriggers } from "@voltagent/core"; - **Key improvements:** - - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs - - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration - - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries - - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup - - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + new VoltAgent({ + // ... + triggers: createTriggers((on) => { + on.airtable.recordCreated(({ payload, event }) => { + console.log("New Airtable row", payload, event.metadata); + }); - These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. + on.gmail.newEmail(({ payload }) => { + console.log("New Gmail message", payload); + }); + }), + }); + ``` -## 0.1.10 +## 1.0.8 + +### Patch Changes + +- [#787](https://github.com/VoltAgent/voltagent/pull/787) [`5e81d65`](https://github.com/VoltAgent/voltagent/commit/5e81d6568ba3bee26083ca2a8e5d31f158e36fc0) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add full conversation step persistence across the stack: + - Core now exposes managed-memory step APIs, and the VoltAgent managed memory adapter persists/retrieves steps through VoltOps. + - LibSQL, PostgreSQL, Supabase, and server handlers provision the new `_steps` table, wire up DTOs/routes, and surface the data in Observability/Steps UI (including managed-memory backends). + + fixes: #613 + +## 1.0.7 + +### Patch Changes + +- [#738](https://github.com/VoltAgent/voltagent/pull/738) [`d3ed347`](https://github.com/VoltAgent/voltagent/commit/d3ed347e064cb36e04ed1ea98d9305b63fd968ec) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: persist workflow execution timeline events to prevent data loss after completion - #647 + + ## The Problem + + When workflows executed, their timeline events (step-start, step-complete, workflow-complete, etc.) were only visible during streaming. Once the workflow completed, the WebSocket state update would replace the execution object without the events field, causing the timeline UI to reset and lose all execution history. Users couldn't see what happened in completed or suspended workflows. -### Patch Changes + **Symptoms:** + - Timeline showed events during execution + - Timeline cleared/reset when workflow completed + - No execution history for completed workflows + - Events were lost after browser refresh -- [#423](https://github.com/VoltAgent/voltagent/pull/423) [`089c039`](https://github.com/VoltAgent/voltagent/commit/089c03993e3b9e05655a1108355e7bee940d33a7) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add message type filtering support to memory storage implementations + ## The Solution - Added the ability to filter messages by type when retrieving conversation history. This enhancement allows the framework to distinguish between different message types (text, tool-call, tool-result) and retrieve only the desired types, improving context preparation for LLMs. + **Backend (Framework)**: + - Added `events`, `output`, and `cancellation` fields to `WorkflowStateEntry` interface + - Modified workflow execution to collect all stream events in memory during execution + - Persist collected events to workflow state when workflow completes, suspends, fails, or is cancelled + - Updated all storage adapters to support the new fields: + - **LibSQL**: Added schema columns + automatic migration method (`addWorkflowStateColumns`) + - **Supabase**: Added schema columns + migration detection + ALTER TABLE migration SQL + - **Postgres**: Added schema columns + INSERT/UPDATE queries + - **In-Memory**: Automatically supported via TypeScript interface - ## Key Changes - - **MessageFilterOptions**: Added optional `types` parameter to filter messages by type - - **prepareConversationContext**: Now filters to only include text messages, excluding tool-call and tool-result messages for cleaner LLM context - - **All storage implementations**: Added database-level filtering for better performance + **Frontend (Console)**: + - Updated `WorkflowPlaygroundProvider` to include events when converting `WorkflowStateEntry` → `WorkflowHistoryEntry` + - Implemented smart merge strategy for WebSocket updates: Use backend persisted events when workflow finishes, keep streaming events during execution + - Events are now preserved across page refreshes and always visible in timeline UI - ## Usage + ## What Gets Persisted ```typescript - // Get only text messages - const textMessages = await memory.getMessages({ - userId: "user-123", - conversationId: "conv-456", - types: ["text"], - }); + // In WorkflowStateEntry (stored in Memory V2): + { + "events": [ + { + "id": "evt_123", + "type": "workflow-start", + "name": "Workflow Started", + "startTime": "2025-01-24T10:00:00Z", + "status": "running", + "input": { "userId": "123" } + }, + { + "id": "evt_124", + "type": "step-complete", + "name": "Step: fetch-user", + "startTime": "2025-01-24T10:00:01Z", + "endTime": "2025-01-24T10:00:02Z", + "status": "success", + "output": { "user": { "name": "John" } } + } + ], + "output": { "result": "success" }, + "cancellation": { + "cancelledAt": "2025-01-24T10:00:05Z", + "reason": "User requested cancellation" + } + } + ``` - // Get tool-related messages - const toolMessages = await memory.getMessages({ - userId: "user-123", - conversationId: "conv-456", - types: ["tool-call", "tool-result"], - }); + ## Migration Guide - // Get all messages (default behavior - backward compatible) - const allMessages = await memory.getMessages({ - userId: "user-123", - conversationId: "conv-456", - }); - ``` + ### LibSQL Users - ## Implementation Details - - **InMemoryStorage**: Filters messages in memory after retrieval - - **LibSQLStorage**: Adds SQL WHERE clause with IN operator for type filtering - - **PostgreSQL**: Uses parameterized IN clause with proper parameter counting - - **Supabase**: Utilizes query builder's `.in()` method for type filtering + No action required - migrations run automatically on next initialization. - This change ensures that `prepareConversationContext` provides cleaner, more focused context to LLMs by excluding intermediate tool execution details, while maintaining full backward compatibility for existing code. + ### Supabase Users -- Updated dependencies [[`089c039`](https://github.com/VoltAgent/voltagent/commit/089c03993e3b9e05655a1108355e7bee940d33a7)]: - - @voltagent/core@0.1.68 + When you upgrade and initialize the adapter, you'll see migration SQL in the console. Run it in your Supabase SQL Editor: -## 0.1.9 + ```sql + -- Add workflow event persistence columns + ALTER TABLE voltagent_workflow_states + ADD COLUMN IF NOT EXISTS events JSONB; -### Patch Changes + ALTER TABLE voltagent_workflow_states + ADD COLUMN IF NOT EXISTS output JSONB; -- [#418](https://github.com/VoltAgent/voltagent/pull/418) [`aa024c1`](https://github.com/VoltAgent/voltagent/commit/aa024c1a7c643b2aff7a5fd0d150c87f8a9a1858) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: memory storage implementations now correctly return the most recent messages when using context limit + ALTER TABLE voltagent_workflow_states + ADD COLUMN IF NOT EXISTS cancellation JSONB; + ``` - Fixed an issue where memory storage implementations (LibSQL, PostgreSQL, Supabase) were returning the oldest messages instead of the most recent ones when a context limit was specified. This was causing AI agents to lose important recent context in favor of old conversation history. + ### Postgres Users - **Before:** - - `contextLimit: 10` returned the first 10 messages (oldest) - - Agents were working with outdated context + No action required - migrations run automatically on next initialization. - **After:** - - `contextLimit: 10` returns the last 10 messages (most recent) in chronological order - - Agents now have access to the most relevant recent context - - InMemoryStorage was already working correctly and remains unchanged + ### In-Memory Users - Changes: - - LibSQLStorage: Modified query to use `ORDER BY DESC` with `LIMIT`, then reverse results - - PostgreSQL: Modified query to use `ORDER BY DESC` with `LIMIT`, then reverse results - - Supabase: Modified query to use `ascending: false` with `limit`, then reverse results + No action required - automatically supported. - This ensures consistent behavior across all storage implementations where context limits provide the most recent messages, improving AI agent response quality and relevance. + ### VoltAgent Managed Memory Users -- Updated dependencies [[`67450c3`](https://github.com/VoltAgent/voltagent/commit/67450c3bc4306ab6021ca8feed2afeef6dcc320e), [`aa024c1`](https://github.com/VoltAgent/voltagent/commit/aa024c1a7c643b2aff7a5fd0d150c87f8a9a1858), [`aa024c1`](https://github.com/VoltAgent/voltagent/commit/aa024c1a7c643b2aff7a5fd0d150c87f8a9a1858)]: - - @voltagent/core@0.1.67 + No action required - migrations run automatically on first request per managed memory database after API deployment. The API has been updated to: + - Include new columns in ManagedMemoryProvisioner CREATE TABLE statements (new databases) + - Run automatic column addition migration for existing databases (lazy migration on first request) + - Update PostgreSQL memory adapter to persist and retrieve events, output, and cancellation fields -## 0.1.8 + **Zero-downtime deployment:** Existing managed memory databases will be migrated lazily when first accessed after the API update. -### Patch Changes + ## Impact + - ✅ Workflow execution timeline is now persistent and survives completion + - ✅ Full execution history visible for completed, suspended, and failed workflows + - ✅ Events, output, and cancellation metadata preserved in database + - ✅ Console UI timeline works consistently across all workflow states + - ✅ All storage backends (LibSQL, Supabase, Postgres, In-Memory) behave consistently + - ✅ No data loss on workflow completion or page refresh -- [#371](https://github.com/VoltAgent/voltagent/pull/371) [`6ddedc2`](https://github.com/VoltAgent/voltagent/commit/6ddedc2b9be9c3dc4978dc53198a43c2cba74945) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add workflow history support to postgres +## 1.0.6 - This update introduces persistence for workflow history when using a PostgreSQL database. This includes storing workflow execution details, individual steps, and timeline events. Database tables are migrated automatically, so no manual action is required. +### Patch Changes -- Updated dependencies [[`6ddedc2`](https://github.com/VoltAgent/voltagent/commit/6ddedc2b9be9c3dc4978dc53198a43c2cba74945)]: - - @voltagent/core@0.1.60 +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` +- Updated dependencies [[`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e)]: + - @voltagent/internal@0.0.12 -## 0.1.7 +## 1.0.5 ### Patch Changes -- [#317](https://github.com/VoltAgent/voltagent/pull/317) [`16bb8d0`](https://github.com/VoltAgent/voltagent/commit/16bb8d003c17799688e8b70eb9236b46a5c339be) Thanks [@thujee](https://github.com/thujee)! - fix: errors related to missing columns "timestamp" and "utc" in Postgres schema - #316 +- [#674](https://github.com/VoltAgent/voltagent/pull/674) [`5aa84b5`](https://github.com/VoltAgent/voltagent/commit/5aa84b5bcf57d19bbe33cc791f0892c96bb3944b) Thanks [@omeraplak](https://github.com/omeraplak)! - ## What Changed -## 0.1.6 + Removed automatic message pruning functionality from all storage adapters (PostgreSQL, Supabase, LibSQL, and InMemory). Previously, messages were automatically deleted when the count exceeded `storageLimit` (default: 100 messages per conversation). -### Patch Changes + ## Why This Change -- [#301](https://github.com/VoltAgent/voltagent/pull/301) [`619e951`](https://github.com/VoltAgent/voltagent/commit/619e9510c05b7e46f8c243db226f220b5fdad824) Thanks [@woutrbe](https://github.com/woutrbe)! - fix(postgres): Fix default value being interpreted as column name + Users reported unexpected data loss when their conversation history exceeded the storage limit. Many users expect their conversation history to be preserved indefinitely rather than automatically deleted. This change gives users full control over their data retention policies. -- Updated dependencies [[`33afe6e`](https://github.com/VoltAgent/voltagent/commit/33afe6ef40ef56c501f7fa69be42da730f87d29d), [`b8529b5`](https://github.com/VoltAgent/voltagent/commit/b8529b53313fa97e941ecacb8c1555205de49c19)]: - - @voltagent/core@0.1.45 + ## Migration Guide -## 0.1.5 + ### Before -### Patch Changes + ```ts + const memory = new Memory({ + storage: new PostgreSQLMemoryAdapter({ + connection: process.env.DATABASE_URL, + storageLimit: 200, // Messages auto-deleted after 200 + }), + }); + ``` -- [#252](https://github.com/VoltAgent/voltagent/pull/252) [`88f2d06`](https://github.com/VoltAgent/voltagent/commit/88f2d0682413d27a7ac2d1d8cd502fd9c665e547) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add userId and conversationId support to agent history tables + ### After - This release adds comprehensive support for `userId` and `conversationId` fields in agent history tables across all memory storage implementations, enabling better conversation tracking and user-specific history management. + ```ts + const memory = new Memory({ + storage: new PostgreSQLMemoryAdapter({ + connection: process.env.DATABASE_URL, + // No storageLimit - all messages preserved + }), + }); + ``` - ### New Features - - **Agent History Enhancement**: Added `userId` and `conversationId` columns to agent history tables - - **Cross-Implementation Support**: Consistent implementation across PostgreSQL, Supabase, LibSQL, and In-Memory storage - - **Automatic Migration**: Safe schema migrations for existing installations - - **Backward Compatibility**: Existing history entries remain functional + ### If You Need Message Cleanup - ### Migration Notes + Implement your own cleanup logic using the `clearMessages()` method: - **PostgreSQL & Supabase**: Automatic schema migration with user-friendly SQL scripts - **LibSQL**: Seamless column addition with proper indexing - **In-Memory**: No migration required, immediate support + ```ts + // Clear all messages for a conversation + await memory.clearMessages(userId, conversationId); - ### Technical Details - - **Database Schema**: Added `userid TEXT` and `conversationid TEXT` columns (PostgreSQL uses lowercase) - - **Indexing**: Performance-optimized indexes for new columns - - **Migration Safety**: Non-destructive migrations with proper error handling - - **API Consistency**: Unified interface across all storage implementations + // Clear all messages for a user + await memory.clearMessages(userId); + ``` -- Updated dependencies [[`88f2d06`](https://github.com/VoltAgent/voltagent/commit/88f2d0682413d27a7ac2d1d8cd502fd9c665e547), [`b63fe67`](https://github.com/VoltAgent/voltagent/commit/b63fe675dfca9121862a9dd67a0fae5d39b9db90)]: - - @voltagent/core@0.1.37 + ## Affected Packages + - `@voltagent/core` - Removed `storageLimit` from types + - `@voltagent/postgres` - Removed from PostgreSQL adapter + - `@voltagent/supabase` - Removed from Supabase adapter + - `@voltagent/libsql` - Removed from LibSQL adapter -## 0.1.4 + ## Impact + - ✅ No more unexpected data loss + - ✅ Users have full control over message retention + - ⚠️ Databases may grow larger over time (consider implementing manual cleanup) + - ⚠️ Breaking change: `storageLimit` parameter no longer accepted + +## 1.0.4 ### Patch Changes -- [#236](https://github.com/VoltAgent/voltagent/pull/236) [`5d39cdc`](https://github.com/VoltAgent/voltagent/commit/5d39cdc68c4ec36ec2f0bf86a29dbf1225644416) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: PostgreSQL string literal syntax error in timeline events table +- Updated dependencies [[`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7), [`355836b`](https://github.com/VoltAgent/voltagent/commit/355836b39a6d1ba36c5cfac82008cab3281703e7)]: + - @voltagent/internal@0.0.11 - Fixed PostgreSQL syntax error where `level TEXT DEFAULT "INFO"` was using double quotes instead of single quotes for string literals. This resolves table creation failures during fresh installations and migrations. +## 1.0.3 - ### Changes - - **Fixed**: `level TEXT DEFAULT "INFO"` → `level TEXT DEFAULT 'INFO'` - - **Affects**: Timeline events table creation in both fresh installations and migrations - - **Impact**: PostgreSQL database setup now works without syntax errors +### Patch Changes - ### Technical Details +- [`9cc4ea4`](https://github.com/VoltAgent/voltagent/commit/9cc4ea4a4985320139e33e8029f299c7ec8329a6) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: @voltagent/core peerDependency version - PostgreSQL requires single quotes for string literals and double quotes for identifiers. The timeline events table creation was failing due to incorrect quote usage for the default value. +## 1.0.2 - **Migration Notes:** - - Existing installations with timeline events table will not be affected - - Fresh installations will now complete successfully - - No manual intervention required +## 1.0.2-next.0 -- Updated dependencies [[`5d39cdc`](https://github.com/VoltAgent/voltagent/commit/5d39cdc68c4ec36ec2f0bf86a29dbf1225644416), [`16c2a86`](https://github.com/VoltAgent/voltagent/commit/16c2a863d3ecdc09f09219bd40f2dbf1d789194d), [`0d85f0e`](https://github.com/VoltAgent/voltagent/commit/0d85f0e960dbc6e8df6a79a16c775ca7a34043bb)]: - - @voltagent/core@0.1.33 +### Patch Changes -## 0.1.3 +- Updated dependencies [[`77a3f64`](https://github.com/VoltAgent/voltagent/commit/77a3f64dea6e8a06fbbd72878711efa9ceb90bc3)]: + - @voltagent/core@1.1.7-next.0 + +## 1.0.1 ### Patch Changes -- [#215](https://github.com/VoltAgent/voltagent/pull/215) [`f2f4539`](https://github.com/VoltAgent/voltagent/commit/f2f4539af7722f25a5aad9f01c2b7b5e50ba51b8) Thanks [@Ajay-Satish-01](https://github.com/Ajay-Satish-01)! - This release introduces powerful new methods for managing conversations with user-specific access control and improved developer experience. +- [`a0d9e84`](https://github.com/VoltAgent/voltagent/commit/a0d9e8404fe3e2cebfc146cd4622b607bd16b462) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: @voltagent/logger dependency version - ### Simple Usage Example +- Updated dependencies [[`134bf9a`](https://github.com/VoltAgent/voltagent/commit/134bf9a2978f0b069f842910fb4fb3e969f70390)]: + - @voltagent/internal@0.0.10 - ```typescript - // Get all conversations for a user - const conversations = await storage.getUserConversations("user-123").limit(10).execute(); +## 1.0.0 - console.log(conversations); +### Major Changes - // Get first conversation and its messages - const conversation = conversations[0]; - if (conversation) { - const messages = await storage.getConversationMessages(conversation.id); - console.log(messages); - } - ``` +- [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93) Thanks [@omeraplak](https://github.com/omeraplak)! - # Supabase 1.x — Memory Adapter - ### Pagination Support + Supabase storage now implements the Memory V2 adapter pattern. - ```typescript - // Get paginated conversations - const result = await storage.getPaginatedUserConversations("user-123", 1, 20); - console.log(result.conversations); // Array of conversations - console.log(result.hasMore); // Boolean indicating if more pages exist + Full migration guide: [Migration Guide](https://voltagent.dev/docs/getting-started/migration-guide/) + + ## Migrate + + Before (0.1.x): + + ```ts + import { SupabaseMemory } from "@voltagent/supabase"; + + const agent = new Agent({ + // ... + memory: new SupabaseMemory({ url: process.env.SUPABASE_URL!, key: process.env.SUPABASE_KEY! }), + }); ``` -- Updated dependencies [[`f2f4539`](https://github.com/VoltAgent/voltagent/commit/f2f4539af7722f25a5aad9f01c2b7b5e50ba51b8), [`0eba8a2`](https://github.com/VoltAgent/voltagent/commit/0eba8a265c35241da74324613e15801402f7b778)]: - - @voltagent/core@0.1.32 + After (1.x): -## 0.1.2 + ```ts + import { Memory } from "@voltagent/core"; + import { SupabaseMemoryAdapter } from "@voltagent/supabase"; -### Patch Changes + const agent = new Agent({ + // ... + memory: new Memory({ + storage: new SupabaseMemoryAdapter({ + url: process.env.SUPABASE_URL!, + key: process.env.SUPABASE_KEY!, + }), + }), + }); + ``` -- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 +### Patch Changes -- Updated dependencies [[`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f), [`80fd3c0`](https://github.com/VoltAgent/voltagent/commit/80fd3c069de4c23116540a55082b891c4b376ce6)]: - - @voltagent/core@0.1.31 +- [`c2a6ae1`](https://github.com/VoltAgent/voltagent/commit/c2a6ae125abf9c0b6642927ee78721c6a83dc0f8) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: @voltagent/logger dependency -## 0.1.1 +## 1.0.0-next.2 ### Patch Changes -- [#176](https://github.com/VoltAgent/voltagent/pull/176) [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275) Thanks [@omeraplak](https://github.com/omeraplak)! - The `error` column has been deprecated and replaced with `statusMessage` column for better consistency and clearer messaging. The old `error` column is still supported for backward compatibility but will be removed in a future major version. +- [`c2a6ae1`](https://github.com/VoltAgent/voltagent/commit/c2a6ae125abf9c0b6642927ee78721c6a83dc0f8) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: @voltagent/logger dependency - Changes: - - Deprecated `error` column (still functional) - - Improved error handling and status reporting +## 1.0.0-next.1 -- Updated dependencies [[`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275), [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275)]: - - @voltagent/core@0.1.24 +### Major Changes ---- +- [`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93) Thanks [@omeraplak](https://github.com/omeraplak)! - # Supabase 1.x — Memory Adapter -## Package: @voltagent/sdk + Supabase storage now implements the Memory V2 adapter pattern. -## 0.1.6 + Full migration guide: [Migration Guide](https://voltagent.dev/docs/getting-started/migration-guide/) -### Patch Changes + ## Migrate -- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements + Before (0.1.x): - This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + ```ts + import { SupabaseMemory } from "@voltagent/supabase"; - **Key improvements:** - - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs - - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration - - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries - - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup - - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + const agent = new Agent({ + // ... + memory: new SupabaseMemory({ url: process.env.SUPABASE_URL!, key: process.env.SUPABASE_KEY! }), + }); + ``` - These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. + After (1.x): -- Updated dependencies [[`8d89469`](https://github.com/VoltAgent/voltagent/commit/8d8946919820c0298bffea13731ea08660b72c4b), [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5), [`71500c5`](https://github.com/VoltAgent/voltagent/commit/71500c5368cce3ed4aacfb0fb2749752bf71badd), [`6cc552a`](https://github.com/VoltAgent/voltagent/commit/6cc552ada896b1a8344976c46a08b53d2b3a5743)]: - - @voltagent/core@0.1.73 + ```ts + import { Memory } from "@voltagent/core"; + import { SupabaseMemoryAdapter } from "@voltagent/supabase"; -## 0.1.5 + const agent = new Agent({ + // ... + memory: new Memory({ + storage: new SupabaseMemoryAdapter({ + url: process.env.SUPABASE_URL!, + key: process.env.SUPABASE_KEY!, + }), + }), + }); + ``` ### Patch Changes -- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 +- Updated dependencies [[`a2b492e`](https://github.com/VoltAgent/voltagent/commit/a2b492e8ed4dba96fa76862bbddf156f3a1a5c93)]: + - @voltagent/logger@1.0.0-next.0 -- Updated dependencies [[`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f), [`80fd3c0`](https://github.com/VoltAgent/voltagent/commit/80fd3c069de4c23116540a55082b891c4b376ce6)]: - - @voltagent/core@0.1.31 +## 1.0.0-next.0 -## 0.1.4 +### Patch Changes + +- Updated dependencies [[`64a50e6`](https://github.com/VoltAgent/voltagent/commit/64a50e6800dec844fad7b9f3a3b1c2c8d0486229), [`9e8b211`](https://github.com/VoltAgent/voltagent/commit/9e8b2119a783942f114459f0a9b93e645727445e)]: + - @voltagent/core@1.0.0-next.0 + +## 0.1.20 ### Patch Changes -- [#176](https://github.com/VoltAgent/voltagent/pull/176) [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: initial release of VoltAgent Observability SDK +- [#496](https://github.com/VoltAgent/voltagent/pull/496) [`0dcc675`](https://github.com/VoltAgent/voltagent/commit/0dcc6759eb1a95d756a49139610b5352db2e91b0) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve SupabaseClient ESM import error - A TypeScript SDK for monitoring AI agents and conversations with automatic event batching and structured tracing. + Fixed an issue where `SupabaseClient` was not available as a runtime export in the ESM build of @supabase/supabase-js v2.54.0. The type is exported in TypeScript definitions but not in the actual ESM runtime. - **Basic Usage:** + ## What Changed + - Changed `SupabaseClient` to a type-only import using `import { type SupabaseClient }` + - Replaced `P.instanceOf(SupabaseClient)` pattern matching with `P.not(P.nullish)` since the class is not available at runtime + - Added type assertion to maintain TypeScript type safety + + ## Before ```typescript - const sdk = new VoltAgentObservabilitySDK({ - baseUrl: "https://api.voltagent.dev", - publicKey: "your-public-key", - secretKey: "your-secret-key", - autoFlush: true, - flushInterval: 3000, - }); + import { SupabaseClient, createClient } from "@supabase/supabase-js"; + // ... + .with({ client: P.instanceOf(SupabaseClient) }, (o) => o.client) + ``` - const trace = await sdk.trace({ - name: "Customer Support Query", - agentId: "support-agent-v1", - input: { query: "How to reset password?" }, - userId: "user-123", - conversationId: "conv-456", - }); + ## After - const agent = await trace.addAgent({ - name: "Support Agent", - model: "gpt-4", - input: { query: "User needs password reset help" }, - }); + ```typescript + import { createClient, type SupabaseClient } from "@supabase/supabase-js"; + // ... + .with({ client: P.not(P.nullish) }, (o) => o.client as SupabaseClient) ``` - Supports nested agent workflows, custom metadata, and automatic performance metrics collection. + This ensures compatibility with both CommonJS and ESM module systems while maintaining full type safety. -- Updated dependencies [[`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275), [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275)]: - - @voltagent/core@0.1.24 +- Updated dependencies [[`5968cef`](https://github.com/VoltAgent/voltagent/commit/5968cef5fe417cd118867ac78217dddfbd60493d)]: + - @voltagent/internal@0.0.9 + - @voltagent/logger@0.1.4 -## 0.1.3 +## 0.1.19 ### Patch Changes -- [#171](https://github.com/VoltAgent/voltagent/pull/171) [`1cd2a93`](https://github.com/VoltAgent/voltagent/commit/1cd2a9307d10bf5c90083138655aca9614d8053b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: initial release of Vercel AI SDK integration +- [#479](https://github.com/VoltAgent/voltagent/pull/479) [`8b55691`](https://github.com/VoltAgent/voltagent/commit/8b556910b0d1000bf0a956098e5ca49e733b9476) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - feat: Added `logger` to the SupabaseMemory provider and provided improved type safety for the constructor + + ### New Features + + #### `logger` + + You can now pass in a `logger` to the SupabaseMemory provider and it will be used to log messages. + + ```typescript + import { createPinoLogger } from "@voltagent/logger"; + + const memory = new SupabaseMemory({ + client: supabaseClient, + logger: createPinoLogger({ name: "memory-supabase" }), + }); + ``` + + #### Improved type safety for the constructor - Add support for Vercel AI SDK observability with automated tracing and monitoring capabilities. + The constructor now has improved type safety for the `client` and `logger` options. - Documentation: https://voltagent.dev/voltops-llm-observability-docs/vercel-ai/ + ```typescript + const memory = new SupabaseMemory({ + client: supabaseClient, + supabaseUrl: "https://test.supabase.co", // this will show a TypeScript error + supabaseKey: "test-key", + }); + ``` -## 0.1.1 + The `client` option also checks that the `client` is an instance of `SupabaseClient` -### Patch Changes + ```typescript + const memory = new SupabaseMemory({ + client: aNonSupabaseClient, // this will show a TypeScript error AND throw an error at runtime + }); + ``` -- [#160](https://github.com/VoltAgent/voltagent/pull/160) [`03ed437`](https://github.com/VoltAgent/voltagent/commit/03ed43723cd56f29ac67088f0624a88632a14a1b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: introduce new VoltAgent SDK package - - Add new `@voltagent/sdk` package for client-side interactions with VoltAgent API - - Includes VoltAgentClient for managing agents, conversations, and telemetry - - Provides wrapper utilities for enhanced agent functionality - - Supports TypeScript with complete type definitions + ### Internal Changes + - Cleaned up and reorganized the SupabaseMemory class + - Renamed files to be more descriptive and not in the `index.ts` file + - Added improved mocking to the test implementation for the SupabaseClient + - Removed all `console.*` statements and added a `biome` lint rule to prevent them from being added back -- Updated dependencies [[`03ed437`](https://github.com/VoltAgent/voltagent/commit/03ed43723cd56f29ac67088f0624a88632a14a1b)]: - - @voltagent/core@0.1.21 +## 0.1.18 ---- +### Patch Changes -## Package: @voltagent/supabase +- [#475](https://github.com/VoltAgent/voltagent/pull/475) [`9b4ea38`](https://github.com/VoltAgent/voltagent/commit/9b4ea38b28df248c1e1ad5541d414bd47838df9a) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: Remove other potentially problematic `JSON.stringify` usages ## 0.1.17 @@ -5243,313 +18273,90 @@ - [#215](https://github.com/VoltAgent/voltagent/pull/215) [`f2f4539`](https://github.com/VoltAgent/voltagent/commit/f2f4539af7722f25a5aad9f01c2b7b5e50ba51b8) Thanks [@Ajay-Satish-01](https://github.com/Ajay-Satish-01)! - This release introduces powerful new methods for managing conversations with user-specific access control and improved developer experience. - ### Simple Usage Example - - ```typescript - // Get all conversations for a user - const conversations = await storage.getUserConversations("user-123").limit(10).execute(); - - console.log(conversations); - - // Get first conversation and its messages - const conversation = conversations[0]; - if (conversation) { - const messages = await storage.getConversationMessages(conversation.id); - console.log(messages); - } - ``` - - ### Pagination Support - - ```typescript - // Get paginated conversations - const result = await storage.getPaginatedUserConversations("user-123", 1, 20); - console.log(result.conversations); // Array of conversations - console.log(result.hasMore); // Boolean indicating if more pages exist - ``` - -- Updated dependencies [[`f2f4539`](https://github.com/VoltAgent/voltagent/commit/f2f4539af7722f25a5aad9f01c2b7b5e50ba51b8), [`0eba8a2`](https://github.com/VoltAgent/voltagent/commit/0eba8a265c35241da74324613e15801402f7b778)]: - - @voltagent/core@0.1.32 - -## 0.1.8 - -### Patch Changes - -- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 - -- Updated dependencies [[`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f), [`80fd3c0`](https://github.com/VoltAgent/voltagent/commit/80fd3c069de4c23116540a55082b891c4b376ce6)]: - - @voltagent/core@0.1.31 - -## 0.1.7 - -### Patch Changes - -- [#176](https://github.com/VoltAgent/voltagent/pull/176) [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275) Thanks [@omeraplak](https://github.com/omeraplak)! - The `error` column has been deprecated and replaced with `statusMessage` column for better consistency and clearer messaging. The old `error` column is still supported for backward compatibility but will be removed in a future major version. - - Changes: - - Deprecated `error` column (still functional) - - Improved error handling and status reporting - -- Updated dependencies [[`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275), [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275)]: - - @voltagent/core@0.1.24 - -## 0.1.6 - -### Patch Changes - -- [#160](https://github.com/VoltAgent/voltagent/pull/160) [`03ed437`](https://github.com/VoltAgent/voltagent/commit/03ed43723cd56f29ac67088f0624a88632a14a1b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: enhanced Supabase memory provider with better performance - - We've significantly improved the Supabase memory provider with better schema design and enhanced performance capabilities. The update includes database schema changes that require migration. - - Migration commands will appear in your terminal - follow those instructions to apply the database changes. If you experience any issues with the migration or memory operations, please reach out on [Discord](https://s.voltagent.dev/discord) for assistance. - - **What's Improved:** - - Better performance for memory operations and large datasets - - Enhanced database schema with optimized indexing - - Improved error handling and data validation - - Better support for timeline events and metadata storage - - **Migration Notes:** - - Migration commands will be displayed in your terminal - - Follow the terminal instructions to update your database schema - - Existing memory data will be preserved during the migration - -- Updated dependencies [[`03ed437`](https://github.com/VoltAgent/voltagent/commit/03ed43723cd56f29ac67088f0624a88632a14a1b)]: - - @voltagent/core@0.1.21 - -## 0.1.5 - -### Patch Changes - -- [#155](https://github.com/VoltAgent/voltagent/pull/155) [`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c) Thanks [@baseballyama](https://github.com/baseballyama)! - chore: update `tsconfig.json`'s `target` to `ES2022` - -- Updated dependencies [[`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c), [`b164bd0`](https://github.com/VoltAgent/voltagent/commit/b164bd014670452cb162b388f03565db992767af), [`9412cf0`](https://github.com/VoltAgent/voltagent/commit/9412cf0633f20d6b77c87625fc05e9e216936758)]: - - @voltagent/core@0.1.20 - -## 0.1.4 - -### Patch Changes - -- [#102](https://github.com/VoltAgent/voltagent/pull/102) [`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3) Thanks [@omeraplak](https://github.com/omeraplak)! - refactor: use 'instructions' field for Agent definitions in examples - #88 - - Updated documentation examples (READMEs, docs, blogs) and relevant package code examples to use the `instructions` field instead of `description` when defining `Agent` instances. - - This change aligns the examples with the preferred API usage for the `Agent` class, where `instructions` provides behavioral guidance to the agent/LLM. This prepares for the eventual deprecation of the `description` field specifically for `Agent` class definitions. - - **Example Change for Agent Definition:** - - ```diff - const agent = new Agent({ - name: "My Assistant", - - description: "A helpful assistant.", - + instructions: "A helpful assistant.", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - }); - ``` - -- Updated dependencies [[`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3)]: - - @voltagent/core@0.1.14 - -## 0.1.3 - -### Patch Changes - -- [#71](https://github.com/VoltAgent/voltagent/pull/71) [`1f20509`](https://github.com/VoltAgent/voltagent/commit/1f20509528fc2cb2ba00f86d649848afae34af04) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Standardize Agent Error and Finish Handling - - This change introduces a more robust and consistent way errors and successful finishes are handled across the `@voltagent/core` Agent and LLM provider implementations (like `@voltagent/vercel-ai`). - - **Key Improvements:** - - **Standardized Errors (`VoltAgentError`):** - - Introduced `VoltAgentError`, `ToolErrorInfo`, and `StreamOnErrorCallback` types in `@voltagent/core`. - - LLM Providers (e.g., Vercel) now wrap underlying SDK/API errors into a structured `VoltAgentError` before passing them to `onError` callbacks or throwing them. - - Agent methods (`generateText`, `streamText`, `generateObject`, `streamObject`) now consistently handle `VoltAgentError`, enabling richer context (stage, code, tool details) in history events and logs. - - - **Standardized Stream Finish Results:** - - Introduced `StreamTextFinishResult`, `StreamTextOnFinishCallback`, `StreamObjectFinishResult`, and `StreamObjectOnFinishCallback` types in `@voltagent/core`. - - LLM Providers (e.g., Vercel) now construct these standardized result objects upon successful stream completion. - - Agent streaming methods (`streamText`, `streamObject`) now receive these standardized results in their `onFinish` handlers, ensuring consistent access to final output (`text` or `object`), `usage`, `finishReason`, etc., for history, events, and hooks. - - - **Updated Interfaces:** The `LLMProvider` interface and related options types (`StreamTextOptions`, `StreamObjectOptions`) have been updated to reflect these new standardized callback types and error-throwing expectations. - - These changes lead to more predictable behavior, improved debugging capabilities through structured errors, and a more consistent experience when working with different LLM providers. - -- Updated dependencies [[`1f20509`](https://github.com/VoltAgent/voltagent/commit/1f20509528fc2cb2ba00f86d649848afae34af04), [`1f20509`](https://github.com/VoltAgent/voltagent/commit/1f20509528fc2cb2ba00f86d649848afae34af04), [`7a7a0f6`](https://github.com/VoltAgent/voltagent/commit/7a7a0f672adbe42635c3edc5f0a7f282575d0932)]: - - @voltagent/core@0.1.9 - -## 0.1.2 - -### Patch Changes - -- [#33](https://github.com/VoltAgent/voltagent/pull/33) [`3ef2eaa`](https://github.com/VoltAgent/voltagent/commit/3ef2eaa9661e8ecfebf17af56b09af41285d0ca9) Thanks [@kwaa](https://github.com/kwaa)! - Update package.json files: - - Remove `src` directory from the `files` array. - - Add explicit `exports` field for better module resolution. - -- Updated dependencies [[`52d5fa9`](https://github.com/VoltAgent/voltagent/commit/52d5fa94045481dc43dc260a40b701606190585c), [`3ef2eaa`](https://github.com/VoltAgent/voltagent/commit/3ef2eaa9661e8ecfebf17af56b09af41285d0ca9), [`52d5fa9`](https://github.com/VoltAgent/voltagent/commit/52d5fa94045481dc43dc260a40b701606190585c)]: - - @voltagent/core@0.1.6 - -## 0.1.1 - -### Patch Changes - -- [#21](https://github.com/VoltAgent/voltagent/pull/21) [`8c3506e`](https://github.com/VoltAgent/voltagent/commit/8c3506e27486ac371192ef9ffb6a997e8e1692e9) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Introduce Supabase Memory Provider (`@voltagent/supabase`) - - This new package provides a persistent memory solution for VoltAgent using Supabase. - - **Features:** - - Stores conversation history, agent history entries, events, and steps in your Supabase database. - - Requires specific table setup in your Supabase project (SQL provided in the package README). - - Easy integration by initializing `SupabaseMemory` with your Supabase URL and key and passing it to your `Agent` configuration. - - See the `@voltagent/supabase` [README](https://github.com/voltagent/voltagent/blob/main/packages/supabase/README.md) and [Documentation](https://voltagent.dev/docs/agents/memory/supabase/) for detailed setup and usage instructions. - - closes #8 - ---- - -## Package: @voltagent/vercel-ai - -## 0.1.17 - -### Patch Changes - -- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements - - This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: - - **Key improvements:** - - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs - - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration - - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries - - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup - - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported - - These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. - -## 0.1.16 - -### Patch Changes - -- [#425](https://github.com/VoltAgent/voltagent/pull/425) [`8605e70`](https://github.com/VoltAgent/voltagent/commit/8605e708d17e6fa0150bd13235e795288422c52b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Promise-based properties and warnings to AI responses - #422 - - Enhanced AI response types to align with Vercel AI SDK's API and provide better metadata: - - **For `streamObject`:** - - Added optional `object?: Promise` property that resolves to the final generated object - - Added optional `usage?: Promise` property that resolves to token usage information - - Added optional `warnings?: Promise` property for provider warnings - - **For `streamText`:** - - Added optional `text?: Promise` property that resolves to the full generated text - - Added optional `finishReason?: Promise` property that resolves to the reason generation stopped - - Added optional `usage?: Promise` property that resolves to token usage information - - Added optional `reasoning?: Promise` property that resolves to model's reasoning text - - **For `generateText` and `generateObject`:** - - Added optional `reasoning?: string` property for model's reasoning text (generateText only) - - Added optional `warnings?: any[]` property for provider warnings - - These properties are optional to maintain backward compatibility. Providers that support these features (like Vercel AI) now return these values, allowing users to access rich metadata: - - ```typescript - // For streamObject - const response = await agent.streamObject(input, schema); - const finalObject = await response.object; // Promise - const usage = await response.usage; // Promise - - // For streamText - const response = await agent.streamText(input); - const fullText = await response.text; // Promise - const usage = await response.usage; // Promise - - // For generateText - const response = await agent.generateText(input); - console.log(response.warnings); // Any provider warnings - console.log(response.reasoning); // Model's reasoning (if available) - ``` - -- Updated dependencies [[`8605e70`](https://github.com/VoltAgent/voltagent/commit/8605e708d17e6fa0150bd13235e795288422c52b)]: - - @voltagent/core@0.1.69 - -## 0.1.15 - -### Patch Changes - -- [`1f8ce22`](https://github.com/VoltAgent/voltagent/commit/1f8ce226fec449f16f1dce6c2b96cef7030eff3a) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: zod peer dependency to allow flexible versioning (^3.24.2 instead of 3.24.2) to resolve npm install conflicts - -- Updated dependencies [[`1f8ce22`](https://github.com/VoltAgent/voltagent/commit/1f8ce226fec449f16f1dce6c2b96cef7030eff3a)]: - - @voltagent/core@0.1.66 - -## 0.1.14 + ### Simple Usage Example -### Patch Changes + ```typescript + // Get all conversations for a user + const conversations = await storage.getUserConversations("user-123").limit(10).execute(); -- [#401](https://github.com/VoltAgent/voltagent/pull/401) [`4a7145d`](https://github.com/VoltAgent/voltagent/commit/4a7145debd66c7b1dfb953608e400b6c1ed02db7) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve TypeScript performance issues by fixing Zod dependency configuration (#377) + console.log(conversations); - Moved Zod from direct dependencies to peer dependencies in @voltagent/vercel-ai to prevent duplicate Zod installations that were causing TypeScript server slowdowns. Also standardized Zod versions across the workspace to ensure consistency. + // Get first conversation and its messages + const conversation = conversations[0]; + if (conversation) { + const messages = await storage.getConversationMessages(conversation.id); + console.log(messages); + } + ``` - Changes: - - @voltagent/vercel-ai: Moved `zod` from dependencies to peerDependencies - - @voltagent/docs-mcp: Updated `zod` from `^3.23.8` to `3.24.2` - - @voltagent/with-postgres: Updated `zod` from `^3.24.2` to `3.24.2` (removed caret) + ### Pagination Support - This fix significantly improves TypeScript language server performance by ensuring only one Zod version is processed, eliminating the "Type instantiation is excessively deep and possibly infinite" errors that users were experiencing. + ```typescript + // Get paginated conversations + const result = await storage.getPaginatedUserConversations("user-123", 1, 20); + console.log(result.conversations); // Array of conversations + console.log(result.hasMore); // Boolean indicating if more pages exist + ``` -- Updated dependencies [[`57c4874`](https://github.com/VoltAgent/voltagent/commit/57c4874d4d4807c50242b2e34ab9574fc6129888), [`da66f86`](https://github.com/VoltAgent/voltagent/commit/da66f86d92a278007c2d3386d22b482fa70d93ff), [`4a7145d`](https://github.com/VoltAgent/voltagent/commit/4a7145debd66c7b1dfb953608e400b6c1ed02db7)]: - - @voltagent/core@0.1.61 +- Updated dependencies [[`f2f4539`](https://github.com/VoltAgent/voltagent/commit/f2f4539af7722f25a5aad9f01c2b7b5e50ba51b8), [`0eba8a2`](https://github.com/VoltAgent/voltagent/commit/0eba8a265c35241da74324613e15801402f7b778)]: + - @voltagent/core@0.1.32 -## 0.1.13 +## 0.1.8 ### Patch Changes -- [`8eced6d`](https://github.com/VoltAgent/voltagent/commit/8eced6dad9c688a33b4700a6fc4be34bfc3ba88b) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve onStepFinishHandler issue preventing tool_calls and hooks from functioning properly +- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 - Fixed a critical bug in the Vercel AI provider where the `onStepFinishHandler` was blocking tool calls and agent hooks from executing correctly. This issue was preventing agents from properly utilizing tools and executing lifecycle hooks during operations. +- Updated dependencies [[`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f), [`80fd3c0`](https://github.com/VoltAgent/voltagent/commit/80fd3c069de4c23116540a55082b891c4b376ce6)]: + - @voltagent/core@0.1.31 -## 0.1.12 +## 0.1.7 ### Patch Changes -- [#251](https://github.com/VoltAgent/voltagent/pull/251) [`be0cf47`](https://github.com/VoltAgent/voltagent/commit/be0cf47ec6e9640119d752dd6b608097d06bf69d) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add fullStream support for generative UIs +- [#176](https://github.com/VoltAgent/voltagent/pull/176) [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275) Thanks [@omeraplak](https://github.com/omeraplak)! - The `error` column has been deprecated and replaced with `statusMessage` column for better consistency and clearer messaging. The old `error` column is still supported for backward compatibility but will be removed in a future major version. - Added `fullStream` support to the Vercel AI provider for better streaming in generative UI applications. + Changes: + - Deprecated `error` column (still functional) + - Improved error handling and status reporting -- Updated dependencies [[`be0cf47`](https://github.com/VoltAgent/voltagent/commit/be0cf47ec6e9640119d752dd6b608097d06bf69d), [`a3b4e60`](https://github.com/VoltAgent/voltagent/commit/a3b4e604e6f79281903ff0c28422e6ee2863b340), [`20119ad`](https://github.com/VoltAgent/voltagent/commit/20119ada182ec5f313a7f46956218d593180e096)]: - - @voltagent/core@0.1.36 +- Updated dependencies [[`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275), [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275)]: + - @voltagent/core@0.1.24 -## 0.1.11 +## 0.1.6 ### Patch Changes -- [#226](https://github.com/VoltAgent/voltagent/pull/226) [`d879e6d`](https://github.com/VoltAgent/voltagent/commit/d879e6d41757081420162cf983223683b72b66a5) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: add toolName to tool-result steps +- [#160](https://github.com/VoltAgent/voltagent/pull/160) [`03ed437`](https://github.com/VoltAgent/voltagent/commit/03ed43723cd56f29ac67088f0624a88632a14a1b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: enhanced Supabase memory provider with better performance - Tool result steps now include the toolName field, ensuring proper identification of which tool generated each result in conversation flows and hook messages. + We've significantly improved the Supabase memory provider with better schema design and enhanced performance capabilities. The update includes database schema changes that require migration. -## 0.1.10 + Migration commands will appear in your terminal - follow those instructions to apply the database changes. If you experience any issues with the migration or memory operations, please reach out on [Discord](https://s.voltagent.dev/discord) for assistance. -### Patch Changes + **What's Improved:** + - Better performance for memory operations and large datasets + - Enhanced database schema with optimized indexing + - Improved error handling and data validation + - Better support for timeline events and metadata storage -- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 + **Migration Notes:** + - Migration commands will be displayed in your terminal + - Follow the terminal instructions to update your database schema + - Existing memory data will be preserved during the migration -- Updated dependencies [[`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f), [`80fd3c0`](https://github.com/VoltAgent/voltagent/commit/80fd3c069de4c23116540a55082b891c4b376ce6)]: - - @voltagent/core@0.1.31 +- Updated dependencies [[`03ed437`](https://github.com/VoltAgent/voltagent/commit/03ed43723cd56f29ac67088f0624a88632a14a1b)]: + - @voltagent/core@0.1.21 -## 0.1.9 +## 0.1.5 ### Patch Changes - [#155](https://github.com/VoltAgent/voltagent/pull/155) [`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c) Thanks [@baseballyama](https://github.com/baseballyama)! - chore: update `tsconfig.json`'s `target` to `ES2022` -- [#162](https://github.com/VoltAgent/voltagent/pull/162) [`b164bd0`](https://github.com/VoltAgent/voltagent/commit/b164bd014670452cb162b388f03565db992767af) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: pin zod version to 3.24.2 to avoid "Type instantiation is excessively deep and possibly infinite" error - - Fixed compatibility issues between different zod versions that were causing TypeScript compilation errors. This issue occurs when multiple packages use different patch versions of zod (e.g., 3.23.x vs 3.24.x), leading to type instantiation depth problems. By pinning to 3.24.2, we ensure consistent behavior across all packages. - - See: https://github.com/colinhacks/zod/issues/3435 - - Updated dependencies [[`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c), [`b164bd0`](https://github.com/VoltAgent/voltagent/commit/b164bd014670452cb162b388f03565db992767af), [`9412cf0`](https://github.com/VoltAgent/voltagent/commit/9412cf0633f20d6b77c87625fc05e9e216936758)]: - @voltagent/core@0.1.20 -## 0.1.7 +## 0.1.4 ### Patch Changes @@ -5574,36 +18381,7 @@ - Updated dependencies [[`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3)]: - @voltagent/core@0.1.14 -## 0.1.6 - -### Patch Changes - -- [`13db262`](https://github.com/VoltAgent/voltagent/commit/13db2621ae6b730667f9991d3c2129c85265e925) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: Update Zod to version 3.24.2 to resolve "Type instantiation is excessively deep and possibly infinite" error (related to https://github.com/colinhacks/zod/issues/3435). - -- Updated dependencies [[`f7de864`](https://github.com/VoltAgent/voltagent/commit/f7de864503d598cf7131cc01afa3779639190107), [`13db262`](https://github.com/VoltAgent/voltagent/commit/13db2621ae6b730667f9991d3c2129c85265e925)]: - - @voltagent/core@0.1.13 - -## 0.1.5 - -### Patch Changes - -- [#77](https://github.com/VoltAgent/voltagent/pull/77) [`beaa8fb`](https://github.com/VoltAgent/voltagent/commit/beaa8fb1f1bc6351f1bede0b65a6a189cc1b6ea2) Thanks [@omeraplak](https://github.com/omeraplak)! - **API & Providers:** Standardized message content format for array inputs. - - The API (`/text`, `/stream`, `/object`, `/stream-object` endpoints) now strictly expects the `content` field within message objects (when `input` is an array) to be either a `string` or an `Array` of content parts (e.g., `[{ type: 'text', text: '...' }]`). - - The previous behavior of allowing a single content object (e.g., `{ type: 'text', ... }`) directly as the value for `content` in message arrays is no longer supported in the API schema. Raw string inputs remain unchanged. - - Provider logic (`google-ai`, `groq-ai`, `xsai`) updated to align with this stricter definition. - - **Console:** - - **Added file and image upload functionality to the Assistant Chat.** Users can now attach multiple files/images via a button, preview attachments, and send them along with text messages. - - Improved the Assistant Chat resizing: Replaced size toggle buttons with a draggable handle (top-left corner). - - Chat window dimensions are now saved to local storage and restored on reload. - - **Internal:** - - Added comprehensive test suites for Groq and XsAI providers. - -- Updated dependencies [[`beaa8fb`](https://github.com/VoltAgent/voltagent/commit/beaa8fb1f1bc6351f1bede0b65a6a189cc1b6ea2)]: - - @voltagent/core@0.1.10 - -## 0.1.4 +## 0.1.3 ### Patch Changes @@ -5629,7 +18407,7 @@ - Updated dependencies [[`1f20509`](https://github.com/VoltAgent/voltagent/commit/1f20509528fc2cb2ba00f86d649848afae34af04), [`1f20509`](https://github.com/VoltAgent/voltagent/commit/1f20509528fc2cb2ba00f86d649848afae34af04), [`7a7a0f6`](https://github.com/VoltAgent/voltagent/commit/7a7a0f672adbe42635c3edc5f0a7f282575d0932)]: - @voltagent/core@0.1.9 -## 0.1.3 +## 0.1.2 ### Patch Changes @@ -5642,113 +18420,113 @@ ## 0.1.1 -- 🚀 **Introducing VoltAgent: TypeScript AI Agent Framework!** +### Patch Changes - This initial release marks the beginning of VoltAgent, a powerful toolkit crafted for the JavaScript developer community. We saw the challenges: the complexity of building AI from scratch, the limitations of No-Code tools, and the lack of first-class AI tooling specifically for JS. +- [#21](https://github.com/VoltAgent/voltagent/pull/21) [`8c3506e`](https://github.com/VoltAgent/voltagent/commit/8c3506e27486ac371192ef9ffb6a997e8e1692e9) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Introduce Supabase Memory Provider (`@voltagent/supabase`) - ![VoltAgent Demo](https://cdn.voltagent.dev/readme/demo.gif) - VoltAgent aims to fix that by providing the building blocks you need: - - **`@voltagent/core`**: The foundational engine for agent capabilities. - - **`@voltagent/voice`**: Easily add voice interaction. - - **`@voltagent/vercel-ai`**: Seamless integration with [Vercel AI SDK](https://sdk.vercel.ai/docs/introduction). - - **`@voltagent/xsai`**: A Seamless integration with [xsAI](https://xsai.js.org/). - - **`@voltagent/cli` & `create-voltagent-app`**: Quick start tools to get you building _fast_. + This new package provides a persistent memory solution for VoltAgent using Supabase. - We're combining the flexibility of code with the clarity of visual tools (like our **currently live [VoltOps LLM Observability Platform](https://console.voltagent.dev/)**) to make AI development easier, clearer, and more powerful. Join us as we build the future of AI in JavaScript! + **Features:** + - Stores conversation history, agent history entries, events, and steps in your Supabase database. + - Requires specific table setup in your Supabase project (SQL provided in the package README). + - Easy integration by initializing `SupabaseMemory` with your Supabase URL and key and passing it to your `Agent` configuration. - Explore the [Docs](https://voltagent.dev/docs/) and join our [Discord community](https://s.voltagent.dev/discord)! + See the `@voltagent/supabase` [README](https://github.com/voltagent/voltagent/blob/main/packages/supabase/README.md) and [Documentation](https://voltagent.dev/docs/agents/memory/supabase/) for detailed setup and usage instructions. + + closes #8 --- ## Package: @voltagent/vercel-ai-exporter -## 0.1.6 +## 2.0.2 ### Patch Changes -- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) - This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. - **Key improvements:** - - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs - - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration - - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries - - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup - - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` - These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ -- Updated dependencies [[`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5)]: - - @voltagent/sdk@0.1.6 +- Updated dependencies [[`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505)]: + - @voltagent/sdk@2.0.2 -## 0.1.5 +## 2.0.1 ### Patch Changes -- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) -- Updated dependencies [[`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f), [`80fd3c0`](https://github.com/VoltAgent/voltagent/commit/80fd3c069de4c23116540a55082b891c4b376ce6)]: - - @voltagent/core@0.1.31 - - @voltagent/sdk@0.1.5 + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. -## 0.1.4 + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` -### Patch Changes + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ -- [`7c28c1e`](https://github.com/VoltAgent/voltagent/commit/7c28c1ee7a11da0e5ca32c248e412cc588e7fcdf) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: the default base URL setting to `https://api.voltagent.dev` +- Updated dependencies [[`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2)]: + - @voltagent/sdk@2.0.1 -## 0.1.3 +## 2.0.0 ### Patch Changes -- [#176](https://github.com/VoltAgent/voltagent/pull/176) [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve displayName issue in agent events - - Fixed an issue where the displayName property was not being properly handled in agent events, ensuring consistent agent identification across the system. - -- Updated dependencies [[`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275), [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275), [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275)]: - - @voltagent/core@0.1.24 - - @voltagent/sdk@0.1.4 +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/core@2.0.0 + - @voltagent/sdk@2.0.0 -## 0.1.2 +## 1.0.2 ### Patch Changes -- [#171](https://github.com/VoltAgent/voltagent/pull/171) [`1cd2a93`](https://github.com/VoltAgent/voltagent/commit/1cd2a9307d10bf5c90083138655aca9614d8053b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: initial release of Vercel AI SDK integration - - Add support for Vercel AI SDK observability with automated tracing and monitoring capabilities. - - Documentation: https://voltagent.dev/voltops-llm-observability-docs/vercel-ai/ +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` +- Updated dependencies [[`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e)]: + - @voltagent/sdk@1.0.1 -- Updated dependencies [[`1cd2a93`](https://github.com/VoltAgent/voltagent/commit/1cd2a9307d10bf5c90083138655aca9614d8053b)]: - - @voltagent/sdk@0.1.3 +## 1.0.1 -## 0.1.1 +## 1.0.1-next.0 ### Patch Changes -- [#160](https://github.com/VoltAgent/voltagent/pull/160) [`03ed437`](https://github.com/VoltAgent/voltagent/commit/03ed43723cd56f29ac67088f0624a88632a14a1b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Vercel AI SDK observability exporter - - Introduce new `@voltagent/vercel-ai-exporter` package for Vercel AI SDK integration - - Provides OpenTelemetry exporter for VoltAgent observability - - Enables comprehensive tracking of LLM operations and multi-agent workflows - - Includes automatic telemetry collection and agent history management - -- Updated dependencies [[`03ed437`](https://github.com/VoltAgent/voltagent/commit/03ed43723cd56f29ac67088f0624a88632a14a1b), [`03ed437`](https://github.com/VoltAgent/voltagent/commit/03ed43723cd56f29ac67088f0624a88632a14a1b)]: - - @voltagent/core@0.1.21 - - @voltagent/sdk@0.1.1 - ---- +- Updated dependencies [[`77a3f64`](https://github.com/VoltAgent/voltagent/commit/77a3f64dea6e8a06fbbd72878711efa9ceb90bc3)]: + - @voltagent/core@1.1.7-next.0 + - @voltagent/sdk@0.1.7-next.0 -## Package: @voltagent/vercel-ui +## 1.0.0 -## 0.1.9 +## 1.0.0-next.0 ### Patch Changes -- Updated dependencies [[`8de5785`](https://github.com/VoltAgent/voltagent/commit/8de5785e385bec632f846bcae44ee5cb22a9022e)]: - - @voltagent/internal@0.0.8 +- Updated dependencies [[`64a50e6`](https://github.com/VoltAgent/voltagent/commit/64a50e6800dec844fad7b9f3a3b1c2c8d0486229), [`9e8b211`](https://github.com/VoltAgent/voltagent/commit/9e8b2119a783942f114459f0a9b93e645727445e)]: + - @voltagent/core@1.0.0-next.0 + - @voltagent/sdk@0.1.7-next.0 -## 0.1.8 +## 0.1.6 ### Patch Changes @@ -5766,192 +18544,164 @@ These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. - Updated dependencies [[`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5)]: - - @voltagent/internal@0.0.7 - -## 0.1.7 - -### Patch Changes - -- [#404](https://github.com/VoltAgent/voltagent/pull/404) [`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: remove devLogger dependency and use native console methods - - Removed the dependency on `@voltagent/internal/dev` logger and replaced devLogger calls with standard console methods (console.error, console.warn) for a cleaner dependency tree and better compatibility. - -- Updated dependencies [[`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726), [`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726)]: - - @voltagent/internal@0.0.6 - - @voltagent/core@0.1.65 - -## 0.1.6 - -### Patch Changes - -- Updated dependencies [[`6fadbb0`](https://github.com/VoltAgent/voltagent/commit/6fadbb098fe40d8b658aa3386e6126fea155f117)]: - - @voltagent/internal@0.0.5 - - @voltagent/core@0.1.62 + - @voltagent/sdk@0.1.6 ## 0.1.5 ### Patch Changes -- [#354](https://github.com/VoltAgent/voltagent/pull/354) [`5bfb1e2`](https://github.com/VoltAgent/voltagent/commit/5bfb1e22162cb69aed0d333072237c68b705f6c0) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: Fixed passing along an ID of empty string +- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 + +- Updated dependencies [[`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f), [`80fd3c0`](https://github.com/VoltAgent/voltagent/commit/80fd3c069de4c23116540a55082b891c4b376ce6)]: + - @voltagent/core@0.1.31 + - @voltagent/sdk@0.1.5 ## 0.1.4 ### Patch Changes -- Updated dependencies [[`8da1ecc`](https://github.com/VoltAgent/voltagent/commit/8da1eccd0332d1f9037085e16cb0b7d5afaac479), [`8da1ecc`](https://github.com/VoltAgent/voltagent/commit/8da1eccd0332d1f9037085e16cb0b7d5afaac479), [`8da1ecc`](https://github.com/VoltAgent/voltagent/commit/8da1eccd0332d1f9037085e16cb0b7d5afaac479)]: - - @voltagent/core@0.1.49 - - @voltagent/internal@0.0.4 +- [`7c28c1e`](https://github.com/VoltAgent/voltagent/commit/7c28c1ee7a11da0e5ca32c248e412cc588e7fcdf) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: the default base URL setting to `https://api.voltagent.dev` ## 0.1.3 ### Patch Changes -- [#311](https://github.com/VoltAgent/voltagent/pull/311) [`1f7fa14`](https://github.com/VoltAgent/voltagent/commit/1f7fa140fcc4062fe85220e61f276e439392b0b4) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix(core, vercel-ui): Currently the `convertToUIMessages` function does not handle tool calls in steps correctly as it does not properly default filter non-tool related steps for sub-agents, same as the `data-stream` functions and in addition in the core the `operationContext` does not have the `subAgent` fields set correctly. - - ### Changes - - deprecated `isSubAgentStreamPart` in favor of `isSubAgent` for universal use - - by default `convertToUIMessages` now filters out non-tool related steps for sub-agents - - now able to exclude specific parts or steps (from OperationContext) in `convertToUIMessages` - - *** - - ### Internals +- [#176](https://github.com/VoltAgent/voltagent/pull/176) [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve displayName issue in agent events - New utils were added to the internal package: - - `isObject` - - `isFunction` - - `isPlainObject` - - `isEmptyObject` - - `isNil` - - `hasKey` + Fixed an issue where the displayName property was not being properly handled in agent events, ensuring consistent agent identification across the system. -- Updated dependencies [[`1f7fa14`](https://github.com/VoltAgent/voltagent/commit/1f7fa140fcc4062fe85220e61f276e439392b0b4)]: - - @voltagent/internal@0.0.3 - - @voltagent/core@0.1.47 +- Updated dependencies [[`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275), [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275), [`790d070`](https://github.com/VoltAgent/voltagent/commit/790d070e26a41a6467927471933399020ceec275)]: + - @voltagent/core@0.1.24 + - @voltagent/sdk@0.1.4 ## 0.1.2 ### Patch Changes -- [#302](https://github.com/VoltAgent/voltagent/pull/302) [`1e1f563`](https://github.com/VoltAgent/voltagent/commit/1e1f563aeb9ac25880ca56a33285abca0b24b389) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - Fix to match the output of `mergeIntoDataStream` and `convertToUIMessages` as the `mergeIntoDataStream` filters out the `SubAgent` prefix of a `toolName` (i.e. `BlogReader: read-blog-post`). `convertToUIMessages` was not filtering out the `SubAgent` prefix by default and it was causing the `toolName` to be different on the server in the `onEnd` hook from whats being sent to the client (and expected by the developer). +- [#171](https://github.com/VoltAgent/voltagent/pull/171) [`1cd2a93`](https://github.com/VoltAgent/voltagent/commit/1cd2a9307d10bf5c90083138655aca9614d8053b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: initial release of Vercel AI SDK integration -- Updated dependencies [[`33afe6e`](https://github.com/VoltAgent/voltagent/commit/33afe6ef40ef56c501f7fa69be42da730f87d29d), [`b8529b5`](https://github.com/VoltAgent/voltagent/commit/b8529b53313fa97e941ecacb8c1555205de49c19)]: - - @voltagent/core@0.1.45 + Add support for Vercel AI SDK observability with automated tracing and monitoring capabilities. + + Documentation: https://voltagent.dev/voltops-llm-observability-docs/vercel-ai/ + +- Updated dependencies [[`1cd2a93`](https://github.com/VoltAgent/voltagent/commit/1cd2a9307d10bf5c90083138655aca9614d8053b)]: + - @voltagent/sdk@0.1.3 ## 0.1.1 ### Patch Changes -- Updated dependencies [[`94de46a`](https://github.com/VoltAgent/voltagent/commit/94de46ab2b7ccead47a539e93c72b357f17168f6)]: - - @voltagent/internal@0.0.2 - - @voltagent/core@0.1.44 - -## 0.1.0 +- [#160](https://github.com/VoltAgent/voltagent/pull/160) [`03ed437`](https://github.com/VoltAgent/voltagent/commit/03ed43723cd56f29ac67088f0624a88632a14a1b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Vercel AI SDK observability exporter + - Introduce new `@voltagent/vercel-ai-exporter` package for Vercel AI SDK integration + - Provides OpenTelemetry exporter for VoltAgent observability + - Enables comprehensive tracking of LLM operations and multi-agent workflows + - Includes automatic telemetry collection and agent history management -### Minor Changes +- Updated dependencies [[`03ed437`](https://github.com/VoltAgent/voltagent/commit/03ed43723cd56f29ac67088f0624a88632a14a1b), [`03ed437`](https://github.com/VoltAgent/voltagent/commit/03ed43723cd56f29ac67088f0624a88632a14a1b)]: + - @voltagent/core@0.1.21 + - @voltagent/sdk@0.1.1 -- [#273](https://github.com/VoltAgent/voltagent/pull/273) [`12b8c90`](https://github.com/VoltAgent/voltagent/commit/12b8c9025488e1d6f4b5a99d74b639bf202ba7d2) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - Added a set of new utility functions for working with data streams in the vercel `ai` package. +--- - ## New Functions +## Package: @voltagent/voice - ### `toDataStream` +## 2.0.2 - You can use this function to convert a VoltAgent `ReadableStream` to a `DataStream`. +### Patch Changes - ```typescript - const result = await agent.streamText("Hello, world!"); - const dataStream = toDataStream(result.fullStream); - ``` +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) - ### `mergeIntoDataStream` + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. - You can use this function to merge a VoltAgent `ReadableStream` into a `DataStream` using the vercel `createDataStream` function. + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` - ```typescript - const result = await agent.streamText("Hello, world!"); + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ - const dataStream = createDataStream({ - execute: async (writer) => { - const result = await agent.streamText("Hello, world!"); - mergeIntoDataStream(writer, result.fullStream); - }, - }); +## 2.0.1 - reply.send(dataStream); - ``` +### Patch Changes - ### `formatDataStreamPart` +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) - You can use this function to format a data stream part for the vercel `ai` package to be used in the `DataStream` interface, this appends certain metadata for VoltAgent. + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. - ```typescript - const result = await agent.streamText("Hello, world!"); + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` - const dataStream = toDataStream(result.fullStream); + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ - // This will append subAgentId and subAgentName to the data stream part - ``` +## 2.0.0 - ### `isSubAgentStreamPart` +### Major Changes - You can use this function to check if a data stream part is a sub-agent stream part. +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) - ```typescript - import { isSubAgentStreamPart } from "@voltagent/vercel-ui"; + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. - const messages = useChat(...); + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` - for (const message of messages) { - if (isSubAgentStreamPart(message)) { - // This is a sub-agent stream part - // NOTE: This will ONLY work for Tool calls and results and not other stream parts - console.log(message.subAgentId, message.subAgentName); - } - } - ``` + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ + +### Patch Changes - ## New Types +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/core@2.0.0 - Additional types have been exposed to make it easier to improve types with the vercel `ai` package. - - `UIMessage` - A VoltAgent ready `UIMessage` type, this is a wrapper around the vercel `UIMessage` type. - - `DataStream` - A VoltAgent ready `DataStream` type, this is a wrapper around the vercel `DataStream` type. +## 1.0.2 ### Patch Changes -- Updated dependencies [[`73632ea`](https://github.com/VoltAgent/voltagent/commit/73632ea229917ab4042bb58b61d5e6dbd9b72804)]: - - @voltagent/core@0.1.42 +- [`9cc4ea4`](https://github.com/VoltAgent/voltagent/commit/9cc4ea4a4985320139e33e8029f299c7ec8329a6) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: @voltagent/core peerDependency version -## 0.0.2 +## 1.0.1 + +## 1.0.1-next.0 ### Patch Changes -- [#226](https://github.com/VoltAgent/voltagent/pull/226) [`d879e6d`](https://github.com/VoltAgent/voltagent/commit/d879e6d41757081420162cf983223683b72b66a5) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - feat: add Vercel UI SDK integration package for converting the `OperationContext` to a list of messages that can be used with the Vercel AI SDK +- Updated dependencies [[`77a3f64`](https://github.com/VoltAgent/voltagent/commit/77a3f64dea6e8a06fbbd72878711efa9ceb90bc3)]: + - @voltagent/core@1.1.7-next.0 - Added `convertToUIMessages` function to the `@voltagent/vercel-ui` package that converts the `OperationContext` to a list of messages that can be used with the Vercel AI SDK. +## 1.0.0 - ```ts - import { convertToUIMessages } from "@voltagent/vercel-ui"; - import { Agent } from "@voltagent/core"; +## 1.0.0-next.0 - const uiMessages = convertToUIMessages(context); +### Patch Changes - // Semi-realistic example - new Agent({ - hooks: { - onEnd: async ({ agent, output, error, conversationId, context }) => { - const uiMessages = convertToUIMessages(context); - await chatStore.save({ - conversationId, - messages: uiMessages, - }); - }, - }, - }); - ``` +- Updated dependencies [[`64a50e6`](https://github.com/VoltAgent/voltagent/commit/64a50e6800dec844fad7b9f3a3b1c2c8d0486229), [`9e8b211`](https://github.com/VoltAgent/voltagent/commit/9e8b2119a783942f114459f0a9b93e645727445e)]: + - @voltagent/core@1.0.0-next.0 ---- +## 0.2.4 -## Package: @voltagent/voice +### Patch Changes + +- [#494](https://github.com/VoltAgent/voltagent/pull/494) [`4459ae2`](https://github.com/VoltAgent/voltagent/commit/4459ae24a7c8b4ed3031f5a81ce7835e90fa6ade) Thanks [@kwaa](https://github.com/kwaa)! - fix(xsai): bump to v0.4.0-beta.1, support file & reasoning ## 0.2.3 @@ -6135,276 +18885,294 @@ --- -## Package: @voltagent/xsai - -## 0.3.2 - -### Patch Changes - -- [`4f4ffc2`](https://github.com/VoltAgent/voltagent/commit/4f4ffc23eaea36675e66eb8a17d275fe9f32a671) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add fullStream support - -- Updated dependencies [[`760a294`](https://github.com/VoltAgent/voltagent/commit/760a294e4d68742d8701d54dc1c541c87959e5d8), [`760a294`](https://github.com/VoltAgent/voltagent/commit/760a294e4d68742d8701d54dc1c541c87959e5d8), [`980d037`](https://github.com/VoltAgent/voltagent/commit/980d037ce535bcc85cc7df3f64354c823453a147)]: - - @voltagent/core@0.1.74 +## Package: @voltagent/voltagent-memory -## 0.3.1 +## 1.0.2 ### Patch Changes -- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements - - This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: - - **Key improvements:** - - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs - - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration - - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries - - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup - - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported - - These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. - -## 0.3.0 +- [`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) -### Minor Changes + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. -- [#411](https://github.com/VoltAgent/voltagent/pull/411) [`80b24e2`](https://github.com/VoltAgent/voltagent/commit/80b24e245daa9584733762c9aaf7e23e1d90c6c5) Thanks [@kwaa](https://github.com/kwaa)! - chore(deps): bump xsai to 0.3.3 + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` -### Patch Changes + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ -- Updated dependencies [[`99fe836`](https://github.com/VoltAgent/voltagent/commit/99fe83662e9b3e550380fce066521a5c27d69eb3)]: - - @voltagent/core@0.1.71 +- Updated dependencies [[`f6ffb8a`](https://github.com/VoltAgent/voltagent/commit/f6ffb8ae0fd95fbe920058e707d492d8c21b2505)]: + - @voltagent/internal@1.0.2 -## 0.2.4 +## 1.0.1 ### Patch Changes -- [#348](https://github.com/VoltAgent/voltagent/pull/348) [`9581df0`](https://github.com/VoltAgent/voltagent/commit/9581df02bce2ba8b25f9f2964b781095bc50b004) Thanks [@Adherentman](https://github.com/Adherentman)! - fix: xsai empty tools will sent undefined - #337 - -- Updated dependencies [[`b7dcded`](https://github.com/VoltAgent/voltagent/commit/b7dcdedfbbdda5bfb1885317b59b4d4e2495c956), [`822739c`](https://github.com/VoltAgent/voltagent/commit/822739c901bbc679cd11dd2c9df99cd041fc40c7)]: - - @voltagent/core@0.1.55 - -## 0.2.3 +- [`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) -### Patch Changes + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. -- [#229](https://github.com/VoltAgent/voltagent/pull/229) [`0eba8a2`](https://github.com/VoltAgent/voltagent/commit/0eba8a265c35241da74324613e15801402f7b778) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: migrate the provider streams to `AsyncIterableStream` + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` - Example: + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ - ```typescript - const stream = createAsyncIterableStream( - new ReadableStream({ - start(controller) { - controller.enqueue("Hello"); - controller.enqueue(", "); - controller.enqueue("world!"); - controller.close(); - }, - }) - ); +- Updated dependencies [[`c3943aa`](https://github.com/VoltAgent/voltagent/commit/c3943aa89a7bee113d99404ecd5a81a62bc159c2)]: + - @voltagent/internal@1.0.1 - for await (const chunk of stream) { - console.log(chunk); - } +## 1.0.0 - // in the agent - const result = await agent.streamObject({ - messages, - model: "test-model", - schema, - }); +### Major Changes - for await (const chunk of result.objectStream) { - console.log(chunk); - } - ``` +- [#894](https://github.com/VoltAgent/voltagent/pull/894) [`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: VoltAgent 2.x (AI SDK v6) - New exports: - - `createAsyncIterableStream` - - `type AsyncIterableStream` + VoltAgent 2.x aligns the framework with AI SDK v6 and adds new features. VoltAgent APIs are compatible, but if you call AI SDK directly, follow the upstream v6 migration guide. -- Updated dependencies [[`f2f4539`](https://github.com/VoltAgent/voltagent/commit/f2f4539af7722f25a5aad9f01c2b7b5e50ba51b8), [`0eba8a2`](https://github.com/VoltAgent/voltagent/commit/0eba8a265c35241da74324613e15801402f7b778)]: - - @voltagent/core@0.1.32 + Migration summary (1.x -> 2.x): + 1. Update VoltAgent packages + - `npm run volt update` + - If the CLI is missing: `npx @voltagent/cli init` then `npm run volt update` + 2. Align AI SDK packages + - `pnpm add ai@^6 @ai-sdk/provider@^3 @ai-sdk/provider-utils@^4 @ai-sdk/openai@^3` + - If you use UI hooks, upgrade `@ai-sdk/react` to `^3` + 3. Structured output + - `generateObject` and `streamObject` are deprecated in VoltAgent 2.x + - Use `generateText` / `streamText` with `Output.object(...)` -## 0.2.2 + Full migration guide: https://voltagent.dev/docs/getting-started/migration-guide/ ### Patch Changes -- [#226](https://github.com/VoltAgent/voltagent/pull/226) [`d879e6d`](https://github.com/VoltAgent/voltagent/commit/d879e6d41757081420162cf983223683b72b66a5) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: add toolName to tool-result steps - - Tool result steps now include the toolName field, ensuring proper identification of which tool generated each result in conversation flows and hook messages. +- Updated dependencies [[`ee05549`](https://github.com/VoltAgent/voltagent/commit/ee055498096b1b99015a8362903712663969677f)]: + - @voltagent/core@2.0.0 + - @voltagent/internal@1.0.0 -## 0.2.1 +## 0.1.5 ### Patch Changes -- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 - -- Updated dependencies [[`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f), [`80fd3c0`](https://github.com/VoltAgent/voltagent/commit/80fd3c069de4c23116540a55082b891c4b376ce6)]: - - @voltagent/core@0.1.31 - -## 0.2.0 - -### Minor Changes - -- [#195](https://github.com/VoltAgent/voltagent/pull/195) [`0c4e941`](https://github.com/VoltAgent/voltagent/commit/0c4e9418ae75c82b20a503678e75277729c0174b) Thanks [@Ajay-Satish-01](https://github.com/Ajay-Satish-01)! - 🚨 Breaking Change: Renamed XsAI and Xsai to XSAI - - We’ve renamed the XsAI and Xsai classes to XSAI to keep naming consistent across the framework. +- [#845](https://github.com/VoltAgent/voltagent/pull/845) [`5432f13`](https://github.com/VoltAgent/voltagent/commit/5432f13bddebd869522ebffbedd9843b4476f08b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: workflow execution listing - #844 - What changed? + Added a unified way to list workflow runs so teams can audit executions across every storage backend and surface them via the API and console. - If you’re using the XsAIProvider or XsAIVoiceProvider, you now need to update your code to use XSAIProvider and XSAIVoiceProvider. + ## What changed + - `queryWorkflowRuns` now exists on all memory adapters (in-memory, libsql, Postgres, Supabase, voltagent-memory) with filters for `workflowId`, `status`, `from`, `to`, `limit`, and `offset`. + - Server routes are consolidated under `/workflows/executions` (no path param needed); `GET /workflows/:id` also returns the workflow result schema for typed clients. Handler naming is standardized to `listWorkflowRuns`. + - VoltOps Console observability panel lists the new endpoint; REST docs updated with query params and sample responses. New unit tests cover handlers and every storage adapter. - Before: + ## Quick fetch ```ts - import { XsAIVoiceProvider } from "@voltagent/voice"; + await fetch( + "http://localhost:3141/workflows/executions?workflowId=expense-approval&status=completed&from=2024-01-01&to=2024-01-31&limit=20&offset=0" + ); + ``` - const agent = new Agent({ - name: "Asistant", - description: "A helpful assistant that answers questions without using tools", - llm: new XsAIProvider({ - apiKey: process.env.OPENAI_API_KEY!, - }), - model: "gpt-4o-mini", - }); +## 0.1.4 - const voiceProvider = new XsAIVoiceProvider({ - apiKey: process.env.OPENAI_API_KEY!, - }); - ``` +### Patch Changes - After: +- [#801](https://github.com/VoltAgent/voltagent/pull/801) [`a26ddd8`](https://github.com/VoltAgent/voltagent/commit/a26ddd826692485278033c22ac9828cb51cdd749) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add triggers DSL improvements and event payload simplification + - Introduce the new `createTriggers` DSL and expose trigger events via sensible provider names (e.g. `on.airtable.recordCreated`) rather than raw catalog IDs. + - Add trigger span metadata propagation so VoltAgent agents receive trigger context automatically without manual mapping. + - Simplify action dispatch payloads: `payload` now contains only the event’s raw data while trigger context lives in the `event`/`metadata` blocks, reducing boilerplate in handlers. ```ts - import { XSAIVoiceProvider } from "@voltagent/voice"; + import { VoltAgent, createTriggers } from "@voltagent/core"; - const agent = new Agent({ - name: "Asistant", - description: "A helpful assistant that answers questions without using tools", - llm: new XSAIProvider({ - apiKey: process.env.OPENAI_API_KEY!, - }), - model: "gpt-4o-mini", - }); + new VoltAgent({ + // ... + triggers: createTriggers((on) => { + on.airtable.recordCreated(({ payload, event }) => { + console.log("New Airtable row", payload, event.metadata); + }); - const voiceProvider = new XSAIVoiceProvider({ - apiKey: process.env.OPENAI_API_KEY!, + on.gmail.newEmail(({ payload }) => { + console.log("New Gmail message", payload); + }); + }), }); ``` - This change resolves [#140](https://github.com/your-repo/issues/140). +## 0.1.3 ### Patch Changes -- Updated dependencies [[`07d99d1`](https://github.com/VoltAgent/voltagent/commit/07d99d133232babf78ba4e1c32fe235d5b3c9944), [`67b0e7e`](https://github.com/VoltAgent/voltagent/commit/67b0e7ea704d23bf9efb722c0b0b4971d0974153)]: - - @voltagent/core@0.1.29 - -## 0.1.9 +- [#787](https://github.com/VoltAgent/voltagent/pull/787) [`5e81d65`](https://github.com/VoltAgent/voltagent/commit/5e81d6568ba3bee26083ca2a8e5d31f158e36fc0) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add full conversation step persistence across the stack: + - Core now exposes managed-memory step APIs, and the VoltAgent managed memory adapter persists/retrieves steps through VoltOps. + - LibSQL, PostgreSQL, Supabase, and server handlers provision the new `_steps` table, wire up DTOs/routes, and surface the data in Observability/Steps UI (including managed-memory backends). -### Patch Changes + fixes: #613 -- [#155](https://github.com/VoltAgent/voltagent/pull/155) [`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c) Thanks [@baseballyama](https://github.com/baseballyama)! - chore: update `tsconfig.json`'s `target` to `ES2022` +## 0.1.2 -- [#162](https://github.com/VoltAgent/voltagent/pull/162) [`b164bd0`](https://github.com/VoltAgent/voltagent/commit/b164bd014670452cb162b388f03565db992767af) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: pin zod version to 3.24.2 to avoid "Type instantiation is excessively deep and possibly infinite" error +### Patch Changes - Fixed compatibility issues between different zod versions that were causing TypeScript compilation errors. This issue occurs when multiple packages use different patch versions of zod (e.g., 3.23.x vs 3.24.x), leading to type instantiation depth problems. By pinning to 3.24.2, we ensure consistent behavior across all packages. +- [#693](https://github.com/VoltAgent/voltagent/pull/693) [`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e) Thanks [@marinoska](https://github.com/marinoska)! - - Added support for provider-defined tools (e.g. `openai.tools.webSearch()`) + - Update tool normalization to pass through provider tool metadata untouched. + - Added support for provider-defined tools both as standalone tool and within a toolkit. + - Upgraded dependency: `ai` → `^5.0.76` +- Updated dependencies [[`f9aa8b8`](https://github.com/VoltAgent/voltagent/commit/f9aa8b8980a9efa53b6a83e6ba2a6db765a4fd0e)]: + - @voltagent/internal@0.0.12 - See: https://github.com/colinhacks/zod/issues/3435 +## 0.1.1 -- Updated dependencies [[`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c), [`b164bd0`](https://github.com/VoltAgent/voltagent/commit/b164bd014670452cb162b388f03565db992767af), [`9412cf0`](https://github.com/VoltAgent/voltagent/commit/9412cf0633f20d6b77c87625fc05e9e216936758)]: - - @voltagent/core@0.1.20 +### Patch Changes -## 0.1.8 +- [#641](https://github.com/VoltAgent/voltagent/pull/641) [`4c42bf7`](https://github.com/VoltAgent/voltagent/commit/4c42bf72834d3cd45ff5246ef65d7b08470d6a8e) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: introduce managed memory - ready-made cloud storage for VoltAgent -### Patch Changes + ## What Changed for You -- [#100](https://github.com/VoltAgent/voltagent/pull/100) [`0bdcf94`](https://github.com/VoltAgent/voltagent/commit/0bdcf9441cc79cf6321b377c303123d28daddda4) Thanks [@kwaa](https://github.com/kwaa)! - feat: Add multi-modal support (see [docs](https://voltagent.dev/docs/providers/xsai/#multi-modal-support)) - [#79](https://github.com/VoltAgent/voltagent/issues/79) + VoltAgent now offers a managed memory solution that eliminates the need to run your own database infrastructure. The new `@voltagent/voltagent-memory` package provides a `ManagedMemoryAdapter` that connects to VoltOps Managed Memory service, perfect for pilots, demos, and production workloads. -## 0.1.6 + ## New Package: @voltagent/voltagent-memory -### Patch Changes + ### Automatic Setup (Recommended) -- [#102](https://github.com/VoltAgent/voltagent/pull/102) [`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3) Thanks [@omeraplak](https://github.com/omeraplak)! - refactor: use 'instructions' field for Agent definitions in examples - #88 + Get your credentials from [console.voltagent.dev/memory/managed-memory](https://console.voltagent.dev/memory/managed-memory) and set environment variables: - Updated documentation examples (READMEs, docs, blogs) and relevant package code examples to use the `instructions` field instead of `description` when defining `Agent` instances. + ```bash + # .env + VOLTAGENT_PUBLIC_KEY=pk_... + VOLTAGENT_SECRET_KEY=sk_... + ``` - This change aligns the examples with the preferred API usage for the `Agent` class, where `instructions` provides behavioral guidance to the agent/LLM. This prepares for the eventual deprecation of the `description` field specifically for `Agent` class definitions. + ```typescript + import { Agent, Memory } from "@voltagent/core"; + import { ManagedMemoryAdapter } from "@voltagent/voltagent-memory"; + import { openai } from "@ai-sdk/openai"; - **Example Change for Agent Definition:** + // Adapter automatically uses VoltOps credentials from environment + const agent = new Agent({ + name: "Assistant", + instructions: "You are a helpful assistant", + model: openai("gpt-4o-mini"), + memory: new Memory({ + storage: new ManagedMemoryAdapter({ + databaseName: "production-memory", + }), + }), + }); - ```diff - const agent = new Agent({ - name: "My Assistant", - - description: "A helpful assistant.", - + instructions: "A helpful assistant.", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), - }); + // Use like any other agent - memory is automatically persisted + const result = await agent.generateText("Hello!", { + userId: "user-123", + conversationId: "conv-456", + }); ``` -- Updated dependencies [[`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3)]: - - @voltagent/core@0.1.14 - - @voltagent/xsai@0.1.6 - -## 0.1.5 + ### Manual Setup -### Patch Changes + Pass a `VoltOpsClient` instance explicitly: -- [`13db262`](https://github.com/VoltAgent/voltagent/commit/13db2621ae6b730667f9991d3c2129c85265e925) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: Update Zod to version 3.24.2 to resolve "Type instantiation is excessively deep and possibly infinite" error (related to https://github.com/colinhacks/zod/issues/3435). + ```typescript + import { Agent, Memory, VoltOpsClient } from "@voltagent/core"; + import { ManagedMemoryAdapter } from "@voltagent/voltagent-memory"; + import { openai } from "@ai-sdk/openai"; -- Updated dependencies [[`f7de864`](https://github.com/VoltAgent/voltagent/commit/f7de864503d598cf7131cc01afa3779639190107), [`13db262`](https://github.com/VoltAgent/voltagent/commit/13db2621ae6b730667f9991d3c2129c85265e925)]: - - @voltagent/core@0.1.13 - - @voltagent/xsai@0.1.5 + const voltOpsClient = new VoltOpsClient({ + publicKey: process.env.VOLTAGENT_PUBLIC_KEY!, + secretKey: process.env.VOLTAGENT_SECRET_KEY!, + }); -## 0.1.4 + const agent = new Agent({ + name: "Assistant", + instructions: "You are a helpful assistant", + model: openai("gpt-4o-mini"), + memory: new Memory({ + storage: new ManagedMemoryAdapter({ + databaseName: "production-memory", + voltOpsClient, // explicit client + }), + }), + }); + ``` -### Patch Changes + ### Vector Storage (Optional) -- [#77](https://github.com/VoltAgent/voltagent/pull/77) [`beaa8fb`](https://github.com/VoltAgent/voltagent/commit/beaa8fb1f1bc6351f1bede0b65a6a189cc1b6ea2) Thanks [@omeraplak](https://github.com/omeraplak)! - **API & Providers:** Standardized message content format for array inputs. - - The API (`/text`, `/stream`, `/object`, `/stream-object` endpoints) now strictly expects the `content` field within message objects (when `input` is an array) to be either a `string` or an `Array` of content parts (e.g., `[{ type: 'text', text: '...' }]`). - - The previous behavior of allowing a single content object (e.g., `{ type: 'text', ... }`) directly as the value for `content` in message arrays is no longer supported in the API schema. Raw string inputs remain unchanged. - - Provider logic (`google-ai`, `groq-ai`, `xsai`) updated to align with this stricter definition. + Enable semantic search with `ManagedMemoryVectorAdapter`: - **Console:** - - **Added file and image upload functionality to the Assistant Chat.** Users can now attach multiple files/images via a button, preview attachments, and send them along with text messages. - - Improved the Assistant Chat resizing: Replaced size toggle buttons with a draggable handle (top-left corner). - - Chat window dimensions are now saved to local storage and restored on reload. + ```typescript + import { ManagedMemoryAdapter, ManagedMemoryVectorAdapter } from "@voltagent/voltagent-memory"; + import { AiSdkEmbeddingAdapter, Memory } from "@voltagent/core"; + import { openai } from "@ai-sdk/openai"; - **Internal:** - - Added comprehensive test suites for Groq and XsAI providers. + const memory = new Memory({ + storage: new ManagedMemoryAdapter({ + databaseName: "production-memory", + }), + embedding: new AiSdkEmbeddingAdapter(openai.embedding("text-embedding-3-small")), + vector: new ManagedMemoryVectorAdapter({ + databaseName: "production-memory", + }), + }); + ``` -- Updated dependencies [[`beaa8fb`](https://github.com/VoltAgent/voltagent/commit/beaa8fb1f1bc6351f1bede0b65a6a189cc1b6ea2)]: - - @voltagent/core@0.1.10 - - @voltagent/xsai@0.1.4 + ## Key Features + - **Zero Infrastructure**: No need to provision or manage databases + - **Quick Setup**: Create a managed memory database in under 3 minutes from VoltOps Console + - **Framework Parity**: Works identically to local Postgres, LibSQL, or Supabase adapters + - **Production Ready**: Managed infrastructure with reliability guardrails + - **Multi-Region**: Available in US (Virginia) and EU (Germany) -## 0.1.3 + ## Getting Started + 1. **Install the package**: -### Patch Changes + ```bash + npm install @voltagent/voltagent-memory + # or + pnpm add @voltagent/voltagent-memory + ``` -- [#33](https://github.com/VoltAgent/voltagent/pull/33) [`3ef2eaa`](https://github.com/VoltAgent/voltagent/commit/3ef2eaa9661e8ecfebf17af56b09af41285d0ca9) Thanks [@kwaa](https://github.com/kwaa)! - Update package.json files: - - Remove `src` directory from the `files` array. - - Add explicit `exports` field for better module resolution. + 2. **Create a managed database**: + - Navigate to [console.voltagent.dev/memory/managed-memory](https://console.voltagent.dev/memory/managed-memory) + - Click **Create Database** + - Enter a name and select region (US or EU) + - Copy your VoltOps API keys from Settings + 3. **Configure environment variables**: -- Updated dependencies [[`52d5fa9`](https://github.com/VoltAgent/voltagent/commit/52d5fa94045481dc43dc260a40b701606190585c), [`3ef2eaa`](https://github.com/VoltAgent/voltagent/commit/3ef2eaa9661e8ecfebf17af56b09af41285d0ca9), [`52d5fa9`](https://github.com/VoltAgent/voltagent/commit/52d5fa94045481dc43dc260a40b701606190585c)]: - - @voltagent/core@0.1.6 + ```bash + VOLTAGENT_PUBLIC_KEY=pk_... + VOLTAGENT_SECRET_KEY=sk_... + ``` -## 0.1.1 + 4. **Use the adapter**: -- 🚀 **Introducing VoltAgent: TypeScript AI Agent Framework!** + ```typescript + import { ManagedMemoryAdapter } from "@voltagent/voltagent-memory"; + import { Memory } from "@voltagent/core"; - This initial release marks the beginning of VoltAgent, a powerful toolkit crafted for the JavaScript developer community. We saw the challenges: the complexity of building AI from scratch, the limitations of No-Code tools, and the lack of first-class AI tooling specifically for JS. + const memory = new Memory({ + storage: new ManagedMemoryAdapter({ + databaseName: "your-database-name", + }), + }); + ``` - ![VoltAgent Demo](https://cdn.voltagent.dev/readme/demo.gif) - VoltAgent aims to fix that by providing the building blocks you need: - - **`@voltagent/core`**: The foundational engine for agent capabilities. - - **`@voltagent/voice`**: Easily add voice interaction. - - **`@voltagent/vercel-ai`**: Seamless integration with [Vercel AI SDK](https://sdk.vercel.ai/docs/introduction). - - **`@voltagent/xsai`**: A Seamless integration with [xsAI](https://xsai.js.org/). - - **`@voltagent/cli` & `create-voltagent-app`**: Quick start tools to get you building _fast_. + ## Why This Matters + - **Faster Prototyping**: Launch pilots without database setup + - **Reduced Complexity**: No infrastructure management overhead + - **Consistent Experience**: Same StorageAdapter interface across all memory providers + - **Scalable Path**: Start with managed memory, migrate to self-hosted when needed + - **Multi-Region Support**: Deploy close to your users in US or EU - We're combining the flexibility of code with the clarity of visual tools (like our **currently live [VoltOps LLM Observability Platform](https://console.voltagent.dev/)**) to make AI development easier, clearer, and more powerful. Join us as we build the future of AI in JavaScript! + ## Migration Notes - Explore the [Docs](https://voltagent.dev/docs/) and join our [Discord community](https://s.voltagent.dev/discord)! + Existing agents using local storage adapters (InMemory, LibSQL, Postgres, Supabase) continue to work unchanged. Managed memory is an optional addition that provides a cloud-hosted alternative for teams who prefer not to manage their own database infrastructure. --- diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 000000000..47dc3e3d8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/CONSOLE.md b/CONSOLE.md index 60238d768..70896b5cf 100644 --- a/CONSOLE.md +++ b/CONSOLE.md @@ -116,11 +116,11 @@ Then, run your VoltAgent application locally. When you run the `dev` command (e. ══════════════════════════════════════════════════ VOLTAGENT SERVER STARTED SUCCESSFULLY ══════════════════════════════════════════════════ - ✓ HTTP Server: http://localhost:3141 + ✓ HTTP Server: http://localhost:3141 + ✓ Swagger UI: http://localhost:3141/ui - VoltOps Platform: https://console.voltagent.dev + Test your agents with VoltOps Console: https://console.voltagent.dev ══════════════════════════════════════════════════ -[VoltAgent] All packages are up to date ``` Visit [console.voltagent.dev](https://console.voltagent.dev/) to see your agent in real-time. @@ -208,7 +208,7 @@ const agent = await trace.addAgent({ }); // Add tools, memory operations, retrievers as needed -const tool = await agent.addTool({ +const tool = await agent.addStandaloneTool({ name: "knowledge-base-search", input: { query: "password reset procedure" }, }); diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 000000000..ef8212ca7 --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,560 @@ +--- +version: alpha +name: Voltagent Inspired +description: An inspired interpretation of Voltagent's design language — a developer-focused AI agent engineering platform whose surface is an unrelenting near-black canvas broken only by a single electric-green brand accent, code-editor mockups inside the hero, and a precise grid of dark feature cards that read like a documentation site dressed as marketing. + +colors: + primary: "#00d992" + primary-soft: "#2fd6a1" + primary-deep: "#10b981" + on-primary: "#101010" + ink: "#f2f2f2" + ink-strong: "#ffffff" + body: "#bdbdbd" + mute: "#8b949e" + hairline: "#3d3a39" + hairline-soft: "#b8b3b0" + canvas: "#101010" + canvas-soft: "#1a1a1a" + canvas-text-soft: "#f5f6f7" + +typography: + display-xl: + fontFamily: Inter, system-ui, -apple-system, Segoe UI, Roboto, sans-serif + fontSize: 60px + fontWeight: 400 + lineHeight: 60px + letterSpacing: -0.65px + display-lg: + fontFamily: Inter, system-ui, -apple-system, Segoe UI, Roboto, sans-serif + fontSize: 36px + fontWeight: 400 + lineHeight: 40px + letterSpacing: -0.9px + display-md: + fontFamily: Inter, system-ui, -apple-system, Segoe UI, Roboto, sans-serif + fontSize: 24px + fontWeight: 700 + lineHeight: 32px + letterSpacing: -0.6px + display-sm: + fontFamily: Inter, system-ui, -apple-system, Segoe UI, Roboto, sans-serif + fontSize: 20px + fontWeight: 600 + lineHeight: 28px + eyebrow-mono: + fontFamily: Inter, system-ui, -apple-system, sans-serif + fontSize: 14px + fontWeight: 600 + lineHeight: 20px + letterSpacing: 2.52px + eyebrow-uppercase: + fontFamily: Inter, system-ui, -apple-system, sans-serif + fontSize: 18px + fontWeight: 600 + lineHeight: 28px + letterSpacing: 0.45px + body-lg: + fontFamily: Inter, system-ui, -apple-system, sans-serif + fontSize: 18px + fontWeight: 400 + lineHeight: 28px + body-md: + fontFamily: Inter, system-ui, -apple-system, sans-serif + fontSize: 16px + fontWeight: 400 + lineHeight: 26px + body-md-strong: + fontFamily: Inter, system-ui, -apple-system, sans-serif + fontSize: 16px + fontWeight: 600 + lineHeight: 24px + body-sm: + fontFamily: Inter, system-ui, -apple-system, sans-serif + fontSize: 14px + fontWeight: 400 + lineHeight: 20px + body-sm-strong: + fontFamily: Inter, system-ui, -apple-system, sans-serif + fontSize: 14px + fontWeight: 600 + lineHeight: 23px + caption: + fontFamily: Inter, system-ui, -apple-system, sans-serif + fontSize: 12px + fontWeight: 400 + lineHeight: 16px + caption-strong: + fontFamily: Inter, system-ui, -apple-system, sans-serif + fontSize: 12px + fontWeight: 500 + lineHeight: 16px + code: + fontFamily: SFMono-Regular, Menlo, Monaco, Consolas, Liberation Mono, monospace + fontSize: 13px + fontWeight: 400 + lineHeight: 18px + code-strong: + fontFamily: SFMono-Regular, Menlo, Monaco, Consolas, monospace + fontSize: 13px + fontWeight: 550 + lineHeight: 16px + button-md: + fontFamily: Inter, system-ui, -apple-system, sans-serif + fontSize: 16px + fontWeight: 600 + lineHeight: 24px + +rounded: + none: 0px + xs: 4px + sm: 6px + md: 8px + pill: 9999px + full: 9999px + +spacing: + xxs: 2px + xs: 4px + sm: 8px + md: 12px + lg: 16px + xl: 20px + 2xl: 24px + 3xl: 32px + 4xl: 40px + 5xl: 48px + 6xl: 64px + +components: + nav-bar: + backgroundColor: "{colors.canvas}" + textColor: "{colors.ink}" + typography: "{typography.body-sm}" + padding: "{spacing.md} {spacing.3xl}" + nav-link: + textColor: "{colors.body}" + typography: "{typography.body-sm}" + button-primary: + backgroundColor: "{colors.primary}" + textColor: "{colors.on-primary}" + typography: "{typography.button-md}" + rounded: "{rounded.sm}" + padding: "{spacing.md} {spacing.lg}" + button-outline-on-dark: + backgroundColor: "{colors.canvas}" + textColor: "{colors.ink}" + borderColor: "{colors.hairline}" + typography: "{typography.button-md}" + rounded: "{rounded.sm}" + padding: "{spacing.md} {spacing.lg}" + button-ghost-green: + backgroundColor: "{colors.canvas}" + textColor: "{colors.primary-soft}" + typography: "{typography.button-md}" + rounded: "{rounded.sm}" + padding: "{spacing.md} {spacing.lg}" + button-pill-tag: + backgroundColor: "{colors.canvas}" + textColor: "{colors.ink}" + borderColor: "{colors.hairline}" + typography: "{typography.body-sm}" + rounded: "{rounded.pill}" + padding: "{spacing.xs} {spacing.md}" + text-input: + backgroundColor: "{colors.canvas-soft}" + textColor: "{colors.ink}" + borderColor: "{colors.hairline}" + typography: "{typography.body-sm}" + rounded: "{rounded.sm}" + padding: "{spacing.md} {spacing.lg}" + card-feature: + backgroundColor: "{colors.canvas}" + textColor: "{colors.ink}" + borderColor: "{colors.hairline}" + typography: "{typography.body-md}" + rounded: "{rounded.md}" + padding: "{spacing.2xl}" + card-feature-emphasized: + backgroundColor: "{colors.canvas}" + textColor: "{colors.ink}" + borderColor: "{colors.hairline}" + typography: "{typography.body-md}" + rounded: "{rounded.md}" + padding: "{spacing.xl}" + code-mockup: + backgroundColor: "{colors.canvas}" + textColor: "{colors.ink}" + borderColor: "{colors.hairline}" + typography: "{typography.code}" + rounded: "{rounded.md}" + padding: "{spacing.xl}" + code-inline-chip: + backgroundColor: "{colors.canvas-soft}" + textColor: "{colors.canvas-text-soft}" + typography: "{typography.code}" + rounded: "{rounded.sm}" + padding: "{spacing.xxs} {spacing.sm}" + hero-band: + backgroundColor: "{colors.canvas}" + textColor: "{colors.ink}" + typography: "{typography.display-xl}" + padding: "{spacing.5xl} {spacing.3xl}" + content-band: + backgroundColor: "{colors.canvas}" + textColor: "{colors.ink}" + typography: "{typography.display-lg}" + padding: "{spacing.5xl} {spacing.3xl}" + green-divider-band: + backgroundColor: "{colors.canvas}" + borderColor: "{colors.primary}" + footer: + backgroundColor: "{colors.canvas}" + textColor: "{colors.body}" + typography: "{typography.body-sm}" + padding: "{spacing.4xl} {spacing.3xl}" + + # ─── Examples (illustrative) — auto-derived; resolve any TO_FILL markers below ─── + ex-pricing-tier: + description: "Default Pricing tier card. Re-uses feature-card chrome with brand canvas-soft surface." + backgroundColor: "{colors.canvas-soft}" + textColor: "{colors.ink}" + borderColor: "{colors.hairline}" + rounded: "{rounded.md}" + padding: "{spacing.2xl}" + ex-pricing-tier-featured: + description: "Featured/highlighted tier — polarity-flipped surface (dark fill + light text in light mode, light fill + dark text in dark mode)." + backgroundColor: "{colors.ink}" + textColor: "{colors.on-primary}" + rounded: "{rounded.md}" + padding: "{spacing.2xl}" + ex-product-selector: + description: "What's Included summary card — re-purposed for SaaS / B2B verticals (NOT a literal product gallery)." + backgroundColor: "{colors.canvas-soft}" + rounded: "{rounded.md}" + padding: "{spacing.2xl}" + ex-cart-drawer: + description: "Subscription summary — re-purposed for SaaS / B2B (line items per add-on, not literal cart)." + backgroundColor: "{colors.canvas}" + rounded: "{rounded.md}" + padding: "{spacing.2xl}" + item-divider: "{colors.hairline}" + ex-app-shell-row: + description: "Sidebar nav row inside the App Shell example. Active state uses brand primary as the indicator." + backgroundColor: "{colors.canvas}" + activeIndicator: "{colors.primary}" + rounded: "{rounded.sm}" + padding: "{spacing.md} {spacing.lg}" + ex-data-table-cell: + description: "Default data-table th + td chrome. Header uses mono-caps eyebrow typography; body uses body-sm." + headerBackground: "{colors.canvas-soft}" + headerTypography: "{typography.caption}" + bodyTypography: "{typography.body-sm}" + cellPadding: "{spacing.md} {spacing.lg}" + rowBorder: "{colors.hairline}" + ex-auth-form-card: + description: "Sign-in / sign-up card. Re-uses feature-card chrome with text-input primitives inside." + backgroundColor: "{colors.canvas-soft}" + rounded: "{rounded.md}" + padding: "{spacing.2xl}" + ex-modal-card: + description: "Modal dialog surface — same chrome as feature-card with elevated shadow." + backgroundColor: "{colors.canvas}" + rounded: "{rounded.md}" + padding: "{spacing.2xl}" + ex-empty-state-card: + description: "Empty-state illustration frame." + backgroundColor: "{colors.canvas-soft}" + rounded: "{rounded.md}" + padding: "{spacing.3xl}" + captionTypography: "{typography.body-md}" + ex-toast: + description: "Toast notification surface — feature-card shape + medium shadow." + backgroundColor: "{colors.canvas}" + rounded: "{rounded.md}" + padding: "{spacing.md} {spacing.lg}" + typography: "{typography.body-sm}" +--- + +## Overview + +Voltagent is an AI agent engineering platform built for developers, and the brand wears that audience proudly: a near-black `{colors.canvas}` (`#101010`) page background that runs edge-to-edge with no light-mode counterpart, a single electric-green accent (`{colors.primary}` `#00d992`) reserved for CTAs, status pills, and the brand lightning glyph, and a typography system that pairs sentence-case Inter with SF Mono for inline code and command snippets. The whole page reads like polished documentation that decided to also sell something. + +The decorative system is restrained. There is no gradient mesh, no atmospheric backdrop, no illustration suite. Instead, the brand uses small typographic moments — a green code chip (`npx voltagent ...`), a 3-px outlined feature card sitting against the same near-black canvas, a green hairline divider between section bands — to mark its identity. The result is a page that feels engineered: every card has a hairline border, every snippet has a copy-to-clipboard button, every metric is rendered in a numeric monospace. + +Type stays calm. Hero display sits at 60 px in regular weight with `-0.65 px` tracking — not a billboard headline, more like a documentation H1. Section headings step down to 36 px / 24 px in similar weights. Body copy is 16 px Inter at line-height 1.65 for the kind of legibility long-form devs expect. Uppercase eyebrows are common — `EVERYTHING YOU NEED` style mono-cap labels above section headlines — and they use Inter at weight 600 with wide positive tracking (`2.52 px` at 14 px). + +**Key Characteristics:** + +- A single electric-green accent `{colors.primary}` (`#00d992`) carries every CTA, every status pill, and the brand's lightning logo. No second accent. +- Dark canvas (`{colors.canvas}` `#101010`) is the only page surface — there is no light-mode rhythm; the entire site reads as one continuous dark surface broken by feature-card boundaries. +- Hairline-bordered feature cards (`{colors.hairline}` `#3d3a39`, 1 px solid) are the brand's primary chrome — no shadows, no fills, just precise hairline rectangles. +- A signature dashed-border accent (`1px dashed rgba(79, 93, 117, 0.4)`) appears between sections as a quiet rhythm cue — the brand's only ornamental line. +- Inter + SF Mono pair carries every typographic role. SF Mono is reserved for code blocks, inline command snippets, and metric counters. +- Buttons are tight 6 px rounded rectangles (not pills); only inline status tags use the 9999 px full pill. + +## Colors + +### Brand & Accent + +- **Electric Green** (`{colors.primary}` — `#00d992`): The single brand accent. Every primary CTA, every status pill, every "live" indicator, the brand's lightning glyph itself. Reserved. +- **Primary Soft** (`{colors.primary-soft}` — `#2fd6a1`): A slightly more muted green used inside button-ghost variants and tooltip / focus indicators. +- **Primary Deep** (`{colors.primary-deep}` — `#10b981`): The darker green used for inline link colour in body copy. + +### Surface + +- **Canvas** (`{colors.canvas}` — `#101010`): The default near-black page background. The only surface mode in the brand's marketing system. +- **Canvas Soft** (`{colors.canvas-soft}` — `#1a1a1a`): A slightly lighter dark fill used inside code blocks and form inputs to mark them visually distinct against the canvas. +- **Hairline** (`{colors.hairline}` — `#3d3a39`): 1 px solid borders — feature cards, buttons, dividers between rows. The brand's universal "edge" colour. +- **Hairline Soft** (`{colors.hairline-soft}` — `#b8b3b0`): A lighter divider tint used in rare on-light secondary contexts. + +### Text + +- **Ink** (`{colors.ink}` — `#f2f2f2`): Default text colour on the dark canvas — slightly off-white to reduce contrast strain. +- **Ink Strong** (`{colors.ink-strong}` — `#ffffff`): Pure-white text for hero headlines and high-emphasis copy. +- **Body** (`{colors.body}` — `#bdbdbd`): Secondary text — supporting copy, body paragraphs in long-form sections. +- **Mute** (`{colors.mute}` — `#8b949e`): Lowest-priority on-dark text — captions, fine print, footer secondary lines. +- **Canvas Text Soft** (`{colors.canvas-text-soft}` — `#f5f6f7`): Used inside code mockups to keep code colour just slightly cooler than the surrounding body text. + +### Semantic + +The brand doesn't surface a separate error / warning palette in its public marketing pages — the underlying Docusaurus default semantic palette exists in the design system but is reserved for in-product / docs contexts. Validation cues on the marketing surface use the primary green for success and a muted body grey for missing states. + +## Typography + +### Font Family + +Two faces carry the system: + +1. **Inter** for every display, body, button, and link role. Weights 400 / 500 / 600 / 700 are the working set. Used with OpenType features `"calt"` and `"rlig"` enabled across the page so the geometric Inter ligatures and contextual alternates render correctly. +2. **SF Mono** (`SFMono-Regular` with Menlo / Monaco / Consolas / Liberation Mono fallbacks) for inline code, command snippets, terminal mockups, and the brand's numeric counters. Weights 400 / 549 / 550 / 700 are present — the unusual 549 / 550 sub-bold weight gives the mono a "slightly heavier than regular" voice for emphasis. + +### Hierarchy + +| Token | Size | Weight | Line Height | Letter Spacing | Use | +| -------------------------------- | ---- | ------ | ----------- | -------------- | ---------------------------------------------------------- | +| `{typography.display-xl}` | 60px | 400 | 60px | -0.65px | Hero headline ("AI Agent Engineering Platform"). | +| `{typography.display-lg}` | 36px | 400 | 40px | -0.9px | Section headlines. | +| `{typography.display-md}` | 24px | 700 | 32px | -0.6px | Sub-section / card-title displays. | +| `{typography.display-sm}` | 20px | 600 | 28px | 0 | Card titles in dense grids. | +| `{typography.eyebrow-mono}` | 14px | 600 | 20px | 2.52px | UPPERCASE eyebrow tags ("EVERYTHING YOU NEED"). | +| `{typography.eyebrow-uppercase}` | 18px | 600 | 28px | 0.45px | Larger uppercase eyebrows above hero subsections. | +| `{typography.body-lg}` | 18px | 400 | 28px | 0 | Lead paragraphs. | +| `{typography.body-md}` | 16px | 400 | 26px | 0 | Default body paragraph. | +| `{typography.body-md-strong}` | 16px | 600 | 24px | 0 | Bolded inline body. | +| `{typography.body-sm}` | 14px | 400 | 20px | 0 | Secondary body. | +| `{typography.body-sm-strong}` | 14px | 600 | 23px | 0 | Bold caption / pill-tag labels. | +| `{typography.caption}` | 12px | 400 | 16px | 0 | Fine print. | +| `{typography.caption-strong}` | 12px | 500 | 16px | 0 | Bold caption. | +| `{typography.code}` | 13px | 400 | 18px | 0 | Code blocks, inline command snippets. | +| `{typography.code-strong}` | 13px | 550 | 16px | 0 | Emphasised inline code (the SF Mono "almost-bold" weight). | +| `{typography.button-md}` | 16px | 600 | 24px | 0 | Button labels. | + +### Principles + +- **Inter regular at 60 px display** is the brand's calming counter to AI marketing's tendency to shout. The light tracking and modest weight read like documentation. +- **Two-face contrast carries the technical voice.** Inter for narrative; SF Mono for anything that could be typed at a terminal. +- **Uppercase eyebrow with tracking is the brand's signature label style.** `2.52 px` at 14 px is the documented value. + +### Note on Font Substitutes + +- **Sans** — _Inter_ is the brand's actual face; substitute is the brand itself when self-hosting is not available. +- **Mono** — _SF Mono_ is Apple-system; _JetBrains Mono_ or _Geist Mono_ are the best free substitutes. + +## Layout + +### Spacing System + +- **Base unit**: 4 px; small 5 / 6.4 px values appear inside code-mockup line-height compensation. +- **Tokens**: `{spacing.xxs}` 2 px · `{spacing.xs}` 4 px · `{spacing.sm}` 8 px · `{spacing.md}` 12 px · `{spacing.lg}` 16 px · `{spacing.xl}` 20 px · `{spacing.2xl}` 24 px · `{spacing.3xl}` 32 px · `{spacing.4xl}` 40 px · `{spacing.5xl}` 48 px · `{spacing.6xl}` 64 px. +- **Section padding**: hero + content bands use `{spacing.5xl}` 48 px top/bottom. +- **Card interior padding**: feature cards sit at `{spacing.2xl}` 24 px. + +### Grid & Container + +- Marketing container centres at roughly 1200 – 1400 px; content stays edge-to-edge in colour with horizontal gutters of `{spacing.3xl}` on desktop. +- Feature-card grids: 2-up to 3-up at desktop, 1-up at mobile. + +### Responsive Strategy + +#### Breakpoints + +| Name | Width | Key Changes | +| ------- | ---------- | ----------------------------------------- | +| Mobile | < 768px | Hero 60→32 px; cards 1-up; nav hamburger. | +| Tablet | 768–1023px | Cards 2-up; nav stays horizontal. | +| Desktop | ≥ 1024px | Full 3-up card grids. | + +#### Touch Targets + +Buttons render at ~44 px tall (12 px vertical padding + 24 px line-height). Meet WCAG AAA at all breakpoints. + +#### Collapsing Strategy + +Nav collapses to hamburger at mobile; the menu overlay keeps the same green CTA pinned at the bottom. Feature-card grids drop to 1-up; hero typography scales fluidly. + +#### Image Behavior + +Code-editor mockups render as image-like cards with copy-to-clipboard affordances. No photography in the brand's marketing surface. + +## Elevation & Depth + +| Level | Treatment | Use | +| --------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------ | +| Level 0 — Flat | No shadow, no border. | Full-bleed bands. | +| Level 1 — Hairline | 1 px solid `{colors.hairline}` border on `{colors.canvas}`. | Default for every feature card and button. | +| Level 2 — Inset Glow | `0 0 15px rgba(92, 88, 85, 0.2)` subtle outer glow. | Hovering / featured cards. | +| Level 3 — Modal Stack | `0 20px 60px rgba(0,0,0,0.7), 0 0 0 1px rgba(148,163,184,0.1) inset` heavy drop + inset ring. | Modal / dialog surfaces in-product. | + +### Decorative Depth + +- Hairline cards on dark canvas — the brand's only true elevation mode. +- A 2 px solid `{colors.primary}` green border occasionally marks "featured" or "active" status on a card. +- A 1 px dashed `rgba(79, 93, 117, 0.4)` divider sits between section bands as a quiet rhythm cue. + +## Shapes + +### Border Radius Scale + +| Token | Value | Use | +| ---------------- | ------ | ----------------------------------------- | +| `{rounded.none}` | 0px | Full-bleed bands. | +| `{rounded.xs}` | 4px | Smallest inline pills, code inline chips. | +| `{rounded.sm}` | 6px | Default button and input radius. | +| `{rounded.md}` | 8px | Card chrome, code-block chrome. | +| `{rounded.pill}` | 9999px | Inline status tags ("Live", "Beta"). | +| `{rounded.full}` | 9999px | Circular icon containers. | + +## Components + +### Buttons + +**`button-primary`** — the electric-green CTA. + +- Background `{colors.primary}`, text `{colors.on-primary}` (near-black), label `{typography.button-md}`, padding `{spacing.md} {spacing.lg}`, shape `{rounded.sm}` 6 px. + +**`button-outline-on-dark`** — the hairline-on-dark secondary button. + +- Background `{colors.canvas}`, text `{colors.ink}`, 1 px solid `{colors.hairline}` border, same typography / padding / shape. + +**`button-ghost-green`** — text-only with green label, for tertiary actions. + +- Background `{colors.canvas}`, text `{colors.primary-soft}`, no border. + +**`button-pill-tag`** — the inline pill for category tags / status labels. + +- Background `{colors.canvas}`, text `{colors.ink}`, hairline border, body in `{typography.body-sm}`, padding `{spacing.xs} {spacing.md}`, shape `{rounded.pill}` 9999 px. + +### Cards & Containers + +**`card-feature`** — the default feature card. + +- Background `{colors.canvas}`, text `{colors.ink}`, 1 px solid `{colors.hairline}` border, padding `{spacing.2xl}`, shape `{rounded.md}` 8 px. The brand's most-repeated card chrome. + +**`card-feature-emphasized`** — the same card with a 3 px hairline border for emphasis. + +- Same chrome as `card-feature` with 3 px solid `{colors.hairline}`. + +**`code-mockup`** — the dark code-editor card with copy-to-clipboard affordance. + +- Background `{colors.canvas}`, text `{colors.ink}`, 1 px solid `{colors.hairline}`, body in `{typography.code}` (SF Mono 13 px), padding `{spacing.xl}`, shape `{rounded.md}`. + +**`code-inline-chip`** — the inline command snippet pill. + +- Background `{colors.canvas-soft}`, text `{colors.canvas-text-soft}`, body in `{typography.code}`, padding `{spacing.xxs} {spacing.sm}`, shape `{rounded.sm}`. + +### Inputs & Forms + +**`text-input`** — the standard text input on dark. + +- Background `{colors.canvas-soft}`, text `{colors.ink}`, 1 px solid `{colors.hairline}`, body in `{typography.body-sm}`, padding `{spacing.md} {spacing.lg}`, shape `{rounded.sm}` 6 px. + +### Navigation + +**`nav-bar`** — the sticky top nav on dark. + +- Background `{colors.canvas}`, text `{colors.ink}`, padding `{spacing.md} {spacing.3xl}`. + +**`nav-link`** — link items in nav. + +- Text `{colors.body}`, set in `{typography.body-sm}`. + +**`footer`** — the dark footer band. + +- Background `{colors.canvas}`, text `{colors.body}`, padding `{spacing.4xl} {spacing.3xl}`. Body in `{typography.body-sm}`. + +### Signature Components + +**`hero-band`** — the dark hero band with the 60-px Inter headline. + +- Background `{colors.canvas}`, text `{colors.ink}` (with the headline at `{colors.ink-strong}` white), padding `{spacing.5xl} {spacing.3xl}`. Headline in `{typography.display-xl}` (60 px / weight 400 / `-0.65 px` tracking). Eyebrow above headline in `{typography.eyebrow-mono}` (uppercase, tracked). + +**`content-band`** — the standard content band hosting feature grids. + +- Background `{colors.canvas}`, text `{colors.ink}`, padding `{spacing.5xl} {spacing.3xl}`. Section headline in `{typography.display-lg}`. + +**`green-divider-band`** — a thin green-glow band that occasionally separates major sections. + +- Background `{colors.canvas}`, 2 px solid `{colors.primary}` top/bottom border. The brand's only chromatic divider. + +### Examples (illustrative) + +> Auto-derived kit-mirror demonstration surfaces (`scripts/derive-examples-block.mjs`). Each `ex-*` entry references brand-native primitives so downstream consumers (`/preview-design`, `/generate-kit`) re-skin the same 10 surfaces consistently. `TO_FILL` markers indicate missing primitives — resolve in the LLM judgment pass. + +**`ex-pricing-tier`** — Default Pricing tier card. Re-uses feature-card chrome with brand canvas-soft surface. + +- Properties: `backgroundColor`, `textColor`, `borderColor`, `rounded`, `padding` + +**`ex-pricing-tier-featured`** — Featured/highlighted tier — polarity-flipped surface (dark fill + light text in light mode, light fill + dark text in dark mode). + +- Properties: `backgroundColor`, `textColor`, `rounded`, `padding` + +**`ex-product-selector`** — What's Included summary card — re-purposed for SaaS / B2B verticals (NOT a literal product gallery). + +- Properties: `backgroundColor`, `rounded`, `padding` + +**`ex-cart-drawer`** — Subscription summary — re-purposed for SaaS / B2B (line items per add-on, not literal cart). + +- Properties: `backgroundColor`, `rounded`, `padding`, `item-divider` + +**`ex-app-shell-row`** — Sidebar nav row inside the App Shell example. Active state uses brand primary as the indicator. + +- Properties: `backgroundColor`, `activeIndicator`, `rounded`, `padding` + +**`ex-data-table-cell`** — Default data-table th + td chrome. Header uses mono-caps eyebrow typography; body uses body-sm. + +- Properties: `headerBackground`, `headerTypography`, `bodyTypography`, `cellPadding`, `rowBorder` + +**`ex-auth-form-card`** — Sign-in / sign-up card. Re-uses feature-card chrome with text-input primitives inside. + +- Properties: `backgroundColor`, `rounded`, `padding` + +**`ex-modal-card`** — Modal dialog surface — same chrome as feature-card with elevated shadow. + +- Properties: `backgroundColor`, `rounded`, `padding` + +**`ex-empty-state-card`** — Empty-state illustration frame. + +- Properties: `backgroundColor`, `rounded`, `padding`, `captionTypography` + +**`ex-toast`** — Toast notification surface — feature-card shape + medium shadow. + +- Properties: `backgroundColor`, `rounded`, `padding`, `typography` + +## Do's and Don'ts + +### Do + +- Reserve `{colors.primary}` (`#00d992`) for every primary CTA, the lightning logo glyph, and live-status indicators. The green is the brand's centre of gravity. +- Use the dark `{colors.canvas}` (`#101010`) as the only page surface. There is no light-mode rhythm. +- Build cards with 1 px `{colors.hairline}` borders, not shadows. Hairlines on dark IS the brand's elevation system. +- Pair Inter (sentence-case) with SF Mono (inline code, command snippets). Every uppercase moment uses Inter at weight 600 with `2.52 px` tracking — not a separate mono. +- Use `{rounded.sm}` 6 px for buttons, `{rounded.md}` 8 px for cards, `{rounded.pill}` 9999 px only for inline status tags. + +### Don't + +- Don't introduce a light-mode counterpart. The brand is dark-canvas only. +- Don't use the primary green as a body-text fill. It's CTA-only. +- Don't drop a soft drop-shadow on cards. The brand uses hairlines + occasional glow, never material shadows. +- Don't render the hero headline in heavy weight (700+). The brand's display is intentionally calm at weight 400. +- Don't replace Inter or SF Mono with a different family — both faces are part of the brand's voice and pairing. diff --git a/PRERELEASE.md b/PRERELEASE.md new file mode 100644 index 000000000..9f75de5f5 --- /dev/null +++ b/PRERELEASE.md @@ -0,0 +1,148 @@ +# VoltAgent Prerelease Process + +This document outlines how to work with prereleases in the VoltAgent monorepo. + +## Overview + +We use [Changesets](https://github.com/changesets/changesets) to manage prereleases. The `next` branch is used for prerelease versions that will eventually become the next major version. + +## Branches + +- **`main`**: Stable releases (0.x.x currently) +- **`next`**: Prerelease versions (1.0.0-next.x) + +## Working with Prereleases + +### 1. Switching to Prerelease Mode + +The `next` branch is already in prerelease mode. When you're on this branch: + +```bash +# Check if you're in prerelease mode +cat .changeset/pre.json +``` + +### 2. Adding Changes + +When adding new features or fixes to the prerelease: + +```bash +# Create a changeset for your changes +pnpm changeset + +# Select the packages you've changed +# Choose the type of change (patch/minor/major) +# Add a description of your changes +``` + +### 3. Versioning Packages + +After adding changesets: + +```bash +# Version packages with prerelease tags +pnpm changeset version + +# This will update: +# - package.json files with new versions (e.g., 1.0.0-next.1) +# - CHANGELOG.md files with your changes +# - .changeset/pre.json with consumed changesets +``` + +### 4. Publishing Prereleases + +```bash +# Build all packages +pnpm build + +# Publish to npm with the 'next' tag +pnpm changeset publish --tag next + +# Or if you want to do a dry run first +pnpm changeset publish --tag next --no-git-tag --dry-run +``` + +### 5. Installing Prerelease Versions + +Users can install prerelease versions: + +```bash +# Install a specific prerelease version +npm install @voltagent/core@next + +# Or specify exact version +npm install @voltagent/core@1.0.0-next.0 +``` + +## Workflow Example + +```bash +# 1. Switch to next branch +git checkout next +git pull origin next + +# 2. Make your changes +# ... edit files ... + +# 3. Create a changeset +pnpm changeset + +# 4. Commit your changes +git add . +git commit -m "feat: add new feature" + +# 5. Version packages +pnpm changeset version + +# 6. Commit version updates +git add . +git commit -m "chore: version packages" + +# 7. Push to next branch +git push origin next + +# 8. Publish prereleases (usually done in CI) +pnpm build +pnpm changeset publish --tag next +``` + +## Exiting Prerelease Mode + +When ready to release the final major version: + +```bash +# 1. Exit prerelease mode +pnpm changeset pre exit + +# 2. Version packages (this removes the -next.x suffix) +pnpm changeset version + +# 3. Publish the final release +pnpm changeset publish +``` + +## Troubleshooting + +### Accidentally published without tag + +If you accidentally publish without the `next` tag: + +```bash +# Fix the npm tags +npm dist-tag add @voltagent/core@0.1.81 latest +npm dist-tag add @voltagent/core@1.0.0-next.0 next +``` + +### Check current prerelease state + +```bash +# See what versions will be published +pnpm changeset status + +# Check prerelease configuration +cat .changeset/pre.json +``` + +## Questions? + +For questions about the prerelease process, please open an issue or reach out to the maintainers. diff --git a/README.md b/README.md index 4921eac7f..2893368e8 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,11 @@
-435380213-b6253409-8741-462b-a346-834cd18565a9 +voltagent -
-
+

+AI Agent Engineering Platform +

English | 繁體中文 | 简体中文 | 日本語 | 한국어 @@ -15,78 +16,62 @@ English | 繁體中文 | Home Page | Documentation | - Examples | - Discord | - Blog + Examples

-
- VoltAgent is an open source TypeScript framework for building and orchestrating AI agents.
-Escape the limitations of no-code builders and the complexity of starting from scratch. -
-
-
-
-[![npm version](https://img.shields.io/npm/v/@voltagent/core.svg)](https://www.npmjs.com/package/@voltagent/core) +[![GitHub issues](https://img.shields.io/github/issues/voltagent/voltagent)](https://github.com/voltagent/voltagent/issues) +[![GitHub pull requests](https://img.shields.io/github/issues-pr/voltagent/voltagent)](https://github.com/voltagent/voltagent/pulls) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](CODE_OF_CONDUCT.md) -[![Discord](https://img.shields.io/discord/1361559153780195478.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://s.voltagent.dev/discord) -[![Twitter Follow](https://img.shields.io/twitter/follow/voltagent_dev?style=social)](https://twitter.com/voltagent_dev) - -
- -
+[![npm version](https://img.shields.io/npm/v/@voltagent/core.svg)](https://www.npmjs.com/package/@voltagent/core) -
- -flow - +[![npm downloads](https://img.shields.io/npm/dm/@voltagent/core.svg)](https://www.npmjs.com/package/@voltagent/core) +[![Discord](https://img.shields.io/discord/1361559153780195478.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://s.voltagent.dev/discord) +[![Twitter Follow](https://img.shields.io/twitter/follow/voltagent_dev?style=social)](https://x.com/voltagent_dev)
-## What is VoltAgent? +VoltAgent is an end-to-end AI Agent Engineering Platform that consists of two main parts: -> An **AI Agent Framework** provides the foundational structure and tools needed to build applications powered by autonomous agents. These agents, often driven by Large Language Models (LLMs), can perceive their environment, make decisions, and take actions to achieve specific goals. Building such agents from scratch involves managing complex interactions with LLMs, handling state, connecting to external tools and data, and orchestrating workflows. +- **[Open-Source TypeScript Framework](#core-framework)** – Memory, RAG, Guardrails, Tools, MCP, Voice, Workflow, and more. +- **[VoltOps Console](#voltops-console)** `Cloud` `Self-Hosted` – Observability, Automation, Deployment, Evals, Guardrails, Prompts, and more. -**VoltAgent** is an open-source TypeScript framework that acts as this essential toolkit. It simplifies the development of AI agent applications by providing modular building blocks, standardized patterns, and abstractions. Whether you're creating chatbots, virtual assistants, automated workflows, or complex multi-agent systems, VoltAgent handles the underlying complexity, allowing you to focus on defining your agents' capabilities and logic. +Build agents with full code control and ship them with production-ready visibility and operations. -Instead of building everything from scratch, VoltAgent provides ready-made, modular building blocks: +

Core TypeScript Framework

-- **Core Engine (`@voltagent/core`)**: The heart of VoltAgent, providing fundamental capabilities for your AI agents Define individual agents with specific roles, tools, and memory. -- **Multi-Agent Systems**: Architect complex applications by coordinating multiple specialized agents using Supervisors. -- **Workflow Engine**: Go beyond simple request-response. Orchestrate multi-step automations that can process data, call APIs, run tasks in parallel, and execute conditional logic. -- **Extensible Packages**: Enhance functionality with packages like `@voltagent/voice` for voice interactions. -- **Tooling & Integrations**: Equip agents with tools to connect to external APIs, databases, and services, enabling them to perform real-world tasks. **Supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for standardized tool interactions.** -- **Data Retrieval & RAG**: Implement specialized retriever agents for efficient information fetching and **Retrieval-Augmented Generation (RAG)**. -- **Memory**: Enable agents to remember past interactions for more natural and context-aware conversations. -- **LLM Compatibility**: Works with popular AI models from OpenAI, Google, Anthropic, and more, allowing easy switching. -- **Developer Ecosystem**: Includes helpers like `create-voltagent-app`, `@voltagent/cli`, and the visual [VoltOps LLM Observability Platform](https://console.voltagent.dev) for quick setup, monitoring, and debugging. +With the open-source framework, you can build intelligent agents with memory, tools, and multi-step workflows while connecting to any AI provider. Create sophisticated multi-agent systems where specialized agents work together under supervisor coordination. -In essence, VoltAgent helps developers build sophisticated AI applications faster and more reliably, avoiding repetitive setup and the limitations of simpler tools. +- **[Core Runtime](https://voltagent.dev/docs/agents/overview/) (`@voltagent/core`)**: Define agents with typed roles, tools, memory, and model providers in one place so everything stays organized. +- **[Workflow Engine](https://voltagent.dev/docs/workflows/overview/)**: Describe multi-step automations declaratively rather than stitching together custom control flow. +- **[Supervisors & Sub-Agents](https://voltagent.dev/docs/agents/sub-agents/)**: Run teams of specialized agents under a supervisor runtime that routes tasks and keeps them in sync. +- **[Tool Registry](https://voltagent.dev/docs/agents/tools/) & [MCP](https://voltagent.dev/docs/agents/mcp/)**: Ship Zod-typed tools with lifecycle hooks and cancellation, and connect to [Model Context Protocol](https://modelcontextprotocol.io/) servers without extra glue code. +- **[LLM Compatibility](https://voltagent.dev/docs/getting-started/providers-models/)**: Swap between OpenAI, Anthropic, Google, or other providers by changing config, not rewriting agent logic. +- **[Memory](https://voltagent.dev/docs/agents/memory/overview/)**: Attach durable memory adapters so agents remember important context across runs. +- **[Resumable Streaming](https://voltagent.dev/docs/agents/resumable-streaming/)**: Let clients reconnect to in-flight streams after refresh and continue receiving the same response. +- **[Retrieval & RAG](https://voltagent.dev/docs/rag/overview/)**: Plug in retriever agents to pull facts from your data sources and ground responses (RAG) before the model answers. +- **[VoltAgent Knowledge Base](https://voltagent.dev/docs/rag/voltagent/)**: Use the managed RAG service for document ingestion, chunking, embeddings, and search. +- **[Voice](https://voltagent.dev/docs/agents/voice/)**: Add text-to-speech and speech-to-text capabilities with OpenAI, ElevenLabs, or custom voice providers. +- **[Guardrails](https://voltagent.dev/docs/guardrails/overview/)**: Intercept and validate agent input or output at runtime to enforce content policies and safety rules. +- **[Evals](https://voltagent.dev/docs/evals/overview/)**: Run agent eval suites alongside your workflows to measure and improve agent behavior. -## Why VoltAgent? +#### MCP Server (@voltagent/mcp-docs-server) -Building AI applications often involves a trade-off: +You can use the MCP server `@voltagent/mcp-docs-server` to teach your LLM how to use VoltAgent for AI-powered coding assistants like Claude, Cursor, or Windsurf. This allows AI assistants to access VoltAgent documentation, examples, and changelogs directly while you code. -1. **DIY Approach:** Using basic AI provider tools offers control but leads to complex, hard-to-manage code and repeated effort. -2. **No-Code Builders:** Simpler initially but often restrictive, limiting customization, provider choice, and complexity. +📖 [How to setup MCP docs server](https://voltagent.dev/docs/getting-started/mcp-docs-server/) -VoltAgent provides a middle ground, offering structure and components without sacrificing flexibility: +## 💛 Sponsors -- **Build Faster:** Accelerate development with pre-built components compared to starting from scratch. -- **Maintainable Code:** Encourages organization for easier updates and debugging. -- **Scalability:** Start simple and easily scale to complex, multi-agent systems handling intricate workflows. -- **Build Sophisticated Automations:** It's not just for chat. The workflow engine lets you build complex, multi-step processes for tasks like data analysis pipelines, automated content generation, or intelligent decision-making systems. -- **Flexibility:** Full control over agent behavior, LLM choice, tool integrations, and UI connections. -- **Avoid Lock-in:** Freedom to switch AI providers and models as needed. -- **Cost Efficiency:** Features designed to optimize AI service usage and reduce redundant calls. -- **Visual Monitoring:** Use the [VoltOps LLM Observability Platform](https://console.voltagent.dev) to track agent performance, inspect state, and debug visually. - -VoltAgent empowers developers to build their envisioned AI applications efficiently, from simple helpers to complex systems. +| | | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| TestMu AI | [TestMu AI (formerly LambdaTest)](https://www.testmuai.com) is an AI-native testing cloud platform built for modern engineering teams. Covering everything from autonomous test creation and fast execution to testing AI agents, chatbots and voice assistants. | +| Ego Lite | [Ego Lite](https://lite.ego.app/?utm_source=voltagent-github&utm_medium=sponsor&utm_campaign=github-sponsor) is the fastest browser for your AI agents to run browser automation tasks, 3.45x faster than agent-browser (Vercel), always free, no setup, and lets your agents run 100+ browser tasks at the same time in their Spaces. | ## ⚡ Quick Start @@ -101,18 +86,32 @@ This command guides you through setup. You'll see the starter code in `src/index.ts`, which now registers both an agent and a comprehensive workflow example found in `src/workflows/index.ts`. ```typescript -import { VoltAgent, Agent } from "@voltagent/core"; -import { VercelAIProvider } from "@voltagent/vercel-ai"; +import { VoltAgent, Agent, Memory } from "@voltagent/core"; +import { LibSQLMemoryAdapter } from "@voltagent/libsql"; +import { createPinoLogger } from "@voltagent/logger"; +import { honoServer } from "@voltagent/server-hono"; import { openai } from "@ai-sdk/openai"; -import { comprehensiveWorkflow } from "./workflows"; +import { expenseApprovalWorkflow } from "./workflows"; +import { weatherTool } from "./tools"; + +// Create a logger instance +const logger = createPinoLogger({ + name: "my-agent-app", + level: "info", +}); + +// Optional persistent memory (remove to use default in-memory) +const memory = new Memory({ + storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }), +}); // A simple, general-purpose agent for the project. const agent = new Agent({ name: "my-agent", - instructions: "A helpful assistant that answers questions without using tools", - llm: new VercelAIProvider(), + instructions: "A helpful assistant that can check weather and help with various tasks", model: openai("gpt-4o-mini"), - tools: [], + tools: [weatherTool], + memory, }); // Initialize VoltAgent with your agent(s) and workflow(s) @@ -121,8 +120,10 @@ new VoltAgent({ agent, }, workflows: { - comprehensiveWorkflow, + expenseApprovalWorkflow, }, + server: honoServer(), + logger, }); ``` @@ -152,56 +153,203 @@ Your agent is now running! To interact with it: 4. Start Chatting: On the agent detail page, click the chat icon in the bottom right corner to open the chat window. 5. Send a Message: Type a message like "Hello" and press Enter. -[![VoltAgent VoltOps Platform Demo](https://github.com/user-attachments/assets/0adbec33-1373-4cf4-b67d-825f7baf1cb4)](https://console.voltagent.dev/) +[![VoltAgent Demo](thumbnail.png)](https://github.com/user-attachments/assets/26340c6a-be34-48a5-9006-e822bf6098a7) ### Running Your First Workflow -Your new project also includes a powerful workflow engine. You can test the pre-built `comprehensiveWorkflow` directly from the VoltOps console: +Your new project also includes a powerful workflow engine. -![VoltOps Workflow Observability](https://github.com/user-attachments/assets/9b877c65-f095-407f-9237-d7879964c38a) +The expense approval workflow demonstrates human-in-the-loop automation with suspend/resume capabilities: + +```typescript +import { createWorkflowChain } from "@voltagent/core"; +import { z } from "zod"; + +export const expenseApprovalWorkflow = createWorkflowChain({ + id: "expense-approval", + name: "Expense Approval Workflow", + purpose: "Process expense reports with manager approval for high amounts", + + input: z.object({ + employeeId: z.string(), + amount: z.number(), + category: z.string(), + description: z.string(), + }), + result: z.object({ + status: z.enum(["approved", "rejected"]), + approvedBy: z.string(), + finalAmount: z.number(), + }), +}) + // Step 1: Validate expense and check if approval needed + .andThen({ + id: "check-approval-needed", + resumeSchema: z.object({ + approved: z.boolean(), + managerId: z.string(), + comments: z.string().optional(), + adjustedAmount: z.number().optional(), + }), + execute: async ({ data, suspend, resumeData }) => { + // If we're resuming with manager's decision + if (resumeData) { + return { + ...data, + approved: resumeData.approved, + approvedBy: resumeData.managerId, + finalAmount: resumeData.adjustedAmount || data.amount, + }; + } + + // Check if manager approval is needed (expenses over $500) + if (data.amount > 500) { + await suspend("Manager approval required", { + employeeId: data.employeeId, + requestedAmount: data.amount, + }); + } + + // Auto-approve small expenses + return { + ...data, + approved: true, + approvedBy: "system", + finalAmount: data.amount, + }; + }, + }) + // Step 2: Process the final decision + .andThen({ + id: "process-decision", + execute: async ({ data }) => { + return { + status: data.approved ? "approved" : "rejected", + approvedBy: data.approvedBy, + finalAmount: data.finalAmount, + }; + }, + }); +``` + +You can test the pre-built `expenseApprovalWorkflow` directly from the VoltOps console: + +[![expense-approval](thumbnail.png)](https://github.com/user-attachments/assets/3d3ea67b-4ab5-4dc0-932d-cedd92894b18) 1. **Go to the Workflows Page:** After starting your server, go directly to the [Workflows page](https://console.voltagent.dev/workflows). 2. **Select Your Project:** Use the project selector to choose your project (e.g., "my-agent-app"). -3. **Find and Run:** You will see **"Comprehensive Workflow Example"** listed. Click it, then click the **"Run"** button. -4. **Provide Input:** The workflow expects a JSON object with a `text` key. Try it with a negative sentiment to see the conditional logic in action: +3. **Find and Run:** You will see **"Expense Approval Workflow"** listed. Click it, then click the **"Run"** button. +4. **Provide Input:** The workflow expects a JSON object with expense details. Try a small expense for automatic approval: ```json - { "text": "I am very disappointed with this product, it is terrible." } + { + "employeeId": "EMP-123", + "amount": 250, + "category": "office-supplies", + "description": "New laptop mouse and keyboard" + } ``` 5. **View the Results:** After execution, you can inspect the detailed logs for each step and see the final output directly in the console. -## Key Features - -- **Agent Core:** Define agents with descriptions, LLM providers, tools, and memory management. -- **Workflow Engine:** Orchestrate complex, multi-step automations with a powerful and declarative API (`andThen`, `andAgent`, `andAll`, `andRace`, `andWhen`). -- **Multi-Agent Systems:** Build complex workflows using Supervisor Agents coordinating multiple specialized Sub-Agents. -- **Tool Usage & Lifecycle:** Equip agents with custom or pre-built tools (functions) with type-safety (Zod), lifecycle hooks, and cancellation support to interact with external systems. -- **Flexible LLM Support:** Integrate seamlessly with various LLM providers (OpenAI, Anthropic, Google, etc.) and easily switch between models. -- **Memory Management:** Enable agents to retain context across interactions using different configurable memory providers. -- **Observability & Debugging:** Visually monitor agent states, interactions, logs, and performance via the [VoltOps LLM Observability Platform](https://console.voltagent.dev). -- **Custom API Endpoints:** Extend the VoltAgent API server with your own custom endpoints to build specialized functionality on top of the core framework. -- **Voice Interaction:** Build voice-enabled agents capable of speech recognition and synthesis using the `@voltagent/voice` package. -- **Data Retrieval & RAG:** Integrate specialized retriever agents for efficient information fetching and **Retrieval-Augmented Generation (RAG)** from various sources. -- **Model Context Protocol (MCP) Support:** Connect to external tool servers (HTTP/stdio) adhering to the [MCP standard](https://modelcontextprotocol.io/) for extended capabilities. -- **Prompt Engineering Tools:** Leverage utilities like `createPrompt` for crafting and managing effective prompts for your agents. -- **Framework Compatibility:** Designed for easy integration into existing Node.js applications and popular frameworks. - -## Use Cases - -VoltAgent is versatile and can power a wide range of AI-driven applications: - -- **Complex Workflow Automation:** Orchestrate multi-step processes involving various tools, APIs, and decision points using coordinated agents. -- **Intelligent Data Pipelines:** Build agents that fetch, process, analyze, and transform data from diverse sources. -- **AI-Powered Internal Tools & Dashboards:** Create interactive internal applications that leverage AI for analysis, reporting, or task automation, often integrated with UIs using hooks. -- **Automated Customer Support Agents:** Develop sophisticated chatbots that can understand context (memory), use tools (e.g., check order status), and escalate complex issues. -- **Repository Analysis & Codebase Automation:** Analyze code repositories, automate refactoring tasks, generate documentation, or manage CI/CD processes. -- **Retrieval-Augmented Generation (RAG) Systems:** Build agents that retrieve relevant information from knowledge bases (using retriever agents) before generating informed responses. -- **Voice-Controlled Interfaces & Applications:** Utilize the `@voltagent/voice` package to create applications that respond to and generate spoken language. -- **Personalized User Experiences:** Develop agents that adapt responses and actions based on user history and preferences stored in memory. -- **Real-time Monitoring & Alerting:** Design agents that continuously monitor data streams or systems and trigger actions or notifications based on defined conditions. -- **And Virtually Anything Else...**: If you can imagine an AI agent doing it, VoltAgent can likely help you build it! ⚡ +## Examples + +For more examples, visit our [examples repository](https://github.com/VoltAgent/voltagent/tree/main/examples). + +- **[Airtable Agent](https://voltagent.dev/recipes-and-guides/airtable-agent)** - React to new records and write updates back into Airtable with VoltOps actions. +- **[Slack Agent](https://voltagent.dev/recipes-and-guides/slack-agent)** - Respond to channel messages and reply via VoltOps Slack actions. +- **[ChatGPT App With VoltAgent](https://voltagent.dev/examples/agents/chatgpt-app)** - Deploy VoltAgent over MCP and connect to ChatGPT Apps. +- **[WhatsApp Order Agent](https://voltagent.dev/examples/agents/whatsapp-ai-agent)** - Build a WhatsApp chatbot that handles food orders through natural conversation. ([Source](https://github.com/VoltAgent/voltagent/tree/main/examples/with-whatsapp)) +- **[YouTube to Blog Agent](https://voltagent.dev/examples/agents/youtube-blog-agent)** - Convert YouTube videos into Markdown blog posts using a supervisor agent with MCP tools. ([Source](https://github.com/VoltAgent/voltagent/tree/main/examples/with-youtube-to-blog)) +- **[AI Ads Generator Agent](https://voltagent.dev/examples/agents/ai-instagram-ad-agent)** - Generate Instagram ads using BrowserBase Stagehand and Google Gemini AI. ([Source](https://github.com/VoltAgent/voltagent/tree/main/examples/with-ad-creator)) +- **[AI Recipe Generator Agent](https://voltagent.dev/examples/agents/recipe-generator)** - Create personalized cooking suggestions based on ingredients and preferences. ([Source](https://github.com/VoltAgent/voltagent/tree/main/examples/with-recipe-generator) | [Video](https://youtu.be/KjV1c6AhlfY)) +- **[AI Research Assistant Agent](https://voltagent.dev/examples/agents/research-assistant)** - Multi-agent research workflow for generating comprehensive reports. ([Source](https://github.com/VoltAgent/voltagent/tree/main/examples/with-research-assistant) | [Video](https://youtu.be/j6KAUaoZMy4)) + +

VoltOps Console: LLM Observability - Automation - Deployment

+ +VoltOps Console is the platform side of VoltAgent, providing observability, automation, and deployment so you can monitor and debug agents in production with real-time execution traces, performance metrics, and visual dashboards. + +🎬 [Try Live Demo](https://console.voltagent.dev/demo) + +📖 [VoltOps Documentation](https://voltagent.dev/voltops-llm-observability-docs/) + +🚀 [VoltOps Platform](https://voltagent.dev/voltops-llm-observability/) + +### Observability & Tracing + +Deep dive into agent execution flow with detailed traces and performance metrics. + +1 + +### Dashboard + +Get a comprehensive overview of all your agents, workflows, and system performance metrics. + +dashboar + +### Logs + +Track detailed execution logs for every agent interaction and workflow step. + +![VoltOps Logs](https://cdn.voltagent.dev/console/logs.png) + +### Memory Management + +Inspect and manage agent memory, context, and conversation history. + +![VoltOps Memory Overview](https://cdn.voltagent.dev/console/memory.png) + +### Traces + +Analyze complete execution traces to understand agent behavior and optimize performance. + +![VoltOps Traces](https://cdn.voltagent.dev/console/traces.png) + +### Prompt Builder + +Design, test, and refine prompts directly in the console. + +prompts + +### Deployment + +Deploy your agents to production with one-click GitHub integration and managed infrastructure. + +deployment + +📖 [VoltOps Deploy Documentation](https://voltagent.dev/docs/deployment/voltops/) + +### Triggers & Actions + +Automate agent workflows with webhooks, schedules, and custom triggers to react to external events. + +triggers + +### Monitoring + +Monitor agent health, performance metrics, and resource usage across your entire system. + +monitoring + +### Guardrails + +Set up safety boundaries and content filters to ensure agents operate within defined parameters. + +guardrails + +### Evals + +Run evaluation suites to test agent behavior, accuracy, and performance against benchmarks. + +evals + +### RAG (Knowledge Base) + +Connect your agents to knowledge sources with built-in retrieval-augmented generation capabilities. + +rag ## Learning VoltAgent +- **[Start with interactive tutorial](https://voltagent.dev/tutorial/introduction/)** to learn the fundamentals building AI Agents. - **[Documentation](https://voltagent.dev/docs/)**: Dive into guides, concepts, and tutorials. - **[Examples](https://github.com/voltagent/voltagent/tree/main/examples)**: Explore practical implementations. - **[Blog](https://voltagent.dev/blog/)**: Read more about technical insights, and best practices. @@ -216,10 +364,8 @@ Big thanks to everyone who's been part of the VoltAgent journey, whether you've VoltAgent is a community effort, and it keeps getting better because of people like you. -![Contributors](https://contrib.rocks/image?repo=voltagent/voltagent) - -Your stars help us reach more developers! If you find VoltAgent useful, please consider giving us a star on GitHub to support the project and help others discover it. +![Contributors](https://contrib.rocks/image?repo=voltagent/voltagent&max=500&columns=20&anon=1) ## License -Licensed under the MIT License, Copyright © 2025-present VoltAgent. +Licensed under the MIT License, Copyright © 2026-present VoltAgent. diff --git a/announcements.json b/announcements.json new file mode 100644 index 000000000..8809897fd --- /dev/null +++ b/announcements.json @@ -0,0 +1,22 @@ +{ + "announcements": [ + { + "id": "2024-12-09-deployments", + "date": "2024-12-09", + "title": "Introducing VoltOps Deployments", + "description": "Deploy your AI agents to production with one click. Connect your GitHub repo and let VoltOps handle the rest.", + "url": "https://console.voltagent.dev/deployments", + "version": "1.0.0", + "enabled": true + }, + { + "id": "2025-12-19-voltagent-rag", + "date": "2025-12-19", + "title": "VoltAgent RAG Is Live", + "description": "VoltAgent Knowledge Base is live. Upload documents, preview chunks, and use managed RAG in your agents.", + "url": "https://voltagent.dev/docs/rag/voltagent/", + "version": "1.2.20", + "enabled": true + } + ] +} diff --git a/archive/deprecated-providers/anthropic-ai/package.json b/archive/deprecated-providers/anthropic-ai/package.json index 7e6603053..cd1b7ce23 100644 --- a/archive/deprecated-providers/anthropic-ai/package.json +++ b/archive/deprecated-providers/anthropic-ai/package.json @@ -45,5 +45,10 @@ "test": "vitest", "test:coverage": "vitest run --coverage" }, + "repository": { + "type": "git", + "url": "https://github.com/VoltAgent/voltagent.git", + "directory": "archive/deprecated-providers/anthropic-ai" + }, "types": "dist/index.d.ts" } diff --git a/archive/deprecated-providers/google-ai/package.json b/archive/deprecated-providers/google-ai/package.json index 6a2a6731b..aa35af861 100644 --- a/archive/deprecated-providers/google-ai/package.json +++ b/archive/deprecated-providers/google-ai/package.json @@ -47,5 +47,10 @@ "test": "vitest", "test:coverage": "vitest run" }, + "repository": { + "type": "git", + "url": "https://github.com/VoltAgent/voltagent.git", + "directory": "archive/deprecated-providers/google-ai/" + }, "types": "dist/index.d.ts" } diff --git a/archive/deprecated-providers/groq-ai/package.json b/archive/deprecated-providers/groq-ai/package.json index 87e431047..3c017f365 100644 --- a/archive/deprecated-providers/groq-ai/package.json +++ b/archive/deprecated-providers/groq-ai/package.json @@ -46,6 +46,11 @@ "publint": "publint --strict", "test": "vitest", "test:coverage": "vitest run --coverage" + }, + "repository": { + "type": "git", + "url": "https://github.com/VoltAgent/voltagent.git", + "directory": "archive/deprecated-providers/groq-ai" }, "types": "dist/index.d.ts" } diff --git a/archive/deprecated-providers/groq-ai/src/index.ts b/archive/deprecated-providers/groq-ai/src/index.ts index 629614f8a..0b0cb466b 100644 --- a/archive/deprecated-providers/groq-ai/src/index.ts +++ b/archive/deprecated-providers/groq-ai/src/index.ts @@ -19,6 +19,29 @@ import zodToJsonSchema from "zod-to-json-schema"; import type { GroqProviderOptions } from "./types"; import { convertToolsForSDK } from "./utils"; +type GroqUsage = { + promptTokens: number; + completionTokens: number; + totalTokens: number; +}; + +type GroqStreamState = { + accumulatedText: string; + usage?: GroqUsage; + groqMessages: Groq.Chat.ChatCompletionMessageParam[]; +}; + +type GroqStreamConfig = { + model: string; + temperature: number; + maxTokens?: number; + topP?: number; + frequencyPenalty?: number; + presencePenalty?: number; + stopSequences?: string[] | string; + tools?: Groq.Chat.ChatCompletionTool[]; +}; + // Deprecation warning console.warn( "\x1b[33m⚠️ DEPRECATION WARNING: @voltagent/groq-ai is deprecated and will no longer receive updates.\x1b[0m\n" + @@ -208,6 +231,208 @@ export class GroqProvider implements LLMProvider { return null; }; + private buildStreamParams( + config: GroqStreamConfig, + messages: Groq.Chat.ChatCompletionMessageParam[], + includeTools: boolean, + ) { + return { + model: config.model, + messages, + temperature: config.temperature, + max_tokens: config.maxTokens, + top_p: config.topP, + frequency_penalty: config.frequencyPenalty, + presence_penalty: config.presencePenalty, + stop: config.stopSequences, + stream: true, + ...(includeTools ? { tools: config.tools } : {}), + }; + } + + private updateUsageFromChunk( + chunk: Groq.Chat.ChatCompletionChunk, + currentUsage: GroqUsage | undefined, + ): GroqUsage | undefined { + if (chunk.x_groq?.usage) { + return { + promptTokens: chunk.x_groq.usage.prompt_tokens, + completionTokens: chunk.x_groq.usage.completion_tokens, + totalTokens: chunk.x_groq.usage.total_tokens, + }; + } + return currentUsage; + } + + private async emitTextChunk( + content: string, + controller: ReadableStreamDefaultController, + options: StreamTextOptions, + state: GroqStreamState, + ): Promise { + if (!content) { + return; + } + + state.accumulatedText += content; + controller.enqueue(content); + + if (options.onChunk) { + const step = { + id: "", + type: "text" as const, + content, + role: "assistant" as MessageRole, + }; + await options.onChunk(step); + } + } + + private async executeToolCalls( + toolCalls: Array, + tools: NonNullable["tools"]>, + options: StreamTextOptions, + usage: GroqUsage | undefined, + groqMessages: Groq.Chat.ChatCompletionMessageParam[], + ): Promise> { + const toolResults: Array<{ toolCallId: string; name: string; output: any }> = []; + + for (const toolCall of toolCalls) { + const step = this.createStepFromChunk({ + type: "tool-call", + toolCallId: toolCall.id, + toolName: toolCall.function?.name, + args: toolCall.function?.arguments, + usage, + }); + if (step && options.onChunk) await options.onChunk(step); + if (step && options.onStepFinish) await options.onStepFinish(step); + + const functionName = toolCall.function?.name; + const functionToCall = tools.find((toolItem) => functionName === toolItem.name)?.execute; + const functionArgs = JSON.parse( + toolCall.function?.arguments ? toolCall.function?.arguments : "{}", + ); + if (functionToCall === undefined) { + throw new Error(`Function ${functionName} not found in tools`); + } + const functionResponse = await functionToCall(functionArgs); + if (functionResponse === undefined) { + throw new Error(`Function ${functionName} returned undefined`); + } + toolResults.push({ + toolCallId: toolCall.id, + name: functionName, + output: functionResponse, + }); + + groqMessages.push({ + tool_call_id: toolCall.id ? toolCall.id : "", + role: "tool", + content: JSON.stringify(functionResponse), + }); + } + + return toolResults; + } + + private async emitToolResults( + toolResults: Array<{ toolCallId: string; name: string; output: any }>, + options: StreamTextOptions, + usage: GroqUsage | undefined, + ): Promise { + if (toolResults.length === 0) { + return; + } + + for (const toolResult of toolResults) { + const step = this.createStepFromChunk({ + type: "tool-result", + toolCallId: toolResult.toolCallId, + toolName: toolResult.name, + result: toolResult.output, + usage, + }); + if (step && options.onChunk) await options.onChunk(step); + if (step && options.onStepFinish) await options.onStepFinish(step); + } + } + + private async processStreamChunk(params: { + chunk: Groq.Chat.ChatCompletionChunk; + controller: ReadableStreamDefaultController; + options: StreamTextOptions; + state: GroqStreamState; + streamConfig: GroqStreamConfig; + }): Promise { + const { chunk, controller, options, state, streamConfig } = params; + const content = chunk.choices[0]?.delta?.content || ""; + await this.emitTextChunk(content, controller, options, state); + state.usage = this.updateUsageFromChunk(chunk, state.usage); + + const toolCalls = chunk.choices[0]?.delta?.tool_calls || []; + if (toolCalls.length === 0 || !options.tools) { + return; + } + + const toolResults = await this.executeToolCalls( + toolCalls, + options.tools, + options, + state.usage, + state.groqMessages, + ); + await this.emitToolResults(toolResults, options, state.usage); + + const secondStream = await this.groq.chat.completions.create( + this.buildStreamParams(streamConfig, state.groqMessages, false), + ); + + for await (const followUpChunk of secondStream) { + const followUpContent = followUpChunk.choices[0]?.delta?.content || ""; + await this.emitTextChunk(followUpContent, controller, options, state); + state.usage = this.updateUsageFromChunk(followUpChunk, state.usage); + } + } + + private async runTextStreamProcessing(params: { + stream: AsyncIterable; + controller: ReadableStreamDefaultController; + options: StreamTextOptions; + state: GroqStreamState; + streamConfig: GroqStreamConfig; + }): Promise { + const { stream, controller, options, state, streamConfig } = params; + for await (const chunk of stream) { + await this.processStreamChunk({ chunk, controller, options, state, streamConfig }); + } + + controller.close(); + await this.finalizeTextStream(options, state); + } + + private async finalizeTextStream( + options: StreamTextOptions, + state: GroqStreamState, + ): Promise { + if (options.onFinish) { + await options.onFinish({ + text: state.accumulatedText, + }); + } + + if (options.onStepFinish && state.accumulatedText) { + const textStep = { + id: "", + type: "text" as const, + content: state.accumulatedText, + role: "assistant" as MessageRole, + usage: state.usage, + }; + await options.onStepFinish(textStep); + } + } + generateText = async ( options: GenerateTextOptions, ): Promise> => { @@ -372,184 +597,38 @@ export class GroqProvider implements LLMProvider { } = options.provider || {}; // Create stream from Groq API - const stream = await this.groq.chat.completions.create({ + const streamConfig: GroqStreamConfig = { model: options.model, - messages: groqMessages, temperature, - max_tokens: maxTokens, - top_p: topP, - frequency_penalty: frequencyPenalty, - presence_penalty: presencePenalty, - stop: stopSequences, + maxTokens, + topP, + frequencyPenalty, + presencePenalty, + stopSequences, tools: groqTools, - // Enable streaming - stream: true, - }); + }; + const stream = await this.groq.chat.completions.create( + this.buildStreamParams(streamConfig, groqMessages, true), + ); - let accumulatedText = ""; - let usage: { - promptTokens: number; - completionTokens: number; - totalTokens: number; + const state: GroqStreamState = { + accumulatedText: "", + usage: undefined, + groqMessages, }; - const that = this; // Preserve 'this' context for the stream processing + const provider = this; // Preserve 'this' context for the stream processing // Create a readable stream to return to the caller const textStream = createAsyncIterableStream( new ReadableStream({ async start(controller) { try { - // Process each chunk from the Groq stream - for await (const chunk of stream) { - // Extract content from the chunk - const content = chunk.choices[0]?.delta?.content || ""; - // If we have content, add it to accumulated text and emit it - if (content) { - accumulatedText += content; - controller.enqueue(content); - - // Call onChunk with text chunk - if (options.onChunk) { - const step = { - id: "", - type: "text" as const, - content, - role: "assistant" as MessageRole, - }; - await options.onChunk(step); - } - } - - if (chunk.x_groq?.usage) { - usage = { - promptTokens: chunk.x_groq?.usage.prompt_tokens, - completionTokens: chunk.x_groq?.usage.completion_tokens, - totalTokens: chunk.x_groq?.usage.total_tokens, - }; - } - - const toolCalls = chunk.choices[0]?.delta?.tool_calls || []; - const toolResults = []; - - if (toolCalls && toolCalls.length > 0 && options && options.tools) { - for (const toolCall of toolCalls) { - // Handle all tool calls - each as a separate step - const step = that.createStepFromChunk({ - type: "tool-call", - toolCallId: toolCall.id, - toolName: toolCall.function?.name, - args: toolCall.function?.arguments, - usage: usage, - }); - if (step && options.onChunk) await options.onChunk(step); - if (step && options.onStepFinish) await options.onStepFinish(step); - //Call the function with the arguments - const functionName = toolCall.function?.name; - const functionToCall = options.tools.find( - (toolItem) => functionName === toolItem.name, - )?.execute; - const functionArgs = JSON.parse( - toolCall.function?.arguments ? toolCall.function?.arguments : "{}", - ); - if (functionToCall === undefined) { - throw `Function ${functionName} not found in tools`; - } - const functionResponse = await functionToCall(functionArgs); - if (functionResponse === undefined) { - throw `Function ${functionName} returned undefined`; - } - toolResults.push({ - toolCallId: toolCall.id, - name: functionName, - output: functionResponse, - }); - - groqMessages.push({ - tool_call_id: toolCall.id ? toolCall.id : "", - role: "tool", - content: JSON.stringify(functionResponse), - }); - } - // Handle all tool results - each as a separate step - if (toolCalls && toolResults && toolResults.length > 0) { - for (const toolResult of toolResults) { - const step = that.createStepFromChunk({ - type: "tool-result", - toolCallId: toolResult.toolCallId, - toolName: toolResult.name, - result: toolResult.output, - usage: usage, - }); - if (step && options.onChunk) await options.onChunk(step); - if (step && options.onStepFinish) await options.onStepFinish(step); - } - } - // Call Groq API - const secondStream = await that.groq.chat.completions.create({ - model: options.model, - messages: groqMessages, - temperature, - max_tokens: maxTokens, - top_p: topP, - frequency_penalty: frequencyPenalty, - presence_penalty: presencePenalty, - stop: stopSequences, - stream: true, - }); - - for await (const chunk of secondStream) { - // Extract content from the chunk - const content = chunk.choices[0]?.delta?.content || ""; - // If we have content, add it to accumulated text and emit it - if (content) { - accumulatedText += content; - controller.enqueue(content); - - // Call onChunk with text chunk - if (options.onChunk) { - const step = { - id: "", - type: "text" as const, - content, - role: "assistant" as MessageRole, - }; - await options.onChunk(step); - } - } - - if (chunk.x_groq?.usage) { - usage = { - promptTokens: chunk.x_groq?.usage.prompt_tokens, - completionTokens: chunk.x_groq?.usage.completion_tokens, - totalTokens: chunk.x_groq?.usage.total_tokens, - }; - } - } - } - } - - // When stream completes, close the controller - controller.close(); - - // Call onFinish with complete result - if (options.onFinish) { - await options.onFinish({ - text: accumulatedText, - }); - } - - // Call onStepFinish with complete result if provided - if (options.onStepFinish) { - if (accumulatedText) { - const textStep = { - id: "", - type: "text" as const, - content: accumulatedText, - role: "assistant" as MessageRole, - usage, - }; - await options.onStepFinish(textStep); - } - } + await provider.runTextStreamProcessing({ + stream, + controller, + options, + state, + streamConfig, + }); } catch (error) { // Handle errors during streaming console.error("Error during Groq stream processing:", error); diff --git a/archive/deprecated-providers/vercel-ai/CHANGELOG.md b/archive/deprecated-providers/vercel-ai/CHANGELOG.md new file mode 100644 index 000000000..a5ce87a4f --- /dev/null +++ b/archive/deprecated-providers/vercel-ai/CHANGELOG.md @@ -0,0 +1,307 @@ +# @voltagent/vercel-ai + +## 1.0.0-next.0 + +### Patch Changes + +- Updated dependencies [[`64a50e6`](https://github.com/VoltAgent/voltagent/commit/64a50e6800dec844fad7b9f3a3b1c2c8d0486229), [`9e8b211`](https://github.com/VoltAgent/voltagent/commit/9e8b2119a783942f114459f0a9b93e645727445e)]: + - @voltagent/core@1.0.0-next.0 + +## 1.0.0 + +### Major Changes + +- [#462](https://github.com/VoltAgent/voltagent/pull/462) [`23ecea4`](https://github.com/VoltAgent/voltagent/commit/23ecea421b8c699f5c395dc8aed687f94d558b6c) Thanks [@omeraplak](https://github.com/omeraplak)! - Update Vercel AI SDK to v5.0.0 + + Major upgrade to Vercel AI SDK v5 with significant improvements: + + ## Package Updates + - Updated `ai` package to v5.0.0 + - Updated `@ai-sdk/provider` to v2.0.0 + - Updated `@ai-sdk/provider-utils` to v3.0.0 + - Updated all other `@ai-sdk/*` packages to v2.0.0 + - Updated peer dependency `zod` to ^3.25.0 (required by AI SDK v5) + + ## Key Changes + - **Breaking**: New provider interface with improved type safety + - **Improved Streaming**: Enhanced streaming capabilities with better error handling + - **Better TypeScript Support**: Stricter types and improved inference + - **Unified Provider API**: Consistent interface across all AI providers + - **Performance**: Optimized token usage and response handling + + ## Migration Notes + - Provider implementations updated to use new `@ai-sdk/provider` v2.0.0 interface + - Maintained backward compatibility with existing VoltAgent agent interfaces + - All streaming methods now use the improved v5 streaming protocol + - Error handling enhanced with more descriptive error types + +### Patch Changes + +- [#462](https://github.com/VoltAgent/voltagent/pull/462) [`23ecea4`](https://github.com/VoltAgent/voltagent/commit/23ecea421b8c699f5c395dc8aed687f94d558b6c) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add cachedInputTokens and reasoningTokens to UsageInfo type + + Enhanced the `UsageInfo` type to include additional token usage metrics: + - Added `cachedInputTokens?: number` to track tokens served from cache + - Added `reasoningTokens?: number` to track tokens used for model reasoning + + These optional fields provide more granular usage information when supported by the underlying LLM provider. The Vercel AI provider now passes through these values when available from the AI SDK. + +- [#462](https://github.com/VoltAgent/voltagent/pull/462) [`23ecea4`](https://github.com/VoltAgent/voltagent/commit/23ecea421b8c699f5c395dc8aed687f94d558b6c) Thanks [@omeraplak](https://github.com/omeraplak)! - Update Zod to v3.25.0 for compatibility with Vercel AI@5 + - Updated Zod dependency to ^3.25.0 across all packages + - Maintained compatibility with zod-from-json-schema@0.0.5 + - Fixed TypeScript declaration build hanging issue + - Resolved circular dependency issues in the build process + +## 0.1.18 + +### Patch Changes + +- [#475](https://github.com/VoltAgent/voltagent/pull/475) [`9b4ea38`](https://github.com/VoltAgent/voltagent/commit/9b4ea38b28df248c1e1ad5541d414bd47838df9a) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: Remove other potentially problematic `JSON.stringify` usages + +## 0.1.17 + +### Patch Changes + +- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements + + This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + + **Key improvements:** + - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs + - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration + - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries + - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup + - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + + These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. + +## 0.1.16 + +### Patch Changes + +- [#425](https://github.com/VoltAgent/voltagent/pull/425) [`8605e70`](https://github.com/VoltAgent/voltagent/commit/8605e708d17e6fa0150bd13235e795288422c52b) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add Promise-based properties and warnings to AI responses - #422 + + Enhanced AI response types to align with Vercel AI SDK's API and provide better metadata: + + **For `streamObject`:** + - Added optional `object?: Promise` property that resolves to the final generated object + - Added optional `usage?: Promise` property that resolves to token usage information + - Added optional `warnings?: Promise` property for provider warnings + + **For `streamText`:** + - Added optional `text?: Promise` property that resolves to the full generated text + - Added optional `finishReason?: Promise` property that resolves to the reason generation stopped + - Added optional `usage?: Promise` property that resolves to token usage information + - Added optional `reasoning?: Promise` property that resolves to model's reasoning text + + **For `generateText` and `generateObject`:** + - Added optional `reasoning?: string` property for model's reasoning text (generateText only) + - Added optional `warnings?: any[]` property for provider warnings + + These properties are optional to maintain backward compatibility. Providers that support these features (like Vercel AI) now return these values, allowing users to access rich metadata: + + ```typescript + // For streamObject + const response = await agent.streamObject(input, schema); + const finalObject = await response.object; // Promise + const usage = await response.usage; // Promise + + // For streamText + const response = await agent.streamText(input); + const fullText = await response.text; // Promise + const usage = await response.usage; // Promise + + // For generateText + const response = await agent.generateText(input); + console.log(response.warnings); // Any provider warnings + console.log(response.reasoning); // Model's reasoning (if available) + ``` + +- Updated dependencies [[`8605e70`](https://github.com/VoltAgent/voltagent/commit/8605e708d17e6fa0150bd13235e795288422c52b)]: + - @voltagent/core@0.1.69 + +## 0.1.15 + +### Patch Changes + +- [`1f8ce22`](https://github.com/VoltAgent/voltagent/commit/1f8ce226fec449f16f1dce6c2b96cef7030eff3a) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: zod peer dependency to allow flexible versioning (^3.24.2 instead of 3.24.2) to resolve npm install conflicts + +- Updated dependencies [[`1f8ce22`](https://github.com/VoltAgent/voltagent/commit/1f8ce226fec449f16f1dce6c2b96cef7030eff3a)]: + - @voltagent/core@0.1.66 + +## 0.1.14 + +### Patch Changes + +- [#401](https://github.com/VoltAgent/voltagent/pull/401) [`4a7145d`](https://github.com/VoltAgent/voltagent/commit/4a7145debd66c7b1dfb953608e400b6c1ed02db7) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve TypeScript performance issues by fixing Zod dependency configuration (#377) + + Moved Zod from direct dependencies to peer dependencies in @voltagent/vercel-ai to prevent duplicate Zod installations that were causing TypeScript server slowdowns. Also standardized Zod versions across the workspace to ensure consistency. + + Changes: + - @voltagent/vercel-ai: Moved `zod` from dependencies to peerDependencies + - @voltagent/docs-mcp: Updated `zod` from `^3.23.8` to `3.24.2` + - @voltagent/with-postgres: Updated `zod` from `^3.24.2` to `3.24.2` (removed caret) + + This fix significantly improves TypeScript language server performance by ensuring only one Zod version is processed, eliminating the "Type instantiation is excessively deep and possibly infinite" errors that users were experiencing. + +- Updated dependencies [[`57c4874`](https://github.com/VoltAgent/voltagent/commit/57c4874d4d4807c50242b2e34ab9574fc6129888), [`da66f86`](https://github.com/VoltAgent/voltagent/commit/da66f86d92a278007c2d3386d22b482fa70d93ff), [`4a7145d`](https://github.com/VoltAgent/voltagent/commit/4a7145debd66c7b1dfb953608e400b6c1ed02db7)]: + - @voltagent/core@0.1.61 + +## 0.1.13 + +### Patch Changes + +- [`8eced6d`](https://github.com/VoltAgent/voltagent/commit/8eced6dad9c688a33b4700a6fc4be34bfc3ba88b) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: resolve onStepFinishHandler issue preventing tool_calls and hooks from functioning properly + + Fixed a critical bug in the Vercel AI provider where the `onStepFinishHandler` was blocking tool calls and agent hooks from executing correctly. This issue was preventing agents from properly utilizing tools and executing lifecycle hooks during operations. + +## 0.1.12 + +### Patch Changes + +- [#251](https://github.com/VoltAgent/voltagent/pull/251) [`be0cf47`](https://github.com/VoltAgent/voltagent/commit/be0cf47ec6e9640119d752dd6b608097d06bf69d) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add fullStream support for generative UIs + + Added `fullStream` support to the Vercel AI provider for better streaming in generative UI applications. + +- Updated dependencies [[`be0cf47`](https://github.com/VoltAgent/voltagent/commit/be0cf47ec6e9640119d752dd6b608097d06bf69d), [`a3b4e60`](https://github.com/VoltAgent/voltagent/commit/a3b4e604e6f79281903ff0c28422e6ee2863b340), [`20119ad`](https://github.com/VoltAgent/voltagent/commit/20119ada182ec5f313a7f46956218d593180e096)]: + - @voltagent/core@0.1.36 + +## 0.1.11 + +### Patch Changes + +- [#226](https://github.com/VoltAgent/voltagent/pull/226) [`d879e6d`](https://github.com/VoltAgent/voltagent/commit/d879e6d41757081420162cf983223683b72b66a5) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: add toolName to tool-result steps + + Tool result steps now include the toolName field, ensuring proper identification of which tool generated each result in conversation flows and hook messages. + +## 0.1.10 + +### Patch Changes + +- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 + +- Updated dependencies [[`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f), [`80fd3c0`](https://github.com/VoltAgent/voltagent/commit/80fd3c069de4c23116540a55082b891c4b376ce6)]: + - @voltagent/core@0.1.31 + +## 0.1.9 + +### Patch Changes + +- [#155](https://github.com/VoltAgent/voltagent/pull/155) [`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c) Thanks [@baseballyama](https://github.com/baseballyama)! - chore: update `tsconfig.json`'s `target` to `ES2022` + +- [#162](https://github.com/VoltAgent/voltagent/pull/162) [`b164bd0`](https://github.com/VoltAgent/voltagent/commit/b164bd014670452cb162b388f03565db992767af) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: pin zod version to 3.24.2 to avoid "Type instantiation is excessively deep and possibly infinite" error + + Fixed compatibility issues between different zod versions that were causing TypeScript compilation errors. This issue occurs when multiple packages use different patch versions of zod (e.g., 3.23.x vs 3.24.x), leading to type instantiation depth problems. By pinning to 3.24.2, we ensure consistent behavior across all packages. + + See: https://github.com/colinhacks/zod/issues/3435 + +- Updated dependencies [[`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c), [`b164bd0`](https://github.com/VoltAgent/voltagent/commit/b164bd014670452cb162b388f03565db992767af), [`9412cf0`](https://github.com/VoltAgent/voltagent/commit/9412cf0633f20d6b77c87625fc05e9e216936758)]: + - @voltagent/core@0.1.20 + +## 0.1.7 + +### Patch Changes + +- [#102](https://github.com/VoltAgent/voltagent/pull/102) [`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3) Thanks [@omeraplak](https://github.com/omeraplak)! - refactor: use 'instructions' field for Agent definitions in examples - #88 + + Updated documentation examples (READMEs, docs, blogs) and relevant package code examples to use the `instructions` field instead of `description` when defining `Agent` instances. + + This change aligns the examples with the preferred API usage for the `Agent` class, where `instructions` provides behavioral guidance to the agent/LLM. This prepares for the eventual deprecation of the `description` field specifically for `Agent` class definitions. + + **Example Change for Agent Definition:** + + ```diff + const agent = new Agent({ + name: "My Assistant", + - description: "A helpful assistant.", + + instructions: "A helpful assistant.", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + ``` + +- Updated dependencies [[`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3)]: + - @voltagent/core@0.1.14 + +## 0.1.6 + +### Patch Changes + +- [`13db262`](https://github.com/VoltAgent/voltagent/commit/13db2621ae6b730667f9991d3c2129c85265e925) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: Update Zod to version 3.24.2 to resolve "Type instantiation is excessively deep and possibly infinite" error (related to https://github.com/colinhacks/zod/issues/3435). + +- Updated dependencies [[`f7de864`](https://github.com/VoltAgent/voltagent/commit/f7de864503d598cf7131cc01afa3779639190107), [`13db262`](https://github.com/VoltAgent/voltagent/commit/13db2621ae6b730667f9991d3c2129c85265e925)]: + - @voltagent/core@0.1.13 + +## 0.1.5 + +### Patch Changes + +- [#77](https://github.com/VoltAgent/voltagent/pull/77) [`beaa8fb`](https://github.com/VoltAgent/voltagent/commit/beaa8fb1f1bc6351f1bede0b65a6a189cc1b6ea2) Thanks [@omeraplak](https://github.com/omeraplak)! - **API & Providers:** Standardized message content format for array inputs. + - The API (`/text`, `/stream`, `/object`, `/stream-object` endpoints) now strictly expects the `content` field within message objects (when `input` is an array) to be either a `string` or an `Array` of content parts (e.g., `[{ type: 'text', text: '...' }]`). + - The previous behavior of allowing a single content object (e.g., `{ type: 'text', ... }`) directly as the value for `content` in message arrays is no longer supported in the API schema. Raw string inputs remain unchanged. + - Provider logic (`google-ai`, `groq-ai`, `xsai`) updated to align with this stricter definition. + + **Console:** + - **Added file and image upload functionality to the Assistant Chat.** Users can now attach multiple files/images via a button, preview attachments, and send them along with text messages. + - Improved the Assistant Chat resizing: Replaced size toggle buttons with a draggable handle (top-left corner). + - Chat window dimensions are now saved to local storage and restored on reload. + + **Internal:** + - Added comprehensive test suites for Groq and XsAI providers. + +- Updated dependencies [[`beaa8fb`](https://github.com/VoltAgent/voltagent/commit/beaa8fb1f1bc6351f1bede0b65a6a189cc1b6ea2)]: + - @voltagent/core@0.1.10 + +## 0.1.4 + +### Patch Changes + +- [#71](https://github.com/VoltAgent/voltagent/pull/71) [`1f20509`](https://github.com/VoltAgent/voltagent/commit/1f20509528fc2cb2ba00f86d649848afae34af04) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: Standardize Agent Error and Finish Handling + + This change introduces a more robust and consistent way errors and successful finishes are handled across the `@voltagent/core` Agent and LLM provider implementations (like `@voltagent/vercel-ai`). + + **Key Improvements:** + - **Standardized Errors (`VoltAgentError`):** + - Introduced `VoltAgentError`, `ToolErrorInfo`, and `StreamOnErrorCallback` types in `@voltagent/core`. + - LLM Providers (e.g., Vercel) now wrap underlying SDK/API errors into a structured `VoltAgentError` before passing them to `onError` callbacks or throwing them. + - Agent methods (`generateText`, `streamText`, `generateObject`, `streamObject`) now consistently handle `VoltAgentError`, enabling richer context (stage, code, tool details) in history events and logs. + + - **Standardized Stream Finish Results:** + - Introduced `StreamTextFinishResult`, `StreamTextOnFinishCallback`, `StreamObjectFinishResult`, and `StreamObjectOnFinishCallback` types in `@voltagent/core`. + - LLM Providers (e.g., Vercel) now construct these standardized result objects upon successful stream completion. + - Agent streaming methods (`streamText`, `streamObject`) now receive these standardized results in their `onFinish` handlers, ensuring consistent access to final output (`text` or `object`), `usage`, `finishReason`, etc., for history, events, and hooks. + + - **Updated Interfaces:** The `LLMProvider` interface and related options types (`StreamTextOptions`, `StreamObjectOptions`) have been updated to reflect these new standardized callback types and error-throwing expectations. + + These changes lead to more predictable behavior, improved debugging capabilities through structured errors, and a more consistent experience when working with different LLM providers. + +- Updated dependencies [[`1f20509`](https://github.com/VoltAgent/voltagent/commit/1f20509528fc2cb2ba00f86d649848afae34af04), [`1f20509`](https://github.com/VoltAgent/voltagent/commit/1f20509528fc2cb2ba00f86d649848afae34af04), [`7a7a0f6`](https://github.com/VoltAgent/voltagent/commit/7a7a0f672adbe42635c3edc5f0a7f282575d0932)]: + - @voltagent/core@0.1.9 + +## 0.1.3 + +### Patch Changes + +- [#33](https://github.com/VoltAgent/voltagent/pull/33) [`3ef2eaa`](https://github.com/VoltAgent/voltagent/commit/3ef2eaa9661e8ecfebf17af56b09af41285d0ca9) Thanks [@kwaa](https://github.com/kwaa)! - Update package.json files: + - Remove `src` directory from the `files` array. + - Add explicit `exports` field for better module resolution. + +- Updated dependencies [[`52d5fa9`](https://github.com/VoltAgent/voltagent/commit/52d5fa94045481dc43dc260a40b701606190585c), [`3ef2eaa`](https://github.com/VoltAgent/voltagent/commit/3ef2eaa9661e8ecfebf17af56b09af41285d0ca9), [`52d5fa9`](https://github.com/VoltAgent/voltagent/commit/52d5fa94045481dc43dc260a40b701606190585c)]: + - @voltagent/core@0.1.6 + +## 0.1.1 + +- 🚀 **Introducing VoltAgent: TypeScript AI Agent Framework!** + + This initial release marks the beginning of VoltAgent, a powerful toolkit crafted for the JavaScript developer community. We saw the challenges: the complexity of building AI from scratch, the limitations of No-Code tools, and the lack of first-class AI tooling specifically for JS. + + ![VoltAgent Demo](https://cdn.voltagent.dev/readme/demo.gif) + VoltAgent aims to fix that by providing the building blocks you need: + - **`@voltagent/core`**: The foundational engine for agent capabilities. + - **`@voltagent/voice`**: Easily add voice interaction. + - **`@voltagent/vercel-ai`**: Seamless integration with [Vercel AI SDK](https://sdk.vercel.ai/docs/introduction). + - **`@voltagent/xsai`**: A Seamless integration with [xsAI](https://xsai.js.org/). + - **`@voltagent/cli` & `create-voltagent-app`**: Quick start tools to get you building _fast_. + + We're combining the flexibility of code with the clarity of visual tools (like our **currently live [VoltOps LLM Observability Platform](https://console.voltagent.dev/)**) to make AI development easier, clearer, and more powerful. Join us as we build the future of AI in JavaScript! + + Explore the [Docs](https://voltagent.dev/docs/) and join our [Discord community](https://s.voltagent.dev/discord)! diff --git a/packages/vercel-ai/README.md b/archive/deprecated-providers/vercel-ai/README.md similarity index 100% rename from packages/vercel-ai/README.md rename to archive/deprecated-providers/vercel-ai/README.md diff --git a/packages/vercel-ai/biome.json b/archive/deprecated-providers/vercel-ai/biome.json similarity index 100% rename from packages/vercel-ai/biome.json rename to archive/deprecated-providers/vercel-ai/biome.json diff --git a/archive/deprecated-providers/vercel-ai/package.json b/archive/deprecated-providers/vercel-ai/package.json new file mode 100644 index 000000000..163c3ee25 --- /dev/null +++ b/archive/deprecated-providers/vercel-ai/package.json @@ -0,0 +1,59 @@ +{ + "name": "@voltagent/vercel-ai", + "description": "VoltAgent Vercel AI - Vercel AI provider integration for VoltAgent", + "version": "1.0.0-next.0", + "dependencies": { + "@ai-sdk/openai": "^2.0.2", + "ai": "^5.0.76", + "ts-pattern": "^5.7.1", + "type-fest": "^4.41.0" + }, + "devDependencies": { + "@types/node": "^24.2.1", + "@vitest/coverage-v8": "^3.2.4", + "@voltagent/core": "^1.0.0-next.0", + "@voltagent/internal": "^0.0.9", + "tsup": "^8.5.0", + "typescript": "^5.8.2", + "vitest": "^3.2.4", + "zod": "^3.25.0" + }, + "exports": { + ".": { + "import": { + "types": "./dist/index.d.mts", + "default": "./dist/index.mjs" + }, + "require": { + "types": "./dist/index.d.ts", + "default": "./dist/index.js" + } + } + }, + "files": [ + "dist" + ], + "license": "MIT", + "main": "dist/index.js", + "module": "dist/index.mjs", + "peerDependencies": { + "@voltagent/core": "^1.0.0-next.0", + "zod": "^3.25.0" + }, + "scripts": { + "attw": "attw --pack", + "build": "tsup", + "dev": "tsup --watch", + "lint": "biome check .", + "lint:fix": "biome check . --write", + "publint": "publint --strict", + "test": "vitest", + "test:coverage": "vitest run --coverage" + }, + "repository": { + "type": "git", + "url": "https://github.com/VoltAgent/voltagent.git", + "directory": "archive/deprecated-providers/vercel-ai" + }, + "types": "dist/index.d.ts" +} diff --git a/packages/vercel-ai/src/index.ts b/archive/deprecated-providers/vercel-ai/src/index.ts similarity index 100% rename from packages/vercel-ai/src/index.ts rename to archive/deprecated-providers/vercel-ai/src/index.ts diff --git a/packages/vercel-ai/src/provider-custom.spec.ts b/archive/deprecated-providers/vercel-ai/src/provider-custom.spec.ts similarity index 100% rename from packages/vercel-ai/src/provider-custom.spec.ts rename to archive/deprecated-providers/vercel-ai/src/provider-custom.spec.ts diff --git a/packages/vercel-ai/src/provider.spec.ts b/archive/deprecated-providers/vercel-ai/src/provider.spec.ts similarity index 100% rename from packages/vercel-ai/src/provider.spec.ts rename to archive/deprecated-providers/vercel-ai/src/provider.spec.ts diff --git a/packages/vercel-ai/src/provider.ts b/archive/deprecated-providers/vercel-ai/src/provider.ts similarity index 100% rename from packages/vercel-ai/src/provider.ts rename to archive/deprecated-providers/vercel-ai/src/provider.ts diff --git a/packages/vercel-ai/src/testing.ts b/archive/deprecated-providers/vercel-ai/src/testing.ts similarity index 100% rename from packages/vercel-ai/src/testing.ts rename to archive/deprecated-providers/vercel-ai/src/testing.ts diff --git a/packages/vercel-ai/src/utils.spec.ts b/archive/deprecated-providers/vercel-ai/src/utils.spec.ts similarity index 100% rename from packages/vercel-ai/src/utils.spec.ts rename to archive/deprecated-providers/vercel-ai/src/utils.spec.ts diff --git a/packages/vercel-ai/src/utils.ts b/archive/deprecated-providers/vercel-ai/src/utils.ts similarity index 100% rename from packages/vercel-ai/src/utils.ts rename to archive/deprecated-providers/vercel-ai/src/utils.ts diff --git a/packages/vercel-ai/tsconfig.json b/archive/deprecated-providers/vercel-ai/tsconfig.json similarity index 100% rename from packages/vercel-ai/tsconfig.json rename to archive/deprecated-providers/vercel-ai/tsconfig.json diff --git a/packages/vercel-ai/tsup.config.ts b/archive/deprecated-providers/vercel-ai/tsup.config.ts similarity index 100% rename from packages/vercel-ai/tsup.config.ts rename to archive/deprecated-providers/vercel-ai/tsup.config.ts diff --git a/packages/vercel-ai/vitest.config.mts b/archive/deprecated-providers/vercel-ai/vitest.config.mts similarity index 100% rename from packages/vercel-ai/vitest.config.mts rename to archive/deprecated-providers/vercel-ai/vitest.config.mts diff --git a/archive/deprecated-providers/vercel-ui/CHANGELOG.md b/archive/deprecated-providers/vercel-ui/CHANGELOG.md new file mode 100644 index 000000000..3ba8854d7 --- /dev/null +++ b/archive/deprecated-providers/vercel-ui/CHANGELOG.md @@ -0,0 +1,323 @@ +# @voltagent/vercel-ui + +## 1.0.0-next.0 + +### Patch Changes + +- Updated dependencies [[`64a50e6`](https://github.com/VoltAgent/voltagent/commit/64a50e6800dec844fad7b9f3a3b1c2c8d0486229), [`9e8b211`](https://github.com/VoltAgent/voltagent/commit/9e8b2119a783942f114459f0a9b93e645727445e)]: + - @voltagent/core@1.0.0-next.0 + +## 1.0.0 + +### Major Changes + +- [#462](https://github.com/VoltAgent/voltagent/pull/462) [`23ecea4`](https://github.com/VoltAgent/voltagent/commit/23ecea421b8c699f5c395dc8aed687f94d558b6c) Thanks [@omeraplak](https://github.com/omeraplak)! - feat!: Migrate from AI SDK v4 to v5 with new adapter pattern + + ## Breaking Changes + - **Removed all v4 exports and utilities**: + - `convertToUIMessages()` - Message conversion utility + - `toDataStream()`, `mergeIntoDataStream()`, `formatDataStreamPart()` - Data stream utilities + - `filterUIMessageParts` (alias: `rejectUIMessageParts`) - Message filtering + - `isSubAgent` (alias: `isSubAgentStreamPart`) - Guard utilities + - Type exports: `UIMessage`, `UIMessagePart`, `ToolInvocationUIPart`, `DataStream`, `DataStreamString`, `DataStreamOptions` + - **Upgraded from AI SDK v4 (^4.3.16) to v5 (^5.0.8)** + + ## New Features + - **New adapter pattern** following LangChain/LlamaIndex conventions: + - `toUIMessageStream(stream, callbacks?)` - Converts VoltAgent's `StreamPart` to AI SDK v5's `UIMessageChunk` + - `toDataStreamResponse(stream, options?)` - Creates HTTP Response for Next.js API routes + - `StreamCallbacks` type for stream event handling + - **Full AI SDK v5 compatibility**: + - Proper `UIMessageChunk` streaming + - Support for reasoning-delta chunks (start/delta/end pattern) + - Tool call and result streaming with dynamic tool names + - Text streaming with proper start/end events + - SubAgent metadata via `data-subagent` chunks + + ## Migration Guide + + ### Data Stream Usage + + Before (v4): + + ```typescript + import { toDataStream, mergeIntoDataStream } from "@voltagent/vercel-ui"; + + // Direct stream conversion + const stream = toDataStream(result.fullStream, { + sendUsage: true, + sendReasoning: false, + }); + + // Or merging into existing stream + mergeIntoDataStream(writer, result.fullStream); + ``` + + After (v5): + + ```typescript + import { toDataStreamResponse } from "@voltagent/vercel-ui"; + + // Direct HTTP response + return toDataStreamResponse(result.fullStream); + + // Or with manual stream handling + import { toUIMessageStream } from "@voltagent/vercel-ui"; + const uiStream = toUIMessageStream(result.fullStream); + ``` + + ### Message Conversion + + Before (v4): + + ```typescript + import { convertToUIMessages } from "@voltagent/vercel-ui"; + + const uiMessages = convertToUIMessages(operationContext); + ``` + + After (v5): + + ```typescript + // Message conversion is now handled by AI SDK v5's built-in utilities + import { convertToModelMessages } from "ai"; + + const modelMessages = convertToModelMessages(messages); + ``` + + ### Type Imports + + Before (v4): + + ```typescript + import type { UIMessage, UIMessagePart } from "@voltagent/vercel-ui"; + ``` + + After (v5): + + ```typescript + import type { UIMessage, UIMessagePart } from "ai"; + ``` + +### Patch Changes + +- [#462](https://github.com/VoltAgent/voltagent/pull/462) [`23ecea4`](https://github.com/VoltAgent/voltagent/commit/23ecea421b8c699f5c395dc8aed687f94d558b6c) Thanks [@omeraplak](https://github.com/omeraplak)! - Update Zod to v3.25.0 for compatibility with Vercel AI@5 + - Updated Zod dependency to ^3.25.0 across all packages + - Maintained compatibility with zod-from-json-schema@0.0.5 + - Fixed TypeScript declaration build hanging issue + - Resolved circular dependency issues in the build process + +## 0.1.10 + +### Patch Changes + +- Updated dependencies [[`5968cef`](https://github.com/VoltAgent/voltagent/commit/5968cef5fe417cd118867ac78217dddfbd60493d)]: + - @voltagent/internal@0.0.9 + +## 0.1.9 + +### Patch Changes + +- Updated dependencies [[`8de5785`](https://github.com/VoltAgent/voltagent/commit/8de5785e385bec632f846bcae44ee5cb22a9022e)]: + - @voltagent/internal@0.0.8 + +## 0.1.8 + +### Patch Changes + +- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements + + This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + + **Key improvements:** + - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs + - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration + - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries + - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup + - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + + These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. + +- Updated dependencies [[`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5)]: + - @voltagent/internal@0.0.7 + +## 0.1.7 + +### Patch Changes + +- [#404](https://github.com/VoltAgent/voltagent/pull/404) [`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: remove devLogger dependency and use native console methods + + Removed the dependency on `@voltagent/internal/dev` logger and replaced devLogger calls with standard console methods (console.error, console.warn) for a cleaner dependency tree and better compatibility. + +- Updated dependencies [[`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726), [`809bd13`](https://github.com/VoltAgent/voltagent/commit/809bd13c5fce7b2afdb0f0d934cc5a21d3e77726)]: + - @voltagent/internal@0.0.6 + - @voltagent/core@0.1.65 + +## 0.1.6 + +### Patch Changes + +- Updated dependencies [[`6fadbb0`](https://github.com/VoltAgent/voltagent/commit/6fadbb098fe40d8b658aa3386e6126fea155f117)]: + - @voltagent/internal@0.0.5 + - @voltagent/core@0.1.62 + +## 0.1.5 + +### Patch Changes + +- [#354](https://github.com/VoltAgent/voltagent/pull/354) [`5bfb1e2`](https://github.com/VoltAgent/voltagent/commit/5bfb1e22162cb69aed0d333072237c68b705f6c0) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: Fixed passing along an ID of empty string + +## 0.1.4 + +### Patch Changes + +- Updated dependencies [[`8da1ecc`](https://github.com/VoltAgent/voltagent/commit/8da1eccd0332d1f9037085e16cb0b7d5afaac479), [`8da1ecc`](https://github.com/VoltAgent/voltagent/commit/8da1eccd0332d1f9037085e16cb0b7d5afaac479), [`8da1ecc`](https://github.com/VoltAgent/voltagent/commit/8da1eccd0332d1f9037085e16cb0b7d5afaac479)]: + - @voltagent/core@0.1.49 + - @voltagent/internal@0.0.4 + +## 0.1.3 + +### Patch Changes + +- [#311](https://github.com/VoltAgent/voltagent/pull/311) [`1f7fa14`](https://github.com/VoltAgent/voltagent/commit/1f7fa140fcc4062fe85220e61f276e439392b0b4) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix(core, vercel-ui): Currently the `convertToUIMessages` function does not handle tool calls in steps correctly as it does not properly default filter non-tool related steps for sub-agents, same as the `data-stream` functions and in addition in the core the `operationContext` does not have the `subAgent` fields set correctly. + + ### Changes + - deprecated `isSubAgentStreamPart` in favor of `isSubAgent` for universal use + - by default `convertToUIMessages` now filters out non-tool related steps for sub-agents + - now able to exclude specific parts or steps (from OperationContext) in `convertToUIMessages` + + *** + + ### Internals + + New utils were added to the internal package: + - `isObject` + - `isFunction` + - `isPlainObject` + - `isEmptyObject` + - `isNil` + - `hasKey` + +- Updated dependencies [[`1f7fa14`](https://github.com/VoltAgent/voltagent/commit/1f7fa140fcc4062fe85220e61f276e439392b0b4)]: + - @voltagent/internal@0.0.3 + - @voltagent/core@0.1.47 + +## 0.1.2 + +### Patch Changes + +- [#302](https://github.com/VoltAgent/voltagent/pull/302) [`1e1f563`](https://github.com/VoltAgent/voltagent/commit/1e1f563aeb9ac25880ca56a33285abca0b24b389) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - Fix to match the output of `mergeIntoDataStream` and `convertToUIMessages` as the `mergeIntoDataStream` filters out the `SubAgent` prefix of a `toolName` (i.e. `BlogReader: read-blog-post`). `convertToUIMessages` was not filtering out the `SubAgent` prefix by default and it was causing the `toolName` to be different on the server in the `onEnd` hook from whats being sent to the client (and expected by the developer). + +- Updated dependencies [[`33afe6e`](https://github.com/VoltAgent/voltagent/commit/33afe6ef40ef56c501f7fa69be42da730f87d29d), [`b8529b5`](https://github.com/VoltAgent/voltagent/commit/b8529b53313fa97e941ecacb8c1555205de49c19)]: + - @voltagent/core@0.1.45 + +## 0.1.1 + +### Patch Changes + +- Updated dependencies [[`94de46a`](https://github.com/VoltAgent/voltagent/commit/94de46ab2b7ccead47a539e93c72b357f17168f6)]: + - @voltagent/internal@0.0.2 + - @voltagent/core@0.1.44 + +## 0.1.0 + +### Minor Changes + +- [#273](https://github.com/VoltAgent/voltagent/pull/273) [`12b8c90`](https://github.com/VoltAgent/voltagent/commit/12b8c9025488e1d6f4b5a99d74b639bf202ba7d2) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - Added a set of new utility functions for working with data streams in the vercel `ai` package. + + ## New Functions + + ### `toDataStream` + + You can use this function to convert a VoltAgent `ReadableStream` to a `DataStream`. + + ```typescript + const result = await agent.streamText("Hello, world!"); + const dataStream = toDataStream(result.fullStream); + ``` + + ### `mergeIntoDataStream` + + You can use this function to merge a VoltAgent `ReadableStream` into a `DataStream` using the vercel `createDataStream` function. + + ```typescript + const result = await agent.streamText("Hello, world!"); + + const dataStream = createDataStream({ + execute: async (writer) => { + const result = await agent.streamText("Hello, world!"); + mergeIntoDataStream(writer, result.fullStream); + }, + }); + + reply.send(dataStream); + ``` + + ### `formatDataStreamPart` + + You can use this function to format a data stream part for the vercel `ai` package to be used in the `DataStream` interface, this appends certain metadata for VoltAgent. + + ```typescript + const result = await agent.streamText("Hello, world!"); + + const dataStream = toDataStream(result.fullStream); + + // This will append subAgentId and subAgentName to the data stream part + ``` + + ### `isSubAgentStreamPart` + + You can use this function to check if a data stream part is a sub-agent stream part. + + ```typescript + import { isSubAgentStreamPart } from "@voltagent/vercel-ui"; + + const messages = useChat(...); + + for (const message of messages) { + if (isSubAgentStreamPart(message)) { + // This is a sub-agent stream part + // NOTE: This will ONLY work for Tool calls and results and not other stream parts + console.log(message.subAgentId, message.subAgentName); + } + } + ``` + + ## New Types + + Additional types have been exposed to make it easier to improve types with the vercel `ai` package. + - `UIMessage` - A VoltAgent ready `UIMessage` type, this is a wrapper around the vercel `UIMessage` type. + - `DataStream` - A VoltAgent ready `DataStream` type, this is a wrapper around the vercel `DataStream` type. + +### Patch Changes + +- Updated dependencies [[`73632ea`](https://github.com/VoltAgent/voltagent/commit/73632ea229917ab4042bb58b61d5e6dbd9b72804)]: + - @voltagent/core@0.1.42 + +## 0.0.2 + +### Patch Changes + +- [#226](https://github.com/VoltAgent/voltagent/pull/226) [`d879e6d`](https://github.com/VoltAgent/voltagent/commit/d879e6d41757081420162cf983223683b72b66a5) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - feat: add Vercel UI SDK integration package for converting the `OperationContext` to a list of messages that can be used with the Vercel AI SDK + + Added `convertToUIMessages` function to the `@voltagent/vercel-ui` package that converts the `OperationContext` to a list of messages that can be used with the Vercel AI SDK. + + ```ts + import { convertToUIMessages } from "@voltagent/vercel-ui"; + import { Agent } from "@voltagent/core"; + + const uiMessages = convertToUIMessages(context); + + // Semi-realistic example + new Agent({ + hooks: { + onEnd: async ({ agent, output, error, conversationId, context }) => { + const uiMessages = convertToUIMessages(context); + await chatStore.save({ + conversationId, + messages: uiMessages, + }); + }, + }, + }); + ``` diff --git a/packages/vercel-ui/README.md b/archive/deprecated-providers/vercel-ui/README.md similarity index 100% rename from packages/vercel-ui/README.md rename to archive/deprecated-providers/vercel-ui/README.md diff --git a/packages/vercel-ui/biome.json b/archive/deprecated-providers/vercel-ui/biome.json similarity index 100% rename from packages/vercel-ui/biome.json rename to archive/deprecated-providers/vercel-ui/biome.json diff --git a/archive/deprecated-providers/vercel-ui/package.json b/archive/deprecated-providers/vercel-ui/package.json new file mode 100644 index 000000000..cf00f2c75 --- /dev/null +++ b/archive/deprecated-providers/vercel-ui/package.json @@ -0,0 +1,58 @@ +{ + "name": "@voltagent/vercel-ui", + "description": "VoltAgent Vercel UI - Vercel UI integration for VoltAgent", + "version": "1.0.0-next.0", + "dependencies": { + "@voltagent/internal": "^0.0.9", + "ai": "^5.0.76", + "ts-pattern": "^5.7.1", + "type-fest": "^4.41.0" + }, + "devDependencies": { + "@types/node": "^24.2.1", + "@vitest/coverage-v8": "^3.2.4", + "@voltagent/core": "^1.0.0-next.0", + "tsup": "^8.5.0", + "typescript": "^5.8.2", + "vitest": "^3.2.4", + "zod": "^3.25.0" + }, + "exports": { + ".": { + "import": { + "types": "./dist/index.d.mts", + "default": "./dist/index.mjs" + }, + "require": { + "types": "./dist/index.d.ts", + "default": "./dist/index.js" + } + } + }, + "files": [ + "dist" + ], + "license": "MIT", + "main": "dist/index.js", + "module": "dist/index.mjs", + "peerDependencies": { + "@voltagent/core": "^1.0.0-next.0", + "zod": "^3.25.0" + }, + "scripts": { + "attw": "attw --pack", + "build": "tsup", + "dev": "tsup --watch", + "lint": "biome check .", + "lint:fix": "biome check . --write", + "publint": "publint --strict", + "test": "vitest --coverage", + "test:coverage": "vitest run --coverage" + }, + "repository": { + "type": "git", + "url": "https://github.com/VoltAgent/voltagent.git", + "directory": "archive/deprecated-providers/vercel-ui" + }, + "types": "dist/index.d.ts" +} diff --git a/packages/vercel-ui/src/adapter/index.ts b/archive/deprecated-providers/vercel-ui/src/adapter/index.ts similarity index 100% rename from packages/vercel-ui/src/adapter/index.ts rename to archive/deprecated-providers/vercel-ui/src/adapter/index.ts diff --git a/packages/vercel-ui/src/adapter/stream-callbacks.ts b/archive/deprecated-providers/vercel-ui/src/adapter/stream-callbacks.ts similarity index 100% rename from packages/vercel-ui/src/adapter/stream-callbacks.ts rename to archive/deprecated-providers/vercel-ui/src/adapter/stream-callbacks.ts diff --git a/packages/vercel-ui/src/adapter/to-ui-message-stream.ts b/archive/deprecated-providers/vercel-ui/src/adapter/to-ui-message-stream.ts similarity index 100% rename from packages/vercel-ui/src/adapter/to-ui-message-stream.ts rename to archive/deprecated-providers/vercel-ui/src/adapter/to-ui-message-stream.ts diff --git a/packages/vercel-ui/src/index.ts b/archive/deprecated-providers/vercel-ui/src/index.ts similarity index 100% rename from packages/vercel-ui/src/index.ts rename to archive/deprecated-providers/vercel-ui/src/index.ts diff --git a/packages/vercel-ui/tsconfig.json b/archive/deprecated-providers/vercel-ui/tsconfig.json similarity index 100% rename from packages/vercel-ui/tsconfig.json rename to archive/deprecated-providers/vercel-ui/tsconfig.json diff --git a/packages/vercel-ui/tsconfig.spec.json b/archive/deprecated-providers/vercel-ui/tsconfig.spec.json similarity index 100% rename from packages/vercel-ui/tsconfig.spec.json rename to archive/deprecated-providers/vercel-ui/tsconfig.spec.json diff --git a/packages/vercel-ui/tsup.config.ts b/archive/deprecated-providers/vercel-ui/tsup.config.ts similarity index 100% rename from packages/vercel-ui/tsup.config.ts rename to archive/deprecated-providers/vercel-ui/tsup.config.ts diff --git a/packages/vercel-ui/vitest.config.ts b/archive/deprecated-providers/vercel-ui/vitest.config.ts similarity index 100% rename from packages/vercel-ui/vitest.config.ts rename to archive/deprecated-providers/vercel-ui/vitest.config.ts diff --git a/archive/deprecated-providers/xsai/CHANGELOG.md b/archive/deprecated-providers/xsai/CHANGELOG.md new file mode 100644 index 000000000..d4e3788d4 --- /dev/null +++ b/archive/deprecated-providers/xsai/CHANGELOG.md @@ -0,0 +1,297 @@ +# @voltagent/xsai + +## 1.0.0-next.0 + +### Patch Changes + +- Updated dependencies [[`64a50e6`](https://github.com/VoltAgent/voltagent/commit/64a50e6800dec844fad7b9f3a3b1c2c8d0486229), [`9e8b211`](https://github.com/VoltAgent/voltagent/commit/9e8b2119a783942f114459f0a9b93e645727445e)]: + - @voltagent/core@1.0.0-next.0 + +## 0.3.4 + +### Patch Changes + +- [#462](https://github.com/VoltAgent/voltagent/pull/462) [`23ecea4`](https://github.com/VoltAgent/voltagent/commit/23ecea421b8c699f5c395dc8aed687f94d558b6c) Thanks [@omeraplak](https://github.com/omeraplak)! - Update Zod to v3.25.0 for compatibility with Vercel AI@5 + - Updated Zod dependency to ^3.25.0 across all packages + - Maintained compatibility with zod-from-json-schema@0.0.5 + - Fixed TypeScript declaration build hanging issue + - Resolved circular dependency issues in the build process + +- Updated dependencies [[`23ecea4`](https://github.com/VoltAgent/voltagent/commit/23ecea421b8c699f5c395dc8aed687f94d558b6c), [`23ecea4`](https://github.com/VoltAgent/voltagent/commit/23ecea421b8c699f5c395dc8aed687f94d558b6c)]: + - @voltagent/core@0.1.84 + +## 0.3.3 + +### Patch Changes + +- [#494](https://github.com/VoltAgent/voltagent/pull/494) [`4459ae2`](https://github.com/VoltAgent/voltagent/commit/4459ae24a7c8b4ed3031f5a81ce7835e90fa6ade) Thanks [@kwaa](https://github.com/kwaa)! - fix(xsai): bump to v0.4.0-beta.1, support file & reasoning + +## 0.3.2 + +### Patch Changes + +- [`4f4ffc2`](https://github.com/VoltAgent/voltagent/commit/4f4ffc23eaea36675e66eb8a17d275fe9f32a671) Thanks [@omeraplak](https://github.com/omeraplak)! - feat: add fullStream support + +- Updated dependencies [[`760a294`](https://github.com/VoltAgent/voltagent/commit/760a294e4d68742d8701d54dc1c541c87959e5d8), [`760a294`](https://github.com/VoltAgent/voltagent/commit/760a294e4d68742d8701d54dc1c541c87959e5d8), [`980d037`](https://github.com/VoltAgent/voltagent/commit/980d037ce535bcc85cc7df3f64354c823453a147)]: + - @voltagent/core@0.1.74 + +## 0.3.1 + +### Patch Changes + +- [`90a1316`](https://github.com/VoltAgent/voltagent/commit/90a131622a876c0d91e1b9046a5e1fc143fef6b5) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: improve code quality with biome linting and package configuration enhancements + + This update focuses on improving code quality and package configuration across the entire VoltAgent monorepo: + + **Key improvements:** + - **Biome Linting**: Fixed numerous linting issues identified by Biome across all packages, ensuring consistent code style and catching potential bugs + - **Package Configuration**: Added `publint` script to all packages for strict validation of package.json files to ensure proper publishing configuration + - **TypeScript Exports**: Fixed `typesVersions` structure in @voltagent/internal package and removed duplicate entries + - **Test Utilities**: Refactored `createTrackedStorage` function in core package by simplifying its API - removed the `testName` parameter for cleaner test setup + - **Type Checking**: Enabled `attw` (Are The Types Wrong) checking to ensure TypeScript types are correctly exported + + These changes improve the overall maintainability and reliability of the VoltAgent framework without affecting the public API. + +## 0.3.0 + +### Minor Changes + +- [#411](https://github.com/VoltAgent/voltagent/pull/411) [`80b24e2`](https://github.com/VoltAgent/voltagent/commit/80b24e245daa9584733762c9aaf7e23e1d90c6c5) Thanks [@kwaa](https://github.com/kwaa)! - chore(deps): bump xsai to 0.3.3 + +### Patch Changes + +- Updated dependencies [[`99fe836`](https://github.com/VoltAgent/voltagent/commit/99fe83662e9b3e550380fce066521a5c27d69eb3)]: + - @voltagent/core@0.1.71 + +## 0.2.4 + +### Patch Changes + +- [#348](https://github.com/VoltAgent/voltagent/pull/348) [`9581df0`](https://github.com/VoltAgent/voltagent/commit/9581df02bce2ba8b25f9f2964b781095bc50b004) Thanks [@Adherentman](https://github.com/Adherentman)! - fix: xsai empty tools will sent undefined - #337 + +- Updated dependencies [[`b7dcded`](https://github.com/VoltAgent/voltagent/commit/b7dcdedfbbdda5bfb1885317b59b4d4e2495c956), [`822739c`](https://github.com/VoltAgent/voltagent/commit/822739c901bbc679cd11dd2c9df99cd041fc40c7)]: + - @voltagent/core@0.1.55 + +## 0.2.3 + +### Patch Changes + +- [#229](https://github.com/VoltAgent/voltagent/pull/229) [`0eba8a2`](https://github.com/VoltAgent/voltagent/commit/0eba8a265c35241da74324613e15801402f7b778) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: migrate the provider streams to `AsyncIterableStream` + + Example: + + ```typescript + const stream = createAsyncIterableStream( + new ReadableStream({ + start(controller) { + controller.enqueue("Hello"); + controller.enqueue(", "); + controller.enqueue("world!"); + controller.close(); + }, + }) + ); + + for await (const chunk of stream) { + console.log(chunk); + } + + // in the agent + const result = await agent.streamObject({ + messages, + model: "test-model", + schema, + }); + + for await (const chunk of result.objectStream) { + console.log(chunk); + } + ``` + + New exports: + - `createAsyncIterableStream` + - `type AsyncIterableStream` + +- Updated dependencies [[`f2f4539`](https://github.com/VoltAgent/voltagent/commit/f2f4539af7722f25a5aad9f01c2b7b5e50ba51b8), [`0eba8a2`](https://github.com/VoltAgent/voltagent/commit/0eba8a265c35241da74324613e15801402f7b778)]: + - @voltagent/core@0.1.32 + +## 0.2.2 + +### Patch Changes + +- [#226](https://github.com/VoltAgent/voltagent/pull/226) [`d879e6d`](https://github.com/VoltAgent/voltagent/commit/d879e6d41757081420162cf983223683b72b66a5) Thanks [@zrosenbauer](https://github.com/zrosenbauer)! - fix: add toolName to tool-result steps + + Tool result steps now include the toolName field, ensuring proper identification of which tool generated each result in conversation flows and hook messages. + +## 0.2.1 + +### Patch Changes + +- [#213](https://github.com/VoltAgent/voltagent/pull/213) [`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f) Thanks [@baseballyama](https://github.com/baseballyama)! - chore!: drop Node.js v18 + +- Updated dependencies [[`ed68922`](https://github.com/VoltAgent/voltagent/commit/ed68922e4c71560c2f68117064b84e874a72009f), [`80fd3c0`](https://github.com/VoltAgent/voltagent/commit/80fd3c069de4c23116540a55082b891c4b376ce6)]: + - @voltagent/core@0.1.31 + +## 0.2.0 + +### Minor Changes + +- [#195](https://github.com/VoltAgent/voltagent/pull/195) [`0c4e941`](https://github.com/VoltAgent/voltagent/commit/0c4e9418ae75c82b20a503678e75277729c0174b) Thanks [@Ajay-Satish-01](https://github.com/Ajay-Satish-01)! - 🚨 Breaking Change: Renamed XsAI and Xsai to XSAI + + We’ve renamed the XsAI and Xsai classes to XSAI to keep naming consistent across the framework. + + What changed? + + If you’re using the XsAIProvider or XsAIVoiceProvider, you now need to update your code to use XSAIProvider and XSAIVoiceProvider. + + Before: + + ```ts + import { XsAIVoiceProvider } from "@voltagent/voice"; + + const agent = new Agent({ + name: "Asistant", + description: "A helpful assistant that answers questions without using tools", + llm: new XsAIProvider({ + apiKey: process.env.OPENAI_API_KEY!, + }), + model: "gpt-4o-mini", + }); + + const voiceProvider = new XsAIVoiceProvider({ + apiKey: process.env.OPENAI_API_KEY!, + }); + ``` + + After: + + ```ts + import { XSAIVoiceProvider } from "@voltagent/voice"; + + const agent = new Agent({ + name: "Asistant", + description: "A helpful assistant that answers questions without using tools", + llm: new XSAIProvider({ + apiKey: process.env.OPENAI_API_KEY!, + }), + model: "gpt-4o-mini", + }); + + const voiceProvider = new XSAIVoiceProvider({ + apiKey: process.env.OPENAI_API_KEY!, + }); + ``` + + This change resolves [#140](https://github.com/your-repo/issues/140). + +### Patch Changes + +- Updated dependencies [[`07d99d1`](https://github.com/VoltAgent/voltagent/commit/07d99d133232babf78ba4e1c32fe235d5b3c9944), [`67b0e7e`](https://github.com/VoltAgent/voltagent/commit/67b0e7ea704d23bf9efb722c0b0b4971d0974153)]: + - @voltagent/core@0.1.29 + +## 0.1.9 + +### Patch Changes + +- [#155](https://github.com/VoltAgent/voltagent/pull/155) [`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c) Thanks [@baseballyama](https://github.com/baseballyama)! - chore: update `tsconfig.json`'s `target` to `ES2022` + +- [#162](https://github.com/VoltAgent/voltagent/pull/162) [`b164bd0`](https://github.com/VoltAgent/voltagent/commit/b164bd014670452cb162b388f03565db992767af) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: pin zod version to 3.24.2 to avoid "Type instantiation is excessively deep and possibly infinite" error + + Fixed compatibility issues between different zod versions that were causing TypeScript compilation errors. This issue occurs when multiple packages use different patch versions of zod (e.g., 3.23.x vs 3.24.x), leading to type instantiation depth problems. By pinning to 3.24.2, we ensure consistent behavior across all packages. + + See: https://github.com/colinhacks/zod/issues/3435 + +- Updated dependencies [[`35b11f5`](https://github.com/VoltAgent/voltagent/commit/35b11f5258073dd39f3032db6d9b29146f4b940c), [`b164bd0`](https://github.com/VoltAgent/voltagent/commit/b164bd014670452cb162b388f03565db992767af), [`9412cf0`](https://github.com/VoltAgent/voltagent/commit/9412cf0633f20d6b77c87625fc05e9e216936758)]: + - @voltagent/core@0.1.20 + +## 0.1.8 + +### Patch Changes + +- [#100](https://github.com/VoltAgent/voltagent/pull/100) [`0bdcf94`](https://github.com/VoltAgent/voltagent/commit/0bdcf9441cc79cf6321b377c303123d28daddda4) Thanks [@kwaa](https://github.com/kwaa)! - feat: Add multi-modal support (see [docs](https://voltagent.dev/docs/providers/xsai/#multi-modal-support)) - [#79](https://github.com/VoltAgent/voltagent/issues/79) + +## 0.1.6 + +### Patch Changes + +- [#102](https://github.com/VoltAgent/voltagent/pull/102) [`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3) Thanks [@omeraplak](https://github.com/omeraplak)! - refactor: use 'instructions' field for Agent definitions in examples - #88 + + Updated documentation examples (READMEs, docs, blogs) and relevant package code examples to use the `instructions` field instead of `description` when defining `Agent` instances. + + This change aligns the examples with the preferred API usage for the `Agent` class, where `instructions` provides behavioral guidance to the agent/LLM. This prepares for the eventual deprecation of the `description` field specifically for `Agent` class definitions. + + **Example Change for Agent Definition:** + + ```diff + const agent = new Agent({ + name: "My Assistant", + - description: "A helpful assistant.", + + instructions: "A helpful assistant.", + llm: new VercelAIProvider(), + model: openai("gpt-4o-mini"), + }); + ``` + +- Updated dependencies [[`cdfec65`](https://github.com/VoltAgent/voltagent/commit/cdfec657f731fdc1b6d0c307376e3299813f55d3)]: + - @voltagent/core@0.1.14 + - @voltagent/xsai@0.1.6 + +## 0.1.5 + +### Patch Changes + +- [`13db262`](https://github.com/VoltAgent/voltagent/commit/13db2621ae6b730667f9991d3c2129c85265e925) Thanks [@omeraplak](https://github.com/omeraplak)! - fix: Update Zod to version 3.24.2 to resolve "Type instantiation is excessively deep and possibly infinite" error (related to https://github.com/colinhacks/zod/issues/3435). + +- Updated dependencies [[`f7de864`](https://github.com/VoltAgent/voltagent/commit/f7de864503d598cf7131cc01afa3779639190107), [`13db262`](https://github.com/VoltAgent/voltagent/commit/13db2621ae6b730667f9991d3c2129c85265e925)]: + - @voltagent/core@0.1.13 + - @voltagent/xsai@0.1.5 + +## 0.1.4 + +### Patch Changes + +- [#77](https://github.com/VoltAgent/voltagent/pull/77) [`beaa8fb`](https://github.com/VoltAgent/voltagent/commit/beaa8fb1f1bc6351f1bede0b65a6a189cc1b6ea2) Thanks [@omeraplak](https://github.com/omeraplak)! - **API & Providers:** Standardized message content format for array inputs. + - The API (`/text`, `/stream`, `/object`, `/stream-object` endpoints) now strictly expects the `content` field within message objects (when `input` is an array) to be either a `string` or an `Array` of content parts (e.g., `[{ type: 'text', text: '...' }]`). + - The previous behavior of allowing a single content object (e.g., `{ type: 'text', ... }`) directly as the value for `content` in message arrays is no longer supported in the API schema. Raw string inputs remain unchanged. + - Provider logic (`google-ai`, `groq-ai`, `xsai`) updated to align with this stricter definition. + + **Console:** + - **Added file and image upload functionality to the Assistant Chat.** Users can now attach multiple files/images via a button, preview attachments, and send them along with text messages. + - Improved the Assistant Chat resizing: Replaced size toggle buttons with a draggable handle (top-left corner). + - Chat window dimensions are now saved to local storage and restored on reload. + + **Internal:** + - Added comprehensive test suites for Groq and XsAI providers. + +- Updated dependencies [[`beaa8fb`](https://github.com/VoltAgent/voltagent/commit/beaa8fb1f1bc6351f1bede0b65a6a189cc1b6ea2)]: + - @voltagent/core@0.1.10 + - @voltagent/xsai@0.1.4 + +## 0.1.3 + +### Patch Changes + +- [#33](https://github.com/VoltAgent/voltagent/pull/33) [`3ef2eaa`](https://github.com/VoltAgent/voltagent/commit/3ef2eaa9661e8ecfebf17af56b09af41285d0ca9) Thanks [@kwaa](https://github.com/kwaa)! - Update package.json files: + - Remove `src` directory from the `files` array. + - Add explicit `exports` field for better module resolution. + +- Updated dependencies [[`52d5fa9`](https://github.com/VoltAgent/voltagent/commit/52d5fa94045481dc43dc260a40b701606190585c), [`3ef2eaa`](https://github.com/VoltAgent/voltagent/commit/3ef2eaa9661e8ecfebf17af56b09af41285d0ca9), [`52d5fa9`](https://github.com/VoltAgent/voltagent/commit/52d5fa94045481dc43dc260a40b701606190585c)]: + - @voltagent/core@0.1.6 + +## 0.1.1 + +- 🚀 **Introducing VoltAgent: TypeScript AI Agent Framework!** + + This initial release marks the beginning of VoltAgent, a powerful toolkit crafted for the JavaScript developer community. We saw the challenges: the complexity of building AI from scratch, the limitations of No-Code tools, and the lack of first-class AI tooling specifically for JS. + + ![VoltAgent Demo](https://cdn.voltagent.dev/readme/demo.gif) + VoltAgent aims to fix that by providing the building blocks you need: + - **`@voltagent/core`**: The foundational engine for agent capabilities. + - **`@voltagent/voice`**: Easily add voice interaction. + - **`@voltagent/vercel-ai`**: Seamless integration with [Vercel AI SDK](https://sdk.vercel.ai/docs/introduction). + - **`@voltagent/xsai`**: A Seamless integration with [xsAI](https://xsai.js.org/). + - **`@voltagent/cli` & `create-voltagent-app`**: Quick start tools to get you building _fast_. + + We're combining the flexibility of code with the clarity of visual tools (like our **currently live [VoltOps LLM Observability Platform](https://console.voltagent.dev/)**) to make AI development easier, clearer, and more powerful. Join us as we build the future of AI in JavaScript! + + Explore the [Docs](https://voltagent.dev/docs/) and join our [Discord community](https://s.voltagent.dev/discord)! diff --git a/packages/xsai/README.md b/archive/deprecated-providers/xsai/README.md similarity index 100% rename from packages/xsai/README.md rename to archive/deprecated-providers/xsai/README.md diff --git a/packages/xsai/biome.json b/archive/deprecated-providers/xsai/biome.json similarity index 100% rename from packages/xsai/biome.json rename to archive/deprecated-providers/xsai/biome.json diff --git a/archive/deprecated-providers/xsai/package.json b/archive/deprecated-providers/xsai/package.json new file mode 100644 index 000000000..d73adc388 --- /dev/null +++ b/archive/deprecated-providers/xsai/package.json @@ -0,0 +1,58 @@ +{ + "name": "@voltagent/xsai", + "description": "VoltAgent xsAI - xsAI provider integration for VoltAgent", + "version": "1.0.0-next.0", + "dependencies": { + "@voltagent/core": "^1.0.0-next.0", + "ts-pattern": "^5.7.1", + "type-fest": "^4.41.0", + "xsai": "0.4.0-beta.1", + "zod": "^3.25.0" + }, + "devDependencies": { + "@types/node": "^24.2.1", + "@vitest/coverage-v8": "^3.2.4", + "tsup": "^8.5.0", + "typescript": "^5.8.2", + "vitest": "^3.2.4", + "zod": "^3.25.0" + }, + "exports": { + ".": { + "import": { + "types": "./dist/index.d.mts", + "default": "./dist/index.mjs" + }, + "require": { + "types": "./dist/index.d.ts", + "default": "./dist/index.js" + } + } + }, + "files": [ + "dist" + ], + "license": "MIT", + "main": "dist/index.js", + "module": "dist/index.mjs", + "peerDependencies": { + "@voltagent/core": "^1.0.0-next.0", + "zod": "^3.25.0" + }, + "scripts": { + "attw": "attw --pack", + "build": "tsup", + "dev": "tsup --watch", + "lint": "biome check .", + "lint:fix": "biome check . --write", + "publint": "publint --strict", + "test": "vitest", + "test:coverage": "vitest run" + }, + "repository": { + "type": "git", + "url": "https://github.com/VoltAgent/voltagent.git", + "directory": "archive/deprecated-providers/xsai" + }, + "types": "dist/index.d.ts" +} diff --git a/packages/xsai/src/index.spec.ts b/archive/deprecated-providers/xsai/src/index.spec.ts similarity index 100% rename from packages/xsai/src/index.spec.ts rename to archive/deprecated-providers/xsai/src/index.spec.ts diff --git a/packages/xsai/src/index.ts b/archive/deprecated-providers/xsai/src/index.ts similarity index 100% rename from packages/xsai/src/index.ts rename to archive/deprecated-providers/xsai/src/index.ts diff --git a/packages/xsai/src/types.ts b/archive/deprecated-providers/xsai/src/types.ts similarity index 100% rename from packages/xsai/src/types.ts rename to archive/deprecated-providers/xsai/src/types.ts diff --git a/packages/xsai/src/utils.spec.ts b/archive/deprecated-providers/xsai/src/utils.spec.ts similarity index 100% rename from packages/xsai/src/utils.spec.ts rename to archive/deprecated-providers/xsai/src/utils.spec.ts diff --git a/packages/xsai/src/utils.ts b/archive/deprecated-providers/xsai/src/utils.ts similarity index 100% rename from packages/xsai/src/utils.ts rename to archive/deprecated-providers/xsai/src/utils.ts diff --git a/packages/xsai/tsconfig.json b/archive/deprecated-providers/xsai/tsconfig.json similarity index 100% rename from packages/xsai/tsconfig.json rename to archive/deprecated-providers/xsai/tsconfig.json diff --git a/packages/xsai/tsup.config.ts b/archive/deprecated-providers/xsai/tsup.config.ts similarity index 100% rename from packages/xsai/tsup.config.ts rename to archive/deprecated-providers/xsai/tsup.config.ts diff --git a/packages/xsai/vitest.config.mts b/archive/deprecated-providers/xsai/vitest.config.mts similarity index 100% rename from packages/xsai/vitest.config.mts rename to archive/deprecated-providers/xsai/vitest.config.mts diff --git a/biome.json b/biome.json index 6f266bedb..2304d8c4d 100644 --- a/biome.json +++ b/biome.json @@ -38,6 +38,9 @@ "formatter": { "quoteStyle": "double", "semicolons": "always" + }, + "parser": { + "unsafeParameterDecoratorsEnabled": true } }, "files": { @@ -53,7 +56,12 @@ "**/*.module.css", "**/.docusaurus/**", "**/generated/**", - "**/package.json" + "**/package.json", + "website/src/data/tweets.json", + ".wrangler", + "packages/server-hono/src/vendor", + "examples/with-nuxt", + "examples/with-assistant-ui" ] }, "overrides": [ @@ -76,6 +84,16 @@ } } } + }, + { + "include": ["**/examples/with-nestjs/**/*.ts"], + "linter": { + "rules": { + "style": { + "useImportType": "off" + } + } + } } ] } diff --git a/docs/linting.md b/docs/linting.md new file mode 100644 index 000000000..7886d5f84 --- /dev/null +++ b/docs/linting.md @@ -0,0 +1,32 @@ +# Linting + +VoltAgent uses Biome for linting and formatting code. Biome is a fast and modern linter and formatter for TypeScript and JavaScript that has set of pre-defined rules that are applied to the codebase. + +## Tools + +- **Linter + Formatter**: Biome (replaces ESLint + Prettier) +- **Config**: `biome.json` + +## Running Commands + +```bash +# Check all files +pnpm lint + +# Auto-fix issues +pnpm lint:fix + +# Check only (CI mode) +pnpm lint:ci +``` + +## VS Code Integration + +Install the Biome extension: + +```json +{ + "editor.defaultFormatter": "biomejs.biome", + "editor.formatOnSave": true +} +``` diff --git a/docs/structure.md b/docs/structure.md new file mode 100644 index 000000000..d449b86aa --- /dev/null +++ b/docs/structure.md @@ -0,0 +1,83 @@ +# Repository Structure + +This monorepo is organized using pnpm workspaces and Lerna with the following main directories: + +## Overview + +``` +voltagent/ +├── packages/ # Core packages and integrations +├── examples/ # Example implementations +├── website/ # Documentation website and marketplace +├── docs/ # Project documentation +├── scripts/ # Build and utility scripts +├── .changeset/ # Changeset configuration +└── package.json # Root package configuration +``` + +## Details + +### `packages/` + +Core packages, AI provider integrations, and utilities: + +- **cli** - VoltAgent CLI for project scaffolding and management +- **core** - Main VoltAgent framework with agent orchestration, memory management, tools, and observability. Includes the `ConversationBuffer` (merges model/tool messages into UI messages for persistence) and `MemoryPersistQueue` (debounced memory write pipeline). +- **create-voltagent-app** - Project initialization tool +- **docs-mcp** - Model Context Protocol documentation server +- **internal** - Internal utilities and shared types used across packages +- **langfuse-exporter** - LangFuse telemetry exporter +- **libsql** - LibSQL database integration +- **logger** - Universal logger implementation +- **postgres** - PostgreSQL database integration +- **sdk** - JavaScript/TypeScript SDK for VoltAgent API +- **server-core** - Core server handlers, schemas, and business logic +- **server-hono** - Hono-based server implementation with API routes +- **supabase** - Supabase client integration +- **vercel-ai-exporter** - Vercel AI telemetry exporter +- **voice** - Voice interaction capabilities + +#### Conventions + +Packages are named using the following conventions: + +- `@voltagent/*` - Core framework packages +- `@voltagent/*-exporter` - Telemetry exporters +- `voltagent-example-*` - Example applications + +Certain packages are `deprecated` and include a `DEPRECATED.md` file with migration instructions in the root of the package (i.e. `google-ai`). + +### `examples/` + +Example implementations demonstrating VoltAgent usage: + +- Basic agent examples +- Integration patterns +- Advanced use cases +- Best practices demonstrations + +#### Conventions + +Examples are named using the following conventions: + +- `with-*` - Example application using the specific integration (i.e. `with-chroma` or `with-google-ai`) + +### `website/` + +Documentation website built with Docusaurus: + +- **docs/** - Technical documentation +- **blog/** - Blog posts and tutorials +- **static/** - Static assets and images + +### `docs/` + +Project-level documentation: + +- **structure.md** - This file, describing repository organization +- **tooling.md** - Development tools and workflows +- Additional architecture and design documents + +### `scripts/` + +Reusable scripts for the project, for repeatable development tasks. diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 000000000..a0830b6e5 --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,150 @@ +# Testing + +VoltAgent uses `vitest` for testing, with the naming convention of `*.spec.ts` for unit tests, and `*.spec-d.ts` for type tests. + +## Overview + +- **Framework**: vitest +- **Test Files**: `*.spec.ts` +- **Type Test Files**: `*.spec-d.ts` +- **Coverage**: V8 provider +- **Environment**: Node.js + +## Running Tests + +```bash +# Run all tests +pnpm test:all + +# Run tests with coverage +pnpm test:all:coverage + +# Run tests for specific package +pnpm test --filter @voltagent/core + +# Run single test file +cd packages/core && pnpm vitest run src/tool/index.spec.ts +``` + +## Writing Tests + +All tests are using the `vitest` framework, and use the format of `*.spec.ts` for unit tests, and `*.spec-d.ts` for type tests. Tests should be co-located with the code they are testing, using the same naming convention (i.e. `tool.spec.ts` is testing the `tool.ts` file). + +### Basic Structure + +```typescript +import { describe, expect, it, vi } from "vitest"; +import { yourFunction } from "./index"; + +describe("yourFunction", () => { + it("should do something", () => { + // Arrange + const instance = new YourClass(); + + // Act + const result = instance.methodName(); + + // Assert + expect(result).toBe("expected"); + }); +}); +``` + +### Type Tests + +Type tests are used to test the types of the codebase. They are located in the `*.spec-d.ts` files, and are used to test the types of the codebase. + +```typescript +import { describe, expectTypeOf, it } from "vitest"; +import type { YourType } from "./index"; + +describe("YourType", () => { + it("should have the correct type", () => { + expectTypeOf().toBeObject(); + }); +}); +``` + +[Type Test Documentation](https://vitest.dev/guide/testing-types.html + +### Mocking + +```typescript +// Mock external modules +vi.mock("uuid", () => ({ + v4: vi.fn().mockReturnValue("mock-uuid"), +})); + +// Mock AI SDK functions +vi.mock("ai", () => ({ + generateText: vi.fn(), + streamText: vi.fn(), +})); + +// Mock functions +const mockExecute = vi.fn(); +``` + +[Mocking Documentation](https://vitest.dev/guide/mocking.html#mocking) + +### Testing Agents with the AI SDK + +VoltAgent is built on top of the `ai` SDK, and uses the `ai/test` package to mock the AI SDK functions for testing. + +```typescript +import { MockLanguageModelV3 } from "ai/test"; +import { Agent } from "./agent"; + +describe("Agent", () => { + let mockModel: MockLanguageModelV3; + + beforeEach(() => { + mockModel = new MockLanguageModelV3({ + doGenerate: vi.fn().mockResolvedValue({ + finishReason: "stop", + content: [{ type: "text", text: "Hello, world!" }], + usage: { + inputTokens: 10, + outputTokens: 20, + totalTokens: 30, + inputTokenDetails: { noCacheTokens: 10, cacheReadTokens: 0, cacheWriteTokens: 0 }, + outputTokenDetails: { textTokens: 20, reasoningTokens: 0 }, + }, + }), + }); + }); + + it("should generate text", async () => { + const agent = new Agent({ + name: "test-agent", + model: mockModel, + }); + + const result = await agent.generateText("Say hello"); + expect(result.text).toBe("Hello, world!"); + }); +}); +``` + +### Testing Tools + +```typescript +import { z } from "zod"; +import { createTool } from "./index"; + +describe("Tool", () => { + it("should create tool with schema", () => { + const tool = createTool({ + name: "testTool", + description: "A test tool", + parameters: z.object({ + input: z.string(), + }), + execute: async ({ input }) => `Output: ${input}`, + }); + + expect(tool.name).toBe("testTool"); + expect(tool.execute).resolves.toBe("Output: test"); + }); +}); +``` diff --git a/docs/tooling.md b/docs/tooling.md new file mode 100644 index 000000000..32b819f33 --- /dev/null +++ b/docs/tooling.md @@ -0,0 +1,58 @@ +# Tooling + +Development tools and utilities used in this repository. + +- **package manager**: pnpm +- **monorepo**: lerna +- **language**: typescript +- **formatter**: biome +- **linter**: biome +- **build system**: tsup + +## pnpm + +Fast, disk space efficient package manager with built-in workspace support for managing dependencies across the monorepo. + +### Links + +- [Documentation](https://pnpm.io/pnpm-cli) + +## lerna + +Lerna is a tool for managing JavaScript projects with multiple packages. + +### Links + +- [Documentation](https://lerna.js.org/docs/introduction) + +## nx + +High-performance build system optimized for JavaScript and TypeScript monorepos with smart caching and parallel execution. Lerna and nx are integrated as nx acquired lerna. + +### Links + +- [Documentation](https://nx.dev/getting-started/intro) + +## Biome + +All-in-one toolchain for web projects, combining formatter and linter functionality (replaces ESLint + Prettier). + +### Links + +- [Documentation](https://biomejs.dev/guides/getting-started/) + +## TypeScript + +Strongly typed programming language that builds on JavaScript, providing static type checking at compile time. + +### Links + +- [Documentation](https://www.typescriptlang.org/docs/) + +## tsup + +Builds and bundles TypeScript code into JavaScript. + +### Links + +- [Documentation](https://tsup.egoist.dev/) diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 000000000..a69801d31 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,156 @@ +# VoltAgent AI Agent Examples + +Discover end‑to‑end, runnable examples that show how to build real AI agents with VoltAgent. These projects demonstrate core patterns such as RAG retrieval, typed tools, persistent memory, supervisor‑subagent orchestration, workflows, MCP tool integration, and voice/UX integrations. Use them as learning guides or as starters for your own apps. + +What you’ll find here + +- RAG and retrieval over vectors and databases +- Typed tool design, MCP servers, and external APIs +- Working and persistent memory for grounded conversations +- Resumable streaming examples for reconnecting to in-flight responses +- Supervisor + sub‑agent orchestration and workflows +- Deployments for Next.js, Cloudflare Workers, Netlify and more + +## Featured + +### [WhatsApp Order Agent](./with-whatsapp) + +Build a WhatsApp chatbot that handles food orders through natural conversation, manages menu items from a database, and processes orders with full conversation context. + +
+ +whatsapp + +
+
+ +- 📖 Tutorial: https://voltagent.dev/examples/agents/whatsapp-ai-agent + +### [YouTube to Blog Agent](./with-youtube-to-blog) + +Convert YouTube videos into Markdown blog posts using a supervisor agent that coordinates subagents with MCP tools, shared working memory, and VoltOps observability. + +
+ +youtube + +
+
+ +- 📖 Tutorial: https://voltagent.dev/examples/agents/youtube-blog-agent + +### [AI Ads Generator Agent](./with-ad-creator) + +Implement an Instagram ad generator that uses BrowserBase Stagehand to analyze landing pages, extract brand data, and generate visuals through Google Gemini AI. + +
+ +instagram + +
+
+ +- 📖 Tutorial: https://voltagent.dev/examples/agents/ai-instagram-ad-agent + +### [AI Recipe Generator Agent](./with-recipe-generator) + +Build an intelligent recipe recommendation system that creates personalized cooking suggestions based on available ingredients, dietary preferences, and time constraints. + +
+ +cook + +
+
+ +- 📖 Tutorial: https://voltagent.dev/examples/agents/recipe-generator +- 📹 Watch Video: https://youtu.be/KjV1c6AhlfY + +### [AI Research Assistant Agent](./with-research-assistant) + +Create a multi-agent research workflow where different AI agents collaborate to research topics and generate comprehensive reports with type-safe data flow. + +
+ +research + +
+
+ +- 📖 Tutorial: https://voltagent.dev/examples/agents/research-assistant +- 📹 Watch Video: https://youtu.be/j6KAUaoZMy4 + +## All Examples + +- [Base Starter](./base) — Minimal VoltAgent starter with a single agent, memory, and dev server. +- [Workspace](./with-workspace) — Workspace filesystem, sandbox execution, search, and skills. +- [Summarization](./with-summarization) — Agent summarization with a low trigger window for easy testing. +- [Retries and Fallbacks](./with-retries-fallback) — Model fallback list with per-model retries and agent-level defaults. +- [Middleware](./with-middleware) — Input/output middleware with retry feedback. +- [PlanAgents](./with-planagents) — Quickstart for PlanAgents with planning, filesystem tools, and subagent tasks. +- [Slack](./with-slack) — Slack app mention bot that replies in the same channel/thread via VoltOps Slack actions. +- [Chat SDK (Slack)](./with-chat-sdk) — Next.js webhook bot with Chat SDK transport and VoltAgent-powered responses. +- [Airtable](./with-airtable) — React to new Airtable records and write updates back using VoltOps Airtable actions. +- [GitHub Repo Analyzer](./github-repo-analyzer) — Agents read repository code and summarize insights/issues from GitHub projects. +- [GitHub Star Stories](./github-star-stories) — Celebrate new GitHub stars with enriched profiles, AI-written stories, and VoltOps Discord actions. +- [SDK Trace Example](./sdk-trace-example) — OpenTelemetry tracing wired to VoltOps so you can inspect spans and events. +- [Agent‑to‑Agent Server](./with-a2a-server) — Expose agents over HTTP so other agents/services can call them. +- [Amazon Bedrock](./with-amazon-bedrock) — Run AWS Bedrock models by configuring credentials and model IDs in VoltAgent. +- [Anthropic](./with-anthropic) — Use Claude models as your agent’s LLM via the AI SDK. +- [OpenRouter](./with-openrouter) — Use OpenRouter through VoltAgent's built-in `openrouter/` routing. +- [Chroma](./with-chroma) — RAG with Chroma vectors showing automatic vs tool‑driven retrieval patterns. +- [Client‑side Tools](./with-client-side-tools) — Next.js UI triggers typed client‑side tools safely, VoltAgent on the server. +- [Cloudflare Workers](./with-cloudflare-workers) — Deploy your agent on Workers using the Hono server adapter. +- [Composio (MCP)](./with-composio-mcp) — Call Composio actions through MCP tools inside your workflows. +- [Custom Endpoints](./with-custom-endpoints) — Add bespoke REST endpoints alongside agent/workflow routes. +- [Dynamic Parameters](./with-dynamic-parameters) — Validate and inject runtime parameters into agents with Zod. +- [Dynamic Prompts](./with-dynamic-prompts) — Build prompts from templates and live data programmatically. +- [Google AI](./with-google-ai) — Use Google Gemini models via the AI SDK provider. +- [Google Drive (MCP)](./with-google-drive-mcp) — Browse and read Drive files through a Google Drive MCP server. +- [Google Vertex AI](./with-google-vertex-ai) — Connect agents to Vertex AI models in your GCP project. +- [Groq](./with-groq-ai) — Ultra‑low latency responses using Groq’s LPU inference. +- [Guardrails](./with-guardrails) — Add output validation and schema enforcement to keep responses on spec. +- [Hooks](./with-hooks) — Demonstrates lifecycle hooks/middleware for logging, auth, or customization. +- [Hugging Face (MCP)](./with-hugging-face-mcp) — Access HF tools and models through MCP from agents. +- [JWT Auth](./with-jwt-auth) — Protect agent endpoints with JWT verification and helpers. +- [Langfuse](./with-langfuse) — Send traces and metrics to Langfuse for observability. +- [Feedback Templates](./with-feedback) — Configure per-agent feedback templates for thumbs, numeric, and categorical feedback. +- [Live Evals](./with-live-evals) — Run online evaluations against prompts/agents during development. +- [MCP Basics](./with-mcp) — Connect to MCP servers and call tools from an agent. +- [MCP Elicitation](./with-mcp-elicitation) — Handle `elicitation/create` requests from MCP tools with per-request handlers. +- [MCP Server](./with-mcp-server) — Implement and run a local MCP server that exposes custom tools. +- [Netlify Functions](./with-netlify-functions) — Ship serverless agent APIs on Netlify. +- [Next.js](./with-nextjs) — React UI with agent APIs and streaming responses. +- [Next.js + Resumable Streams](./with-nextjs-resumable-stream) — AI Elements chat UI with VoltAgent and resumable streams. +- [Nuxt](./with-nuxt) — Vue/Nuxt front‑end talking to VoltAgent APIs. +- [Offline Evals](./with-offline-evals) — Batch datasets and score outputs for regression testing. +- [Peaka (MCP)](./with-peaka-mcp) — Integrate Peaka services via MCP tools. +- [Pinecone](./with-pinecone) — RAG retrieval backed by Pinecone vectors and embeddings. +- [Playwright](./with-playwright) — Web automation tools powered by Playwright for browsing and actions. +- [Postgres](./with-postgres) — Use Postgres/pgvector for storage and semantic retrieval. +- [Qdrant](./with-qdrant) — RAG with Qdrant showing retriever‑on‑every‑turn vs LLM‑decides search. +- [RAG Chatbot](./with-rag-chatbot) — A conversational bot grounded in your documents with citations. +- [Retrieval](./with-retrieval) — Minimal retrieval helpers demonstrating the retriever API. +- [VoltOps Retrieval](./with-voltops-retrieval) — Use VoltOps Knowledge Bases as a retriever via @voltagent/core. +- [Sub‑agents](./with-subagents) — Supervisor orchestrates focused sub‑agents to divide tasks. +- [Supabase](./with-supabase) — Use Supabase auth/database in tools and server endpoints. +- [Tavily Search](./with-tavily-search) — Augment answers with web results from Tavily. +- [Xquik Tools](./with-xquik-tools) — Research public X/Twitter posts, users, and trends with Xquik tools. +- [Thinking Tool](./with-thinking-tool) — Structured reasoning via a dedicated “thinking” tool and schema. +- [Tool Routing](./with-tool-routing) — Route large tool pools through a small set of router tools. +- [Tools](./with-tools) — Author Zod‑typed tools with cancellation and streaming support. +- [VoltOps Actions + Airtable](./with-voltagent-actions) — Call VoltOps Actions as tools to create and list Airtable records. +- [Turso](./with-turso) — Persist memory on LibSQL/Turso with simple setup. +- [Vector Search](./with-vector-search) — Semantic memory with embeddings and automatic recall during chats. +- [Vercel AI](./with-vercel-ai) — VoltAgent with Vercel AI SDK provider and streaming. +- [Resumable Streams](./with-resumable-streams) — Persist and resume chat streams with Redis-backed SSE storage. +- [VoltOps Resumable Streams](./with-voltops-resumable-streams) — Persist and resume chat streams with VoltOps managed storage. +- [ViteVal](./with-viteval) — Integrate ViteVal to evaluate agents and prompts. +- [Voice (ElevenLabs)](./with-voice-elevenlabs) — Convert agent replies to speech using ElevenLabs TTS. +- [Voice (OpenAI)](./with-voice-openai) — Speak responses with OpenAI’s TTS voices. +- [Voice (xAI)](./with-voice-xsai) — Use xAI audio models for voice output. +- [VoltAgent Exporter](./with-voltagent-exporter) — Export traces/events to external observability targets. +- [Managed Memory](./with-voltagent-managed-memory) — Production‑grade memory via VoltOps Managed Memory REST adapter. +- [Workflow](./with-workflow) — Build multi‑step flows with createWorkflowChain and human‑in‑the‑loop. +- [Working Memory](./with-working-memory) — Persist per‑conversation/user facts with built‑in read/update tools. +- [Zapier (MCP)](./with-zapier-mcp) — Trigger Zapier actions through MCP from your agents. diff --git a/examples/base/package.json b/examples/base/package.json index 021ecb7d1..5938c17b3 100644 --- a/examples/base/package.json +++ b/examples/base/package.json @@ -2,16 +2,18 @@ "name": "voltagent-example-base", "author": "", "dependencies": { - "@ai-sdk/openai": "^2.0.2", - "@voltagent/cli": "^0.1.10", - "@voltagent/core": "^0.1.85", - "@voltagent/logger": "^0.1.4", - "@voltagent/vercel-ai": "^1.0.0", - "zod": "^3.25.0" + "@ai-sdk/openai": "^3.0.0", + "@voltagent/cli": "^0.1.21", + "@voltagent/core": "^2.9.1", + "@voltagent/libsql": "^2.1.2", + "@voltagent/logger": "^2.0.2", + "@voltagent/server-hono": "^2.0.14", + "ai": "^6.0.0", + "zod": "^3.25.76" }, "devDependencies": { - "@types/node": "^24.0.3", - "tsx": "^4.19.3", + "@types/node": "^24.2.1", + "tsx": "^4.21.0", "typescript": "^5.8.2" }, "keywords": [ @@ -21,6 +23,11 @@ ], "license": "MIT", "private": true, + "repository": { + "type": "git", + "url": "https://github.com/VoltAgent/voltagent.git", + "directory": "examples/base" + }, "scripts": { "build": "tsc", "dev": "tsx watch --env-file=.env ./src", diff --git a/examples/base/src/index.ts b/examples/base/src/index.ts index e08ddf4f5..2b28cbe1d 100644 --- a/examples/base/src/index.ts +++ b/examples/base/src/index.ts @@ -1,14 +1,7 @@ -import { openai } from "@ai-sdk/openai"; -import { Agent, VoltAgent } from "@voltagent/core"; +import { Agent, Memory, VoltAgent } from "@voltagent/core"; +import { LibSQLMemoryAdapter, LibSQLVectorAdapter } from "@voltagent/libsql"; import { createPinoLogger } from "@voltagent/logger"; -import { VercelAIProvider } from "@voltagent/vercel-ai"; - -const agent = new Agent({ - name: "Base Agent", - description: "You are a helpful assistant", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), -}); +import { honoServer } from "@voltagent/server-hono"; // Create logger const logger = createPinoLogger({ @@ -16,9 +9,23 @@ const logger = createPinoLogger({ level: "info", }); +// Create Memory instance with vector support for semantic search and working memory +const memory = new Memory({ + storage: new LibSQLMemoryAdapter(), + embedding: "openai/text-embedding-3-small", + vector: new LibSQLVectorAdapter(), + generateTitle: true, +}); + +const agent = new Agent({ + name: "Base Agent", + instructions: "You are a helpful assistant.", + model: "openai/gpt-4o-mini", + memory: memory, +}); + new VoltAgent({ - agents: { - agent, - }, + agents: { agent }, + server: honoServer(), logger, }); diff --git a/examples/github-repo-analyzer/.gitignore b/examples/github-repo-analyzer/.gitignore index b16899e7d..7d5da51c3 100644 --- a/examples/github-repo-analyzer/.gitignore +++ b/examples/github-repo-analyzer/.gitignore @@ -1,3 +1,6 @@ node_modules +dist .env -dist/ \ No newline at end of file +memory.db +memory.db-shm +memory.db-wal \ No newline at end of file diff --git a/examples/github-repo-analyzer/package.json b/examples/github-repo-analyzer/package.json index 546e14b88..10ac59a5e 100644 --- a/examples/github-repo-analyzer/package.json +++ b/examples/github-repo-analyzer/package.json @@ -2,20 +2,27 @@ "name": "voltagent-example-github-repo-analyzer", "version": "0.1.0", "dependencies": { - "@ai-sdk/openai": "^2.0.2", + "@ai-sdk/openai": "^3.0.0", "@octokit/rest": "^21.0.0", - "@voltagent/core": "^0.1.85", - "@voltagent/logger": "^0.1.4", - "@voltagent/vercel-ai": "^1.0.0", - "zod": "^3.25.0" + "@voltagent/core": "^2.9.1", + "@voltagent/libsql": "^2.1.2", + "@voltagent/logger": "^2.0.2", + "@voltagent/server-hono": "^2.0.14", + "ai": "^6.0.0", + "zod": "^3.25.76" }, "devDependencies": { - "@types/node": "^24.0.3", - "@voltagent/cli": "^0.1.10", - "tsx": "^4.19.3", + "@types/node": "^24.2.1", + "@voltagent/cli": "^0.1.21", + "tsx": "^4.21.0", "typescript": "^5.8.2" }, "private": true, + "repository": { + "type": "git", + "url": "https://github.com/VoltAgent/voltagent.git", + "directory": "examples/github-repo-analyzer" + }, "scripts": { "build": "tsc", "dev": "tsx watch --env-file=.env ./src ", diff --git a/examples/github-repo-analyzer/src/index.ts b/examples/github-repo-analyzer/src/index.ts index 1f63eeb14..dd54ca152 100644 --- a/examples/github-repo-analyzer/src/index.ts +++ b/examples/github-repo-analyzer/src/index.ts @@ -1,62 +1,68 @@ -import { openai } from "@ai-sdk/openai"; -import { Agent, VoltAgent, createHooks, createTool } from "@voltagent/core"; +import { Agent, InMemoryVectorAdapter, Memory, VoltAgent } from "@voltagent/core"; +import { LibSQLMemoryAdapter } from "@voltagent/libsql"; import { createPinoLogger } from "@voltagent/logger"; -import { VercelAIProvider } from "@voltagent/vercel-ai"; +import { honoServer } from "@voltagent/server-hono"; import { fetchRepoContributorsTool } from "./tools"; import { fetchRepoStarsTool } from "./tools"; +// Create logger +const logger = createPinoLogger({ + name: "github-repo-analyzer", + level: "info", +}); + +const memory = new Memory({ + storage: new LibSQLMemoryAdapter({}), + embedding: "openai/text-embedding-3-small", + vector: new InMemoryVectorAdapter(), +}); + // Create the stars fetcher agent const starsFetcherAgent = new Agent({ name: "Stars Fetcher", - description: "Fetches the number of stars for a GitHub repository using the GitHub API", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), + instructions: "Fetches the number of stars for a GitHub repository using the GitHub API", + model: "openai/gpt-4o-mini", tools: [fetchRepoStarsTool], + memory: memory, }); // Create the contributors fetcher agent const contributorsFetcherAgent = new Agent({ name: "Contributors Fetcher", - description: "Fetches the list of contributors for a GitHub repository using the GitHub API", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), + instructions: "Fetches the list of contributors for a GitHub repository using the GitHub API", + model: "openai/gpt-4o-mini", tools: [fetchRepoContributorsTool], + memory: memory, }); // Create the analyzer agent const analyzerAgent = new Agent({ name: "Repo Analyzer", - description: "Analyzes repository statistics and provides insights", - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), + instructions: "Analyzes repository statistics and provides insights", + model: "openai/gpt-4o-mini", + memory: memory, }); // Create the supervisor agent that coordinates all the sub-agents const supervisorAgent = new Agent({ name: "Supervisor", - description: `You are a GitHub repository analyzer. When given a GitHub repository URL or owner/repo format, you will: + instructions: `You are a GitHub repository analyzer. When given a GitHub repository URL or owner/repo format, you will: 1. Use the StarsFetcher agent to get the repository's star count 2. Use the ContributorsFetcher agent to get the repository's contributors 3. Use the RepoAnalyzer agent to analyze this data and provide insights Example input: https://github.com/vercel/ai-sdk or vercel/ai-sdk `, - llm: new VercelAIProvider(), - model: openai("gpt-4o-mini"), + model: "openai/gpt-4o-mini", subAgents: [starsFetcherAgent, contributorsFetcherAgent, analyzerAgent], + memory: memory, }); -// Initialize the VoltAgent with the agent hierarchy - -// Create logger -const logger = createPinoLogger({ - name: "github-repo-analyzer", - level: "info", -}); - +// Initialize the VoltAgent with the agent hierarchy and server new VoltAgent({ agents: { supervisorAgent, }, logger, + server: honoServer({ port: 3141 }), }); diff --git a/examples/github-star-stories/.env.example b/examples/github-star-stories/.env.example new file mode 100644 index 000000000..a5ab97560 --- /dev/null +++ b/examples/github-star-stories/.env.example @@ -0,0 +1,8 @@ +OPENAI_API_KEY=xxxxx + +VOLTAGENT_PUBLIC_KEY=xxxxx +VOLTAGENT_SECRET_KEY=xxxxx + +VOLTAGENT_CREDENTIAL_ID=-xxxxx + +GITHUB_TOKEN=xxxxx \ No newline at end of file diff --git a/examples/github-star-stories/.gitignore b/examples/github-star-stories/.gitignore new file mode 100644 index 000000000..8fceec7e1 --- /dev/null +++ b/examples/github-star-stories/.gitignore @@ -0,0 +1,2 @@ +.wrangler +.dev.vars \ No newline at end of file diff --git a/examples/github-star-stories/README.md b/examples/github-star-stories/README.md new file mode 100644 index 000000000..ec409e632 --- /dev/null +++ b/examples/github-star-stories/README.md @@ -0,0 +1,52 @@ +# GitHub Star Stories (VoltOps + Octokit Tools) + +A minimal VoltAgent example (based on the `base` starter) that exposes a single agent. +Give it commands like `celebrate octocat` and it will: + +1. Call an Octokit-powered tool to fetch the user’s profile +2. Write a short thank-you story (120 words max) +3. Send that story to Discord through VoltOps Actions + +## Run locally + +```bash +cd examples/with-github-star-stories +cp .env.example .env +pnpm install +pnpm dev +``` + +Once the server is running, you can hit the VoltAgent generate endpoint: + +```bash +curl -X POST http://localhost:3141/api/agent/generateText \ + -H "Content-Type: application/json" \ + -d '{ + "agent": "storyteller", + "input": "celebrate octocat" + }' +``` + +The agent responds with the Markdown story and (if VoltOps credentials are set) the same text is pushed to Discord. + +## Environment + +| Variable | Description | +| ----------------------------------------------- | -------------------------------------------------------------------------------------------- | +| `VOLTAGENT_PUBLIC_KEY` / `VOLTAGENT_SECRET_KEY` | VoltOps API keys (needed for Discord actions + observability) | +| `VOLTOPS_DISCORD_CREDENTIAL_ID` | Credential ID from your Discord action binding (stored credential path) | +| `VOLTOPS_DISCORD_CATALOG_ID` | Optional catalog/binding ID for stored credentials | +| `DISCORD_BOT_TOKEN` / `DISCORD_WEBHOOK_URL` | Inline credential option – provide a bot token or webhook URL instead of a stored credential | +| `DISCORD_CHANNEL_ID` / `DISCORD_GUILD_ID` | Target Discord channel + guild (defaults to the binding’s config when omitted) | +| `GITHUB_TOKEN` | Personal access token with basic read access | +| `GITHUB_TARGET_REPO` / `GITHUB_TARGET_REPO_URL` | Repo name/URL to reference in stories | + +## Wiring to VoltOps triggers + +To celebrate real GitHub stars: + +1. Add the GitHub “Repository Starred” trigger in VoltOps +2. When the trigger fires, queue a VoltOps action or workflow that calls this agent with `celebrate ` +3. The toolchain ensures Discord gets the story automatically + +That’s it—no extra routes or boilerplate required. diff --git a/examples/github-star-stories/package.json b/examples/github-star-stories/package.json new file mode 100644 index 000000000..69453ec78 --- /dev/null +++ b/examples/github-star-stories/package.json @@ -0,0 +1,41 @@ +{ + "name": "voltagent-example-github-star-stories", + "version": "0.0.0", + "dependencies": { + "@voltagent/cli": "^0.1.21", + "@voltagent/core": "^2.9.1", + "@voltagent/logger": "^2.0.2", + "@voltagent/server-hono": "^2.0.14", + "@voltagent/serverless-hono": "^2.0.12", + "dotenv": "^16.4.5", + "wrangler": "^3.38.0", + "zod": "^3.25.76" + }, + "devDependencies": { + "@types/node": "^24.2.1", + "tsx": "^4.21.0", + "typescript": "^5.8.2" + }, + "keywords": [ + "agent", + "ai", + "discord", + "github", + "voltagent" + ], + "private": true, + "repository": { + "type": "git", + "url": "https://github.com/VoltAgent/voltagent.git", + "directory": "examples/github-star-stories" + }, + "scripts": { + "build": "tsc", + "deploy": "wrangler deploy", + "dev": "tsx watch --env-file=.env ./src/index.ts", + "preview": "tsc && wrangler dev --local", + "start": "node dist/index.js", + "volt": "volt" + }, + "type": "module" +} diff --git a/examples/github-star-stories/src/index.ts b/examples/github-star-stories/src/index.ts new file mode 100644 index 000000000..f040d377d --- /dev/null +++ b/examples/github-star-stories/src/index.ts @@ -0,0 +1,56 @@ +import "dotenv/config"; +import { Agent, VoltAgent, VoltOpsClient, createTool, createTriggers } from "@voltagent/core"; +import { createPinoLogger } from "@voltagent/logger"; +/* import { honoServer } from "@voltagent/server-hono"; */ +import { serverlessHono } from "@voltagent/serverless-hono"; +import { fetchGithubProfileTool, shareDiscordStoryTool } from "./tools.js"; + +const logger = createPinoLogger({ + name: "github-star-stories", + level: "info", +}); + +const storytellerAgent = new Agent({ + name: "StarStoryAgent", + model: "openai/gpt-4o-mini", + tools: [fetchGithubProfileTool, shareDiscordStoryTool], + instructions: `You celebrate developers who star our GitHub repository with fun and creative messages! + +When the user says "celebrate ", do the following: +1. Call fetch_github_profile with that username. +2. Create a fun, creative celebration message (3-4 sentences, <120 words) that: + - Thanks them for the star with enthusiasm and humor + - Mentions 1-2 interesting stats from their profile (followers, repos, location, etc.) + - Uses emojis to make it lively (🌟⭐🎉🚀💫) + - Has a playful, friendly tone +3. Call share_discord_story with a catchy headline (use emojis!) and the celebration message. + +Be creative! You can use puns, jokes, or references based on their username or location. Make each celebration unique and memorable.`, +}); + +interface GitHubStarPayload { + action: "created" | "deleted"; + starred_at: string | null; + sender: { login: string; id: number; avatar_url: string }; + repository: { id: number; name: string; full_name: string }; +} + +// For Serverless +const voltAgent = new VoltAgent({ + agents: { + storyteller: storytellerAgent, + }, + triggers: createTriggers((on) => { + on.github.star(async ({ payload }) => { + const star = payload as GitHubStarPayload; + if (star.action !== "created") return { skip: true, reason: "Unstarred" }; + await storytellerAgent.generateText(`celebrate '${star.sender.login}'`); + }); + }), + logger, + serverless: serverlessHono(), + // For REST Server + // server: honoServer(), +}); + +export default voltAgent.serverless().toCloudflareWorker(); diff --git a/examples/github-star-stories/src/tools.ts b/examples/github-star-stories/src/tools.ts new file mode 100644 index 000000000..aa2424280 --- /dev/null +++ b/examples/github-star-stories/src/tools.ts @@ -0,0 +1,67 @@ +import { VoltOpsClient, createTool } from "@voltagent/core"; +import { z } from "zod"; + +export const fetchGithubProfileTool = createTool({ + name: "fetch_github_profile", + description: "Fetch GitHub profile metadata (followers, repos, location, etc.)", + parameters: z.object({ + username: z.string().describe("GitHub username to inspect"), + }), + execute: async ({ username }) => { + console.log(process.env.GITHUB_TOKEN); + try { + const response = await fetch(`https://api.github.com/users/${username}`, { + method: "GET", + headers: { + Authorization: `Bearer ${process.env.GITHUB_TOKEN}`, + "X-GitHub-Api-Version": "2022-11-28", + "User-Agent": "Cloudflare-Workers/1.0", + }, + }); + + if (!response.ok) { + throw new Error(`Failed to fetch GitHub profile: ${response.statusText}`); + } + + const data = await response.json(); + + return { + login: data.login, + name: data.name ?? data.login, + bio: data.bio, + followers: data.followers, + publicRepos: data.public_repos, + location: data.location, + url: data.html_url, + }; + } catch (error) { + console.log(error); + } + }, +}); + +export const shareDiscordStoryTool = createTool({ + name: "share_discord_story", + description: "Send the celebration story to Discord via VoltOps Actions.", + parameters: z.object({ + headline: z.string().describe("Short headline announcing the star"), + story: z.string().describe("Markdown formatted story"), + }), + execute: async ({ headline, story }: { headline: string; story: string }) => { + const voltOpsClient = new VoltOpsClient({ + publicKey: process.env.VOLTAGENT_PUBLIC_KEY, + secretKey: process.env.VOLTAGENT_SECRET_KEY, + }); + + await voltOpsClient.actions.discord.sendMessage({ + credential: { + credentialId: process.env.VOLTAGENT_CREDENTIAL_ID || "", + }, + channelId: "1438213235114246285", + guildId: "1361559153780195478", + content: `${headline}\n\n${story}`, + }); + + return { delivered: true }; + }, +}); diff --git a/examples/with-xsai/tsconfig.json b/examples/github-star-stories/tsconfig.json similarity index 100% rename from examples/with-xsai/tsconfig.json rename to examples/github-star-stories/tsconfig.json diff --git a/examples/github-star-stories/wrangler.toml b/examples/github-star-stories/wrangler.toml new file mode 100644 index 000000000..5c5bd9908 --- /dev/null +++ b/examples/github-star-stories/wrangler.toml @@ -0,0 +1,18 @@ +# Generated by VoltAgent CLI +name = "voltagent-worker" +main = "dist/index.js" +compatibility_date = "2025-01-01" +account_id = "" +workers_dev = true +compatibility_flags = [ + "nodejs_compat", + "nodejs_compat_populate_process_env", + "no_handle_cross_request_promise_resolution", +] + +[observability] +[observability.logs] +enabled = true +head_sampling_rate = 1 +invocation_logs = true +persist = true \ No newline at end of file diff --git a/examples/next-js-chatbot-starter-template/.env.example b/examples/next-js-chatbot-starter-template/.env.example new file mode 100644 index 000000000..c6e224e4f --- /dev/null +++ b/examples/next-js-chatbot-starter-template/.env.example @@ -0,0 +1,38 @@ +# ========================================== +# AI Provider Configuration +# ========================================== +# Choose your AI provider by setting AI_PROVIDER +# Options: "openai", "anthropic", "google", "groq" +AI_PROVIDER=openai + +# ========================================== +# OpenAI Configuration +# ========================================== +# Get your API key from: https://platform.openai.com/api-keys +OPENAI_API_KEY=sk-your-openai-api-key-here +# Optional: Override default model +# OPENAI_MODEL=gpt-4o-mini + +# ========================================== +# Anthropic Configuration +# ========================================== +# Get your API key from: https://console.anthropic.com/ +ANTHROPIC_API_KEY=sk-your-anthropic-api-key-here +# Optional: Override default model +# ANTHROPIC_MODEL=claude-3-5-sonnet-20241022 + +# ========================================== +# Google AI Configuration +# ========================================== +# Get your API key from: https://makersuite.google.com/app/apikey +GOOGLE_API_KEY=your-google-ai-api-key-here +# Optional: Override default model +# GOOGLE_MODEL=gemini-2.0-flash-exp + +# ========================================== +# Groq Configuration +# ========================================== +# Get your API key from: https://console.groq.com/keys +GROQ_API_KEY=your-groq-api-key-here +# Optional: Override default model +# GROQ_MODEL=llama-3.3-70b-versatile diff --git a/examples/next-js-chatbot-starter-template/.gitignore b/examples/next-js-chatbot-starter-template/.gitignore new file mode 100644 index 000000000..664b5f9f9 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/.gitignore @@ -0,0 +1,45 @@ +# See https://help.github.com/articles/ignoring-files/ for more about ignoring files. + +# dependencies +/node_modules +/.pnp +.pnp.* +.yarn/* +!.yarn/patches +!.yarn/plugins +!.yarn/releases +!.yarn/versions + +# testing +/coverage + +# next.js +/.next/ +/out/ + +# production +/build + +# misc +.DS_Store +*.pem + +# debug +npm-debug.log* +yarn-debug.log* +yarn-error.log* +.pnpm-debug.log* + +# env files (can opt-in for committing if needed) +.env* +!.env.example + +# voltagent +.voltagent/ + +# vercel +.vercel + +# typescript +*.tsbuildinfo +next-env.d.ts diff --git a/examples/next-js-chatbot-starter-template/README.md b/examples/next-js-chatbot-starter-template/README.md new file mode 100644 index 000000000..8aab222d7 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/README.md @@ -0,0 +1,64 @@ +
+ +435380213-b6253409-8741-462b-a346-834cd18565a9 + + +
+
+ + +
+ +
+ +
+ VoltAgent is an open source TypeScript framework for building and orchestrating AI agents.
+Escape the limitations of no-code builders and the complexity of starting from scratch. +
+
+
+ +
+ +[![npm version](https://img.shields.io/npm/v/@voltagent/core.svg)](https://www.npmjs.com/package/@voltagent/core) +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](CODE_OF_CONDUCT.md) +[![Discord](https://img.shields.io/discord/1361559153780195478.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://s.voltagent.dev/discord) +[![Twitter Follow](https://img.shields.io/twitter/follow/voltagent_dev?style=social)](https://twitter.com/voltagent_dev) + +
+ +
+ +
+ +VoltAgent Schema + + +
+ +## VoltAgent: Build AI Agents Fast and Flexibly + +VoltAgent is an open-source TypeScript framework for creating and managing AI agents. It provides modular components to build, customize, and scale agents with ease. From connecting to APIs and memory management to supporting multiple LLMs, VoltAgent simplifies the process of creating sophisticated AI systems. It enables fast development, maintains clean code, and offers flexibility to switch between models and tools without vendor lock-in. + +## Try Example + +```bash +npm create voltagent-app@latest -- --example next-js-chatbot-starter-template +``` + +## Run the Example + +Run the Next.js app and the VoltAgent built-in server in separate terminals: + +```bash +pnpm dev +pnpm voltagent:run +``` + +Then open `https://console.voltagent.dev` and connect it to `http://localhost:3141`. diff --git a/examples/next-js-chatbot-starter-template/app/api/chat/route.ts b/examples/next-js-chatbot-starter-template/app/api/chat/route.ts new file mode 100644 index 000000000..dcf502bc6 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/app/api/chat/route.ts @@ -0,0 +1,55 @@ +import { validateAIConfig } from "@/lib/ai/config"; +import type { ChatRequest } from "@/lib/types/api"; +import { chatbotAgent } from "@/voltagent"; + +export async function POST(req: Request) { + try { + // Validate AI configuration first + const configValidation = validateAIConfig(); + if (!configValidation.valid) { + return new Response( + JSON.stringify({ + error: + configValidation.error || + "Invalid AI configuration. Please check your .env.local file.", + }), + { + status: 500, + headers: { "Content-Type": "application/json" }, + }, + ); + } + + const body: ChatRequest = await req.json(); + const { messages, conversationId = "default", userId = "user-1" } = body; + + // Validate request + if (!messages || !Array.isArray(messages) || messages.length === 0) { + return new Response(JSON.stringify({ error: "Messages array is required" }), { + status: 400, + headers: { "Content-Type": "application/json" }, + }); + } + + // Stream response with tool invocations support + const result = await chatbotAgent.streamText(messages, { + userId, + conversationId, + }); + + // Use toUIMessageStreamResponse to properly handle tool calls + return result.toUIMessageStreamResponse(); + } catch (error) { + console.error("Chat API error:", error); + + return new Response( + JSON.stringify({ + error: error instanceof Error ? error.message : "Internal server error", + }), + { + status: 500, + headers: { "Content-Type": "application/json" }, + }, + ); + } +} diff --git a/examples/next-js-chatbot-starter-template/app/favicon.ico b/examples/next-js-chatbot-starter-template/app/favicon.ico new file mode 100644 index 000000000..718d6fea4 Binary files /dev/null and b/examples/next-js-chatbot-starter-template/app/favicon.ico differ diff --git a/examples/next-js-chatbot-starter-template/app/globals.css b/examples/next-js-chatbot-starter-template/app/globals.css new file mode 100644 index 000000000..4546af1b7 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/app/globals.css @@ -0,0 +1,330 @@ +@import "tailwindcss"; +@import "tw-animate-css"; + +@custom-variant dark (&:is(.dark *)); + +:root { + --emerald-50: #ecfdf5; + --emerald-100: #d1fae5; + --emerald-500: #10b981; + --emerald-600: #059669; + --emerald-900: #064e3b; + --radius: 0.625rem; + --background: oklch(1 0 0); + --foreground: oklch(0.145 0 0); + --card: oklch(1 0 0); + --card-foreground: oklch(0.145 0 0); + --popover: oklch(1 0 0); + --popover-foreground: oklch(0.145 0 0); + --primary: oklch(0.205 0 0); + --primary-foreground: oklch(0.985 0 0); + --secondary: oklch(0.97 0 0); + --secondary-foreground: oklch(0.205 0 0); + --muted: oklch(0.97 0 0); + --muted-foreground: oklch(0.556 0 0); + --accent: oklch(0.97 0 0); + --accent-foreground: oklch(0.205 0 0); + --destructive: oklch(0.577 0.245 27.325); + --border: oklch(0.922 0 0); + --input: oklch(0.922 0 0); + --ring: oklch(0.708 0 0); + --chart-1: oklch(0.646 0.222 41.116); + --chart-2: oklch(0.6 0.118 184.704); + --chart-3: oklch(0.398 0.07 227.392); + --chart-4: oklch(0.828 0.189 84.429); + --chart-5: oklch(0.769 0.188 70.08); + --sidebar: oklch(0.985 0 0); + --sidebar-foreground: oklch(0.145 0 0); + --sidebar-primary: oklch(0.205 0 0); + --sidebar-primary-foreground: oklch(0.985 0 0); + --sidebar-accent: oklch(0.97 0 0); + --sidebar-accent-foreground: oklch(0.205 0 0); + --sidebar-border: oklch(0.922 0 0); + --sidebar-ring: oklch(0.708 0 0); +} + +@theme inline { + --color-background: var(--background); + --color-foreground: var(--foreground); + --font-sans: var(--font-geist-sans); + --font-mono: var(--font-geist-mono); + --color-sidebar-ring: var(--sidebar-ring); + --color-sidebar-border: var(--sidebar-border); + --color-sidebar-accent-foreground: var(--sidebar-accent-foreground); + --color-sidebar-accent: var(--sidebar-accent); + --color-sidebar-primary-foreground: var(--sidebar-primary-foreground); + --color-sidebar-primary: var(--sidebar-primary); + --color-sidebar-foreground: var(--sidebar-foreground); + --color-sidebar: var(--sidebar); + --color-chart-5: var(--chart-5); + --color-chart-4: var(--chart-4); + --color-chart-3: var(--chart-3); + --color-chart-2: var(--chart-2); + --color-chart-1: var(--chart-1); + --color-ring: var(--ring); + --color-input: var(--input); + --color-border: var(--border); + --color-destructive: var(--destructive); + --color-accent-foreground: var(--accent-foreground); + --color-accent: var(--accent); + --color-muted-foreground: var(--muted-foreground); + --color-muted: var(--muted); + --color-secondary-foreground: var(--secondary-foreground); + --color-secondary: var(--secondary); + --color-primary-foreground: var(--primary-foreground); + --color-primary: var(--primary); + --color-popover-foreground: var(--popover-foreground); + --color-popover: var(--popover); + --color-card-foreground: var(--card-foreground); + --color-card: var(--card); + --radius-sm: calc(var(--radius) - 4px); + --radius-md: calc(var(--radius) - 2px); + --radius-lg: var(--radius); + --radius-xl: calc(var(--radius) + 4px); +} + +body { + font-family: var(--font-geist-sans), system-ui, -apple-system, sans-serif; +} + +/* Custom scrollbar for messages */ +.messages-container::-webkit-scrollbar { + width: 8px; +} + +.messages-container::-webkit-scrollbar-track { + background: rgba(16, 185, 129, 0.05); + border-radius: 4px; +} + +.messages-container::-webkit-scrollbar-thumb { + background: rgba(16, 185, 129, 0.2); + border-radius: 4px; +} + +.messages-container::-webkit-scrollbar-thumb:hover { + background: rgba(16, 185, 129, 0.3); +} + +/* Smooth animations */ +@keyframes slideInUp { + from { + opacity: 0; + transform: translateY(10px); + } + to { + opacity: 1; + transform: translateY(0); + } +} + +.message-animate { + animation: slideInUp 0.3s ease-out; +} + +/* Code block styling */ +pre { + overflow-x: auto; + padding: 0.75rem; + border-radius: 0.5rem; + background: rgba(0, 0, 0, 0.2); + font-size: 0.875rem; + line-height: 1.5; +} + +code { + font-family: var(--font-geist-mono), monospace; +} + +/* Markdown content styling */ +.markdown-content { + font-size: 0.9375rem; + line-height: 1.7; + color: #e5e7eb; +} + +/* Code syntax highlighting overrides for dark theme */ +.markdown-content pre code.hljs { + background: transparent; + padding: 0; + display: block; +} + +.markdown-content .hljs { + color: #e5e7eb; + background: #0d1117; +} + +.markdown-content .hljs-comment, +.markdown-content .hljs-quote { + color: #8b949e; + font-style: italic; +} + +.markdown-content .hljs-keyword, +.markdown-content .hljs-selector-tag, +.markdown-content .hljs-subst { + color: #ff7b72; +} + +.markdown-content .hljs-number, +.markdown-content .hljs-literal, +.markdown-content .hljs-variable, +.markdown-content .hljs-template-variable, +.markdown-content .hljs-tag .hljs-attr { + color: #79c0ff; +} + +.markdown-content .hljs-string, +.markdown-content .hljs-doctag { + color: #a5d6ff; +} + +.markdown-content .hljs-title, +.markdown-content .hljs-section, +.markdown-content .hljs-selector-id { + color: #d2a8ff; + font-weight: bold; +} + +.markdown-content .hljs-subst { + font-weight: normal; +} + +.markdown-content .hljs-type, +.markdown-content .hljs-class .hljs-title { + color: #ffa657; + font-weight: bold; +} + +.markdown-content .hljs-tag, +.markdown-content .hljs-name, +.markdown-content .hljs-attribute { + color: #7ee787; + font-weight: normal; +} + +.markdown-content .hljs-regexp, +.markdown-content .hljs-link { + color: #a5d6ff; +} + +.markdown-content .hljs-symbol, +.markdown-content .hljs-bullet { + color: #ffa657; +} + +.markdown-content .hljs-built_in, +.markdown-content .hljs-builtin-name { + color: #ffa657; +} + +.markdown-content .hljs-meta { + color: #79c0ff; +} + +.markdown-content .hljs-deletion { + background: #490202; +} + +.markdown-content .hljs-addition { + background: #1c4220; +} + +.markdown-content .hljs-emphasis { + font-style: italic; +} + +.markdown-content .hljs-strong { + font-weight: bold; +} + +/* Ensure proper spacing in markdown lists */ +.markdown-content ul ul, +.markdown-content ol ul, +.markdown-content ul ol, +.markdown-content ol ol { + margin-top: 0.5rem; + margin-bottom: 0.5rem; +} + +/* Task lists */ +.markdown-content input[type="checkbox"] { + margin-right: 0.5rem; + cursor: pointer; +} + +.dark { + --background: oklch(0.145 0 0); + --foreground: oklch(0.985 0 0); + --card: oklch(0.205 0 0); + --card-foreground: oklch(0.985 0 0); + --popover: oklch(0.205 0 0); + --popover-foreground: oklch(0.985 0 0); + --primary: oklch(0.922 0 0); + --primary-foreground: oklch(0.205 0 0); + --secondary: oklch(0.269 0 0); + --secondary-foreground: oklch(0.985 0 0); + --muted: oklch(0.269 0 0); + --muted-foreground: oklch(0.708 0 0); + --accent: oklch(0.269 0 0); + --accent-foreground: oklch(0.985 0 0); + --destructive: oklch(0.704 0.191 22.216); + --border: oklch(1 0 0 / 10%); + --input: oklch(1 0 0 / 15%); + --ring: oklch(0.556 0 0); + --chart-1: oklch(0.488 0.243 264.376); + --chart-2: oklch(0.696 0.17 162.48); + --chart-3: oklch(0.769 0.188 70.08); + --chart-4: oklch(0.627 0.265 303.9); + --chart-5: oklch(0.645 0.246 16.439); + --sidebar: oklch(0.205 0 0); + --sidebar-foreground: oklch(0.985 0 0); + --sidebar-primary: oklch(0.488 0.243 264.376); + --sidebar-primary-foreground: oklch(0.985 0 0); + --sidebar-accent: oklch(0.269 0 0); + --sidebar-accent-foreground: oklch(0.985 0 0); + --sidebar-border: oklch(1 0 0 / 10%); + --sidebar-ring: oklch(0.556 0 0); +} + +@layer base { + * { + @apply border-border outline-ring/50; + } + body { + @apply bg-background text-foreground antialiased; + } +} + +/* Clean v0-style enhancements */ +@layer components { + /* Smooth transitions */ + * { + @apply transition-colors duration-200; + } + + /* Clean scrollbar */ + *::-webkit-scrollbar { + width: 6px; + height: 6px; + } + + *::-webkit-scrollbar-track { + background: transparent; + } + + *::-webkit-scrollbar-thumb { + background: hsl(var(--muted-foreground) / 0.2); + border-radius: 3px; + } + + *::-webkit-scrollbar-thumb:hover { + background: hsl(var(--muted-foreground) / 0.3); + } + + /* Clean focus states */ + :focus-visible { + @apply outline-none ring-2 ring-ring ring-offset-2 ring-offset-background; + } +} diff --git a/examples/next-js-chatbot-starter-template/app/layout.tsx b/examples/next-js-chatbot-starter-template/app/layout.tsx new file mode 100644 index 000000000..fe8b5f7c1 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/app/layout.tsx @@ -0,0 +1,37 @@ +import type { Metadata } from "next"; +import { Geist, Geist_Mono } from "next/font/google"; +import { Toaster } from "sonner"; +import "./globals.css"; + +const geistSans = Geist({ + variable: "--font-geist-sans", + subsets: ["latin"], +}); + +const geistMono = Geist_Mono({ + variable: "--font-geist-mono", + subsets: ["latin"], +}); + +export const metadata: Metadata = { + title: "VoltAgent Chatbot - Next.js Starter Template", + description: "A modern chatbot starter template built with Next.js and VoltAgent", +}; + +export default function RootLayout({ + children, +}: Readonly<{ + children: React.ReactNode; +}>) { + return ( + + + {children} + + + + ); +} diff --git a/examples/next-js-chatbot-starter-template/app/page.tsx b/examples/next-js-chatbot-starter-template/app/page.tsx new file mode 100644 index 000000000..e80efa647 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/app/page.tsx @@ -0,0 +1,5 @@ +import { ChatInterface } from "../components/chat-interface"; + +export default function Home() { + return ; +} diff --git a/examples/next-js-chatbot-starter-template/components.json b/examples/next-js-chatbot-starter-template/components.json new file mode 100644 index 000000000..5d989a5d7 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components.json @@ -0,0 +1,24 @@ +{ + "$schema": "https://ui.shadcn.com/schema.json", + "style": "new-york", + "rsc": true, + "tsx": true, + "tailwind": { + "config": "", + "css": "app/globals.css", + "baseColor": "neutral", + "cssVariables": true, + "prefix": "" + }, + "iconLibrary": "lucide", + "aliases": { + "components": "@/components", + "utils": "@/lib/utils", + "ui": "@/components/ui", + "lib": "@/lib", + "hooks": "@/hooks" + }, + "registries": { + "@ai-elements": "https://registry.ai-sdk.dev/{name}.json" + } +} diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/actions.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/actions.tsx new file mode 100644 index 000000000..dbd19b11a --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/actions.tsx @@ -0,0 +1,57 @@ +"use client"; + +import { Button } from "@/components/ui/button"; +import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip"; +import { cn } from "@/lib/utils"; +import type { ComponentProps } from "react"; + +export type ActionsProps = ComponentProps<"div">; + +export const Actions = ({ className, children, ...props }: ActionsProps) => ( +
+ {children} +
+); + +export type ActionProps = ComponentProps & { + tooltip?: string; + label?: string; +}; + +export const Action = ({ + tooltip, + children, + label, + className, + variant = "ghost", + size = "sm", + ...props +}: ActionProps) => { + const button = ( + + ); + + if (tooltip) { + return ( + + + {button} + +

{tooltip}

+ + + + ); + } + + return button; +}; diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/artifact.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/artifact.tsx new file mode 100644 index 000000000..898b6d403 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/artifact.tsx @@ -0,0 +1,118 @@ +"use client"; + +import { Button } from "@/components/ui/button"; +import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip"; +import { cn } from "@/lib/utils"; +import { type LucideIcon, XIcon } from "lucide-react"; +import type { ComponentProps, HTMLAttributes } from "react"; + +export type ArtifactProps = HTMLAttributes; + +export const Artifact = ({ className, ...props }: ArtifactProps) => ( +
+); + +export type ArtifactHeaderProps = HTMLAttributes; + +export const ArtifactHeader = ({ className, ...props }: ArtifactHeaderProps) => ( +
+); + +export type ArtifactCloseProps = ComponentProps; + +export const ArtifactClose = ({ + className, + children, + size = "sm", + variant = "ghost", + ...props +}: ArtifactCloseProps) => ( + +); + +export type ArtifactTitleProps = HTMLAttributes; + +export const ArtifactTitle = ({ className, ...props }: ArtifactTitleProps) => ( +

+); + +export type ArtifactDescriptionProps = HTMLAttributes; + +export const ArtifactDescription = ({ className, ...props }: ArtifactDescriptionProps) => ( +

+); + +export type ArtifactActionsProps = HTMLAttributes; + +export const ArtifactActions = ({ className, ...props }: ArtifactActionsProps) => ( +

+); + +export type ArtifactActionProps = ComponentProps & { + tooltip?: string; + label?: string; + icon?: LucideIcon; +}; + +export const ArtifactAction = ({ + tooltip, + label, + icon: Icon, + children, + className, + size = "sm", + variant = "ghost", + ...props +}: ArtifactActionProps) => { + const button = ( + + ); + + if (tooltip) { + return ( + + + {button} + +

{tooltip}

+ + + + ); + } + + return button; +}; + +export type ArtifactContentProps = HTMLAttributes; + +export const ArtifactContent = ({ className, ...props }: ArtifactContentProps) => ( +
+); diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/branch.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/branch.tsx new file mode 100644 index 000000000..06db0d8c1 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/branch.tsx @@ -0,0 +1,190 @@ +"use client"; + +import { Button } from "@/components/ui/button"; +import { cn } from "@/lib/utils"; +import type { UIMessage } from "ai"; +import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react"; +import type { ComponentProps, HTMLAttributes, ReactElement } from "react"; +import { createContext, useContext, useEffect, useMemo, useState } from "react"; + +type BranchContextType = { + currentBranch: number; + totalBranches: number; + goToPrevious: () => void; + goToNext: () => void; + branches: ReactElement[]; + setBranches: (branches: ReactElement[]) => void; +}; + +const BranchContext = createContext(null); + +const useBranch = () => { + const context = useContext(BranchContext); + + if (!context) { + throw new Error("Branch components must be used within Branch"); + } + + return context; +}; + +export type BranchProps = HTMLAttributes & { + defaultBranch?: number; + onBranchChange?: (branchIndex: number) => void; +}; + +export const Branch = ({ defaultBranch = 0, onBranchChange, className, ...props }: BranchProps) => { + const [currentBranch, setCurrentBranch] = useState(defaultBranch); + const [branches, setBranches] = useState([]); + + const handleBranchChange = (newBranch: number) => { + setCurrentBranch(newBranch); + onBranchChange?.(newBranch); + }; + + const goToPrevious = () => { + const newBranch = currentBranch > 0 ? currentBranch - 1 : branches.length - 1; + handleBranchChange(newBranch); + }; + + const goToNext = () => { + const newBranch = currentBranch < branches.length - 1 ? currentBranch + 1 : 0; + handleBranchChange(newBranch); + }; + + const contextValue: BranchContextType = { + currentBranch, + totalBranches: branches.length, + goToPrevious, + goToNext, + branches, + setBranches, + }; + + return ( + +
div]:pb-0", className)} {...props} /> + + ); +}; + +export type BranchMessagesProps = HTMLAttributes; + +export const BranchMessages = ({ children, ...props }: BranchMessagesProps) => { + const { currentBranch, setBranches, branches } = useBranch(); + const childrenArray = useMemo( + () => (Array.isArray(children) ? children : [children]), + [children], + ); + + // Use useEffect to update branches when they change + useEffect(() => { + if (branches.length !== childrenArray.length) { + setBranches(childrenArray); + } + }, [childrenArray, branches, setBranches]); + + return childrenArray.map((branch, index) => ( +
div]:pb-0", + index === currentBranch ? "block" : "hidden", + )} + key={branch.key} + {...props} + > + {branch} +
+ )); +}; + +export type BranchSelectorProps = HTMLAttributes & { + from: UIMessage["role"]; +}; + +export const BranchSelector = ({ className, from, ...props }: BranchSelectorProps) => { + const { totalBranches } = useBranch(); + + // Don't render if there's only one branch + if (totalBranches <= 1) { + return null; + } + + return ( +
+ ); +}; + +export type BranchPreviousProps = ComponentProps; + +export const BranchPrevious = ({ className, children, ...props }: BranchPreviousProps) => { + const { goToPrevious, totalBranches } = useBranch(); + + return ( + + ); +}; + +export type BranchNextProps = ComponentProps; + +export const BranchNext = ({ className, children, ...props }: BranchNextProps) => { + const { goToNext, totalBranches } = useBranch(); + + return ( + + ); +}; + +export type BranchPageProps = HTMLAttributes; + +export const BranchPage = ({ className, ...props }: BranchPageProps) => { + const { currentBranch, totalBranches } = useBranch(); + + return ( + + {currentBranch + 1} of {totalBranches} + + ); +}; diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/canvas.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/canvas.tsx new file mode 100644 index 000000000..e0466aef5 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/canvas.tsx @@ -0,0 +1,24 @@ +import { Background, ReactFlow, type ReactFlowProps } from "@xyflow/react"; +import type { ReactNode } from "react"; +import "@xyflow/react/dist/style.css"; +import { Controls } from "./controls"; + +type CanvasProps = ReactFlowProps & { + children?: ReactNode; +}; + +export const Canvas = ({ children, ...props }: CanvasProps) => ( + + + + {children} + +); diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/chain-of-thought.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/chain-of-thought.tsx new file mode 100644 index 000000000..87bb307bf --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/chain-of-thought.tsx @@ -0,0 +1,198 @@ +"use client"; + +import { Badge } from "@/components/ui/badge"; +import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible"; +import { cn } from "@/lib/utils"; +import { useControllableState } from "@radix-ui/react-use-controllable-state"; +import { BrainIcon, ChevronDownIcon, DotIcon, type LucideIcon } from "lucide-react"; +import type { ComponentProps } from "react"; +import { createContext, memo, useContext, useMemo } from "react"; + +type ChainOfThoughtContextValue = { + isOpen: boolean; + setIsOpen: (open: boolean) => void; +}; + +const ChainOfThoughtContext = createContext(null); + +const useChainOfThought = () => { + const context = useContext(ChainOfThoughtContext); + if (!context) { + throw new Error("ChainOfThought components must be used within ChainOfThought"); + } + return context; +}; + +export type ChainOfThoughtProps = ComponentProps<"div"> & { + open?: boolean; + defaultOpen?: boolean; + onOpenChange?: (open: boolean) => void; +}; + +export const ChainOfThought = memo( + ({ + className, + open, + defaultOpen = false, + onOpenChange, + children, + ...props + }: ChainOfThoughtProps) => { + const [isOpen, setIsOpen] = useControllableState({ + prop: open, + defaultProp: defaultOpen, + onChange: onOpenChange, + }); + + const chainOfThoughtContext = useMemo(() => ({ isOpen, setIsOpen }), [isOpen, setIsOpen]); + + return ( + +
+ {children} +
+ + ); + }, +); + +export type ChainOfThoughtHeaderProps = ComponentProps; + +export const ChainOfThoughtHeader = memo( + ({ className, children, ...props }: ChainOfThoughtHeaderProps) => { + const { isOpen, setIsOpen } = useChainOfThought(); + + return ( + + + + {children ?? "Chain of Thought"} + + + + ); + }, +); + +export type ChainOfThoughtStepProps = ComponentProps<"div"> & { + icon?: LucideIcon; + label: string; + description?: string; + status?: "complete" | "active" | "pending"; +}; + +export const ChainOfThoughtStep = memo( + ({ + className, + icon: Icon = DotIcon, + label, + description, + status = "complete", + children, + ...props + }: ChainOfThoughtStepProps) => { + const statusStyles = { + complete: "text-muted-foreground", + active: "text-foreground", + pending: "text-muted-foreground/50", + }; + + return ( +
+
+ +
+
+
+
{label}
+ {description &&
{description}
} + {children} +
+
+ ); + }, +); + +export type ChainOfThoughtSearchResultsProps = ComponentProps<"div">; + +export const ChainOfThoughtSearchResults = memo( + ({ className, ...props }: ChainOfThoughtSearchResultsProps) => ( +
+ ), +); + +export type ChainOfThoughtSearchResultProps = ComponentProps; + +export const ChainOfThoughtSearchResult = memo( + ({ className, children, ...props }: ChainOfThoughtSearchResultProps) => ( + + {children} + + ), +); + +export type ChainOfThoughtContentProps = ComponentProps; + +export const ChainOfThoughtContent = memo( + ({ className, children, ...props }: ChainOfThoughtContentProps) => { + const { isOpen } = useChainOfThought(); + + return ( + + + {children} + + + ); + }, +); + +export type ChainOfThoughtImageProps = ComponentProps<"div"> & { + caption?: string; +}; + +export const ChainOfThoughtImage = memo( + ({ className, children, caption, ...props }: ChainOfThoughtImageProps) => ( +
+
+ {children} +
+ {caption &&

{caption}

} +
+ ), +); + +ChainOfThought.displayName = "ChainOfThought"; +ChainOfThoughtHeader.displayName = "ChainOfThoughtHeader"; +ChainOfThoughtStep.displayName = "ChainOfThoughtStep"; +ChainOfThoughtSearchResults.displayName = "ChainOfThoughtSearchResults"; +ChainOfThoughtSearchResult.displayName = "ChainOfThoughtSearchResult"; +ChainOfThoughtContent.displayName = "ChainOfThoughtContent"; +ChainOfThoughtImage.displayName = "ChainOfThoughtImage"; diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/code-block.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/code-block.tsx new file mode 100644 index 000000000..8b29ca1de --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/code-block.tsx @@ -0,0 +1,175 @@ +"use client"; + +import { Button } from "@/components/ui/button"; +import { cn } from "@/lib/utils"; +import type { Element } from "hast"; +import { CheckIcon, CopyIcon } from "lucide-react"; +import { + type ComponentProps, + type HTMLAttributes, + createContext, + useContext, + useEffect, + useRef, + useState, +} from "react"; +import { type BundledLanguage, type ShikiTransformer, codeToHtml } from "shiki"; + +type CodeBlockProps = HTMLAttributes & { + code: string; + language: BundledLanguage; + showLineNumbers?: boolean; +}; + +type CodeBlockContextType = { + code: string; +}; + +const CodeBlockContext = createContext({ + code: "", +}); + +const lineNumberTransformer: ShikiTransformer = { + name: "line-numbers", + line(node: Element, line: number) { + node.children.unshift({ + type: "element", + tagName: "span", + properties: { + className: [ + "inline-block", + "min-w-10", + "mr-4", + "text-right", + "select-none", + "text-muted-foreground", + ], + }, + children: [{ type: "text", value: String(line) }], + }); + }, +}; + +export async function highlightCode( + code: string, + language: BundledLanguage, + showLineNumbers = false, +) { + const transformers: ShikiTransformer[] = showLineNumbers ? [lineNumberTransformer] : []; + + return await Promise.all([ + codeToHtml(code, { + lang: language, + theme: "one-light", + transformers, + }), + codeToHtml(code, { + lang: language, + theme: "one-dark-pro", + transformers, + }), + ]); +} + +export const CodeBlock = ({ + code, + language, + showLineNumbers = false, + className, + children, + ...props +}: CodeBlockProps) => { + const [html, setHtml] = useState(""); + const [darkHtml, setDarkHtml] = useState(""); + const mounted = useRef(false); + + useEffect(() => { + highlightCode(code, language, showLineNumbers).then(([light, dark]) => { + if (!mounted.current) { + setHtml(light); + setDarkHtml(dark); + mounted.current = true; + } + }); + + return () => { + mounted.current = false; + }; + }, [code, language, showLineNumbers]); + + return ( + +
+
+
+
+ {children && ( +
{children}
+ )} +
+
+ + ); +}; + +export type CodeBlockCopyButtonProps = ComponentProps & { + onCopy?: () => void; + onError?: (error: Error) => void; + timeout?: number; +}; + +export const CodeBlockCopyButton = ({ + onCopy, + onError, + timeout = 2000, + children, + className, + ...props +}: CodeBlockCopyButtonProps) => { + const [isCopied, setIsCopied] = useState(false); + const { code } = useContext(CodeBlockContext); + + const copyToClipboard = async () => { + if (typeof window === "undefined" || !navigator?.clipboard?.writeText) { + onError?.(new Error("Clipboard API not available")); + return; + } + + try { + await navigator.clipboard.writeText(code); + setIsCopied(true); + onCopy?.(); + setTimeout(() => setIsCopied(false), timeout); + } catch (error) { + onError?.(error as Error); + } + }; + + const Icon = isCopied ? CheckIcon : CopyIcon; + + return ( + + ); +}; diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/confirmation.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/confirmation.tsx new file mode 100644 index 000000000..addea92d6 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/confirmation.tsx @@ -0,0 +1,119 @@ +"use client"; + +import { Alert, AlertDescription } from "@/components/ui/alert"; +import { Button } from "@/components/ui/button"; +import { cn } from "@/lib/utils"; +import type { ToolUIPart } from "ai"; +import { type ComponentProps, type ReactNode, createContext, useContext } from "react"; + +type ConfirmationContextValue = { + approval: ToolUIPart["approval"]; + state: ToolUIPart["state"]; +}; + +const ConfirmationContext = createContext(null); + +const useConfirmation = () => { + const context = useContext(ConfirmationContext); + + if (!context) { + throw new Error("Confirmation components must be used within Confirmation"); + } + + return context; +}; + +export type ConfirmationProps = ComponentProps & { + approval?: ToolUIPart["approval"]; + state: ToolUIPart["state"]; +}; + +export const Confirmation = ({ className, approval, state, ...props }: ConfirmationProps) => { + if (!approval || state === "input-streaming" || state === "input-available") { + return null; + } + + return ( + + + + ); +}; + +export type ConfirmationTitleProps = ComponentProps; + +export const ConfirmationTitle = ({ className, ...props }: ConfirmationTitleProps) => ( + +); + +export type ConfirmationRequestProps = { + children?: ReactNode; +}; + +export const ConfirmationRequest = ({ children }: ConfirmationRequestProps) => { + const { state } = useConfirmation(); + + // Only show when approval is requested + if (state !== "approval-requested") { + return null; + } + + return children; +}; + +export type ConfirmationAcceptedProps = { + children?: ReactNode; +}; + +export const ConfirmationAccepted = ({ children }: ConfirmationAcceptedProps) => { + const { approval, state } = useConfirmation(); + + // Only show when approved and in response states + if ( + !approval?.approved || + (state !== "approval-responded" && state !== "output-denied" && state !== "output-available") + ) { + return null; + } + + return children; +}; + +export type ConfirmationRejectedProps = { + children?: ReactNode; +}; + +export const ConfirmationRejected = ({ children }: ConfirmationRejectedProps) => { + const { approval, state } = useConfirmation(); + + // Only show when rejected and in response states + if ( + approval?.approved !== false || + (state !== "approval-responded" && state !== "output-denied" && state !== "output-available") + ) { + return null; + } + + return children; +}; + +export type ConfirmationActionsProps = ComponentProps<"div">; + +export const ConfirmationActions = ({ className, ...props }: ConfirmationActionsProps) => { + const { state } = useConfirmation(); + + // Only show when approval is requested + if (state !== "approval-requested") { + return null; + } + + return ( +
+ ); +}; + +export type ConfirmationActionProps = ComponentProps; + +export const ConfirmationAction = (props: ConfirmationActionProps) => ( + + )} + + ); +}; + +export type ContextContentProps = ComponentProps; + +export const ContextContent = ({ className, ...props }: ContextContentProps) => ( + +); + +export type ContextContentHeaderProps = ComponentProps<"div">; + +export const ContextContentHeader = ({ + children, + className, + ...props +}: ContextContentHeaderProps) => { + const { usedTokens, maxTokens } = useContextValue(); + const usedPercent = usedTokens / maxTokens; + const displayPct = new Intl.NumberFormat("en-US", { + style: "percent", + maximumFractionDigits: 1, + }).format(usedPercent); + const used = new Intl.NumberFormat("en-US", { + notation: "compact", + }).format(usedTokens); + const total = new Intl.NumberFormat("en-US", { + notation: "compact", + }).format(maxTokens); + + return ( +
+ {children ?? ( + <> +
+

{displayPct}

+

+ {used} / {total} +

+
+
+ +
+ + )} +
+ ); +}; + +export type ContextContentBodyProps = ComponentProps<"div">; + +export const ContextContentBody = ({ children, className, ...props }: ContextContentBodyProps) => ( +
+ {children} +
+); + +export type ContextContentFooterProps = ComponentProps<"div">; + +export const ContextContentFooter = ({ + children, + className, + ...props +}: ContextContentFooterProps) => { + const { modelId, usage } = useContextValue(); + const costUSD = modelId + ? getUsage({ + modelId, + usage: { + input: usage?.inputTokens ?? 0, + output: usage?.outputTokens ?? 0, + }, + }).costUSD?.totalUSD + : undefined; + const totalCost = new Intl.NumberFormat("en-US", { + style: "currency", + currency: "USD", + }).format(costUSD ?? 0); + + return ( +
+ {children ?? ( + <> + Total cost + {totalCost} + + )} +
+ ); +}; + +export type ContextInputUsageProps = ComponentProps<"div">; + +export const ContextInputUsage = ({ className, children, ...props }: ContextInputUsageProps) => { + const { usage, modelId } = useContextValue(); + const inputTokens = usage?.inputTokens ?? 0; + + if (children) { + return children; + } + + if (!inputTokens) { + return null; + } + + const inputCost = modelId + ? getUsage({ + modelId, + usage: { input: inputTokens, output: 0 }, + }).costUSD?.totalUSD + : undefined; + const inputCostText = new Intl.NumberFormat("en-US", { + style: "currency", + currency: "USD", + }).format(inputCost ?? 0); + + return ( +
+ Input + +
+ ); +}; + +export type ContextOutputUsageProps = ComponentProps<"div">; + +export const ContextOutputUsage = ({ className, children, ...props }: ContextOutputUsageProps) => { + const { usage, modelId } = useContextValue(); + const outputTokens = usage?.outputTokens ?? 0; + + if (children) { + return children; + } + + if (!outputTokens) { + return null; + } + + const outputCost = modelId + ? getUsage({ + modelId, + usage: { input: 0, output: outputTokens }, + }).costUSD?.totalUSD + : undefined; + const outputCostText = new Intl.NumberFormat("en-US", { + style: "currency", + currency: "USD", + }).format(outputCost ?? 0); + + return ( +
+ Output + +
+ ); +}; + +export type ContextReasoningUsageProps = ComponentProps<"div">; + +export const ContextReasoningUsage = ({ + className, + children, + ...props +}: ContextReasoningUsageProps) => { + const { usage, modelId } = useContextValue(); + const reasoningTokens = usage?.reasoningTokens ?? 0; + + if (children) { + return children; + } + + if (!reasoningTokens) { + return null; + } + + const reasoningCost = modelId + ? getUsage({ + modelId, + usage: { reasoningTokens }, + }).costUSD?.totalUSD + : undefined; + const reasoningCostText = new Intl.NumberFormat("en-US", { + style: "currency", + currency: "USD", + }).format(reasoningCost ?? 0); + + return ( +
+ Reasoning + +
+ ); +}; + +export type ContextCacheUsageProps = ComponentProps<"div">; + +export const ContextCacheUsage = ({ className, children, ...props }: ContextCacheUsageProps) => { + const { usage, modelId } = useContextValue(); + const cacheTokens = usage?.cachedInputTokens ?? 0; + + if (children) { + return children; + } + + if (!cacheTokens) { + return null; + } + + const cacheCost = modelId + ? getUsage({ + modelId, + usage: { cacheReads: cacheTokens, input: 0, output: 0 }, + }).costUSD?.totalUSD + : undefined; + const cacheCostText = new Intl.NumberFormat("en-US", { + style: "currency", + currency: "USD", + }).format(cacheCost ?? 0); + + return ( +
+ Cache + +
+ ); +}; + +const TokensWithCost = ({ + tokens, + costText, +}: { + tokens?: number; + costText?: string; +}) => ( + + {tokens === undefined + ? "—" + : new Intl.NumberFormat("en-US", { + notation: "compact", + }).format(tokens)} + {costText ? • {costText} : null} + +); diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/controls.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/controls.tsx new file mode 100644 index 000000000..f994a634e --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/controls.tsx @@ -0,0 +1,18 @@ +"use client"; + +import { cn } from "@/lib/utils"; +import { Controls as ControlsPrimitive } from "@xyflow/react"; +import type { ComponentProps } from "react"; + +export type ControlsProps = ComponentProps; + +export const Controls = ({ className, ...props }: ControlsProps) => ( + button]:rounded-md [&>button]:border-none! [&>button]:bg-transparent! [&>button]:hover:bg-secondary!", + className, + )} + {...props} + /> +); diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/conversation.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/conversation.tsx new file mode 100644 index 000000000..411b124bc --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/conversation.tsx @@ -0,0 +1,87 @@ +"use client"; + +import { Button } from "@/components/ui/button"; +import { cn } from "@/lib/utils"; +import { ArrowDownIcon } from "lucide-react"; +import type { ComponentProps } from "react"; +import { useCallback } from "react"; +import { StickToBottom, useStickToBottomContext } from "use-stick-to-bottom"; + +export type ConversationProps = ComponentProps; + +export const Conversation = ({ className, ...props }: ConversationProps) => ( + +); + +export type ConversationContentProps = ComponentProps; + +export const ConversationContent = ({ className, ...props }: ConversationContentProps) => ( + +); + +export type ConversationEmptyStateProps = ComponentProps<"div"> & { + title?: string; + description?: string; + icon?: React.ReactNode; +}; + +export const ConversationEmptyState = ({ + className, + title = "No messages yet", + description = "Start a conversation to see messages here", + icon, + children, + ...props +}: ConversationEmptyStateProps) => ( +
+ {children ?? ( + <> + {icon &&
{icon}
} +
+

{title}

+ {description &&

{description}

} +
+ + )} +
+); + +export type ConversationScrollButtonProps = ComponentProps; + +export const ConversationScrollButton = ({ + className, + ...props +}: ConversationScrollButtonProps) => { + const { isAtBottom, scrollToBottom } = useStickToBottomContext(); + + const handleScrollToBottom = useCallback(() => { + scrollToBottom(); + }, [scrollToBottom]); + + return ( + !isAtBottom && ( + + ) + ); +}; diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/edge.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/edge.tsx new file mode 100644 index 000000000..1f4e4e2cd --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/edge.tsx @@ -0,0 +1,131 @@ +import { + BaseEdge, + type EdgeProps, + type InternalNode, + type Node, + Position, + getBezierPath, + getSimpleBezierPath, + useInternalNode, +} from "@xyflow/react"; + +const Temporary = ({ + id, + sourceX, + sourceY, + targetX, + targetY, + sourcePosition, + targetPosition, +}: EdgeProps) => { + const [edgePath] = getSimpleBezierPath({ + sourceX, + sourceY, + sourcePosition, + targetX, + targetY, + targetPosition, + }); + + return ( + + ); +}; + +const getHandleCoordsByPosition = (node: InternalNode, handlePosition: Position) => { + // Choose the handle type based on position - Left is for target, Right is for source + const handleType = handlePosition === Position.Left ? "target" : "source"; + + const handle = node.internals.handleBounds?.[handleType]?.find( + (h) => h.position === handlePosition, + ); + + if (!handle) { + return [0, 0] as const; + } + + let offsetX = handle.width / 2; + let offsetY = handle.height / 2; + + // this is a tiny detail to make the markerEnd of an edge visible. + // The handle position that gets calculated has the origin top-left, so depending which side we are using, we add a little offset + // when the handlePosition is Position.Right for example, we need to add an offset as big as the handle itself in order to get the correct position + switch (handlePosition) { + case Position.Left: + offsetX = 0; + break; + case Position.Right: + offsetX = handle.width; + break; + case Position.Top: + offsetY = 0; + break; + case Position.Bottom: + offsetY = handle.height; + break; + default: + throw new Error(`Invalid handle position: ${handlePosition}`); + } + + const x = node.internals.positionAbsolute.x + handle.x + offsetX; + const y = node.internals.positionAbsolute.y + handle.y + offsetY; + + return [x, y] as const; +}; + +const getEdgeParams = (source: InternalNode, target: InternalNode) => { + const sourcePos = Position.Right; + const [sx, sy] = getHandleCoordsByPosition(source, sourcePos); + const targetPos = Position.Left; + const [tx, ty] = getHandleCoordsByPosition(target, targetPos); + + return { + sx, + sy, + tx, + ty, + sourcePos, + targetPos, + }; +}; + +const Animated = ({ id, source, target, markerEnd, style }: EdgeProps) => { + const sourceNode = useInternalNode(source); + const targetNode = useInternalNode(target); + + if (!(sourceNode && targetNode)) { + return null; + } + + const { sx, sy, tx, ty, sourcePos, targetPos } = getEdgeParams(sourceNode, targetNode); + + const [edgePath] = getBezierPath({ + sourceX: sx, + sourceY: sy, + sourcePosition: sourcePos, + targetX: tx, + targetY: ty, + targetPosition: targetPos, + }); + + return ( + <> + + + + + + ); +}; + +export const Edge = { + Temporary, + Animated, +}; diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/image.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/image.tsx new file mode 100644 index 000000000..0a9f62816 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/image.tsx @@ -0,0 +1,17 @@ +import { cn } from "@/lib/utils"; +import type { Experimental_GeneratedImage } from "ai"; + +export type ImageProps = Experimental_GeneratedImage & { + className?: string; + alt?: string; +}; + +export const Image = ({ base64, mediaType, ...props }: ImageProps) => ( + // eslint-disable-next-line @next/next/no-img-element + {props.alt} +); diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/inline-citation.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/inline-citation.tsx new file mode 100644 index 000000000..f07f06583 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/inline-citation.tsx @@ -0,0 +1,255 @@ +"use client"; + +import { Badge } from "@/components/ui/badge"; +import { + Carousel, + type CarouselApi, + CarouselContent, + CarouselItem, +} from "@/components/ui/carousel"; +import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card"; +import { cn } from "@/lib/utils"; +import { ArrowLeftIcon, ArrowRightIcon } from "lucide-react"; +import { + type ComponentProps, + createContext, + useCallback, + useContext, + useEffect, + useState, +} from "react"; + +export type InlineCitationProps = ComponentProps<"span">; + +export const InlineCitation = ({ className, ...props }: InlineCitationProps) => ( + +); + +export type InlineCitationTextProps = ComponentProps<"span">; + +export const InlineCitationText = ({ className, ...props }: InlineCitationTextProps) => ( + +); + +export type InlineCitationCardProps = ComponentProps; + +export const InlineCitationCard = (props: InlineCitationCardProps) => ( + +); + +export type InlineCitationCardTriggerProps = ComponentProps & { + sources: string[]; +}; + +export const InlineCitationCardTrigger = ({ + sources, + className, + ...props +}: InlineCitationCardTriggerProps) => ( + + + {sources[0] ? ( + <> + {new URL(sources[0]).hostname} {sources.length > 1 && `+${sources.length - 1}`} + + ) : ( + "unknown" + )} + + +); + +export type InlineCitationCardBodyProps = ComponentProps<"div">; + +export const InlineCitationCardBody = ({ className, ...props }: InlineCitationCardBodyProps) => ( + +); + +const CarouselApiContext = createContext(undefined); + +const useCarouselApi = () => { + const context = useContext(CarouselApiContext); + return context; +}; + +export type InlineCitationCarouselProps = ComponentProps; + +export const InlineCitationCarousel = ({ + className, + children, + ...props +}: InlineCitationCarouselProps) => { + const [api, setApi] = useState(); + + return ( + + + {children} + + + ); +}; + +export type InlineCitationCarouselContentProps = ComponentProps<"div">; + +export const InlineCitationCarouselContent = (props: InlineCitationCarouselContentProps) => ( + +); + +export type InlineCitationCarouselItemProps = ComponentProps<"div">; + +export const InlineCitationCarouselItem = ({ + className, + ...props +}: InlineCitationCarouselItemProps) => ( + +); + +export type InlineCitationCarouselHeaderProps = ComponentProps<"div">; + +export const InlineCitationCarouselHeader = ({ + className, + ...props +}: InlineCitationCarouselHeaderProps) => ( +
+); + +export type InlineCitationCarouselIndexProps = ComponentProps<"div">; + +export const InlineCitationCarouselIndex = ({ + children, + className, + ...props +}: InlineCitationCarouselIndexProps) => { + const api = useCarouselApi(); + const [current, setCurrent] = useState(0); + const [count, setCount] = useState(0); + + useEffect(() => { + if (!api) { + return; + } + + const updateCarouselState = () => { + setCount(api.scrollSnapList().length); + setCurrent(api.selectedScrollSnap() + 1); + }; + + updateCarouselState(); + + api.on("select", () => { + setCurrent(api.selectedScrollSnap() + 1); + }); + }, [api]); + + return ( +
+ {children ?? `${current}/${count}`} +
+ ); +}; + +export type InlineCitationCarouselPrevProps = ComponentProps<"button">; + +export const InlineCitationCarouselPrev = ({ + className, + ...props +}: InlineCitationCarouselPrevProps) => { + const api = useCarouselApi(); + + const handleClick = useCallback(() => { + if (api) { + api.scrollPrev(); + } + }, [api]); + + return ( + + ); +}; + +export type InlineCitationCarouselNextProps = ComponentProps<"button">; + +export const InlineCitationCarouselNext = ({ + className, + ...props +}: InlineCitationCarouselNextProps) => { + const api = useCarouselApi(); + + const handleClick = useCallback(() => { + if (api) { + api.scrollNext(); + } + }, [api]); + + return ( + + ); +}; + +export type InlineCitationSourceProps = ComponentProps<"div"> & { + title?: string; + url?: string; + description?: string; +}; + +export const InlineCitationSource = ({ + title, + url, + description, + className, + children, + ...props +}: InlineCitationSourceProps) => ( +
+ {title &&

{title}

} + {url &&

{url}

} + {description && ( +

{description}

+ )} + {children} +
+); + +export type InlineCitationQuoteProps = ComponentProps<"blockquote">; + +export const InlineCitationQuote = ({ + children, + className, + ...props +}: InlineCitationQuoteProps) => ( +
+ {children} +
+); diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/loader.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/loader.tsx new file mode 100644 index 000000000..1259e64a7 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/loader.tsx @@ -0,0 +1,85 @@ +import { cn } from "@/lib/utils"; +import type { HTMLAttributes } from "react"; + +type LoaderIconProps = { + size?: number; +}; + +const LoaderIcon = ({ size = 16 }: LoaderIconProps) => ( + + Loader + + + + + + + + + + + + + + + + + + +); + +export type LoaderProps = HTMLAttributes & { + size?: number; +}; + +export const Loader = ({ className, size = 16, ...props }: LoaderProps) => ( +
+ +
+); diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/message.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/message.tsx new file mode 100644 index 000000000..8ce634b51 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/message.tsx @@ -0,0 +1,63 @@ +import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"; +import { cn } from "@/lib/utils"; +import type { UIMessage } from "ai"; +import { type VariantProps, cva } from "class-variance-authority"; +import type { ComponentProps, HTMLAttributes } from "react"; + +export type MessageProps = HTMLAttributes & { + from: UIMessage["role"]; +}; + +export const Message = ({ className, from, ...props }: MessageProps) => ( +
+); + +const messageContentVariants = cva( + "is-user:dark flex flex-col gap-2 overflow-hidden rounded-lg text-sm", + { + variants: { + variant: { + contained: [ + "max-w-[80%] px-4 py-3", + "group-[.is-user]:bg-primary group-[.is-user]:text-primary-foreground", + "group-[.is-assistant]:bg-secondary group-[.is-assistant]:text-foreground", + ], + flat: [ + "group-[.is-user]:max-w-[80%] group-[.is-user]:bg-secondary group-[.is-user]:px-4 group-[.is-user]:py-3 group-[.is-user]:text-foreground", + "group-[.is-assistant]:text-foreground", + ], + }, + }, + defaultVariants: { + variant: "contained", + }, + }, +); + +export type MessageContentProps = HTMLAttributes & + VariantProps; + +export const MessageContent = ({ children, className, variant, ...props }: MessageContentProps) => ( +
+ {children} +
+); + +export type MessageAvatarProps = ComponentProps & { + src: string; + name?: string; +}; + +export const MessageAvatar = ({ src, name, className, ...props }: MessageAvatarProps) => ( + + + {name?.slice(0, 2) || "ME"} + +); diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/node.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/node.tsx new file mode 100644 index 000000000..ad9ed348b --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/node.tsx @@ -0,0 +1,63 @@ +import { + Card, + CardAction, + CardContent, + CardDescription, + CardFooter, + CardHeader, + CardTitle, +} from "@/components/ui/card"; +import { cn } from "@/lib/utils"; +import { Handle, Position } from "@xyflow/react"; +import type { ComponentProps } from "react"; + +export type NodeProps = ComponentProps & { + handles: { + target: boolean; + source: boolean; + }; +}; + +export const Node = ({ handles, className, ...props }: NodeProps) => ( + + {handles.target && } + {handles.source && } + {props.children} + +); + +export type NodeHeaderProps = ComponentProps; + +export const NodeHeader = ({ className, ...props }: NodeHeaderProps) => ( + +); + +export type NodeTitleProps = ComponentProps; + +export const NodeTitle = (props: NodeTitleProps) => ; + +export type NodeDescriptionProps = ComponentProps; + +export const NodeDescription = (props: NodeDescriptionProps) => ; + +export type NodeActionProps = ComponentProps; + +export const NodeAction = (props: NodeActionProps) => ; + +export type NodeContentProps = ComponentProps; + +export const NodeContent = ({ className, ...props }: NodeContentProps) => ( + +); + +export type NodeFooterProps = ComponentProps; + +export const NodeFooter = ({ className, ...props }: NodeFooterProps) => ( + +); diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/open-in-chat.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/open-in-chat.tsx new file mode 100644 index 000000000..108b86f67 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/open-in-chat.tsx @@ -0,0 +1,333 @@ +import { Button } from "@/components/ui/button"; +import { + DropdownMenu, + DropdownMenuContent, + DropdownMenuItem, + DropdownMenuLabel, + DropdownMenuSeparator, + DropdownMenuTrigger, +} from "@/components/ui/dropdown-menu"; +import { cn } from "@/lib/utils"; +import { ChevronDownIcon, ExternalLinkIcon, MessageCircleIcon } from "lucide-react"; +import { type ComponentProps, createContext, useContext } from "react"; + +const providers = { + github: { + title: "Open in GitHub", + createUrl: (url: string) => url, + icon: ( + + GitHub + + + ), + }, + scira: { + title: "Open in Scira", + createUrl: (q: string) => + `https://scira.ai/?${new URLSearchParams({ + q, + })}`, + icon: ( + + Scira AI + + + + + + + + + ), + }, + chatgpt: { + title: "Open in ChatGPT", + createUrl: (prompt: string) => + `https://chatgpt.com/?${new URLSearchParams({ + hints: "search", + prompt, + })}`, + icon: ( + + OpenAI + + + ), + }, + claude: { + title: "Open in Claude", + createUrl: (q: string) => + `https://claude.ai/new?${new URLSearchParams({ + q, + })}`, + icon: ( + + Claude + + + ), + }, + t3: { + title: "Open in T3 Chat", + createUrl: (q: string) => + `https://t3.chat/new?${new URLSearchParams({ + q, + })}`, + icon: , + }, + v0: { + title: "Open in v0", + createUrl: (q: string) => + `https://v0.app?${new URLSearchParams({ + q, + })}`, + icon: ( + + v0 + + + + ), + }, + cursor: { + title: "Open in Cursor", + createUrl: (text: string) => { + const url = new URL("https://cursor.com/link/prompt"); + url.searchParams.set("text", text); + return url.toString(); + }, + icon: ( + + Cursor + + + ), + }, +}; + +const OpenInContext = createContext<{ query: string } | undefined>(undefined); + +const useOpenInContext = () => { + const context = useContext(OpenInContext); + if (!context) { + throw new Error("OpenIn components must be used within an OpenIn provider"); + } + return context; +}; + +export type OpenInProps = ComponentProps & { + query: string; +}; + +export const OpenIn = ({ query, ...props }: OpenInProps) => ( + + + +); + +export type OpenInContentProps = ComponentProps; + +export const OpenInContent = ({ className, ...props }: OpenInContentProps) => ( + +); + +export type OpenInItemProps = ComponentProps; + +export const OpenInItem = (props: OpenInItemProps) => ; + +export type OpenInLabelProps = ComponentProps; + +export const OpenInLabel = (props: OpenInLabelProps) => ; + +export type OpenInSeparatorProps = ComponentProps; + +export const OpenInSeparator = (props: OpenInSeparatorProps) => ( + +); + +export type OpenInTriggerProps = ComponentProps; + +export const OpenInTrigger = ({ children, ...props }: OpenInTriggerProps) => ( + + {children ?? ( + + )} + +); + +export type OpenInChatGPTProps = ComponentProps; + +export const OpenInChatGPT = (props: OpenInChatGPTProps) => { + const { query } = useOpenInContext(); + return ( + + + {providers.chatgpt.icon} + {providers.chatgpt.title} + + + + ); +}; + +export type OpenInClaudeProps = ComponentProps; + +export const OpenInClaude = (props: OpenInClaudeProps) => { + const { query } = useOpenInContext(); + return ( + + + {providers.claude.icon} + {providers.claude.title} + + + + ); +}; + +export type OpenInT3Props = ComponentProps; + +export const OpenInT3 = (props: OpenInT3Props) => { + const { query } = useOpenInContext(); + return ( + + + {providers.t3.icon} + {providers.t3.title} + + + + ); +}; + +export type OpenInSciraProps = ComponentProps; + +export const OpenInScira = (props: OpenInSciraProps) => { + const { query } = useOpenInContext(); + return ( + + + {providers.scira.icon} + {providers.scira.title} + + + + ); +}; + +export type OpenInv0Props = ComponentProps; + +export const OpenInv0 = (props: OpenInv0Props) => { + const { query } = useOpenInContext(); + return ( + + + {providers.v0.icon} + {providers.v0.title} + + + + ); +}; + +export type OpenInCursorProps = ComponentProps; + +export const OpenInCursor = (props: OpenInCursorProps) => { + const { query } = useOpenInContext(); + return ( + + + {providers.cursor.icon} + {providers.cursor.title} + + + + ); +}; diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/panel.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/panel.tsx new file mode 100644 index 000000000..d8d7e2545 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/panel.tsx @@ -0,0 +1,12 @@ +import { cn } from "@/lib/utils"; +import { Panel as PanelPrimitive } from "@xyflow/react"; +import type { ComponentProps } from "react"; + +type PanelProps = ComponentProps; + +export const Panel = ({ className, ...props }: PanelProps) => ( + +); diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/plan.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/plan.tsx new file mode 100644 index 000000000..689efab18 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/plan.tsx @@ -0,0 +1,123 @@ +"use client"; + +import { Button } from "@/components/ui/button"; +import { + Card, + CardAction, + CardContent, + CardDescription, + CardFooter, + CardHeader, + CardTitle, +} from "@/components/ui/card"; +import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible"; +import { cn } from "@/lib/utils"; +import { ChevronsUpDownIcon } from "lucide-react"; +import type { ComponentProps } from "react"; +import { createContext, useContext } from "react"; +import { Shimmer } from "./shimmer"; + +type PlanContextValue = { + isStreaming: boolean; +}; + +const PlanContext = createContext(null); + +const usePlan = () => { + const context = useContext(PlanContext); + if (!context) { + throw new Error("Plan components must be used within Plan"); + } + return context; +}; + +export type PlanProps = ComponentProps & { + isStreaming?: boolean; +}; + +export const Plan = ({ className, isStreaming = false, children, ...props }: PlanProps) => ( + + + {children} + + +); + +export type PlanHeaderProps = ComponentProps; + +export const PlanHeader = ({ className, ...props }: PlanHeaderProps) => ( + +); + +export type PlanTitleProps = Omit, "children"> & { + children: string; +}; + +export const PlanTitle = ({ children, ...props }: PlanTitleProps) => { + const { isStreaming } = usePlan(); + + return ( + + {isStreaming ? {children} : children} + + ); +}; + +export type PlanDescriptionProps = Omit, "children"> & { + children: string; +}; + +export const PlanDescription = ({ className, children, ...props }: PlanDescriptionProps) => { + const { isStreaming } = usePlan(); + + return ( + + {isStreaming ? {children} : children} + + ); +}; + +export type PlanActionProps = ComponentProps; + +export const PlanAction = (props: PlanActionProps) => ( + +); + +export type PlanContentProps = ComponentProps; + +export const PlanContent = (props: PlanContentProps) => ( + + + +); + +export type PlanFooterProps = ComponentProps<"div">; + +export const PlanFooter = (props: PlanFooterProps) => ( + +); + +export type PlanTriggerProps = ComponentProps; + +export const PlanTrigger = ({ className, ...props }: PlanTriggerProps) => ( + + + +); diff --git a/examples/next-js-chatbot-starter-template/components/ai-elements/prompt-input.tsx b/examples/next-js-chatbot-starter-template/components/ai-elements/prompt-input.tsx new file mode 100644 index 000000000..081df4db9 --- /dev/null +++ b/examples/next-js-chatbot-starter-template/components/ai-elements/prompt-input.tsx @@ -0,0 +1,1226 @@ +"use client"; + +import { Button } from "@/components/ui/button"; +import { + Command, + CommandEmpty, + CommandGroup, + CommandInput, + CommandItem, + CommandList, + CommandSeparator, +} from "@/components/ui/command"; +import { + DropdownMenu, + DropdownMenuContent, + DropdownMenuItem, + DropdownMenuTrigger, +} from "@/components/ui/dropdown-menu"; +import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card"; +import { + InputGroup, + InputGroupAddon, + InputGroupButton, + InputGroupTextarea, +} from "@/components/ui/input-group"; +import { + Select, + SelectContent, + SelectItem, + SelectTrigger, + SelectValue, +} from "@/components/ui/select"; +import { cn } from "@/lib/utils"; +import type { ChatStatus, FileUIPart } from "ai"; +import { + ImageIcon, + Loader2Icon, + MicIcon, + PaperclipIcon, + PlusIcon, + SendIcon, + SquareIcon, + XIcon, +} from "lucide-react"; +import { nanoid } from "nanoid"; +import { + type ChangeEvent, + type ChangeEventHandler, + Children, + type ClipboardEventHandler, + type ComponentProps, + type FormEvent, + type FormEventHandler, + Fragment, + type HTMLAttributes, + type KeyboardEventHandler, + type PropsWithChildren, + type ReactNode, + type RefObject, + createContext, + useCallback, + useContext, + useEffect, + useMemo, + useRef, + useState, +} from "react"; +// ============================================================================ +// Provider Context & Types +// ============================================================================ + +export type AttachmentsContext = { + files: (FileUIPart & { id: string })[]; + add: (files: File[] | FileList) => void; + remove: (id: string) => void; + clear: () => void; + openFileDialog: () => void; + fileInputRef: RefObject; +}; + +export type TextInputContext = { + value: string; + setInput: (v: string) => void; + clear: () => void; +}; + +export type PromptInputControllerProps = { + textInput: TextInputContext; + attachments: AttachmentsContext; + /** INTERNAL: Allows PromptInput to register its file textInput + "open" callback */ + __registerFileInput: (ref: RefObject, open: () => void) => void; +}; + +const PromptInputController = createContext(null); +const ProviderAttachmentsContext = createContext(null); + +export const usePromptInputController = () => { + const ctx = useContext(PromptInputController); + if (!ctx) { + throw new Error( + "Wrap your component inside to use usePromptInputController().", + ); + } + return ctx; +}; + +// Optional variants (do NOT throw). Useful for dual-mode components. +const useOptionalPromptInputController = () => useContext(PromptInputController); + +export const useProviderAttachments = () => { + const ctx = useContext(ProviderAttachmentsContext); + if (!ctx) { + throw new Error( + "Wrap your component inside to use useProviderAttachments().", + ); + } + return ctx; +}; + +const useOptionalProviderAttachments = () => useContext(ProviderAttachmentsContext); + +export type PromptInputProviderProps = PropsWithChildren<{ + initialInput?: string; +}>; + +/** + * Optional global provider that lifts PromptInput state outside of PromptInput. + * If you don't use it, PromptInput stays fully self-managed. + */ +export function PromptInputProvider({ + initialInput: initialTextInput = "", + children, +}: PromptInputProviderProps) { + // ----- textInput state + const [textInput, setTextInput] = useState(initialTextInput); + const clearInput = useCallback(() => setTextInput(""), []); + + // ----- attachments state (global when wrapped) + const [attachements, setAttachements] = useState<(FileUIPart & { id: string })[]>([]); + const fileInputRef = useRef(null); + const openRef = useRef<() => void>(() => {}); + + const add = useCallback((files: File[] | FileList) => { + const incoming = Array.from(files); + if (incoming.length === 0) return; + + setAttachements((prev) => + prev.concat( + incoming.map((file) => ({ + id: nanoid(), + type: "file" as const, + url: URL.createObjectURL(file), + mediaType: file.type, + filename: file.name, + })), + ), + ); + }, []); + + const remove = useCallback((id: string) => { + setAttachements((prev) => { + const found = prev.find((f) => f.id === id); + if (found?.url) URL.revokeObjectURL(found.url); + return prev.filter((f) => f.id !== id); + }); + }, []); + + const clear = useCallback(() => { + setAttachements((prev) => { + for (const f of prev) if (f.url) URL.revokeObjectURL(f.url); + return []; + }); + }, []); + + const openFileDialog = useCallback(() => { + openRef.current?.(); + }, []); + + const attachments = useMemo( + () => ({ + files: attachements, + add, + remove, + clear, + openFileDialog, + fileInputRef, + }), + [attachements, add, remove, clear, openFileDialog], + ); + + const __registerFileInput = useCallback( + (ref: RefObject, open: () => void) => { + fileInputRef.current = ref.current; + openRef.current = open; + }, + [], + ); + + const controller = useMemo( + () => ({ + textInput: { + value: textInput, + setInput: setTextInput, + clear: clearInput, + }, + attachments, + __registerFileInput, + }), + [textInput, clearInput, attachments, __registerFileInput], + ); + + return ( + + + {children} + + + ); +} + +// ============================================================================ +// Component Context & Hooks +// ============================================================================ + +const LocalAttachmentsContext = createContext(null); + +export const usePromptInputAttachments = () => { + // Dual-mode: prefer provider if present, otherwise use local + const provider = useOptionalProviderAttachments(); + const local = useContext(LocalAttachmentsContext); + const context = provider ?? local; + if (!context) { + throw new Error( + "usePromptInputAttachments must be used within a PromptInput or PromptInputProvider", + ); + } + return context; +}; + +export type PromptInputAttachmentProps = HTMLAttributes & { + data: FileUIPart & { id: string }; + className?: string; +}; + +export function PromptInputAttachment({ data, className, ...props }: PromptInputAttachmentProps) { + const attachments = usePromptInputAttachments(); + + const filename = data.filename || ""; + + const mediaType = data.mediaType?.startsWith("image/") && data.url ? "image" : "file"; + const isImage = mediaType === "image"; + + const attachmentLabel = filename || (isImage ? "Image" : "Attachment"); + + return ( + + +
+
+
+ {isImage ? ( + // eslint-disable-next-line @next/next/no-img-element + {filename + ) : ( +
+ +
+ )} +
+ +
+ + {attachmentLabel} +
+ + +
+ {isImage && ( +
+ {/* eslint-disable-next-line @next/next/no-img-element */} + {filename +
+ )} +
+
+

+ {filename || (isImage ? "Image" : "Attachment")} +

+ {data.mediaType && ( +

{data.mediaType}

+ )} +
+
+
+ + + ); +} + +export type PromptInputAttachmentsProps = Omit, "children"> & { + children: (attachment: FileUIPart & { id: string }) => ReactNode; +}; + +export function PromptInputAttachments({ children }: PromptInputAttachmentsProps) { + const attachments = usePromptInputAttachments(); + + if (!attachments.files.length) { + return null; + } + + return attachments.files.map((file) => {children(file)}); +} + +export type PromptInputActionAddAttachmentsProps = ComponentProps & { + label?: string; +}; + +export const PromptInputActionAddAttachments = ({ + label = "Add photos or files", + ...props +}: PromptInputActionAddAttachmentsProps) => { + const attachments = usePromptInputAttachments(); + + return ( + { + e.preventDefault(); + attachments.openFileDialog(); + }} + > + {label} + + ); +}; + +export type PromptInputMessage = { + text?: string; + files?: FileUIPart[]; +}; + +export type PromptInputProps = Omit, "onSubmit" | "onError"> & { + accept?: string; // e.g., "image/*" or leave undefined for any + multiple?: boolean; + // When true, accepts drops anywhere on document. Default false (opt-in). + globalDrop?: boolean; + // Render a hidden input with given name and keep it in sync for native form posts. Default false. + syncHiddenInput?: boolean; + // Minimal constraints + maxFiles?: number; + maxFileSize?: number; // bytes + onError?: (err: { + code: "max_files" | "max_file_size" | "accept"; + message: string; + }) => void; + onSubmit: ( + message: PromptInputMessage, + event: FormEvent, + ) => void | Promise; +}; + +export const PromptInput = ({ + className, + accept, + multiple, + globalDrop, + syncHiddenInput, + maxFiles, + maxFileSize, + onError, + onSubmit, + children, + ...props +}: PromptInputProps) => { + // Try to use a provider controller if present + const controller = useOptionalPromptInputController(); + const usingProvider = !!controller; + + // Refs + const inputRef = useRef(null); + const anchorRef = useRef(null); + const formRef = useRef(null); + + // Find nearest form to scope drag & drop + useEffect(() => { + const root = anchorRef.current?.closest("form"); + if (root instanceof HTMLFormElement) { + formRef.current = root; + } + }, []); + + // ----- Local attachments (only used when no provider) + const [items, setItems] = useState<(FileUIPart & { id: string })[]>([]); + const files = usingProvider ? controller.attachments.files : items; + + const openFileDialogLocal = useCallback(() => { + inputRef.current?.click(); + }, []); + + const matchesAccept = useCallback( + (f: File) => { + if (!accept || accept.trim() === "") { + return true; + } + if (accept.includes("image/*")) { + return f.type.startsWith("image/"); + } + // NOTE: keep simple; expand as needed + return true; + }, + [accept], + ); + + const addLocal = useCallback( + (fileList: File[] | FileList) => { + const incoming = Array.from(fileList); + const accepted = incoming.filter((f) => matchesAccept(f)); + if (incoming.length && accepted.length === 0) { + onError?.({ + code: "accept", + message: "No files match the accepted types.", + }); + return; + } + const withinSize = (f: File) => (maxFileSize ? f.size <= maxFileSize : true); + const sized = accepted.filter(withinSize); + if (accepted.length > 0 && sized.length === 0) { + onError?.({ + code: "max_file_size", + message: "All files exceed the maximum size.", + }); + return; + } + + setItems((prev) => { + const capacity = + typeof maxFiles === "number" ? Math.max(0, maxFiles - prev.length) : undefined; + const capped = typeof capacity === "number" ? sized.slice(0, capacity) : sized; + if (typeof capacity === "number" && sized.length > capacity) { + onError?.({ + code: "max_files", + message: "Too many files. Some were not added.", + }); + } + const next: (FileUIPart & { id: string })[] = []; + for (const file of capped) { + next.push({ + id: nanoid(), + type: "file", + url: URL.createObjectURL(file), + mediaType: file.type, + filename: file.name, + }); + } + return prev.concat(next); + }); + }, + [matchesAccept, maxFiles, maxFileSize, onError], + ); + + const add = useMemo( + () => + usingProvider && controller + ? (files: File[] | FileList) => controller.attachments.add(files) + : addLocal, + [usingProvider, controller, addLocal], + ); + + const remove = useMemo( + () => + usingProvider && controller + ? (id: string) => controller.attachments.remove(id) + : (id: string) => + setItems((prev) => { + const found = prev.find((file) => file.id === id); + if (found?.url) { + URL.revokeObjectURL(found.url); + } + return prev.filter((file) => file.id !== id); + }), + [usingProvider, controller], + ); + + const clear = useMemo( + () => + usingProvider && controller + ? () => controller.attachments.clear() + : () => + setItems((prev) => { + for (const file of prev) { + if (file.url) { + URL.revokeObjectURL(file.url); + } + } + return []; + }), + [usingProvider, controller], + ); + + const openFileDialog = useMemo( + () => + usingProvider && controller + ? () => controller.attachments.openFileDialog() + : openFileDialogLocal, + [usingProvider, controller, openFileDialogLocal], + ); + + // Let provider know about our hidden file input so external menus can call openFileDialog() + useEffect(() => { + if (!usingProvider) return; + controller.__registerFileInput(inputRef, () => inputRef.current?.click()); + }, [usingProvider, controller]); + + // Note: File input cannot be programmatically set for security reasons + // The syncHiddenInput prop is no longer functional + useEffect(() => { + if (syncHiddenInput && inputRef.current && files.length === 0) { + inputRef.current.value = ""; + } + }, [files, syncHiddenInput]); + + // Attach drop handlers on nearest form and document (opt-in) + useEffect(() => { + const form = formRef.current; + if (!form) return; + + const onDragOver = (e: DragEvent) => { + if (e.dataTransfer?.types?.includes("Files")) { + e.preventDefault(); + } + }; + const onDrop = (e: DragEvent) => { + if (e.dataTransfer?.types?.includes("Files")) { + e.preventDefault(); + } + if (e.dataTransfer?.files && e.dataTransfer.files.length > 0) { + add(e.dataTransfer.files); + } + }; + form.addEventListener("dragover", onDragOver); + form.addEventListener("drop", onDrop); + return () => { + form.removeEventListener("dragover", onDragOver); + form.removeEventListener("drop", onDrop); + }; + }, [add]); + + useEffect(() => { + if (!globalDrop) return; + + const onDragOver = (e: DragEvent) => { + if (e.dataTransfer?.types?.includes("Files")) { + e.preventDefault(); + } + }; + const onDrop = (e: DragEvent) => { + if (e.dataTransfer?.types?.includes("Files")) { + e.preventDefault(); + } + if (e.dataTransfer?.files && e.dataTransfer.files.length > 0) { + add(e.dataTransfer.files); + } + }; + document.addEventListener("dragover", onDragOver); + document.addEventListener("drop", onDrop); + return () => { + document.removeEventListener("dragover", onDragOver); + document.removeEventListener("drop", onDrop); + }; + }, [add, globalDrop]); + + useEffect( + () => () => { + if (!usingProvider) { + for (const f of files) { + if (f.url) URL.revokeObjectURL(f.url); + } + } + }, + [usingProvider, files], + ); + + const handleChange: ChangeEventHandler = (event) => { + if (event.currentTarget.files) { + add(event.currentTarget.files); + } + }; + + const convertBlobUrlToDataUrl = async (url: string): Promise => { + const response = await fetch(url); + const blob = await response.blob(); + return new Promise((resolve, reject) => { + const reader = new FileReader(); + reader.onloadend = () => resolve(reader.result as string); + reader.onerror = reject; + reader.readAsDataURL(blob); + }); + }; + + const ctx = useMemo( + () => ({ + files: files.map((item) => ({ ...item, id: item.id })), + add, + remove, + clear, + openFileDialog, + fileInputRef: inputRef, + }), + [files, add, remove, clear, openFileDialog], + ); + + const handleSubmit: FormEventHandler = (event) => { + event.preventDefault(); + + const form = event.currentTarget; + const text = usingProvider + ? controller.textInput.value + : (() => { + const formData = new FormData(form); + return (formData.get("message") as string) || ""; + })(); + + // Reset form immediately after capturing text to avoid race condition + // where user input during async blob conversion would be lost + if (!usingProvider) { + form.reset(); + } + + // Convert blob URLs to data URLs asynchronously + Promise.all( + files.map(async (item) => { + if (item.url?.startsWith("blob:")) { + return { + ...item, + url: await convertBlobUrlToDataUrl(item.url), + }; + } + return item; + }), + ).then((convertedFiles: FileUIPart[]) => { + try { + const result = onSubmit({ text, files: convertedFiles }, event); + + // Handle both sync and async onSubmit + if (result instanceof Promise) { + result + .then(() => { + clear(); + if (usingProvider) { + controller.textInput.clear(); + } + }) + .catch(() => { + // Don't clear on error - user may want to retry + }); + } else { + // Sync function completed without throwing, clear attachments + clear(); + if (usingProvider) { + controller.textInput.clear(); + } + } + } catch { + // Don't clear on error - user may want to retry + } + }); + }; + + // Render with or without local provider + const inner = ( + <> +