Introduction

Calling a provider's raw API is easy. Turning that into a real agent — one that calls tools, remembers a conversation, knows what it costs, and doesn't loop forever — is a week of plumbing every team ends up rebuilding.

VisvoAI is that plumbing, published as two independent, MIT-licensed packages:

• visvoai-ai — one interface to any provider's chat model, plus a live registry of model facts (pricing, context window, capabilities, thinking levels) most facades skip.
• visvoai-core — the agent↔tools loop on LangGraph, done once: a soft step cap instead of GraphRecursionError, semantic tool retrieval for large tool fleets, and a tool lifecycle with pluggable persistence.

Use either on its own. visvoai-core takes any LangChain BaseChatModel — it does not require visvoai-ai. Both are proven by two real consumers: visvoai-cli, a full terminal coding agent built on this stack unmodified, and a hosted platform that subclasses the same extension seams documented here.

Install

pip install "visvoai-ai[gemini]"   # or [anthropic] / [openai] / [all]
pip install visvoai-core           # pulls langgraph + langchain-core only

Sixty seconds to a working agent

from visvoai.ai import build_chat_model
from visvoai.core.runtime import AgentRuntime
from visvoai.core import ask
from langchain_core.tools import tool

@tool
def read_file(path: str) -> str:
    """Read a file and return its contents."""
    return open(path).read()

graph = AgentRuntime().build_graph(
    model=build_chat_model("gemini:gemini-2.5-flash"),
    core_tools=[read_file],
    system_prompt="You are a code assistant.",
)

# inside an async function, or via asyncio.run(...)
answer = await ask(graph, "What's in pyproject.toml?")

How the docs are organized

visvoai-ai

• Providers & the model registry — build_chat_model, the provider facade classes, the deployment id codec, and the models.dev catalog
• Cost, usage & thinking levels — cost_of, usage_from, and the normalized ThinkingLevel scale
• Grounded search & URL fetch — run_search / fetch_url

visvoai-core

• The agent loop — AgentRuntime, build_graph, the soft step cap
• Defining tools — the four tool shapes build_graph accepts
• Extension seams — every hook for reshaping the graph
• Persistence — ToolPersistence / LLMPersistence
• Tool retrieval at scale — ToolCatalog, per_round_retrieve
• Subagents — an agent calling another agent

Reference

• Migrating from LangChain
• When not to use this
• API reference — every public signature, both packages
• Quickstart: a full example — a runnable ops-assistant in one file

When not to use this

If you want hundreds of integrations, chains, and a batteries-included ecosystem, use LangChain/LangGraph directly — that's what they're for. VisvoAI is for when you're building a product on the loop and want the sharp edges (recursion deaths, runaway rounds, tool sprawl, lifecycle plumbing, provider spelling of "reasoning") already filed down. See When not to use this for the full case.