오케스트레이션과 핸드오프

여러 전문 에이전트가 작업을 나누어 맡아야 할 때는 멀티 에이전트 워크플로우가 유용합니다. 설계할 때는 먼저 워크플로우의 각 분기에서 어떤 에이전트가 사용자에게 보낼 최종 답변을 책임질지 정하세요.

오케스트레이션 패턴 선택하기

핸드오프로 응답 책임 위임하기

전문 에이전트의 역할이 다른 에이전트를 돕는 데 그치지 않고 다음 응답을 직접 맡는 것이라면 핸드오프가 가장 적합합니다.

1
2
3
4
5
6
7
8
9import { Agent, handoff } from "@openai/agents";

const billingAgent = new Agent({ name: "Billing agent" });
const refundAgent = new Agent({ name: "Refund agent" });

const triageAgent = Agent.create({
  name: "Triage agent",
  handoffs: [billingAgent, handoff(refundAgent)],
});

1
2
3
4
5
6
7
8
9from agents import Agent, handoff

billing_agent = Agent(name="Billing agent")
refund_agent = Agent(name="Refund agent")

triage_agent = Agent(
    name="Triage agent",
    handoffs=[billing_agent, handoff(refund_agent)],
)

어떤 에이전트에 작업을 넘겨야 하는지 쉽게 파악할 수 있도록 설계하세요.

• 각 전문 에이전트가 맡는 작업의 범위를 좁게 정하세요.
• handoffDescription은 짧고 구체적으로 작성하세요.
• 다음 단계에서 다른 지침, 도구 또는 정책이 꼭 필요할 때만 분기를 나누세요.

고급 사용 사례에서는 핸드오프를 통해 구조화된 메타데이터나 필터링한 대화 기록도 전달할 수 있습니다. 구현 방식은 언어마다 다르므로 구체적인 API는 SDK 문서에서 확인하세요.

매니저가 워크플로우를 제어할 때 에이전트를 도구로 사용하기

주 에이전트가 최종 답변을 책임지면서 전문 에이전트를 호출해 도움을 받아야 한다면 agent.asTool()을 사용하세요.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import { Agent } from "@openai/agents";

const summarizer = new Agent({
  name: "Summarizer",
  instructions: "Generate a concise summary of the supplied text.",
});

const mainAgent = new Agent({
  name: "Research assistant",
  tools: [
    summarizer.asTool({
      toolName: "summarize_text",
      toolDescription: "Generate a concise summary of the supplied text.",
    }),
  ],
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16from agents import Agent

summarizer = Agent(
    name="Summarizer",
    instructions="Generate a concise summary of the supplied text.",
)

main_agent = Agent(
    name="Research assistant",
    tools=[
        summarizer.as_tool(
            tool_name="summarize_text",
            tool_description="Generate a concise summary of the supplied text.",
        )
    ],
)

다음과 같은 상황에서는 대체로 이 방식이 더 적합합니다.

• 매니저 에이전트가 결과를 종합해 최종 답변을 작성해야 할 때
• 전문 에이전트가 요약이나 분류처럼 범위가 명확한 작업을 수행할 때
• 응답 책임을 넘기지 않고 하나의 안정적인 상위 워크플로우 안에서 전문 에이전트를 호출하고 싶을 때

역할 요건이 달라질 때만 전문 에이전트 추가하기

가능하면 에이전트 하나로 시작하세요. 전문 에이전트를 추가했을 때 기능이나 정책을 더 확실히 분리할 수 있거나, 프롬프트가 한층 명확해지거나, 트레이스를 훨씬 쉽게 읽을 수 있을 때만 추가하세요.

작업을 너무 일찍 나누면 프롬프트와 트레이스가 늘고 승인이 필요한 지점도 많아지지만 워크플로우가 반드시 개선되지는 않습니다.

다음 단계

어떤 에이전트가 응답을 책임질지 정했다면, 실행 방식이나 상태 관리에 관해 더 알고 싶은 내용을 다루는 가이드로 이동하세요.