feat(AIC-3408): add Vercel AI SDK messages and agents adapters

.env.example

@@ -4,6 +4,7 @@ LD_SDK_KEY=your-sdk-key-here
 # AI providers (set the ones you use)
 OPENAI_API_KEY=your-openai-key-here
 ANTHROPIC_API_KEY=your-anthropic-key-here
+AI_GATEWAY_API_KEY=your-vercel-ai-gateway-key-here
 
 # LaunchDarkly endpoints (leave blank to use production defaults)
 LD_BASE_URI=

.release-please-manifest.json

@@ -6,5 +6,7 @@
   "packages/openai-agents": "0.2.3",
   "packages/openai-messages": "0.2.3",
   "packages/langchain-agents": "0.2.3",
-  "packages/langchain-messages": "0.2.3"
+  "packages/langchain-messages": "0.2.3",
+  "packages/vercel-agents": "0.1.0",
+  "packages/vercel-messages": "0.1.0"
 }

.sdk_metadata.json

@@ -102,6 +102,30 @@
         "aiAgentGraph": { "introduced": "0.1" },
         "aiTrackMetrics": { "introduced": "0.1" }
       }
+    },
+    "python-ai-vercel-messages": {
+      "name": "Vercel Messages AI SDK for Python",
+      "type": "ai-provider",
+      "path": "packages/vercel-messages",
+      "languages": ["Python"],
+      "aiSdkNames": ["launchdarkly-ai-vercel-messages"],
+      "releases": { "tag-prefix": "launchdarkly-ai-vercel-messages-" },
+      "features": {
+        "aiCompletionConfig": { "introduced": "0.1" }
+      }
+    },
+    "python-ai-vercel-agents": {
+      "name": "Vercel Agents AI SDK for Python",
+      "type": "ai-provider",
+      "path": "packages/vercel-agents",
+      "languages": ["Python"],
+      "aiSdkNames": ["launchdarkly-ai-vercel-agents"],
+      "releases": { "tag-prefix": "launchdarkly-ai-vercel-agents-" },
+      "features": {
+        "aiAgentConfig": { "introduced": "0.1" },
+        "aiAgentGraph": { "introduced": "0.1" },
+        "aiTrackMetrics": { "introduced": "0.1" }
+      }
     }
   }
 }

AGENTS.md

@@ -87,6 +87,7 @@ graph TD
   claude["launchdarkly-ai-claude-agents"]
   openai["launchdarkly-ai-openai-agents"]
   langchain["launchdarkly-ai-langchain-agents"]
+  vercel["launchdarkly-ai-vercel-agents"]
   newHandler["launchdarkly-ai-new-provider\n(future)"]
  end
  subgraph tier0 ["Tier 0 — Core"]
@@ -102,6 +103,7 @@ graph TD
  claude --> client
  openai --> client
  langchain --> client
