플러그인으로 에이전트 구성 (함수 호출·도구)

Semantic Kernel 플러그인으로 에이전트 구성하기

[!IMPORTANT] 이 기능은 릴리스 후보(release candidate) 단계예요. 거의 완성되어 일반적으로 안정적이지만, GA(general availability) 전에 사소한 다듬기나 최적화가 있을 수 있어요.

Semantic Kernel의 함수와 플러그인

함수 호출(function calling) 은 개발자가 커스텀 기능을 추가해 AI 애플리케이션의 능력을 확장하게 해주는 강력한 도구예요. Semantic Kernel의 플러그인(Plugin) 아키텍처는 함수 호출을 지원하는 유연한 프레임워크예요. 에이전트에 플러그인과 함수 호출을 통합하는 것도 바로 이 파운데이션 기능 위에 쌓여 있어요.

한번 구성하면, 에이전트는 Agent Framework 바깥에서 쓸 때와 똑같이 언제, 어떻게 사용 가능한 함수를 호출할지를 스스로 선택해요.

에이전트에 플러그인 추가하기

에이전트가 쓸 수 있는 모든 플러그인은 각자의 Kernel 인스턴스 안에서 관리돼요. 이 구조 덕분에 각 에이전트가 자기 역할에 맞는 서로 다른 기능에 접근할 수 있죠. 플러그인은 에이전트를 만들기 전이나 후에 Kernel 에 추가할 수 있고, 초기화 과정은 일반적인 Semantic Kernel 구현과 같은 패턴을 따릅니다.

Python — 방법 1: 생성자에서 플러그인 지정

from semantic_kernel.agents import ChatCompletionAgent

# Create the Chat Completion Agent instance by specifying a list of plugins
agent = ChatCompletionAgent(
    service=AzureChatCompletion(),
    instructions="<instructions>",
    plugins=[SamplePlugin()]
)

[!TIP] 기본적으로 auto-function calling이 켜져 있어요. 끄려면 생성자에서 function_choice_behavior=FunctionChoiceBehavior.Auto(auto_invoke=False) 로 설정하면 돼요. 이렇게 하면 플러그인이 모델에 브로드캐스트되지만 자동으로 호출되진 않아요. 실행 설정(execution settings)이 AI 서비스 구성과 같은 service_id 나 ai_model_id 를 지정하면, KernelArguments 로 정의된 함수 호출 동작이 생성자의 function choice behavior보다 우선해요.

Python — 방법 2: Kernel을 직접 구성

from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion, AzureChatPromptExecutionSettings
from semantic_kernel.functions import KernelFunctionFromPrompt
from semantic_kernel.kernel import Kernel

# Create the instance of the Kernel
kernel = Kernel()
kernel.add_service(AzureChatCompletion())

# Get the AI service settings
settings = kernel.get_prompt_execution_settings_from_service_id()

# Configure the function choice behavior to auto invoke kernel functions
settings.function_choice_behavior = FunctionChoiceBehavior.Auto()

# Add the Plugin to the Kernel
kernel.add_plugin(SamplePlugin(), plugin_name="<plugin name>")

# Create the agent
agent = ChatCompletionAgent(
    kernel=kernel,
    name=<agent name>,
    instructions=<agent instructions>,
    arguments=KernelArguments(settings=settings),
)

생성자로 kernel을 주지 않으면 모델 검증 시 하나가 자동 생성되고, 전달된 플러그인이 우선해 그 kernel에 추가돼요. kernel 상태를 세밀하게 제어하고 싶다면 위처럼 직접 구성하면 됩니다.

[!TIP] kernel에 서비스를 추가할 때 service_id 를 지정하지 않으면 기본값 default 를 사용해요. kernel에 여러 AI 서비스를 구성할 때는 service_id 인자로 구분하는 걸 권장해요. 그래야 특정 service_id 의 실행 설정을 가져와 원하는 서비스에 연결할 수 있거든요.

C# — FunctionChoiceBehavior.Auto() 로 자동 함수 호출 켜기

// Factory method to produce an agent with a specific role.
ChatCompletionAgent CreateSpecificAgent(Kernel kernel, string credentials)
{
    // Clone kernel instance to allow for agent specific plug-in definition
    Kernel agentKernel = kernel.Clone();

    // Import plug-in from type
    agentKernel.ImportPluginFromType<StatelessPlugin>();

    // Import plug-in from object
    agentKernel.ImportPluginFromObject(new StatefulPlugin(credentials));

    return
        new ChatCompletionAgent()
        {
            Name = "<agent name>",
            Instructions = "<agent instructions>",
            Kernel = agentKernel,
            Arguments = new KernelArguments(
                new OpenAIPromptExecutionSettings()
                {
                    FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
                })
        };
}

[!NOTE] ChatCompletionAgent 의 경우 함수 호출 모드를 명시적으로 켜야 해요. 반면 OpenAIAssistant 에이전트는 항상 자동 함수 호출을 기반으로 동작해요.

에이전트에 함수 추가하기

플러그인이 함수 호출을 구성하는 가장 흔한 방법이지만, 프롬프트 함수를 포함해 개별 함수 하나씩도 독립적으로 제공할 수 있어요.

from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion, AzureChatPromptExecutionSettings
from semantic_kernel.functions import KernelFunctionFromPrompt
from semantic_kernel.kernel import Kernel

kernel = Kernel()
kernel.add_service(AzureChatCompletion())

settings = AzureChatPromptExecutionSettings()
settings.function_choice_behavior = FunctionChoiceBehavior.Auto()

kernel.add_function(
    plugin_name="<plugin_name>",
    function=KernelFunctionFromPrompt(
        function_name="<function_name>",
        prompt="<your prompt instructions>",
    )
)

agent = ChatCompletionAgent(
    kernel=kernel,
    name=<agent name>,
    instructions=<agent instructions>,
    arguments=KernelArguments(settings=settings),
)

C#에서는 agentKernel.CreateFunctionFromMethod(StatelessPlugin.AStaticMethod) 로 메서드에서 함수를, agentKernel.CreateFunctionFromPrompt("<...>") 로 프롬프트에서 함수를 만들고 agentKernel.ImportPluginFromFunctions("my_plugin", [...]) 로 kernel에 추가해요.

에이전트 함수 호출의 제약

ChatCompletionAgent 를 직접 호출할 때는 모든 Function Choice Behavior가 지원돼요. 하지만 OpenAIAssistant 를 쓸 때는 현재 자동(Automatic) 함수 호출만 사용할 수 있어요.

다음 단계

함수 호출을 end-to-end로 쓰는 예제는 How-To: ChatCompletionAgent 를, 그다음은 에이전트 응답 스트리밍 을 확인해 보세요.