에이전트

에이전트란?

에이전트는 질문을 받아 어떤 도구를 사용할지 결정하고 답변을 생성하는 프로그램입니다. ReAct 루프 (Reason + Act)를 실행합니다:

사용자 질문
  -> LLM이 생각 + 도구 선택
    -> 도구 실행, 결과 반환
      -> LLM이 다시 생각 (도구 결과 포함)
        -> 최종 답변 (또는 다른 도구 선택)

루프는 LLM이 최종 답변을 생성하거나 maxSteps (기본값: 10)에 도달할 때까지 계속됩니다.

에이전트 생성

import { Schift, Agent, RAG } from "@schift-io/sdk";

const schift = new Schift({ apiKey: "sch_..." });
const rag = new RAG({ bucket: "my-docs" }, schift.transport);

const agent = new Agent({
  name: "My Agent",
  instructions: "You are a helpful assistant. Use the knowledge base.",
  rag,
  tools: [myCustomTool],
  model: "gpt-4o-mini",
  transport: schift.transport,
  maxSteps: 15,
});

const result = await agent.run("What is Schift?");
console.log(result.output);

LLM 연결 모드

에이전트는 세 가지 방식으로 LLM에 연결할 수 있습니다:

1. Schift Cloud (기본)

Schift의 /v1/chat/completions 엔드포인트를 통해 라우팅합니다. OpenAI, Google, Anthropic 모델 라우팅을 지원합니다.

const agent = new Agent({
  name: "Cloud Agent",
  instructions: "...",
  model: "gpt-4o-mini", // 또는 "claude-sonnet-4-6", "gemini-2.5-flash"
  transport: schift.transport,
});

2. Direct Provider

OpenAI, Google, Anthropic 엔드포인트에 직접 연결합니다. LLM 호출은 Schift Cloud를 거치지 않습니다 (RAG는 여전히 Schift Cloud 사용).

const agent = new Agent({
  name: "Direct Agent",
  instructions: "...",
  model: "gpt-4o-mini",
  baseUrl: "https://api.openai.com/v1",
  apiKey: process.env.OPENAI_API_KEY,
});

3. Self-hosted

Ollama, vLLM, LiteLLM 또는 OpenAI 호환 엔드포인트에 연결합니다.

const agent = new Agent({
  name: "Local Agent",
  instructions: "...",
  model: "llama3",
  baseUrl: "http://localhost:11434/v1",
});

자세한 내용은 Self-hosting 가이드를 참조하세요.

Agent vs Workflow vs Client

	Agent	Workflow	Client
사용 시점	대화형 Q&A, 도구 호출	고정 데이터 파이프라인 (ETL, 배치)	단순 embed/search 호출
루프	ReAct (동적, LLM이 결정)	DAG (고정 단계, 결정적)	없음
도구	지원	블록 타입	해당 없음
메모리	대화 이력	해당 없음	해당 없음

설정 레퍼런스

옵션	타입	기본값	설명
name	string	필수	표시 이름
instructions	string	필수	LLM의 시스템 프롬프트
model	ModelId | string	"gpt-4o-mini"	LLM 모델 식별자
transport	Transport	—	Schift Cloud 트랜스포트 (schift.transport에서 가져옴)
baseUrl	string	—	커스텀 OpenAI 호환 엔드포인트
apiKey	string	—	Direct/Self-hosted 모드 API 키
tools	AgentTool[]	[]	에이전트가 사용할 수 있는 도구
rag	RAG	—	RAG 인스턴스 (자동으로 도구 등록)
memory	MemoryConfig	—	대화 메모리 설정. 생략 시 stateless
maxSteps	number	10	최대 ReAct 루프 반복 횟수
toolTimeoutMs	number	30000	각 도구 실행 타임아웃 (ms)
maxToolCalls	number	maxSteps * 5	실행당 최대 도구 호출 횟수
parallelToolExecution	boolean	false	턴당 여러 도구를 병렬 실행
skills	SkillsConfig	—	동적 스킬 로딩. Skills 참조
extensions	Array	—	Extension 초기화 함수 또는 모듈 경로
mcp	MCPServerConfig[]	—	MCP 서버 설정 (포워드 호환)

실행 옵션

agent.run()에 실행별 옵션을 전달합니다:

const result = await agent.run("question", {
  requestId: "req_abc123",    // 로그/트레이싱에서 추적
  signal: AbortSignal.timeout(30000), // 30초 후 취소
});

옵션	타입	설명
requestId	string	로깅/트레이싱 상관 ID
signal	AbortSignal	중단 시 실행 취소

이벤트

에이전트는 실행 중 이벤트를 발행합니다. agent.on()으로 구독:

agent.on("tool_call", (event) => {
  console.log(`${event.toolName} 호출 중...`);
});

agent.on("agent_end", (event) => {
  console.log(`${event.totalDurationMs}ms에 완료`);
});

// 와일드카드: 모든 이벤트 수신
agent.on("*", (event) => {
  console.log(event.type, event);
});

이벤트	발행 시점
agent_start	실행 시작
turn_start	각 ReAct 반복 시작
tool_call	LLM이 도구 호출을 결정
tool_result	도구 실행 완료
message_delta	LLM이 최종 답변 텍스트 생성
agent_end	실행 성공 완료
error	에러 발생
policy_violation	스킬 정책이 도구 호출 차단

반환된 정리 함수로 구독 해제:

const unsub = agent.on("tool_call", handler);
unsub(); // 수신 중지

실행 결과

agent.run()은 AgentRunResult를 반환합니다:

interface AgentRunResult {
  steps: AgentStep[];       // ReAct 루프의 각 단계
  output: string;           // 최종 답변 텍스트
  totalDurationMs: number;  // 총 실행 시간
}

각 단계의 타입: think, tool_call, tool_result, final_answer, error.