Expand Python agent framework integrations (#235)

* feat(python): expand agent framework adapters

* fix(python): address agent adapter review feedback

Author: linfangw

docs/cn/zh-CN/js-sdk.md

@@ -154,7 +154,7 @@ const { text } = await generateText({
 });
 ```
 
-[Python SDK](python-sdk.md) 还提供 LangChain 和 OpenAI Agents SDK 适配器。
+[Python SDK](python-sdk.md) 还提供 LangChain/LangGraph、OpenAI Agents SDK、CrewAI、AutoGen、LlamaIndex 和 Pydantic AI 适配器。
 
 ## 错误处理
 

docs/cn/zh-CN/python-sdk.md

@@ -263,60 +263,104 @@ if handled and not is_error:
 
 ### 框架集成
 
-把 QVeris 的 discover/inspect/call 工作流暴露为主流 Agent 框架的工具。适配器惰性导入各自框架，因此基础 `qveris` 包不依赖它们。
+把 QVeris 的 discover/inspect/call 工作流暴露为主流 Agent 框架的原生工具。适配器惰性导入各自框架，因此基础 `qveris` 包不依赖它们。
 
-**LangChain**
+| 框架 | 原生工具类型 | Adapter 安装 | 完整 Agent 还需要 |
+|------|--------------|--------------|-------------------|
+| LangChain / LangGraph | `StructuredTool` | `pip install "qveris[langchain]"`（Adapter 支持 Python 3.9+） | 下方当前版 `create_agent` 示例需要 Python 3.10+、`langchain>=1.0` 和模型 provider 包。 |
+| OpenAI Agents SDK | `FunctionTool` | `pip install "qveris[openai-agents]"`（Python 3.10+） | 将工具传给 `Agent`，最后 `await client.close()`。 |
+| CrewAI | `BaseTool` | `pip install "qveris[crewai]"`（Python 3.10+） | Adapter 负责同步/异步桥接，最后调用 `aclose(client)`。 |
+| AutoGen | `autogen_core.tools.FunctionTool` | `pip install "qveris[autogen]"`（Python 3.10+） | 另装 `autogen-agentchat` 和模型扩展，如 `autogen-ext[openai]`。 |
+| LlamaIndex | `llama_index.core.tools.FunctionTool` | `pip install "qveris[llamaindex]"`（Python 3.10+） | 另装 `FunctionAgent` 使用的模型集成包；使用异步 Agent 或 `await tool.acall(...)`。 |
+| Pydantic AI | `pydantic_ai.Tool` | `pip install "qveris[pydantic-ai]"`（Python 3.10+） | Extra 为精简安装；另装模型 provider extra，如 `pydantic-ai-slim[openai]`。 |
+
+每次调用 `get_qveris_tools(client, session_id=...)` 都会按顺序返回 `qveris_discover`、`qveris_inspect`、`qveris_call` 三个工具。工具结果（包括 QVeris 错误结果）统一为 JSON 字符串，Agent 可以读取并自行调整参数或改选能力。`discover` 免费并返回 `search_id`，后续应把它传给 `inspect` 和 `call`。完整 Agent 运行既需要 `QVERIS_API_KEY`，也需要所选模型 provider 的 API key。
+
+**LangChain 与 LangGraph**
+
+使用 LangChain 当前的 `create_agent` API。它运行在 LangGraph 上；自定义 LangGraph 工作流也可以把同一组工具放入 `ToolNode`。
 
 ```bash
-pip install 'qveris[langchain]'
+pip install "qveris[langchain]" "langchain>=1.0" langchain-openai
 ```
 
 ```python
+import asyncio
+
+from langchain.agents import create_agent
 from qveris import QverisClient, QverisConfig
 from qveris.integrations.langchain import get_qveris_tools
 
-client = QverisClient(QverisConfig(base_url="https://qveris.cn/api/v1"))
-tools = get_qveris_tools(client)  # 3 个异步工具：qveris_discover / qveris_inspect / qveris_call
-# 把 `tools` 绑定到 LangChain 或 LangGraph agent，用完 `await client.close()`
-```
+async def main():
+    client = QverisClient(QverisConfig(base_url="https://qveris.cn/api/v1"))
+    try:
+        agent = create_agent("openai:gpt-4o-mini", tools=get_qveris_tools(client))
+        result = await agent.ainvoke({"messages": [{"role": "user", "content": "查找股票报价工具并查询 AAPL。"}]})
+        print(result)
+    finally:
+        await client.close()
 
-工具是异步的（用 `ainvoke` / 异步 agent executor）。
+asyncio.run(main())
+```
 
 **OpenAI Agents SDK**
 
-```bash
-pip install 'qveris[openai-agents]'
-```
-
 ```python
+import asyncio
+
 from agents import Agent, Runner
 from qveris import QverisClient, QverisConfig
 from qveris.integrations.openai_agents import get_qveris_tools
 
-client = QverisClient(QverisConfig(base_url="https://qveris.cn/api/v1"))
-agent = Agent(name="Assistant", tools=get_qveris_tools(client))
-result = await Runner.run(agent, "Find a stock quote capability and quote AAPL.")
-await client.close()
+async def main():
+    client = QverisClient(QverisConfig(base_url="https://qveris.cn/api/v1"))
+    try:
+        agent = Agent(name="Assistant", tools=get_qveris_tools(client))
+        result = await Runner.run(agent, "查找股票报价能力并查询 AAPL。")
+        print(result.final_output)
+    finally:
+        await client.close()
+
+asyncio.run(main())
 ```
 
 **CrewAI**
 
-```bash
-pip install 'qveris[crewai]'
-```
-
 ```python
 from crewai import Agent
 from qveris import QverisClient, QverisConfig
-from qveris.integrations.crewai import get_qveris_tools, aclose
+from qveris.integrations.crewai import aclose, get_qveris_tools
 
 client = QverisClient(QverisConfig(base_url="https://qveris.cn/api/v1"))
-agent = Agent(role="Researcher", goal="...", backstory="...", tools=get_qveris_tools(client))
-# 同步运行你的 crew（crew.kickoff()），然后：
+agent = Agent(role="Researcher", goal="选择正确能力", backstory="工具专家", tools=get_qveris_tools(client))
+# Crew(...).kickoff()
 aclose(client)
 ```
 
-CrewAI 同步执行工具；适配器在一个专用事件循环上桥接到异步 client。由于 client 的连接绑定在该循环上，请用 `aclose(client)` 关闭（而非 `await client.close()`）。TypeScript SDK 提供 Vercel AI SDK 适配器。
+CrewAI 的 client 连接运行在 Adapter 的专用事件循环中，因此要使用 `aclose(client)`，不能使用 `await client.close()`。
+
+**AutoGen、LlamaIndex 与 Pydantic AI**
+
+```python
+# 以下片段假设已配置 QverisClient 以及框架所需的 model_client / llm；
+# 只需选择与你的 Agent 框架对应的 Adapter。
+# AutoGen AssistantAgent
+from autogen_agentchat.agents import AssistantAgent
+from qveris.integrations.autogen import get_qveris_tools
+agent = AssistantAgent("assistant", model_client=model_client, tools=get_qveris_tools(client))
+
+# LlamaIndex FunctionAgent
+from llama_index.core.agent.workflow import FunctionAgent
+from qveris.integrations.llamaindex import get_qveris_tools
+agent = FunctionAgent(tools=get_qveris_tools(client), llm=llm)
+
+# Pydantic AI Agent
+from pydantic_ai import Agent
+from qveris.integrations.pydantic_ai import get_qveris_tools
+agent = Agent("openai:gpt-4o-mini", tools=get_qveris_tools(client))
+```
+
+完整的 provider 配置与资源关闭方式见下方可运行示例。TypeScript SDK 提供 Vercel AI SDK 适配器。
 
 ### 自定义 LLM provider
 
@@ -359,9 +403,15 @@ agent = Agent(llm_provider=MyProvider())
 | `explainable_routing.py` | 基于 `why_recommended` / `expected_cost` 的成本感知能力选型 |
 | `budget_guard.py` | 用 `Agent(budget_credits=...)` 设置会话级积分预算 |
 | `agent_loop_integration.py` | LLM agent 循环集成 |
+| `interactive_chat.py` | 交互式流式终端聊天 |
+| `stock_debate.py` | 多 Agent 股票研究辩论 |
 | `langchain_integration.py` | 把 QVeris 能力作为 LangChain 工具（`qveris[langchain]`） |
 | `openai_agents_integration.py` | 把 QVeris 能力作为 OpenAI Agents SDK 工具（`qveris[openai-agents]`） |
 | `crewai_integration.py` | 把 QVeris 能力作为 CrewAI 工具（`qveris[crewai]`） |
+| `autogen_integration.py` | 把 QVeris 能力作为 AutoGen 工具（`qveris[autogen]`） |
+| `llamaindex_integration.py` | 把 QVeris 能力作为 LlamaIndex 工具（`qveris[llamaindex]`） |
+| `pydantic_ai_integration.py` | 把 QVeris 能力作为 Pydantic AI 工具（`qveris[pydantic-ai]`） |
+| `otel_tracing.py` | 为 discover/call 生成 OpenTelemetry span（`qveris[otel]`） |
 
 设置 `QVERIS_API_KEY` 后，能力示例会运行 `discover`/`inspect`；仅当设置 `RUN_QVERIS_CALLS=1` 时才执行 `call`。运行前请确保已设置 `QVERIS_BASE_URL=https://qveris.cn/api/v1`。
 

docs/en-US/js-sdk.md

@@ -156,7 +156,7 @@ const { text } = await generateText({
 });
 ```
 
-The [Python SDK](python-sdk.md) ships LangChain and OpenAI Agents SDK adapters as well.
+The [Python SDK](python-sdk.md) ships adapters for LangChain/LangGraph, OpenAI Agents SDK, CrewAI, AutoGen, LlamaIndex, and Pydantic AI as well.
 
 ## Error handling
 

docs/en-US/python-sdk.md

@@ -260,60 +260,107 @@ if handled and not is_error:
 
 ### Framework integrations
 
-Expose the QVeris discover/inspect/call workflow as tools for popular agent frameworks. Adapters import their framework lazily, so the base `qveris` package never depends on them.
+Expose the QVeris discover/inspect/call workflow as native tools for popular agent frameworks. Adapters import their framework lazily, so the base `qveris` package never depends on them.
 
-**LangChain**
+| Framework | Native tool type | Adapter install | Complete agent setup |
+|-----------|------------------|-----------------|----------------------|
+| LangChain / LangGraph | `StructuredTool` | `pip install "qveris[langchain]"` (adapter: Python 3.9+) | The current `create_agent` example requires Python 3.10+, `langchain>=1.0`, and a model-provider package. |
+| OpenAI Agents SDK | `FunctionTool` | `pip install "qveris[openai-agents]"` (Python 3.10+) | Pass the tools to `Agent`; close with `await client.close()`. |
+| CrewAI | `BaseTool` | `pip install "qveris[crewai]"` (Python 3.10+) | Tools are sync/async bridged; close with `aclose(client)`. |
+| AutoGen | `autogen_core.tools.FunctionTool` | `pip install "qveris[autogen]"` (Python 3.10+) | Also install `autogen-agentchat` and a model extension such as `autogen-ext[openai]`. |
+| LlamaIndex | `llama_index.core.tools.FunctionTool` | `pip install "qveris[llamaindex]"` (Python 3.10+) | Also install the model integration used by `FunctionAgent`; use an async agent or `await tool.acall(...)`. |
+| Pydantic AI | `pydantic_ai.Tool` | `pip install "qveris[pydantic-ai]"` (Python 3.10+) | The extra is slim; add a provider extra such as `pydantic-ai-slim[openai]`. |
+
+Every `get_qveris_tools(client, session_id=...)` call returns exactly three tools: `qveris_discover`, `qveris_inspect`, and `qveris_call`. Results, including QVeris error payloads, are JSON strings so the agent can inspect them and recover. `discover` is free and returns a `search_id`; pass that ID to `inspect` and `call`. A complete agent run needs `QVERIS_API_KEY` plus the API key required by its model provider.
+
+**LangChain and LangGraph**
+
+Use LangChain's current `create_agent` API. It runs on LangGraph; custom LangGraph workflows can put the same tools in a `ToolNode`.
 
 ```bash
-pip install 'qveris[langchain]'
+pip install "qveris[langchain]" "langchain>=1.0" langchain-openai
 ```
 
 ```python
+import asyncio
+
+from langchain.agents import create_agent
 from qveris import QverisClient
 from qveris.integrations.langchain import get_qveris_tools
 
-client = QverisClient()
-tools = get_qveris_tools(client)  # 3 async tools: qveris_discover / qveris_inspect / qveris_call
-# bind `tools` to a LangChain or LangGraph agent, then `await client.close()` when done
-```
+async def main():
+    client = QverisClient()
+    try:
+        agent = create_agent("openai:gpt-4o-mini", tools=get_qveris_tools(client))
+        result = await agent.ainvoke({"messages": [{"role": "user", "content": "Find a stock quote tool and quote AAPL."}]})
+        print(result)
+    finally:
+        await client.close()
 
-The tools are async (use `ainvoke` / an async agent executor).
+asyncio.run(main())
+```
 
 **OpenAI Agents SDK**
 
-```bash
-pip install 'qveris[openai-agents]'
-```
-
 ```python
+import asyncio
+
 from agents import Agent, Runner
 from qveris import QverisClient
 from qveris.integrations.openai_agents import get_qveris_tools
 
-client = QverisClient()
-agent = Agent(name="Assistant", tools=get_qveris_tools(client))
-result = await Runner.run(agent, "Find a stock quote capability and quote AAPL.")
-await client.close()
+async def main():
+    client = QverisClient()
+    try:
+        agent = Agent(name="Assistant", tools=get_qveris_tools(client))
+        result = await Runner.run(agent, "Find a stock quote capability and quote AAPL.")
+        print(result.final_output)
+    finally:
+        await client.close()
+
+asyncio.run(main())
 ```
 
 **CrewAI**
 
-```bash
-pip install 'qveris[crewai]'
-```
-
 ```python
 from crewai import Agent
 from qveris import QverisClient
-from qveris.integrations.crewai import get_qveris_tools, aclose
+from qveris.integrations.crewai import aclose, get_qveris_tools
 
 client = QverisClient()
-agent = Agent(role="Researcher", goal="...", backstory="...", tools=get_qveris_tools(client))
-# run your crew synchronously (crew.kickoff()), then:
+agent = Agent(role="Researcher", goal="Use the right capability", backstory="Tool specialist", tools=get_qveris_tools(client))
+# Crew(...).kickoff()
 aclose(client)
 ```
 
-CrewAI runs tools synchronously; these bridge to the async client on one dedicated event loop. Close the client with `aclose(client)` (not `await client.close()`), since its connections are bound to that loop. The TypeScript SDK ships a Vercel AI SDK adapter.
+CrewAI's client connections run on the adapter's dedicated event loop, so use `aclose(client)` rather than `await client.close()`.
+
+**AutoGen, LlamaIndex, and Pydantic AI**
+
+```python
+# The following snippets assume a configured QverisClient plus the framework's
+# model_client / llm. Choose the adapter that matches your agent framework.
+# AutoGen AssistantAgent
+from autogen_agentchat.agents import AssistantAgent
+from qveris.integrations.autogen import get_qveris_tools
+
+agent = AssistantAgent("assistant", model_client=model_client, tools=get_qveris_tools(client))
+
+# LlamaIndex FunctionAgent
+from llama_index.core.agent.workflow import FunctionAgent
+from qveris.integrations.llamaindex import get_qveris_tools
+
+agent = FunctionAgent(tools=get_qveris_tools(client), llm=llm)
+
+# Pydantic AI Agent
+from pydantic_ai import Agent
+from qveris.integrations.pydantic_ai import get_qveris_tools
+
+agent = Agent("openai:gpt-4o-mini", tools=get_qveris_tools(client))
+```
+
+See the runnable examples below for provider setup and complete client cleanup. The TypeScript SDK ships a Vercel AI SDK adapter.
 
 ### Custom LLM providers
 
@@ -356,9 +403,15 @@ Runnable examples live under [`packages/python-sdk/examples/`](https://github.co
 | `explainable_routing.py` | Cost-aware capability selection with `why_recommended` / `expected_cost` |
 | `budget_guard.py` | Per-session credit budget with `Agent(budget_credits=...)` |
 | `agent_loop_integration.py` | LLM agent loop integration |
+| `interactive_chat.py` | Interactive streaming terminal chat |
+| `stock_debate.py` | Multi-agent stock research debate |
 | `langchain_integration.py` | QVeris capabilities as LangChain tools (`qveris[langchain]`) |
 | `openai_agents_integration.py` | QVeris capabilities as OpenAI Agents SDK tools (`qveris[openai-agents]`) |
 | `crewai_integration.py` | QVeris capabilities as CrewAI tools (`qveris[crewai]`) |
+| `autogen_integration.py` | QVeris capabilities as AutoGen tools (`qveris[autogen]`) |
+| `llamaindex_integration.py` | QVeris capabilities as LlamaIndex tools (`qveris[llamaindex]`) |
+| `pydantic_ai_integration.py` | QVeris capabilities as Pydantic AI tools (`qveris[pydantic-ai]`) |
+| `otel_tracing.py` | OpenTelemetry spans for discover/call (`qveris[otel]`) |
 
 Capability examples run `discover`/`inspect` when `QVERIS_API_KEY` is set, and only execute `call` when `RUN_QVERIS_CALLS=1`.
 

docs/zh-CN/js-sdk.md

@@ -154,7 +154,7 @@ const { text } = await generateText({
 });
 ```
 
-[Python SDK](python-sdk.md) 还提供 LangChain 和 OpenAI Agents SDK 适配器。
+[Python SDK](python-sdk.md) 还提供 LangChain/LangGraph、OpenAI Agents SDK、CrewAI、AutoGen、LlamaIndex 和 Pydantic AI 适配器。
 
 ## 错误处理