+ vercel --> client
  newHandler --> client
  ai --> client
 ```
@@ -110,7 +112,7 @@ graph TD
 
 - **Tier 0 — Core** (`launchdarkly-ai-server`): The foundation. Owns all LaunchDarkly integration, telemetry orchestration, shared data types, and the primary entry points (`config()`, `graph()`, `resolve_graph()`). Has no dependency on any other `launchdarkly-ai-*` package.
 - **Tier 0 — Convenience barrel** (`launchdarkly-ai-python`): A pure re-export package that makes all of `launchdarkly-ai-server` available under a shorter install name. No new logic — intended as the default install for most Python applications.
-- **Tier 1 — Handler packages** (`launchdarkly-ai-claude-agents`, `launchdarkly-ai-claude-messages`, `launchdarkly-ai-openai-agents`, `launchdarkly-ai-openai-messages`, `launchdarkly-ai-langchain-agents`, `launchdarkly-ai-langchain-messages`, …): Each wraps a specific AI provider SDK. Depends on `launchdarkly-ai-server` for shared types and utilities. Must not depend on other Tier 1 packages.
+- **Tier 1 — Handler packages** (`launchdarkly-ai-claude-agents`, `launchdarkly-ai-claude-messages`, `launchdarkly-ai-openai-agents`, `launchdarkly-ai-openai-messages`, `launchdarkly-ai-langchain-agents`, `launchdarkly-ai-langchain-messages`, `launchdarkly-ai-vercel-agents`, `launchdarkly-ai-vercel-messages`, …): Each wraps a specific AI provider SDK. Depends on `launchdarkly-ai-server` for shared types and utilities. Must not depend on other Tier 1 packages.
 - **Tier 2 — Consumer applications** (e.g. `main.py`, downstream projects): Imports from one or more handler packages and either `launchdarkly-ai-python` or `launchdarkly-ai-server`. Owns tool implementations and orchestration logic. No `launchdarkly-ai-*` package should ever depend on Tier 2 code.
 
 ### Rules
@@ -657,7 +659,7 @@ def my_provider(
 
 For example, `claude_agents(config_key, user_input, context)` is equivalent to `config(key=config_key, handler=create_claude_agents_handler()).invoke(user_input, context)`.
 
-The naming convention matches the package suffix: `claude_agents`, `claude_messages`, `openai_agents`, `openai_messages`, `langchain_agents`, `langchain_messages`.
+The naming convention matches the package suffix: `claude_agents`, `claude_messages`, `openai_agents`, `openai_messages`, `langchain_agents`, `langchain_messages`, `vercel_agents`, `vercel_messages`.
 
 ### Graph Export (optional)
 
@@ -668,7 +670,7 @@ def claude_graph(key: str, **options) -> GraphInstance:
     return graph(key, handlers=[create_claude_agents_handler()], **options)
 ```
 
-Naming convention: `claude_graph`, `openai_graph`, `langchain_graph`.
+Naming convention: `claude_graph`, `openai_graph`, `langchain_graph`, `vercel_graph`.
 
 ### Native Graph Adapter (optional)
 
@@ -678,6 +680,7 @@ Current adapters:
 - `to_claude_agents(def_coro, opts)` — exported from `launchdarkly_ai_claude_agents`
 - `to_openai_agents(def_coro, opts)` — exported from `launchdarkly_ai_openai_agents`
 - `to_lang_graph(def_coro, opts)` — exported from `launchdarkly_ai_langchain_agents`
+- `to_vercel_agents(def_coro, opts)` — exported from `launchdarkly_ai_vercel_agents`
 
 ---
 

README.md

@@ -85,6 +85,8 @@ Tier 0 — Core Client           (launchdarkly-ai-server)
 | [`launchdarkly-ai-claude-agents`](packages/claude-agents/README.md) | Anthropic | `agent` | Claude Agent SDK — agentic loop with MCP tool support |
 | [`launchdarkly-ai-langchain-messages`](packages/langchain-messages/README.md) | `*` (any) | `messages` | Any `BaseChatModel` via LangChain `bind_tools` loop |
 | [`launchdarkly-ai-langchain-agents`](packages/langchain-agents/README.md) | `*` (any) | `agent` | LangGraph `StateGraph` — managed ReAct loop |
+| [`launchdarkly-ai-vercel-messages`](packages/vercel-messages/README.md) | `*` (any) | `messages` | Vercel AI SDK with AI Gateway routing |
+| [`launchdarkly-ai-vercel-agents`](packages/vercel-agents/README.md) | `*` (any) | `agent` | Native Vercel `ai.Agent` loop and graph adapter |
 
 ## Quick Start
 
@@ -149,6 +151,8 @@ asyncio.run(main())
 | `claude_agents` | `launchdarkly-ai-claude-agents` | `claude-agent-sdk` | Claude Agent SDK (MCP) |
 | `langchain_messages` | `launchdarkly-ai-langchain-messages` | `langchain-core` | LangChain `bind_tools` loop |
 | `langchain_agents` | `launchdarkly-ai-langchain-agents` | `langgraph` | LangGraph `StateGraph` |
