把本地 LLM 变成会用工具的研究 Agent：Ollama + OpenAI Agents SDK + Tavily MCP 实战

用户问题
  ↓
OpenAI Agents SDK 负责 agent loop
  ↓
本地 Ollama / Gemma 4 负责生成与决策
  ↓
Tavily MCP 提供网页搜索工具
  ↓
Agent 返回带来源的简短研究答案

curl -fsSL https://ollama.com/install.sh | sh
ollama --version

winget install Ollama.Ollama

http://localhost:11434

curl http://localhost:11434/api/version

{"version":"0.x.x"}

ollama pull gemma4:e4b

ollama pull gemma4:e2b

ollama list

curl http://localhost:11434/api/generate -d '{
  "model": "gemma4:e4b",
  "prompt": "Say hello in one sentence.",
  "stream": false
}'

mkdir local-research-agent
cd local-research-agent
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install openai-agents openai

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install openai-agents openai

https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>

export TAVILY_API_KEY="tvly-..."

$env:TAVILY_API_KEY="tvly-..."

import asyncio
import os
from datetime import datetime
from urllib.parse import quote

from agents import Agent, OpenAIChatCompletionsModel, Runner
from agents.mcp import MCPServerStreamableHttp
from openai import AsyncOpenAI

MODEL_NAME = os.getenv("OLLAMA_MODEL", "gemma4:e4b")
OLLAMA_BASE_URL = os.getenv("OLLAMA_BASE_URL", "http://localhost:11434/v1")
MAX_TURNS = 4

RESEARCH_QUESTION = (
    "Which June 23, 2026 World Cup match had the biggest group-stage stakes, "
    "and why?"
)


def build_tavily_mcp_url() -> str:
    api_key = os.environ.get("TAVILY_API_KEY")
    if not api_key:
        raise RuntimeError("Set TAVILY_API_KEY before running this script.")
    return f"https://mcp.tavily.com/mcp/?tavilyApiKey={quote(api_key)}"


def build_research_instructions() -> str:
    current_date = datetime.now().strftime("%B %d, %Y")
    return f"""
[Role]
You are a concise research assistant.

[Task]
Answer the user's question by turning it into a small web research task.
Use the current date when interpreting time-sensitive questions: {current_date}.

[Research behavior]
Start with one targeted search query.
Use follow-up searches when the first results are insufficient, conflicting, or incomplete.
Prefer relevant and credible sources.
Track which source supports each important claim.
Before answering, check whether the gathered evidence is enough to support the conclusion.

[Expected output]
Give a direct answer first, then briefly explain the evidence behind it.
Include source links for key factual claims.

[Rules]
Do not rely on memory for facts that may have changed.
Do not invent missing details.
Keep the answer concise.
""".strip()


def compact(value: object, limit: int = 220) -> str:
    text = str(value).replace("\n", " ")
    if len(text) <= limit:
        return text
    return text[:limit] + "..."


async def run_agent() -> None:
    client = AsyncOpenAI(
        api_key="ollama",
        base_url=OLLAMA_BASE_URL,
    )
    model = OpenAIChatCompletionsModel(
        model=MODEL_NAME,
        openai_client=client,
    )

    async with MCPServerStreamableHttp(
        name="tavily",
        params={"url": build_tavily_mcp_url()},
    ) as tavily_server:
        tools = await tavily_server.list_tools()
        print("Available Tavily tools:")
        for tool in tools:
            description = (tool.description or "").replace("\n", " ")
            print(f"- {tool.name}: {description[:120]}")

        agent = Agent(
            name="Local Research Agent",
            instructions=build_research_instructions(),
            model=model,
            mcp_servers=[tavily_server],
            mcp_config={"include_server_in_tool_names": True},
        )

        result = await Runner.run(agent, RESEARCH_QUESTION, max_turns=MAX_TURNS)

        print("\nTrace:")
        for step, item in enumerate(result.new_items, start=1):
            raw_item = getattr(item, "raw_item", None)
            raw_type = getattr(raw_item, "type", "")
            raw_name = getattr(raw_item, "name", "")
            raw_output = getattr(raw_item, "output", "")
            print(
                f"{step:02d} | {type(item).__name__} | "
                f"{raw_type or raw_name} | {compact(raw_output or raw_item)}"
            )

        print("\nFinal answer:")
        print(result.final_output)


if __name__ == "__main__":
    asyncio.run(run_agent())

python main.py

Available Tavily tools:
- tavily_search: ...

Trace:
01 | ToolCallItem | function_call | ... mcp_tavily__tavily_search ...
02 | ToolCallOutputItem | ...
03 | MessageOutputItem | message | ...

Final answer:
...

import json
import os
import sys
import urllib.error
import urllib.request

OLLAMA_BASE_URL = os.getenv("OLLAMA_HOST", "http://localhost:11434")
MODEL_NAME = os.getenv("OLLAMA_MODEL", "gemma4:e4b")


def fetch_json(url: str) -> dict:
    request = urllib.request.Request(url, headers={"Accept": "application/json"})
    with urllib.request.urlopen(request, timeout=5) as response:
        return json.loads(response.read().decode("utf-8"))


def fail(message: str) -> None:
    print(f"[FAIL] {message}")
    raise SystemExit(1)


def main() -> None:
    if not os.environ.get("TAVILY_API_KEY"):
        fail("TAVILY_API_KEY is not set.")

    try:
        version = fetch_json(f"{OLLAMA_BASE_URL}/api/version")
    except urllib.error.URLError as exc:
        fail(f"Cannot reach Ollama at {OLLAMA_BASE_URL}: {exc}")

    models = fetch_json(f"{OLLAMA_BASE_URL}/api/tags")
    model_names = {model.get("name") for model in models.get("models", [])}
    if MODEL_NAME not in model_names:
        fail(f"Model {MODEL_NAME!r} is not installed. Run: ollama pull {MODEL_NAME}")

    print(f"[OK] Ollama version: {version.get('version')}")
    print(f"[OK] Model installed: {MODEL_NAME}")
    print("[OK] TAVILY_API_KEY is set")


if __name__ == "__main__":
    main()

python preflight.py

[OK] Ollama version: 0.x.x
[OK] Model installed: gemma4:e4b
[OK] TAVILY_API_KEY is set

01 | ToolCallItem | function_call | ResponseFunctionToolCall(... name='mcp_tavily__tavily_search' ...)
02 | ToolCallOutputItem | ...
03 | MessageOutputItem | message | ... final answer ...

curl http://localhost:11434/api/version

ollama list
ollama pull gemma4:e4b

export OLLAMA_MODEL="gemma4:e2b"
ollama pull gemma4:e2b
python main.py

echo "$TAVILY_API_KEY"

For any question involving current or externally verifiable facts, call the search tool before answering.

If evidence is weak or conflicting, say so explicitly and avoid a definitive answer.
List the source that supports each key claim.

本地模型 → Agent runtime → MCP 工具 → 可观测 trace → 带证据输出