Pi Agent 실천 가이드

Pi에 deep_search 도구를 추가합니다.

이 도구는 다음을 받습니다.
- query: 사용자가 연구할 질문
- depth: 검색 깊이
- maxResults: 반환할 최대 후보 자료 수

이 도구는 다음을 출력합니다.
- 구조화된 검색 결과
- 각 결과의 제목, URL, 요약, 관련성
- 모델이 사용할 증거 힌트

Pi는 이 증거를 받은 후 현재 모델이 최종 결론을 생성합니다.

.pi/extensions/deepsearch/
  package.json
  index.ts

export TAVILY_API_KEY=tvly-...

mkdir -p .pi/extensions/deepsearch

{
  "name": "pi-deepsearch-extension",
  "private": true,
  "dependencies": {
    "typebox": "*",
    "@earendil-works/pi-ai": "*",
    "@earendil-works/pi-coding-agent": "*"
  },
  "pi": {
    "extensions": ["./index.ts"]
  }
}

cd .pi/extensions/deepsearch
npm install

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { StringEnum } from "@earendil-works/pi-ai";
import { Type } from "typebox";

type SearchResult = {
  title: string;
  url: string;
  snippet: string;
  score?: number;
};

export default function (pi: ExtensionAPI) {
  pi.registerTool({
    name: "deep_search",
    label: "DeepSearch",
    description: "Search the web for source-backed evidence about a question.",
    promptSnippet: "Research a question with web search and return source-backed evidence.",
    promptGuidelines: [
      "Use deep_search when the user asks for current facts, external sources, comparison, investigation, or source-backed research.",
      "After deep_search returns results, synthesize an answer with citations and clearly separate facts, inference, and uncertainty.",
      "Do not treat deep_search results as final truth; inspect source quality and mention gaps."
    ],
    parameters: Type.Object({
      query: Type.String({
        description: "The research question or search query."
      }),
      depth: Type.Optional(StringEnum(["quick", "normal", "deep"] as const)),
      maxResults: Type.Optional(Type.Number({
        minimum: 3,
        maximum: 10,
        default: 6
      }))
    }),
    async execute(_toolCallId, params, signal) {
      const depth = params.depth ?? "normal";
      const maxResults = params.maxResults ?? 6;
      const results = await searchWeb(params.query, depth, maxResults, signal);

      return {
        content: [
          {
            type: "text",
            text: formatResultsForModel(params.query, results)
          }
        ],
        details: {
          query: params.query,
          depth,
          results
        }
      };
    }
  });
}

async function searchWeb(
  query: string,
  depth: "quick" | "normal" | "deep",
  maxResults: number,
  signal: AbortSignal
): Promise<SearchResult[]> {
  const apiKey = process.env.TAVILY_API_KEY;
  if (!apiKey) {
    throw new Error("Missing TAVILY_API_KEY. Set it before starting pi.");
  }

  const response = await fetch("https://api.tavily.com/search", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      api_key: apiKey,
      query,
      search_depth: depth === "quick" ? "basic" : "advanced",
      max_results: maxResults,
      include_answer: false,
      include_raw_content: depth === "deep"
    }),
    signal
  });

  if (!response.ok) {
    throw new Error(`Search failed: ${response.status} ${response.statusText}`);
  }

  const data = await response.json() as {
    results?: Array<{
      title?: string;
      url?: string;
      content?: string;
      score?: number;
    }>;
  };

  return dedupeByUrl((data.results ?? []).map((item) => ({
    title: item.title ?? "Untitled",
    url: item.url ?? "",
    snippet: item.content ?? "",
    score: item.score
  }))).filter((item) => item.url);
}

function dedupeByUrl(results: SearchResult[]): SearchResult[] {
  const seen = new Set<string>();
  const deduped: SearchResult[] = [];

  for (const result of results) {
    const key = normalizeUrl(result.url);
    if (seen.has(key)) continue;
    seen.add(key);
    deduped.push(result);
  }

  return deduped;
}

function normalizeUrl(url: string): string {
  try {
    const parsed = new URL(url);
    parsed.hash = "";
    parsed.searchParams.delete("utm_source");
    parsed.searchParams.delete("utm_medium");
    parsed.searchParams.delete("utm_campaign");
    return parsed.toString();
  } catch {
    return url;
  }
}

function formatResultsForModel(query: string, results: SearchResult[]): string {
  if (results.length === 0) {
    return `DeepSearch found no results for: ${query}`;
  }

  const lines = results.map((result, index) => {
    return [
      `## Source ${index + 1}`,
      `Title: ${result.title}`,
      `URL: ${result.url}`,
      result.score === undefined ? undefined : `Score: ${result.score}`,
      `Snippet: ${result.snippet}`
    ].filter(Boolean).join("\n");
  });

  return [
    `DeepSearch query: ${query}`,
    "",
    "Use these sources as evidence. Cite URLs when making factual claims.",
    "Separate confirmed facts from inference and uncertainty.",
    "",
    ...lines
  ].join("\n\n");
}

export default function (pi: ExtensionAPI) {
  pi.registerCommand("deepsearch", {
    description: "Run a source-backed DeepSearch task",
    handler: async (args, ctx) => {
      const query = String(args ?? "").trim();

      if (!query) {
        ctx.ui.notify("Usage: /deepsearch <question>", "warning");
        return;
      }

      pi.sendUserMessage(
        [
          "아래 질문에 대해 DeepSearch를 수행해 주세요.",
          "",
          `질문: ${query}`,
          "",
          "요구 사항:",
          "1. 먼저 deep_search를 호출해야 하는지 판단합니다.",
          "2. 질문이 복잡하면 2-4개의 하위 질문으로 분해하여 각각 검색합니다.",
          "3. 최종 답변에는 반드시 출처 링크가 포함되어야 합니다.",
          "4. 사실, 추론 및 아직 불확실한 부분을 구분합니다.",
          "5. 검색 결과를 그대로 나열하지 말고, 종합적인 판단을 제시합니다."
        ].join("\n"),
        { deliverAs: "followUp" }
      );
    }
  });

  pi.registerTool({
    // deep_search tool definition...
  });
}

/deepsearch Pi Coding Agent의 extension 메커니즘은 어떤 기능에 적합한가요?

TAVILY_API_KEY=tvly-... pi

TAVILY_API_KEY=tvly-... pi -e ./.pi/extensions/deepsearch/index.ts

/deepsearch Pi Coding Agent 최신 버전의 extension 시스템은 어떤 기능을 지원하나요?

promptGuidelines: [
  "Use deep_search to gather evidence, not to produce the final answer.",
  "After deep_search, write a concise research brief with citations.",
  "Prefer official documentation, source code, release notes, and primary sources.",
  "Mention when sources disagree or when the evidence is incomplete."
]

Pi Agent가 Claude Code를 대체할 수 있나요?

function classifySource(url: string): "official" | "source" | "community" | "other" {
  const host = new URL(url).hostname;
  if (host === "pi.dev") return "official";
  if (host === "github.com") return "source";
  if (host.includes("reddit.com")) return "community";
  return "other";
}

fetch_source(url)