---
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]]
