A Szemantikai Kernel Közös Ügynök API Felület

A Szemantikus Kernel-ügynökök egységes felületet implementálnak a híváshoz, amely lehetővé teszi a különböző ügynöktípusok között zökkenőmentesen működő megosztott kód használatát. Ez a kialakítás lehetővé teszi, hogy szükség szerint váltson ügynökökre az alkalmazáslogika többségének módosítása nélkül.

Ügynök meghívása

Az Agent API felülete támogatja a streamelést és a nem streamelt hívásokat is.

Nem streamelő ügynök meghívása

A Semantic Kernel négy nem streamelt ügynök hívási túlterhelését támogatja, amely lehetővé teszi az üzenetek különböző módokon való továbbítását. Ezek egyike lehetővé teszi az ügynök üzenet nélküli meghívását is. Ez hasznos olyan helyzetekben, amikor az ügynök utasításai már rendelkeznek az összes szükséges háttérrel, hogy hasznos választ adjanak.

// 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?")
});

Fontos

Az ügynök meghívása anélkül, hogy egy AgentThread-t átadnánk a InvokeAsync metódusnak, új szálat hoz létre, és a válaszban visszaadja azt.

A Szemantic Kernel két nem streamelt ügynökhívási módszert támogat, amelyek lehetővé teszik az üzenetek különböző módon történő továbbítását. Az ügynök meghívása üzenet nélkül is lehetséges. Ez hasznos olyan helyzetekben, amikor az ügynök utasításai már rendelkeznek az összes szükséges háttérrel, hogy hasznos választ adjanak.

Jótanács

Az ügynökhívási metódusoknak átadott összes argumentumhoz a hívónak kulcsszóargumentumként kell átadnia őket, kivéve az első pozícióargumentumot. messages A messages meghívása történhet pozíció- vagy kulcsszóargumentummal. Például mindkettő await agent.get_response("What is the capital of France?")await agent.get_response(messages="What is the capital of France?") támogatott. Minden más paramétert kulcsszóargumentumként kell megadni.

A get_response() metódus használata

# 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?"),
    ]
)

A invoke() metódus használata

# 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

Fontos

Az ügynök meghívása anélkül, hogy átadna egy AgentThread, a get_response() vagy invoke() metódusoknak létrehoz egy új szálat, és visszaadja az új szálat a válaszban.

A Szemantic Kernel három nem streamelési ügynökhívási túlterhelést támogat, amelyek lehetővé teszik az üzenetek továbbítását különböző módokon. Ezek egyike lehetővé teszi az ügynök üzenet nélküli meghívását is. Ez hasznos olyan helyzetekben, amikor az ügynök utasításai már rendelkeznek az összes szükséges háttérrel, hogy hasznos választ adjanak.

// 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?")
));

Fontos

Az ügynök meghívása anélkül, hogy egy AgentThread-t átadnánk a invokeAsync metódusnak, új szálat hoz létre, és a válaszban visszaadja azt.

Streaming Agent hívása

A Szemantic Kernel négy olyan streamelési ügynök-meghívási túlterhelést támogat, amelyek lehetővé teszik az üzenetek különböző módon történő továbbítását. Ezek egyike lehetővé teszi az ügynök üzenet nélküli meghívását is. Ez hasznos olyan helyzetekben, amikor az ügynök utasításai már rendelkeznek az összes szükséges háttérrel, hogy hasznos választ adjanak.

// 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?")
});

Fontos

Az ügynök meghívása anélkül, hogy egy AgentThread-t átadnánk a InvokeStreamingAsync metódusnak, új szálat hoz létre, és a válaszban visszaadja azt.

A Szemantic Kernel egy streamelési ügynök meghívási metódusát támogatja, amely lehetővé teszi az üzenetek különböző módon történő továbbítását. Az ügynökstreamet üzenet nélkül is meghívhatja. Ez hasznos olyan helyzetekben, amikor az ügynök utasításai már rendelkeznek az összes szükséges háttérrel, hogy hasznos választ adjanak.

# 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

Fontos

Az ügynök meghívása anélkül, hogy egy AgentThread-t átadnánk a invoke_stream() metódusnak, új szálat hoz létre, és a válaszban visszaadja azt.

A funkció jelenleg nem érhető el a Javában.

Meghívás egy AgentThread segítségével

A meghívási metódusok minden túlterhelése lehetővé teszi egy AgentThread paraméter átadását. Ez olyan helyzetekben hasznos, amikor már folyamatban van egy beszélgetése az ügynökkel, amelyet folytatni szeretne.

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

Az összes meghívási metódus az aktív AgentThread értéket is visszaadja a meghívási válasz részeként.

  1. Ha átad egy AgentThread az invoke metódusnak, a visszaadott AgentThread ugyanaz lesz, mint amit átadtunk.
  2. Ha nemet AgentThread adott a meghívási metódusnak, a visszaadott AgentThread érték egy új AgentThreadlesz.