+| `vercel_messages` | `launchdarkly-ai-vercel-messages` | `ai` | Vercel AI SDK stream runtime |
+| `vercel_agents` | `launchdarkly-ai-vercel-agents` | `ai` | Native Vercel `ai.Agent` |
 
 ---
 
@@ -597,6 +601,10 @@ uv run python main.py [example] [flag-key] [user-input]
 | `graph-history` | `uv run python main.py graph-history` | `graph().invoke()` with multimodal `history` forwarded to the root node |
 | `openai-only` | `uv run python main.py openai-only` | `config()` with a custom `Registry` restricted to OpenAI handlers |
 | `streaming` | `uv run python main.py streaming` | `config().stream()` — token-by-token output |
+| `vercel-agents` | `uv run python main.py vercel-agents` | Native Vercel `ai.Agent` handler via AI Gateway |
+| `vercel-messages` | `uv run python main.py vercel-messages` | Vercel AI SDK messages handler via AI Gateway |
+| `vercel-direct` | `uv run python main.py vercel-direct` | Vercel messages handler with a constructed OpenAI model (no Gateway) |
+| `native-graph-vercel` | `uv run python main.py native-graph-vercel` | Framework-native Vercel `ai.Agent` graph runner |
 
 **Examples:**
 

examples/native_graph_vercel.py

@@ -0,0 +1,27 @@
+"""Framework-native graph runner using Vercel ``ai.Agent`` instances."""
+
+from __future__ import annotations
+
+import json
+
+from examples.tools import get_preferences, web_search
+from examples.utils import new_context, write_output
+from launchdarkly_ai_server import resolve_graph
+from launchdarkly_ai_vercel_agents import to_vercel_agents
+
+
+async def run(key: str, user_input: str) -> None:
+    context = new_context()
+    response = await to_vercel_agents(
+        resolve_graph(key, context=context),
+        {
+            "context": context,
+            "tool_handlers": {
+                "user-preferences-lookup": get_preferences,
+                "web-search-tool": web_search,
+            },
+        },
+    ).invoke(user_input, {"user_id": "user-123"})
+
+    print(json.dumps(response, indent=2, default=str))
+    write_output(response)

examples/vercel_agents_example.py

@@ -0,0 +1,31 @@
+"""Run the wildcard native Vercel AI SDK agents adapter."""
+
+from __future__ import annotations
+
+import json
+
+from examples.tools import (
+    fetch_launchdarkly_documentation,
+    get_preferences,
+    search_ld_documentation,
+    web_search,
+)
+from examples.utils import new_context, write_output
+from launchdarkly_ai_vercel_agents import vercel_agents
+
+
+async def run(key: str, user_input: str) -> None:
+    response = await vercel_agents(
+        key,
+        user_input,
+        new_context(),
+        tool_handlers={
+            "get-user-preferences": get_preferences,
+            "search-ld-documentation": search_ld_documentation,
+            "fetch-ld-documentation": fetch_launchdarkly_documentation,
+            "fetch-launchdarkly-documentation": fetch_launchdarkly_documentation,
+            "web-search": web_search,
+        },
+    )
+    print(json.dumps(response, indent=2, default=str))
+    write_output(response)

examples/vercel_direct.py

@@ -0,0 +1,31 @@
+"""Inject a constructed OpenAI model so the Vercel adapter skips AI Gateway.
+
+Usage (via main.py):
+    python main.py vercel-direct launch-darkly-documentation-summarizer-messages-openai "What is the LaunchDarkly AI SDK?"
+"""
+
+from __future__ import annotations
+
+import json
+
+import ai
+
+from examples.utils import new_context, write_output
+from launchdarkly_ai_server import AiConfigRep
+from launchdarkly_ai_vercel_messages import vercel_messages
+
+
+def openai_model(config: AiConfigRep) -> ai.Model:
+    return ai.Model(id=str(config["model"]["name"]), provider=ai.get_provider("openai"))
+
+
+async def run(key: str, user_input: str) -> None:
+    response = await vercel_messages(
+        key,
+        user_input,
+        new_context(),
+        model=openai_model,
+        variables={"user_input": user_input},
+    )
+    print(json.dumps(response, indent=2, default=str))
+    write_output(response)

examples/vercel_messages_example.py

@@ -0,0 +1,32 @@
+"""Run the wildcard Vercel AI SDK messages adapter."""
+
+from __future__ import annotations
+
+import json
+
+from examples.tools import (
+    fetch_launchdarkly_documentation,
+    get_preferences,
+    search_ld_documentation,
+    web_search,
+)
+from examples.utils import new_context, write_output
+from launchdarkly_ai_vercel_messages import vercel_messages
+
+
+async def run(key: str, user_input: str) -> None:
+    response = await vercel_messages(
+        key,
+        user_input,
+        new_context(),
+        tool_handlers={
+            "get-user-preferences": get_preferences,
+            "search-ld-documentation": search_ld_documentation,
+            "fetch-ld-documentation": fetch_launchdarkly_documentation,
+            "fetch-launchdarkly-documentation": fetch_launchdarkly_documentation,
+            "web-search": web_search,
+        },
+        variables={"user_input": user_input},
+    )
+    print(json.dumps(response, indent=2, default=str))
+    write_output(response)

main.py

@@ -17,6 +17,8 @@
     python main.py openai-agents            launch-darkly-documentation-summarizer-open-ai-only "What is the LaunchDarkly AI SDK?"
     python main.py langchain-agents         launch-darkly-documentation-summarizer "What is the LaunchDarkly AI SDK?"
     python main.py langchain-thinking       launch-darkly-documentation-summarizer-messages-claude "Reason it out yourself without any tools: what is 17 times 23?"
