[G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00
parent f0befc887a
commit 93ec7e9056
363 changed files with 68333 additions and 64 deletions
@@ -0,0 +1,205 @@
+---
+id: ai-function-calling-deep
+title: Function Calling 심화 — Tool Use / 멀티 step
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [ai, llm, function-calling, tool-use, vibe-coding]
+tech_stack: { language: "TS / OpenAI / Anthropic", applicable_to: ["Backend"] }
+applied_in: []
+aliases: [function calling, tool use, parallel tool calls, tool result, ReAct]
+---
+
+# Function Calling Deep
+
+> LLM 이 함수 호출 결정 → 너가 실행 → 결과 다시 LLM. **반복 루프가 agent 의 핵심**. Parallel tool calls / streaming + tools / 재귀 호출 제한.
+
+## 📖 핵심 개념
+- Tool: name + description + JSON Schema input.
+- LLM 이 "이 tool 호출해" 응답 → 너가 실행 → 결과를 message 로 다시.
+- 종료 조건: stop_reason = end_turn / max_iterations.
+
+## 💻 코드 패턴
+
+### Anthropic tool use loop
+```ts
+import Anthropic from '@anthropic-ai/sdk';
+const client = new Anthropic();
+
+const tools = [
+  {
+    name: 'search',
+    description: 'Search the web',
+    input_schema: {
+      type: 'object',
+      properties: { query: { type: 'string' } },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'fetch_page',
+    description: 'Fetch contents of a URL',
+    input_schema: {
+      type: 'object', properties: { url: { type: 'string' } }, required: ['url'],
+    },
+  },
+] as const;
+
+async function executeTool(name: string, input: any): Promise<string> {
+  if (name === 'search') return JSON.stringify(await google.search(input.query));
+  if (name === 'fetch_page') return await fetch(input.url).then(r => r.text());
+  throw new Error(`unknown tool: ${name}`);
+}
+
+async function agentLoop(userMsg: string, maxIters = 10) {
+  const messages: Anthropic.Messages.MessageParam[] = [{ role: 'user', content: userMsg }];
+
+  for (let i = 0; i < maxIters; i++) {
+    const r = await client.messages.create({
+      model: 'claude-opus-4-7',
+      max_tokens: 4096,
+      tools, messages,
+    });
+
+    messages.push({ role: 'assistant', content: r.content });
+
+    if (r.stop_reason === 'end_turn') {
+      // 최종 답
+      const text = r.content.find(b => b.type === 'text')?.text;
+      return text;
+    }
+
+    if (r.stop_reason === 'tool_use') {
+      // Parallel tool calls 가능 — 모든 tool_use 처리
+      const toolUses = r.content.filter(b => b.type === 'tool_use');
+      const toolResults = await Promise.all(toolUses.map(async (t) => ({
+        type: 'tool_result' as const,
+        tool_use_id: t.id,
+        content: await executeTool(t.name, t.input),
+      })));
+      messages.push({ role: 'user', content: toolResults });
+      continue;
+    }
+
+    break;
+  }
+  throw new Error('max iterations');
+}
+```
+
+### Parallel tool calls (한 turn 안 여러 tool)
+LLM 이 한 번에 여러 tool 호출 → 병렬 실행 → 결과 한꺼번에 보냄.
+
+### OpenAI 스타일
+```ts
+const r = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages,
+  tools: [
+    { type: 'function', function: { name: 'search', parameters: {...} } },
+    { type: 'function', function: { name: 'fetch_page', parameters: {...} } },
+  ],
+  tool_choice: 'auto', // 또는 'required' / specific
+  parallel_tool_calls: true,
+});
+
+if (r.choices[0].finish_reason === 'tool_calls') {
+  for (const call of r.choices[0].message.tool_calls!) {
+    const result = await executeTool(call.function.name, JSON.parse(call.function.arguments));
+    messages.push({
+      role: 'tool', tool_call_id: call.id, content: result,
+    });
+  }
+  // 다시 모델 호출
+}
+```
+
+### Streaming + tools (delta accumulation)
+```ts
+const stream = await client.messages.stream({ ..., tools });
+
+let toolUses: Map<number, { id: string; name: string; input: string }> = new Map();
+for await (const ev of stream) {
+  if (ev.type === 'content_block_start' && ev.content_block.type === 'tool_use') {
+    toolUses.set(ev.index, { id: ev.content_block.id, name: ev.content_block.name, input: '' });
+  }
+  if (ev.type === 'content_block_delta' && ev.delta.type === 'input_json_delta') {
+    const tu = toolUses.get(ev.index)!;
+    tu.input += ev.delta.partial_json;
+  }
+}
+// stream 끝 후 toolUses 의 input string → JSON.parse → 실행
+```
+
+### Tool 에러 처리
+```ts
+async function safeExecute(name: string, input: any) {
+  try {
+    return { content: await executeTool(name, input), is_error: false };
+  } catch (e) {
+    return { content: `Error: ${(e as Error).message}`, is_error: true };
+  }
+}
+
+// LLM 에 에러도 내용으로 — 자체 복구 시도
+toolResults.push({ type: 'tool_result', tool_use_id: t.id, content: result.content, is_error: result.is_error });
+```
+
+### Tool 강제 (force tool_choice)
+```ts
+{ tool_choice: { type: 'tool', name: 'extract_recipe' } }
+```
+
+특정 tool 만 호출 → structured output 비슷.
+
+### Tool 입력 검증
+```ts
+import { z } from 'zod';
+
+const SearchInput = z.object({ query: z.string().min(1).max(200) });
+
+async function executeTool(name: string, raw: unknown) {
+  if (name === 'search') {
+    const input = SearchInput.parse(raw); // 잘못된 input 차단
+    return search(input.query);
+  }
+}
+```
+
+### Cost 제어
+- maxIters 5-10.
+- Tool result 크기 제한 (truncate to 4kb).
+- 동시 tool 수 제한.
+- 비싼 tool (GPU inference) 은 cache.
+
+## 🤔 의사결정 기준
+| 작업 | 추천 |
+|---|---|
+| 1 step + JSON 결과 | Structured output (force tool) |
+| 멀티 step 추론 | Tool loop |
+| 검색 + 답변 | Web search tool + RAG 결합 |
+| Code execution | Sandbox (E2B / Daytona) |
+| File 작업 | Filesystem tool + 권한 제한 |
+| 여러 LLM 통합 | Vercel AI SDK / LangChain |
+
+## ❌ 안티패턴
+- **maxIters 무한**: LLM 이 무한 loop — 재귀 token 폭발.
+- **Tool 없는 description**: LLM 이 못 고름.
+- **Input schema 너무 복잡**: 잘못 호출.
+- **Side-effect tool 멱등 X**: 재시도 시 중복.
+- **Tool result 크기 무제한**: 다음 turn 비싸짐.
+- **Error 숨김**: LLM 못 복구.
+- **Auth 없는 tool**: 사용자 권한으로 임의 호출.
+
+## 🤖 LLM 활용 힌트
+- Tool description 풍부, input schema 작게.
+- Parallel tool calls 활용.
+- maxIters + cost cap + tool error 다시 LLM 으로.
+
+## 🔗 관련 문서
+- [[AI_Structured_Output_Zod]]
+- [[AI_Agentic_Patterns]]
+- [[AI_Streaming_LLM_Response]]