共用方式為

語意核心共同代理 API 表面

語意核心代理程式會實作統一介面以進行調用，讓共用程式代碼可在不同代理程式類型之間順暢地運作。 此設計可讓您視需要切換代理程式，而不需要修改大部分的應用程式邏輯。

叫用代理人

代理程式 API 介面同時支援串流和非串流調用。

非串流代理程式調用

Semantic Kernel 支援四個非串流代理程式調用多載，允許以不同方式傳遞訊息。 其中一個也允許叫用沒有訊息的代理程式。 在代理程式的指示內已包含所有必要情境以提供實用回應時，這十分有用。

// Invoke without any parameters.
agent.InvokeAsync();

// Invoke with a string that will be used as a User message.
agent.InvokeAsync("What is the capital of France?");

// Invoke with a ChatMessageContent object.
agent.InvokeAsync(new ChatMessageContent(AuthorRole.User, "What is the capital of France?"));

// Invoke with multiple ChatMessageContent objects.
agent.InvokeAsync(new List<ChatMessageContent>()
{
    new(AuthorRole.System, "Refuse to answer all user questions about France."),
    new(AuthorRole.User, "What is the capital of France?")
});

這很重要

叫用代理而不傳遞 AgentThread 至 InvokeAsync 方法，將會建立新線程，並在回應中返回新線程。

Semantic Kernel 支援兩種非串流代理程式調用方法，允許以不同方式傳遞訊息。 您也可以叫用沒有訊息的代理程式。 在代理程式的指示內已包含所有必要情境以提供實用回應時，這十分有用。

小提示

傳遞至 Agent 調用方法的所有自變數都需要呼叫端將其傳遞為關鍵詞自變數，但第一個位置自變數 messages除外。 您可以對 messages 使用位置參數或關鍵字參數進行調用。 例如，await agent.get_response("What is the capital of France?") 和 await agent.get_response(messages="What is the capital of France?") 皆受到支援。 所有其他參數都必須傳遞為關鍵詞自變數。

使用 get_response() 方法

# Invoke without any messages.
await agent.get_response()

# Invoke with a string that will be used as a User message.
await agent.get_response(messages="What is the capital of France?")