A visszaadott AgentThread érték a meghívási metódusok egyes válaszelemeinél és a válaszüzenetben érhető el.

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

Jótanács

Az ügynökszálakról további információt az Ügynökszál architektúrája című szakaszban talál.

Minden meghívási metódus kulcsszóargumentuma lehetővé teszi egy paraméter átadását AgentThread . Ez olyan helyzetekben hasznos, amikor már folyamatban van egy beszélgetése az ügynökkel, amelyet folytatni szeretne.

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

Az összes meghívási metódus az aktív AgentThread értéket is visszaadja a meghívási válasz részeként.

  1. Ha átad egy AgentThread az invoke metódusnak, a visszaadott AgentThread ugyanaz lesz, mint amit átadtunk.
  2. Ha nemet AgentThread adott a meghívási metódusnak, a visszaadott AgentThread érték egy új AgentThreadlesz.

A visszaadott AgentThread érték a meghívási metódusok egyes válaszelemeinél és a válaszüzenetben érhető el.

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

Jótanács

Az ügynökszálakról további információt az Ügynökszál architektúrája című szakaszban talál.

Két meghívási metódus túlterhelés lehetővé teszi egy AgentThread paraméter átadását. Ez olyan helyzetekben hasznos, amikor már folyamatban van egy beszélgetése az ügynökkel, amelyet folytatni szeretne.

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

Ezek a meghívási metódusok az aktív AgentThread értéket is visszaadják a meghívási válasz részeként.

  1. Ha átadta AgentThread a meghívási metódusnak, a visszaadott AgentThread példány egy új példány lesz az előző és az új üzenetekkel.
  2. Ha nemet AgentThread adott a meghívási metódusnak, a visszaadott AgentThread érték egy új AgentThreadlesz.

A visszaadott AgentThread érték a meghívási metódusok egyes válaszelemeinél és a válaszüzenetben érhető el.

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

Jótanács

Az ügynökszálakról további információt az Ügynökszál architektúrája című szakaszban talál.

Meghívás opciókkal

A meghívási metódusok minden túlterhelése lehetővé teszi egy AgentInvokeOptions paraméter átadását. Ez a beállításosztály lehetővé teszi az opcionális beállítások megadását.

// 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."
});

Itt találja a támogatott beállítások listáját.

Opció tulajdonság Leírás
Kern Bírálja felül az ügynök által a meghíváshoz használt alapértelmezett kernelt.
Kernelargumentumok Felülbírálja az ügynök által a meghíváshoz használt alapértelmezett kernelargumentumokat.
További utasítások Adjon meg minden olyan utasítást az eredeti ügynök utasításkészleten kívül, amely csak erre a meghívásra vonatkozik.
OnIntermediateMessage Egy visszahívási funkció, amely képes fogadni az ügynök által belsőleg létrehozott összes teljes üzenetet, beleértve a függvényhívási és a funkciók meghívásával kapcsolatos üzeneteket. Ez teljes üzenetek fogadására is használható a streamhívások során.

Meghívás opciókkal

Egy meghívási metódus túlterhelése lehetővé teszi egy paraméter átadását AgentInvokeOptions . Ez a beállításosztály lehetővé teszi az opcionális beállítások megadását.

// 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()
);

Itt találja a támogatott beállítások listáját.

Opció tulajdonság Leírás
Kern Bírálja felül az ügynök által a meghíváshoz használt alapértelmezett kernelt.
Kernelargumentumok Felülbírálja az ügynök által a meghíváshoz használt alapértelmezett kernelargumentumokat.
További utasítások Adjon meg minden olyan utasítást az eredeti ügynök utasításkészleten kívül, amely csak erre a meghívásra vonatkozik.
InvocationContext Bírálja felül az ügynök által a meghíváshoz használt alapértelmezett meghívási környezetet.

AgentThread-példányok kezelése

Létrehozhat manuálisan egy AgentThread példányt, és átadhatja az ügynöknek híváskor, vagy engedélyezheti, hogy az ügynök automatikusan hozzon létre egy AgentThread példányt híváskor. Az AgentThread objektumok egy szálat jelölnek az összes állapotában, beleértve a még nem létrehozott, aktív és törölt szálakat.

AgentThread a kiszolgálóoldali implementációval rendelkező típusok első használatkor jönnek létre, és nem kell manuálisan létrehozni. Azonban a AgentThread osztály használatával törölhet egy szálat.

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

# Delete a thread
await agent_thread.delete()

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

Jótanács

Az ügynökszálakról további információt az Ügynökszál architektúrája című szakaszban talál.

Következő lépések

Ügynökök konfigurálása beépülő modulokkal

A Csevegő Kitöltő Ügynök felfedezése

  • Last updated on