vectara-agentic

一句话定位

一个构建在 LlamaIndex Agent 框架之上的 Agentic-RAG 库：核心卖点是把 Vectara 的检索/RAG 管线“一行代码封装成工具”（create_rag_tool / create_search_tool），再让 ReAct 或 Function-Calling agent 调度这些工具；并内置多 LLM provider、流式、可观测（Arize Phoenix）以及 Vectara 自家的幻觉纠正（VHC）。

设计理念 / 顶层架构

vectara-agentic 不重写 agent 内核，而是 薄封装 LlamaIndex 的 workflow-based agent（FunctionAgent / ReActAgent），把自己的价值集中在“检索即工具”和“RAG 专属配套能力”上。设计取舍：

• 检索封装为工具（核心范式）：VectaraToolFactory.create_rag_tool()（vectara_agentic/tools.py:448）与 create_search_tool()（tools.py:199）把一次 Vectara RAG/检索调用动态生成成一个 FunctionTool。RAG 工具自动注入 query 参数，再追加用户用 Pydantic schema（tool_args_schema）声明的元数据过滤字段（如 year/ticker）；这些字段经 build_filter_string（tool_utils.py:543）翻译成 Vectara 的 metadata filter，并支持 year='>2022' 这类条件表达式。
• 工厂模式 + 动态函数：所有工具都经 create_tool_from_dynamic_function（tool_utils.py:386）根据签名/schema 生成；ToolsFactory.create_tool()（tools.py:763）把任意 Python 函数转工具，get_llama_index_tools()（tools.py:784）桥接 LlamaIndex ToolSpecs（Tavily/EXA/arXiv/Slack/Google 等）。
• 薄 Agent 内核：Agent 类（vectara_agentic/agent.py:78）只持有 tools/memory/config，真正的 agent 由 create_agent_from_config（agent_core/factory.py:157）按 agent_type 委托给 LlamaIndex 的 FunctionAgent 或 ReActAgent。两类 agent 都是 LlamaIndex workflow，achat() 内部用 current_agent.run(...) 跑 workflow（agent.py:602）。
• 配置集中：AgentConfig（冻结 dataclass，agent_config.py:10）统一 agent_type、main/tool 两套 LLM provider、private LLM、observer，全部可由环境变量回退。
• 入口 API：from vectara_agentic import Agent；agent.chat() / achat() 返回 AgentResponse，stream_chat() / astream_chat() 返回 AgentStreamingResponse（types.py:111）。

最小示例（取自 README）：

import os
from vectara_agentic.tools import VectaraToolFactory
from vectara_agentic import Agent
from pydantic import BaseModel, Field

vec_factory = VectaraToolFactory(
    vectara_api_key=os.environ["VECTARA_API_KEY"],
    vectara_corpus_key=os.environ["VECTARA_CORPUS_KEY"],
)

class QueryFinancialReportsArgs(BaseModel):
    year: int | str = Field(..., description="The year, e.g. 2022 or '>2020'")
    ticker: str = Field(..., description="The company ticker, e.g. AAPL")

# 检索被封装成一个工具；query 参数由 create_rag_tool 自动添加
ask_finance = vec_factory.create_rag_tool(
    tool_name="query_financial_reports",
    tool_description="Query financial reports for a company and year",
    tool_args_schema=QueryFinancialReportsArgs,
)

agent = Agent(
    tools=[ask_finance],
    topic="10-K annual financial reports",
    custom_instructions="You are a helpful financial assistant.",
)
print(agent.chat("What was the revenue for Apple in 2021?").response)

组件实现（横向逐项，无则标 N/A）

设计权衡与特性

• “RAG 优先、薄封装 LlamaIndex” vs 自研内核：与 ConnectOnion 那种自带循环/事件/插件的“电池全包”内核不同，vectara-agentic 几乎不自研 agent 循环——FunctionAgent/ReActAgent 全来自 LlamaIndex。它的差异化完全压在 “检索即工具” 这一层：create_rag_tool 自动注入 query、把 Pydantic 字段映射成 Vectara 元数据过滤、支持 >2022 条件与 fixed_filter，让“给语料配一个带过滤维度的检索工具”变成一行代码。
• 双 LLM 角色：主 agent LLM 与工具内部 LLM（summarize/rephrase 等）可分开配置（LLMRole.MAIN/TOOL），便于“强模型做编排、便宜模型做摘要”。
• VHC（Vectara Hallucination Correction）是独特卖点：对最终回答做幻觉检测与纠正，且只采信标记为 vhc_eligible=True 的工具输出作为事实依据（tools.py:489、agent.py:914）。这是把厂商自有的事实一致性能力（FCS）下沉到 agent 评估层，同类通用框架罕见。
• 生产配套齐全：内置 Arize Phoenix 可观测、OpenAI 兼容 HTTP 端点、Docker、序列化（cloudpickle），定位“快速做出可上线的 Agentic-RAG 助手”。
• 能力边界 / 待确认：① 无真正的多 agent 编排与交互式人在环/审批——多步靠 workflow 子问题分解模拟；② 强绑定 LlamaIndex 版本（requirements.txt 锁 llama-index==0.14.7 等精确版本），升级面较脆；③ 对 Vectara 平台有耦合（RAG 工具、VHC、FCS 评估均依赖 Vectara API key）；④ v0.4 起移除 Fireworks、OPENAI AgentType、StructuredPlanning、token counting（迁移注意，README 有说明）。

关联

• component-taxonomy · tool-use · observability-eval
• 同范式(RAG/检索封装为工具)：connectonion · 源码：agents-example/vectara-agentic/