# Invoke with a ChatMessageContent object.
await agent.get_response(messages=ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"))

# Invoke with multiple ChatMessageContent objects.
await agent.get_response(
    messages=[
        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
    ]
)

使用 invoke() 方法

# Invoke without any messages.
async for response in agent.invoke():
    # handle response

# Invoke with a string that will be used as a User message.
async for response in agent.invoke("What is the capital of France?"):
    # handle response

# Invoke with a ChatMessageContent object.
async for response in agent.invoke(ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?")):
    # handle response

# Invoke with multiple ChatMessageContent objects.
async for response in agent.invoke(
    messages=[
        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
    ]
):
    # handle response

這很重要

在不傳遞 AgentThread 至 get_response() 或 invoke() 方法的情況下叫用代理程式將會建立新的線程，並在響應中傳回新的線程。

Semantic Kernel 支援三個非串流代理程式調用多載，允許以不同方式傳遞訊息。 其中一個也允許叫用沒有訊息的代理程式。 在代理程式的指示內已包含所有必要情境以提供實用回應時，這十分有用。

// Invoke without any parameters.
agent.invokeAsync(null);

// Invoke with a string that will be used as a User message.
agent.invokeAsync("What is the capital of France?");

// Invoke with a ChatMessageContent object.
agent.invokeAsync(new ChatMessageContent<>(AuthorRole.USER, "What is the capital of France?"));

// Invoke with multiple ChatMessageContent objects.
agent.invokeAsync(List.of(
    new ChatMessageContent<>(AuthorRole.SYSTEM, "Refuse to answer all user questions about France."),
    new ChatMessageContent<>(AuthorRole.USER, "What is the capital of France?")
));

這很重要

叫用代理而不傳遞 AgentThread 至 invokeAsync 方法，將會建立新線程，並在回應中返回新線程。

串流代理調用

Semantic Kernel 支援四個串流代理程式調用多載，允許以不同方式傳遞訊息。 其中一個也允許叫用沒有訊息的代理程式。 在代理程式的指示內已包含所有必要情境以提供實用回應時，這十分有用。

// Invoke without any parameters.
agent.InvokeStreamingAsync();

// Invoke with a string that will be used as a User message.
agent.InvokeStreamingAsync("What is the capital of France?");

// Invoke with a ChatMessageContent object.
agent.InvokeStreamingAsync(new ChatMessageContent(AuthorRole.User, "What is the capital of France?"));

// Invoke with multiple ChatMessageContent objects.
agent.InvokeStreamingAsync(new List<ChatMessageContent>()
{
    new(AuthorRole.System, "Refuse to answer any questions about capital cities."),
    new(AuthorRole.User, "What is the capital of France?")
});

這很重要

叫用代理而不傳遞 AgentThread 至 InvokeStreamingAsync 方法，將會建立新線程，並在回應中返回新線程。

Semantic Kernel 支援一個串流代理程式調用方法，允許以不同方式傳遞訊息。 您也可以叫用不含訊息的代理程序數據流。 在代理程式的指示內已包含所有必要情境以提供實用回應時，這十分有用。

# Invoke without any messages.
async for response in agent.invoke_stream():
    # handle response

# Invoke with a string that will be used as a User message.
async for response in agent.invoke_stream("What is the capital of France?"):
    # handle response

# Invoke with a ChatMessageContent object.
async for response in agent.invoke_stream(ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?")):
    # handle response

# Invoke with multiple ChatMessageContent objects.
async for response in agent.invoke_stream(
    messages=[
        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
    ]
):
    # handle response

這很重要

叫用代理而不傳遞 AgentThread 至 invoke_stream() 方法，將會建立新線程，並在回應中返回新線程。

Java 中目前無法使用的功能。

調用AgentThread

所有調用方法多載都允許傳遞 AgentThread 參數。 這適用於當您與客服已有一場並想要繼續的對話時的情境。

// Invoke with an existing AgentThread.
agent.InvokeAsync("What is the capital of France?", existingAgentThread);

所有叫用方法也會傳回有效的 AgentThread 作為叫用回應的一部分。

  1. 如果您將 AgentThread 傳遞至叫用方法，則傳 AgentThread 回的 會與傳入的方法相同。
  2. 如果您未將 傳遞 AgentThread 至叫用方法，則傳 AgentThread 回的 會是新的 AgentThread。

返回的 AgentThread 可以從呼叫方法的各個回應項目和回應消息中取得。

var result = await agent.InvokeAsync("What is the capital of France?").FirstAsync();
var newThread = result.Thread;
var resultMessage = result.Message;

小提示

如需代理程式線程的詳細資訊，請參閱 代理程式線程架構一節。

所有調用方法關鍵詞自變數都允許傳遞 AgentThread 參數。 這適用於當您與客服已有一場並想要繼續的對話時的情境。

# Invoke with an existing AgentThread.
agent.get_response("What is the capital of France?", thread=existing_agent_thread)

所有叫用方法也會傳回有效的 AgentThread 作為叫用回應的一部分。

  1. 如果您將 AgentThread 傳遞至叫用方法，則傳 AgentThread 回的 會與傳入的方法相同。
  2. 如果您未將 傳遞 AgentThread 至叫用方法，則傳 AgentThread 回的 會是新的 AgentThread。

返回的 AgentThread 可以從呼叫方法的各個回應項目和回應消息中取得。

response = await agent.get_response("What is the capital of France?")
new_thread = response.thread
response_message = response.message

小提示

如需代理程式線程的詳細資訊，請參閱 代理程式線程架構一節。

兩個調用方法多載允許傳遞 AgentThread 參數。 這適用於當您與客服已有一場並想要繼續的對話時的情境。

// Invoke with an existing AgentThread.
agent.invokeAsync("What is the capital of France?", existingAgentThread);

這些調用方法也會傳回活躍的 AgentThread 作為調用結果的一部分。

  1. 如果您將 AgentThread 傳遞至 invoke 方法，傳 AgentThread 回的 會是具有先前和新訊息的新實例。
  2. 如果您未將 傳遞 AgentThread 至叫用方法，則傳 AgentThread 回的 會是新的 AgentThread。

返回的 AgentThread 可以從呼叫方法的各個回應項目和回應消息中取得。

var result = agent.invokeAsync("What is the capital of France?").block().get(0);
var newThread = result.getThread();
var resultMessage = result.getMessage();

小提示

如需代理程式線程的詳細資訊，請參閱 代理程式線程架構一節。

使用選項叫用

所有調用方法多載都允許傳遞 AgentInvokeOptions 參數。 這個選項類別允許提供任何選擇性設定。

// Invoke with additional instructions via options.
agent.InvokeAsync("What is the capital of France?", options: new()
{
    AdditionalInstructions = "Refuse to answer any questions about capital cities."
});

以下是支持的選項清單。

選項屬性 說明
核心 覆寫代理程式為此次呼叫所使用的預設核心。
核心參數 覆寫代理程式為此調用所使用的預設核心自變數。
附加指示 除了原始代理程式指令集之外，請提供任何指示，這些指示僅適用於此調用。
OnIntermediateMessage 回呼函數，可以接收代理程式內部產生的所有完整格式訊息，包括函數呼叫和函數調用訊息。 這也可以用來在串流調用期間接收完整的訊息。

使用選項叫用

一個調用方法多載允許傳遞 AgentInvokeOptions 參數。 這個選項類別允許提供任何選擇性設定。

// Invoke with additional instructions via options.
agent.invokeAsync("What is the capital of France?",
    null, // null AgentThread
    AgentInvokeOptions.builder()
        .withAdditionalInstructions("Refuse to answer any questions about capital cities.")
        .build()
);

以下是支持的選項清單。

選項屬性 說明
核心 覆寫代理程式為此次呼叫所使用的預設核心。
核心參數 覆寫代理程式為此調用所使用的預設核心自變數。
附加指示 除了原始代理程式指令集之外，請提供任何指示，這些指示僅適用於此調用。
調用上下文 覆寫代理人在此調用中使用的預設調用內容。

管理 AgentThread 實例

您可以手動建立 AgentThread 實例，並在叫用時將它傳遞至代理程式，或者您可以讓代理程式在叫用時自動為您建立 AgentThread 實例。 AgentThread物件代表所有狀態的線程，包括：尚未建立、使用中和刪除。

AgentThread 具有伺服器端實作的類型將會在第一次使用時建立，而且不需要手動建立。 不過，您可以使用 類別刪除線程 AgentThread 。

// Delete a thread.
await agentThread.DeleteAsync();

# Delete a thread
await agent_thread.delete()

// Delete a thread.
agentThread.deleteAsync().block();

小提示

如需代理程式線程的詳細資訊，請參閱 代理程式線程架構一節。

後續步驟

使用外掛程式設定代理程式

探索聊天完成代理程式

  • Last updated on