Skip to content

Framework integrations ​

Usefully is OpenAI-compatible, so frameworks with an OpenAI-compatible client work out of the box. Each snippet below is tested against the API.

Vercel AI SDK ​

Use the @usefully/ai-sdk provider:

bash
npm install @usefully/ai-sdk ai
ts
import { generateText, streamText, embedMany } from "ai";
import { usefully } from "@usefully/ai-sdk"; // reads USEFULLY_API_KEY

const { text } = await generateText({
  model: usefully("anthropic/claude-sonnet-5-5"),
  prompt: "Write a haiku about failover.",
  // Optional routing preferences:
  providerOptions: { usefully: { provider: { order: ["anthropic"] } } },
});

const result = streamText({ model: usefully("anthropic/claude-sonnet-5-5"), prompt: "Count to five." });
for await (const part of result.textStream) process.stdout.write(part);

const { embeddings } = await embedMany({
  model: usefully.embeddingModel("voyage/voyage-3.5"),
  values: ["first", "second"],
});

createUsefully({ apiKey, baseURL, headers, fetch }) makes a configured instance.

LangChain (Python) ​

bash
pip install langchain-openai
python
import os
from langchain_openai import ChatOpenAI, OpenAIEmbeddings

llm = ChatOpenAI(
    base_url="https://api.usefully.info/v1",
    api_key=os.environ["USEFULLY_API_KEY"],
    model="anthropic/claude-sonnet-5-5",
    # Optional routing preferences:
    extra_body={"provider": {"sort": "latency"}},
)
print(llm.invoke("Hello!").content)

embeddings = OpenAIEmbeddings(
    base_url="https://api.usefully.info/v1",
    api_key=os.environ["USEFULLY_API_KEY"],
    model="voyage/voyage-3.5",
    # Required for non-OpenAI models: send text, not tiktoken token IDs.
    check_embedding_ctx_length=False,
)

LangChain (JavaScript) ​

ts
import { ChatOpenAI, OpenAIEmbeddings } from "@langchain/openai";

const llm = new ChatOpenAI({
  model: "anthropic/claude-sonnet-5-5",
  apiKey: process.env.USEFULLY_API_KEY,
  configuration: { baseURL: "https://api.usefully.info/v1" },
});

LlamaIndex ​

bash
pip install llama-index-llms-openai-like llama-index-embeddings-openai-like
python
import os
from llama_index.llms.openai_like import OpenAILike
from llama_index.embeddings.openai_like import OpenAILikeEmbedding

llm = OpenAILike(
    api_base="https://api.usefully.info/v1",
    api_key=os.environ["USEFULLY_API_KEY"],
    model="anthropic/claude-sonnet-5-5",
    is_chat_model=True,
    context_window=128_000,
)
embed_model = OpenAILikeEmbedding(
    api_base="https://api.usefully.info/v1",
    api_key=os.environ["USEFULLY_API_KEY"],
    model_name="voyage/voyage-3.5",
)

Use OpenAILike (not OpenAI): the OpenAI class rejects model names it doesn't know.

CrewAI ​

bash
pip install "usefully[crewai]"
python
from crewai import Agent
from usefully.integrations.crewai import usefully_tools

researcher = Agent(
    role="Researcher",
    goal="Answer questions with current, cited sources",
    backstory="You check facts on the web before answering.",
    tools=usefully_tools(),  # web search, page reading, deep research
)

usefully_tools() reads USEFULLY_API_KEY. To use a different client, pass usefully_tools(Usefully(api_key=…)). For agents that should stay fast and cheap, pass include_research=False to drop the deep research tool.

n8n ​

Install the community node n8n-nodes-usefully (Settings → Community Nodes), then add a Usefully API credential. The Usefully node can:

  • chat with any model
  • search the web
  • read pages
  • run deep research, waiting for the cited report
  • embed text

Each input item becomes one request.