Skip to content

docs(migration): pinned @ai-sdk/open-responses Agent API example (OpenCode cleanup, draft for Andrew) - #9

Draft
connectors-testing-pplx wants to merge 2 commits into
perplexityai:mainfrom
connectors-testing-pplx:opencode-sonar-to-agent-ai-sdk-cleanup
Draft

docs(migration): pinned @ai-sdk/open-responses Agent API example (OpenCode cleanup, draft for Andrew)#9
connectors-testing-pplx wants to merge 2 commits into
perplexityai:mainfrom
connectors-testing-pplx:opencode-sonar-to-agent-ai-sdk-cleanup

Conversation

@connectors-testing-pplx

Copy link
Copy Markdown

Summary

OpenCode integration cleanup for the Sonar → Agent API migration. Adds a runnable, pinned Vercel AI SDK (@ai-sdk/open-responses) example that reaches the Agent API through Perplexity's /v1/responses endpoint, independent of models.dev.

This is a Draft PR for Andrew to review — not ready for review, no reviewers requested, do not merge or publish.

Why

The live docs page (Perplexity with the Vercel AI SDK) shows the provider setup but ships no standalone runnable file and does not call out two production-relevant points:

  1. Version pinningai and @ai-sdk/open-responses move fast; a floating install can pull a release that changes the provider protocol or the createOpenResponses signature.
  2. No models.dev dependency@ai-sdk/open-responses does not use the models.dev registry at runtime; the model id passed to the provider factory is sent straight through to the API. The Agent API path keeps working even if models.dev is unavailable or changes. This example makes that explicit.

What changed

  • examples/vercel-ai-sdk/agent-api-openresponses.mjs — standalone runnable example: generateText + fetch hook for web_search injection and search_results source capture; status branching for 200-wrapped failures; preset note.
  • examples/vercel-ai-sdk/README.md — setup, run, full Agent API field mapping, models.dev-independence rationale, version-pinning table, streaming/preset variants, and live-test evidence.
  • references/integration-styles.md — new "Vercel AI SDK" section (integration style (e)) covering version pinning, no models.dev dependency, web_search via fetch hook, citations in the output array, 200-wrapped failures, server-side provider creation, and the minimal shape.
  • SKILL.md — add style (e) Vercel AI SDK to the Step 1 integration-style list with a pointer to the runnable example.

Verified versions

Package Pinned version
ai 7.0.93
@ai-sdk/open-responses 2.0.39

Install and run together on Node 20+ (packages declare node>=22; Node 20 works but emits an engine warning).

Live-test evidence

Captured against production with no API key (proves the path resolves, not just that it compiles):

$ npm install ai@7.0.93 @ai-sdk/open-responses@2.0.39
$ node agent-api-openresponses.mjs
REACHED_API_BUT_UNAUTHORIZED: AI_APICallError: Unauthorized

A clean HTTP 401 from api.perplexity.ai/v1/responses — not a transport, DNS, or registry error. With a valid key the run returns status: completed, answer text, and a populated search_results array. The example is explicitly independent of models.dev (no registry lookup at runtime).

Notes for review

  • The /v1/responses URL is the OpenAI-compatible alias of the canonical /v1/agent endpoint — both reach the Agent API; this matches the existing live docs page.
  • No existing example is changed; this is purely additive.
  • Draft only — happy to revise before this goes ready for review.

… independent of models.dev

OpenCode integration cleanup for the Sonar -> Agent API migration. Adds a
runnable Vercel AI SDK example that reaches the Agent API through
@ai-sdk/open-responses pointed at https://api.perplexity.ai/v1/responses,
pinned to verified-compatible versions (ai@7.0.93,
@ai-sdk/open-responses@2.0.39), and explicitly independent of models.dev
(the model id is passed straight through to the provider factory; no
registry lookup at runtime).

- examples/vercel-ai-sdk/agent-api-openresponses.mjs: standalone runnable
  example (generateText + fetch hook for web_search/sources; status branching
  for 200-wrapped failures; preset note).
- examples/vercel-ai-sdk/README.md: setup, run, full Agent API field mapping,
  models.dev-independence rationale, version-pinning table, streaming/preset
  variants, and live-test evidence.
- references/integration-styles.md: new "Vercel AI SDK" section (style (e))
  covering version pinning, no models.dev dependency, web_search via fetch
  hook, citations in the output array, 200-wrapped failures, server-side
  provider creation, and the minimal shape.
- SKILL.md: add style (e) Vercel AI SDK to the Step 1 integration-style list
  with a pointer to the runnable example.

Live-tested against production: with no key the example returns a clean
HTTP 401 from api.perplexity.ai/v1/responses (the path resolves; not a
transport/DNS/registry error), proving the Agent API path works without a
models.dev dependency.
Tracks the OpenCode integration cleanup status and captures the live-test
evidence for API-3600 (Linear connector session expired; this file is the
durable record until the session is restored and the comment can be posted).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant