에이전트 개요

에이전트 개요 (Agents & ToolLoopAgent)

에이전트는 도구(tools)를 루프(loop)로 사용하는 LLM으로, 단순 텍스트 생성 너머의 작업을 수행합니다. LLM이 입력을 처리하고 다음 행동을 결정하고, 도구가 파일 읽기·API 호출·DB 쓰기 같은 능력을 확장하고, 루프가 문맥 관리와 종료 조건으로 실행을 조율합니다.

출처: 공식문서

본문

에이전트 상태와 문맥 (Agent State and Context)

에이전트는 종종 프롬프트에 직접 넣으면 안 되는 서버 측 상태(테넌트 설정, 요청 ID, 기능 플래그, 자격증명, 진행 상황)가 필요합니다. **runtimeContext**는 에이전트의 공유 런타임 상태로, 에이전트 루프를 통과하고 prepareStep·라이프사이클 콜백에서 접근하며 스텝 간에 갱신할 수 있습니다. **toolsContext**는 API 키나 범위 제한 권한 같은 도구별 값을 담으며, 각 도구는 contextSchema에 따라 자신만의 타입 있는 context만 받습니다.

ToolLoopAgent 클래스

ToolLoopAgent는 LLM·도구·루프 세 구성 요소를 한 데 묶는 클래스입니다. 아래는 여러 도구를 루프로 호출해 작업을 완수하는 예시입니다.

import { ToolLoopAgent, tool } from 'ai';
import { z } from 'zod';
const weatherAgent = new ToolLoopAgent({
  model: "xai/grok-4.6",
  tools: {
    weather: tool({
      description: 'Get the weather in a location (in Fahrenheit)',
      inputSchema: z.object({ location: z.string() }),
      execute: async ({ location }) => ({ location,
        temperature: 72 + Math.floor(Math.random() * 21) - 10 }),
    }),
    convertFahrenheitToCelsius: tool({
      description: 'Convert temperature from Fahrenheit to Celsius',
      inputSchema: z.object({ temperature: z.number() }),
      execute: async ({ temperature }) =>
        ({ celsius: Math.round((temperature - 32) * (5 / 9)) }),
    }),
  },
});

에이전트는 자동으로 ① weather 도구로 화씨 온도를 얻고 ② convertFahrenheitToCelsius로 변환한 뒤 ③ 결과가 담긴 최종 텍스트 응답을 생성합니다. ToolLoopAgent가 루프·문맥 관리·종료 조건을 모두 처리합니다.

왜 ToolLoopAgent를 쓰는가

ToolLoopAgent는 가장 보편적인 에이전트 구축의 권장 방식입니다. 루프와 메시지 배열 관리를 줄여 보일러플레이트를 낮추고, 한 번 정의하면 앱 전반에서 재사용되며, 에이전트 설정 변경을 한 곳에서 처리해 유지보수를 단순화합니다. 대부분의 사용 사례는 ToolLoopAgent로 시작하고, 복잡한 구조적 워크플로우에서 각 스텝을 명시적으로 제어해야 할 때만 핵심 함수(generateText/streamText)를 씁니다.

HarnessAgent와 Terminal UI

HarnessAgent는 Claude Code, Codex, Pi 같은 사전 구축된 harness를 직접 루프를 짜지 않고 실행하고 싶을 때 씁니다. @ai-sdk/tui의 runAgentTUI는 ToolLoopAgent를 인터랙티브 터미널 UI(프롬프트·스트리밍 응답·도구 카드·추론 섹션·도구 승인)로 돌려줘 로컬 에이전트 개발·데모·내부 도구에 유용합니다.

구조적 워크플로우

에이전트는 유연하지만 비결정적입니다. 신뢰할 수 있고 반복 가능한 결과가 필요할 때는 핵심 함수로 구조적 워크플로우 패턴(명시적 분기용 조건문, 재사용 로직용 표준 함수, 견고성을 위한 오류 처리, 예측 가능한 명시적 제어 흐름)을 결합해 사용합니다.

더 알아보기