+    python main.py vercel-messages          launch-darkly-documentation-summarizer-messages "What is the LaunchDarkly AI SDK?"
+    python main.py vercel-direct            launch-darkly-documentation-summarizer-messages-openai "What is the LaunchDarkly AI SDK?"
     python main.py native-graph             travel-agent-flow "Book me a flight to Paris"
     python main.py native-graph-langchain   travel-agent-flow "Book me a flight to Paris"
 """
@@ -60,8 +62,12 @@
     "langchain-agents": "examples.langchain_agents_example",
     "langchain-messages": "examples.langchain_messages_example",
     "langchain-thinking": "examples.langchain_thinking",
+    "vercel-agents": "examples.vercel_agents_example",
+    "vercel-direct": "examples.vercel_direct",
+    "vercel-messages": "examples.vercel_messages_example",
     "native-graph": "examples.native_graph",
     "native-graph-langchain": "examples.native_graph_langchain",
+    "native-graph-vercel": "examples.native_graph_vercel",
 }
 
 DEFAULT_EXAMPLE = "agent"
@@ -99,10 +105,17 @@ async def main() -> None:
     await shutdown()
 
 
+def _error_message(exc: BaseException) -> str:
+    """Expose a sole nested provider error instead of an opaque TaskGroup wrapper."""
+    if isinstance(exc, BaseExceptionGroup) and len(exc.exceptions) == 1:
+        return _error_message(exc.exceptions[0])
+    return str(exc)
+
+
 if __name__ == "__main__":
     try:
         asyncio.run(main())
     except Exception as exc:
         sys.stdout.flush()
-        print(f"Error: {exc}", file=sys.stderr)
+        print(f"Error: {_error_message(exc)}", file=sys.stderr)
         sys.exit(1)

packages/vercel-agents/README.md

@@ -0,0 +1,42 @@
+# `launchdarkly-ai-vercel-agents`
+
+Wildcard LaunchDarkly AI agent handler built on the official Vercel `ai.Agent`
+runtime for Python.
+
+## Install
+
+```bash
+pip install launchdarkly-ai-server launchdarkly-server-sdk launchdarkly-ai-vercel-agents
+```
+
+Default routing is AI Gateway via a mapped `creator/model` id (for example,
+`xAI` + `grok-4.5` becomes `spacexai/grok-4.5`). Already-qualified ids remain
+unchanged. Set `AI_GATEWAY_API_KEY` or Vercel OIDC. This package does not load a provider SDK from
+`config.provider.name`. Inject a model or model factory to call a provider
+directly.
+
+All LaunchDarkly providers are handled explicitly. Anthropic, OpenAI, Azure,
+Gemini, Cohere, DeepSeek, Meta, Mistral, Perplexity, and Vertex map directly.
+Bedrock, Cortex, Cursor, Databricks, and Fireworks AI infer the creator from the
+model and fail locally if ambiguous. AI21 Labs and IBM Watson fail locally
+because Vercel's current catalog has no corresponding creator.
+
+## Use
+
+```python
+from launchdarkly_ai_server import config
+from launchdarkly_ai_vercel_agents import create_vercel_agents_handler
+
+result = await config(
+    key="my-agent-config",
+    handler=create_vercel_agents_handler(),
+).invoke("Help me", {"kind": "user", "key": "user-123"})
+```
+
+The package also exports `vercel_graph()` and `to_vercel_agents()` for
+LaunchDarkly and framework-native graph execution. The native adapter builds one
+`ai.Agent` per graph node and follows only a `transfer_to_<target>` tool that the
+current node actually selects.
+
+This package advertises `("*", "agent")`; register only one wildcard agent
+adapter in a handler pool.

packages/vercel-agents/agents.md

@@ -0,0 +1,18 @@
+# Agent Guide — Vercel Agents
+
+This Tier 1 package provides the wildcard `("*", "agent")` handler.
+
+- Default models use a mapped Gateway `creator/model` id. Preserve
+  slash-qualified ids, map `xAI` to `spacexai`, and split recognized LD dotted
+  creator prefixes once. Injected models are the only Gateway opt-out.
+- `handler.py` constructs the native `ai.Agent` and maps models, messages,
+  `AgentTool`/`Tool`/`ToolSpec`, request parameters, streams, usage, and spans.
+- `graph.py` pre-wires exactly one Vercel handler into the core graph API.
+- `native_graph.py` creates one native agent per node. Handoff tools only select
+  a target; execution follows the selected target after the current run ends.
+- Root caller history is never replayed into child nodes.
+- Native graph spans end in `finally`, including `CancelledError`.
+- Runtime calls are always async context-managed and never enable duplicate
+  runtime telemetry.
+
+`TESTING.md` §2.x and Appendix A.14 are authoritative.

packages/vercel-agents/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "launchdarkly-ai-vercel-agents"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+  "launchdarkly-ai-server",
+  "opentelemetry-api>=1.25",
+  "ai>=0.7",
+]
+description = "Vercel AI SDK agent handler for LaunchDarkly AI SDK"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [{name = "LaunchDarkly", email = "team@launchdarkly.com"}]
+keywords = ["launchdarkly", "ai", "vercel", "agents"]
+
+[build-system]
+requires = ["hatchling>=1.32,<2"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/launchdarkly_ai_vercel_agents"]

packages/vercel-agents/src/launchdarkly_ai_vercel_agents/__init__.py

@@ -0,0 +1,18 @@
+"""LaunchDarkly AI SDK integration for native Vercel AI SDK agents."""
+
+__version__ = "0.1.0"  # x-release-please-version
+
+from launchdarkly_ai_server import register_ai_sdk_package
+
+from .graph import vercel_graph
+from .handler import create_vercel_agents_handler, vercel_agents
+from .native_graph import to_vercel_agents
+
+__all__ = [
+    "create_vercel_agents_handler",
+    "to_vercel_agents",
+    "vercel_agents",
+    "vercel_graph",
+]
+
+register_ai_sdk_package("launchdarkly-ai-vercel-agents", __version__)