agent_framework Paket

Paketler

a2a
ag_ui
anthropic
azure
chatkit
declarative
devui
lab
mem0
microsoft
ollama
openai
redis

Modül

exceptions
observability

Sınıflar

AIFunction	Python işlevini yapay zeka modelleri tarafından çağrılabilir hale getirmek için sarmalayan bir araç. Bu sınıf, otomatik parametre doğrulaması ve JSON şeması oluşturma ile yapay zeka modelleri tarafından çağrılabilen bir Python işlevi sarmalar. AIFunction'ı başlatın.
AgentExecutor	iletileri işlemek için bir aracı sarmalayan yerleşik yürütücü. AgentExecutor, davranışını iş akışı yürütme moduna göre uyarlar: run_stream(): Aracı belirteçler üretirken artımlı AgentRunUpdateEvent olaylarını yayar run(): Tam yanıtı içeren tek bir AgentRunEvent yayar Yürütücü, modu WorkflowContext.is_streaming() aracılığıyla otomatik olarak algılar. Yürütücüsü benzersiz bir tanımlayıcıyla başlatın.
AgentExecutorRequest	Aracı yürütücüsine yönelik bir istek.
AgentExecutorResponse	Aracı yürütücüsundan gelen yanıt.
AgentInputRequest	Bir aracı üst düzey oluşturucu iş akışlarında çalışmadan önce insan girişi isteği. Bir aracı yürütülmeden önce bir iş akışı duraklatıldığında RequestInfoEvent aracılığıyla yayılan. Yanıt, aracının davranışını yönlendirmek için konuşmaya kullanıcı iletisi olarak eklenir. Bu, .with_request_info () tarafından SequentialBuilder, ConcurrentBuilder, GroupChatBuilder ve HandoffBuilder üzerinde kullanılan standart istek türüdür.
AgentMiddleware	Aracı çağrılarını kesebilen aracı ara yazılımı için soyut temel sınıf. Aracı ara yazılımı, yürütmeden önce ve sonra aracı çağrılarını kesmenize ve değiştirmenize olanak tanır. İletileri inceleyebilir, bağlamı değiştirebilir, sonuçları geçersiz kılabilir veya yürütmeyi erken sonlandırabilirsiniz. Uyarı AgentMiddleware soyut bir temel sınıftır. Bunu alt sınıflamalı ve uygulamalısınız özel aracı ara yazılımı oluşturmak için process() yöntemi.
AgentProtocol	Bir aracı için çağrılabilen bir protokol. Bu protokol, tanımlama özellikleri ve yürütme yöntemleri dahil olmak üzere tüm aracıların uygulaması gereken arabirimi tanımlar. Uyarı Protokoller yapısal alt stil (ördek yazma) kullanır. Sınıfların gerekli olmadığı uyumlu olarak kabul edilecek şekilde bu protokolden açıkça devralınacak. Bu, kullanmadan tamamen özel aracılar oluşturmanıza olanak tanır herhangi bir Agent Framework temel sınıfı.
AgentRunContext	Aracı ara yazılım çağrıları için bağlam nesnesi. Bu bağlam aracı ara yazılım işlem hattı üzerinden geçirilir ve aracı çağırma hakkındaki tüm bilgileri içerir. AgentRunContext'i başlatın.
AgentRunEvent	Aracı çalıştırması tamamlandığında tetiklenen olay. Aracı çalıştırma olayını başlatın.
AgentRunResponse	Aracı çalıştırma isteğine verilen yanıtı temsil eder. Yanıtla ilgili bir veya daha fazla yanıt iletisi ve meta veri sağlar. Tipik bir yanıt tek bir ileti içerir, ancak işlev çağrıları, RAG almaları veya karmaşık mantık içeren senaryolarda birden çok ileti içerebilir. AgentRunResponse başlatın.
AgentRunResponseUpdate	Bir Aracıdan tek bir akış yanıt öbeklerini temsil eder. AgentRunResponseUpdate'i başlatın.
AgentRunUpdateEvent	Aracı iletilerin akışını yaparken tetiklenen olay. Aracı akış olayını başlatın.
AgentThread	Aracı iş parçacığı sınıfı, hem yerel olarak yönetilen iş parçacığını hem de hizmet tarafından yönetilen bir iş parçacığını temsil edebilir. aracı AgentThread etkileşimi için konuşma durumunu ve ileti geçmişini korur. Hizmet tarafından yönetilen bir iş parçacığı (aracılığıyla service_thread_id) veya yerel bir ileti deposu (aracılığıyla message_store) kullanabilir, ancak ikisini birden kullanamaz. AgentThread başlatın, bu yöntemi el ile kullanmayın, her zaman şunu kullanın: agent.get_new_thread(). Uyarı service_thread_id veya message_store ayarlanabilir, ancak ikisi birden ayarlanamaz.
AggregateContextProvider	Birden çok bağlam sağlayıcısı içeren bir ContextProvider. Olayları birden çok bağlam sağlayıcısına devreder ve döndürmeden önce bu olaylardan yanıtları toplar. Bu, birden çok bağlam sağlayıcısını tek bir sağlayıcıda birleştirmenizi sağlar. Uyarı Tek bir bağlam geçirdiğinizde bir AggregateContextProvider otomatik olarak oluşturulur sağlayıcı veya aracı oluşturucusunun bağlam sağlayıcıları dizisi. Bağlam sağlayıcılarıyla AggregateContextProvider'ı başlatın.
BaseAgent	Tüm Agent Framework aracıları için temel sınıf. Bu sınıf, bağlam sağlayıcıları, ara yazılım desteği ve iş parçacığı yönetimi dahil olmak üzere aracı uygulamaları için temel işlevsellik sağlar. Uyarı BaseAgent örneği doğrudan oluşturulamaz çünkü uygulamaz: run(), run_stream() ve AgentProtocol tarafından gereken diğer yöntemler. ChatAgent gibi somut bir uygulama kullanın veya bir alt sınıf oluşturun. BaseAgent örneğini başlatın.
BaseAnnotation	Tüm AI Ek Açıklama türleri için temel sınıf. BaseAnnotation'ı başlatın.
BaseChatClient	Sohbet istemcileri için temel sınıf. Bu soyut temel sınıf, ara yazılım desteği, ileti hazırlama ve araç normalleştirme dahil olmak üzere sohbet istemcisi uygulamaları için temel işlevsellik sağlar. Uyarı BaseChatClient, soyut bir temel sınıf olduğundan doğrudan örneği oluşturulamaz. Alt sınıfların _inner_get_response() ve _inner_get_streaming_response() uygulaması gerekir. BaseChatClient örneğini başlatın.
BaseContent	Yapay zeka hizmetleri tarafından kullanılan içeriği temsil eder. BaseContent'i başlatın.
Case	Bir anahtar-servis talebi koşulunu hedefiyle birleştiren çalışma zamanı sarmalayıcı. Her Durum , koşul True olarak değerlendirildiğinde iletiyi işlemesi gereken yürütücü ile bir boole koşulu birleştirir. Çalışma zamanı, bu basit kapsayıcıyı serileştirilebilir SwitchCaseEdgeGroupCase'ten ayrı tutarak yürütmenin kalıcı durumu kirletmeden canlı çağrılabilen öğelerle çalışabilmesini sağlar.
ChatAgent	Sohbet İstemci aracısı. Bu, dil modelleriyle etkileşime geçmek için sohbet istemcisi kullanan birincil aracı uygulamasıdır. Araçları, bağlam sağlayıcılarını, ara yazılımı ve hem akış hem de akış dışı yanıtları destekler. Bir ChatAgent örneği başlatın. Uyarı frequency_penalty ile request_kwargs parametreleri kümesi sohbet istemcisini çağırın. Ayrıca her iki çalıştırma yöntemine de geçirilebilir. Her ikisi de ayarlandığında, çalıştırma yöntemlerine geçirilenler öncelikli olur.
ChatClientProtocol	Yanıt oluşturabilen bir sohbet istemcisi protokolü. Bu protokol, hem akış hem de akış dışı yanıt oluşturma yöntemleri dahil olmak üzere tüm sohbet istemcilerinin uygulaması gereken arabirimi tanımlar. Uyarı Protokoller yapısal alt stil (ördek yazma) kullanır. Sınıfların gerekli olmadığı uyumlu olarak kabul edilecek şekilde bu protokolden açıkça devralınacak.
ChatContext	Sohbet ara yazılımı çağrıları için bağlam nesnesi. Bu bağlam, sohbet ara yazılım işlem hattı üzerinden geçirilir ve sohbet isteği hakkındaki tüm bilgileri içerir. ChatContext'i başlatın.
ChatMessage	Sohbet iletisini temsil eder. ChatMessage'ı başlatın.
ChatMessageStore	İletileri bir listede depolayan ChatMessageStoreProtocol'un bellek içi uygulaması. Bu uygulama, serileştirme ve seri durumdan çıkarma desteğiyle sohbet iletileri için basit, liste tabanlı bir depolama alanı sağlar. Protokolün tüm gerekli yöntemlerini ChatMessageStoreProtocol uygular. Depo, iletileri bellekte tutar ve kalıcılık amacıyla durumu seri hale getirmek ve seri durumdan çıkarmak için yöntemler sağlar. bir iş parçacığında kullanmak üzere bir ChatMessageStore oluşturun.
ChatMessageStoreProtocol	Belirli bir yazışmayla ilişkili sohbet iletilerini depolama ve alma yöntemlerini tanımlar. Bu protokolün uygulamaları, iletileri gerektiği gibi keserek veya özetleyerek büyük hacimli verileri işlemek de dahil olmak üzere sohbet iletilerinin depolanmasını yönetmekten sorumludur.
ChatMiddleware	Sohbet istemci isteklerini kesebilen sohbet ara yazılımı için soyut temel sınıf. Sohbet ara yazılımı, yürütmeden önce ve sonra sohbet istemci isteklerini kesmenize ve değiştirmenize olanak tanır. İletileri değiştirebilir, sistem istemleri ekleyebilir, istekleri günlüğe kaydedebilir veya sohbet yanıtlarını geçersiz kılabilirsiniz. Uyarı ChatMiddleware soyut bir temel sınıftır. Bunu alt sınıflamalı ve uygulamalısınız özel sohbet ara yazılımı oluşturmak için process() yöntemi.
ChatOptions	Yapay zeka hizmetleri için yaygın istek ayarları. ChatOptions'ı başlatın.
ChatResponse	Sohbet isteğine verilen yanıtı temsil eder. Sağlanan parametrelerle bir ChatResponse başlatır.
ChatResponseUpdate	Bir ChatClient'tan gelen tek bir akış yanıt öbeklerini temsil eder. Sağlanan parametrelerle bir ChatResponseUpdate başlatır.
CheckpointStorage	Denetim noktası depolama arka uçları için protokol.
CitationAnnotation	Alıntı ek açıklamasını temsil eder. CitationAnnotation'ı başlatın.
ConcurrentBuilder	Eşzamanlı aracı iş akışları için üst düzey oluşturucu. participants([...]) AgentProtocol (önerilen) veya Yürütücü listesini kabul eder. register_participants([...]) AgentProtocol için fabrikaların listesini kabul eder (önerilir) veya Yürütücü fabrikaları build() wires: dispatcher -> fan-out -> participants -> fan-in -> toplayıcı. with_aggregator(...) bir Yürütücü veya geri çağırma ile varsayılan toplayıcıyı geçersiz kılar. register_aggregator(...) özel toplayıcı olarak yürütücü için bir fabrika kabul eder. Kullanım: from agent_framework import ConcurrentBuilder # Minimal: use default aggregator (returns list[ChatMessage]) workflow = ConcurrentBuilder().participants([agent1, agent2, agent3]).build() # With agent factories workflow = ConcurrentBuilder().register_participants([create_agent1, create_agent2, create_agent3]).build() # Custom aggregator via callback (sync or async). The callback receives # list[AgentExecutorResponse] and its return value becomes the workflow's output. def summarize(results: list[AgentExecutorResponse]) -> str: return " | ".join(r.agent_run_response.messages[-1].text for r in results) workflow = ConcurrentBuilder().participants([agent1, agent2, agent3]).with_aggregator(summarize).build() # Custom aggregator via a factory class MyAggregator(Executor): @handler async def aggregate(self, results: list[AgentExecutorResponse], ctx: WorkflowContext[Never, str]) -> None: await ctx.yield_output(" | ".join(r.agent_run_response.messages[-1].text for r in results)) workflow = ( ConcurrentBuilder() .register_participants([create_agent1, create_agent2, create_agent3]) .register_aggregator(lambda: MyAggregator(id="my_aggregator")) .build() ) # Enable checkpoint persistence so runs can resume workflow = ConcurrentBuilder().participants([agent1, agent2, agent3]).with_checkpointing(storage).build() # Enable request info before aggregation workflow = ConcurrentBuilder().participants([agent1, agent2]).with_request_info().build()
Context	ContextProvider tarafından sağlanan şekilde yapay zeka modeline sağlanması gereken bağlamı içeren bir sınıf. Her ContextProvider, her çağrı için kendi bağlamını sağlama özelliğine sahiptir. Context sınıfı, ContextProvider tarafından sağlanan ek bağlamı içerir. Bu bağlam, yapay zeka modeline geçirilmeden önce diğer sağlayıcılar tarafından sağlanan bağlamla birleştirilir. Bu bağlam çağrıya göredir ve sohbet geçmişinin bir parçası olarak depolanmaz. Yeni bir Context nesnesi oluşturun.
ContextProvider	Tüm bağlam sağlayıcıları için temel sınıf. Bağlam sağlayıcısı, yapay zekanın bağlam yönetimini geliştirmek için kullanılabilecek bir bileşendir. Konuşmadaki değişiklikleri dinleyebilir ve çağrıdan hemen önce yapay zeka modeline ek bağlam sağlayabilir. Uyarı ContextProvider soyut bir temel sınıftır. Bunu alt sınıflamalı ve uygulamalısınız özel bağlam sağlayıcısı oluşturmak için invoking() yöntemi. İdeal olarak, ayrıca konuşmayı izlemek için invoked() ve thread_created() yöntemlerini uygulayın durum bilgisidir, ancak bunlar isteğe bağlıdır.
DataContent	İlişkili medya türüyle (MIME türü olarak da bilinir) ikili veri içeriğini temsil eder. Önemli Bu, çevrimiçi kaynaklar için değil, veri URI'si olarak temsil edilen ikili veriler içindir. Çevrimiçi kaynaklar için UriContent kullanın. DataContent örneğini başlatır. Önemli Bu, çevrimiçi kaynaklar için değil, veri URI'si olarak temsil edilen ikili veriler içindir. Çevrimiçi kaynaklar için UriContent kullanın.
Default	Bir anahtar-servis talebi grubundaki varsayılan dalın çalışma zamanı gösterimi. Varsayılan dal yalnızca başka bir büyük/küçük harf koşulu eşleşmediğinde çağrılır. Uygulamada, yönlendirmenin hiçbir zaman boş hedef oluşturmaması için var olması garanti edilir.
Edge	İki yürütücü arasında yönlendirilmiş, isteğe bağlı olarak koşullu bir teslimi modelle. Her Edge , bir iletiyi iş akışı grafı içinde bir yürütücüden diğerine taşımak için gereken en düşük meta verileri yakalar. İsteğe bağlı olarak kenarın çalışma zamanında alınması gerekip gerekmediğini belirleyen bir boole koşulu ekler. Kenarı ilkel öğelere kadar seri hale getirerek, özgün Python işleminden bağımsız olarak bir iş akışının topolojisini yeniden oluşturabiliriz. İki iş akışı yürütücüsü arasında tam olarak belirtilen bir kenar başlatın.
EdgeDuplicationError	İş akışında yinelenen kenarlar algılandığında oluşan özel durum.
ErrorContent	Bir hatayı temsil eder. Açıklamalar: Genellikle işlemin bir parçası olarak bir sorun oluştuğu ancak işlemin devam edebildiği önemli olmayan hatalar için kullanılır. ErrorContent örneğini başlatır.
Executor	İletileri işleyen ve hesaplamalar gerçekleştiren tüm iş akışı yürütücüleri için temel sınıf. Genel Bakış Yürütücüler, iletileri alan, işlem gerçekleştiren ve çıkış üreten tek tek işlem birimlerini temsil eden iş akışlarının temel yapı taşlarıdır. Her yürütücü benzersiz olarak tanımlanır ve düzenlenmiş işleyici yöntemleri aracılığıyla belirli ileti türlerini işleyebilir. Tip Sistemi Yürütücülerin özelliklerini tanımlayan zengin bir tür sistemi vardır: Giriş Türleri Yürütücülerin işleyebileceği ileti türleri, işleyici yöntemi imzalarından bulunur: class MyExecutor(Executor): @handler async def handle_string(self, message: str, ctx: WorkflowContext) -> None: # This executor can handle 'str' input types input_types özelliği aracılığıyla erişim. Çıkış Türleri Yürütücülerin ctx.send_message() aracılığıyla diğer yürütücülere gönderebileceği ileti türleri: class MyExecutor(Executor): @handler async def handle_data(self, message: str, ctx: WorkflowContext[int | bool]) -> None: # This executor can send 'int' or 'bool' messages output_types özelliği aracılığıyla erişim. İş Akışı Çıkış Türleri Yürütücüsü, ctx.yield_output() aracılığıyla iş akışı düzeyinde çıkış olarak yayabileceği veri türleri: class MyExecutor(Executor): @handler async def process(self, message: str, ctx: WorkflowContext[int, str]) -> None: # Can send 'int' messages AND yield 'str' workflow outputs workflow_output_types özelliği aracılığıyla erişim. İşleyici Bulma Yürütücüler, özelliklerini dekore edilmiş yöntemlerle bulur: @handler Dekoratör Gelen iletileri işleyen yöntemleri işaretler: class MyExecutor(Executor): @handler async def handle_text(self, message: str, ctx: WorkflowContext[str]) -> None: await ctx.send_message(message.upper()) Alt iş akışı İstek Kesme Alt iş akışı isteklerini kesmek için yöntemleri kullanın @handler : class ParentExecutor(Executor): @handler async def handle_subworkflow_request( self, request: SubWorkflowRequestMessage, ctx: WorkflowContext[SubWorkflowResponseMessage], ) -> None: if self.is_allowed(request.domain): response = request.create_response(data=True) await ctx.send_message(response, target_id=request.executor_id) else: await ctx.request_info(request.source_event, response_type=request.source_event.response_type) Bağlam Türleri İşleyici yöntemleri, tür ek açıklamalarına göre farklı WorkflowContext varyantları alır: WorkflowContext (tür parametresi yok) yalnızca ileti göndermeden veya çıkışlar vermeden yan etkiler gerçekleştiren işleyiciler için: class LoggingExecutor(Executor): @handler async def log_message(self, msg: str, ctx: WorkflowContext) -> None: print(f"Received: {msg}") # Only logging, no outputs WorkflowContext[T_Out] ctx.send_message () aracılığıyla T_Out türünde iletiler göndermeyi etkinleştirir: class ProcessorExecutor(Executor): @handler async def handler(self, msg: str, ctx: WorkflowContext[int]) -> None: await ctx.send_message(42) # Can send int messages WorkflowContext[T_Out, T_W_Out] hem ileti göndermeyi (T_Out) hem de iş akışı çıkışlarını (T_W_Out) verir: class DualOutputExecutor(Executor): @handler async def handler(self, msg: str, ctx: WorkflowContext[int, str]) -> None: await ctx.send_message(42) # Send int message await ctx.yield_output("done") # Yield str workflow output İşlev Yürütücüleri Basit işlevler , @executor dekoratörü kullanılarak yürütücülere dönüştürülebilir: @executor async def process_text(text: str, ctx: WorkflowContext[str]) -> None: await ctx.send_message(text.upper()) # Or with custom ID: @executor(id="text_processor") def sync_process(text: str, ctx: WorkflowContext[str]) -> None: ctx.send_message(text.lower()) # Sync functions run in thread pool Alt iş akışı Oluşturma Yürütücüler WorkflowExecutor kullanarak alt iş akışları içerebilir. Alt iş akışları üst iş akışlarının araya girebileceği isteklerde bulunabilir. İş akışı oluşturma desenleri ve istek/yanıt işleme hakkında ayrıntılı bilgi için WorkflowExecutor belgelerine bakın. Durum Yönetimi Yürütücüler, iş akışı çalıştırmaları ve denetim noktaları arasında kalıcı olan durumlar içerebilir. Özel durum serileştirme ve geri yükleme mantığı uygulamak için on_checkpoint_save ve on_checkpoint_restore yöntemlerini geçersiz kılın. Uygulama Notları Execute() öğesini doğrudan çağırmayın; iş akışı altyapısı tarafından çağrılır Execute() geçersiz kılma - bunun yerine dekoratörleri kullanarak işleyicileri tanımlama Her yürütücü en az bir @handler yöntemine sahip olmalıdır İşleyici yöntemi imzaları başlatma sırasında doğrulanır Yürütücüsü benzersiz bir tanımlayıcıyla başlatın.
ExecutorCompletedEvent	Yürütücü işleyicisi tamamlandığında tetiklenen olay. Yürütücü olayını yürütücü kimliği ve isteğe bağlı verilerle başlatın.
ExecutorEvent	Yürütücü olayları için temel sınıf. Yürütücü olayını yürütücü kimliği ve isteğe bağlı verilerle başlatın.
ExecutorFailedEvent	Yürütücü işleyicisi hataya neden olduğunda tetiklenen olay.
ExecutorInvokedEvent	Yürütücü işleyicisi çağrıldığında tetiklenen olay. Yürütücü olayını yürütücü kimliği ve isteğe bağlı verilerle başlatın.
FanInEdgeGroup	Tek bir aşağı akış yürütücüsü besleyen bir yakınsanan kenar kümesini temsil eder. Fan-in grupları genellikle birden çok yukarı akış aşaması bağımsız olarak aynı aşağı akış işlemcisine ulaşması gereken iletiler oluşturduğunda kullanılır. Birkaç kaynağı tek bir hedefte birleştirilen bir fan-in eşlemesi oluşturun.
FanOutEdgeGroup	İsteğe bağlı seçim mantığıyla yayın stili bir kenar grubunu temsil edin. Bir yayma, tek bir kaynak yürütücüsü tarafından üretilen bir iletiyi bir veya daha fazla aşağı akış yürütücüsine iletir. Çalışma zamanında yükü inceleyen ve iletiyi alması gereken kimliklerin alt kümesini döndüren bir selection_func yürüterek hedefleri daha da daraltabiliriz. Tek bir kaynaktan birçok hedefe yönelik bir fan-out eşlemesi oluşturun.
FileCheckpointStorage	Kalıcılık için dosya tabanlı denetim noktası depolama alanı. Dosya depolama alanını başlatın.
FinishReason	Sohbet yanıtının tamamlanma nedenini temsil eder. FinishReason'ı bir değerle başlatın.
FunctionApprovalRequestContent	İşlev çağrısının kullanıcı onayı isteğini temsil eder. FunctionApprovalRequestContent örneğini başlatır.
FunctionApprovalResponseContent	İşlev çağrısının kullanıcı onayı için bir yanıtı temsil eder. FunctionApprovalResponseContent örneğini başlatır.
FunctionCallContent	İşlev çağrısı isteğini temsil eder. FunctionCallContent örneğini başlatır.
FunctionExecutor	Kullanıcı tanımlı bir işlevi sarmalayan yürütücü. Bu yürütücü, kullanıcıların tam yürütücü sınıfları oluşturmaya gerek kalmadan basit işlevler (eşitleme ve zaman uyumsuz) tanımlamasına ve bunları iş akışı yürütücüleri olarak kullanmasına olanak tanır. Zaman uyumlu işlevler, olay döngüsünü engellememek için asyncio.to_thread() kullanılarak bir iş parçacığı havuzunda yürütülür. FunctionExecutor'ı kullanıcı tanımlı bir işlevle başlatın.
FunctionInvocationConfiguration	Sohbet istemcilerinde işlev çağırma yapılandırması. Bu sınıf, işlev çağrısını destekleyen her sohbet istemcisinde otomatik olarak oluşturulur. Bu, çoğu durumda yalnızca örnekteki öznitelikleri değiştirebileceğiniz, ardından yeni bir tane oluşturabileceğiniz anlamına gelir. FunctionInvocationConfiguration'ı başlatın.
FunctionInvocationContext	İşlev ara yazılım çağrıları için bağlam nesnesi. Bu bağlam, işlev ara yazılım işlem hattı üzerinden geçirilir ve işlev çağrısı hakkındaki tüm bilgileri içerir. FunctionInvocationContext'i başlatın.
FunctionMiddleware	İşlev çağrılarını kesebilen işlev ara yazılımı için soyut temel sınıf. İşlev ara yazılımı, yürütmeden önce ve sonra işlev/araç çağrılarını kesmenize ve değiştirmenize olanak tanır. Bağımsız değişkenleri doğrulayabilir, sonuçları önbelleğe alabilir, çağrıları günlüğe kaydedebilir veya işlev yürütmesini geçersiz kılabilirsiniz. Uyarı FunctionMiddleware soyut bir temel sınıftır. Bunu alt sınıflamalı ve uygulamalısınız özel işlev ara yazılımı oluşturmak için process() yöntemi.
FunctionResultContent	İşlev çağrısının sonucunu temsil eder. FunctionResultContent örneğini başlatır.
GraphConnectivityError	Grafik bağlantı sorunları algılandığında özel durum ortaya çıkar.
GroupChatBuilder	Dinamik düzenleme ile yönetici tarafından yönlendirilen grup sohbeti iş akışları için üst düzey oluşturucu. GroupChat, bir sonraki katılımcıyı seçen bir yönetici kullanarak çok aracılı konuşmaları koordine eder. Yönetici, aracılığıyla set_select_speakers_funcbasit bir Python işlevi (set_manager) veya aracı tabanlı seçici olabilir. Bu iki yaklaşım birbirini dışlar. Çekirdek İş Akışı: Katılımcıları tanımlama: aracıların listesi (.name kullanır) veya aracılara dikte eşleme adları Konuşmacı seçimini yapılandırma: set_select_speakers_func VEYA set_manager (ikisini birden değil) İsteğe bağlı: yuvarlak sınırları ayarlama, denetim noktası oluşturma, sonlandırma koşulları İş akışını oluşturma ve çalıştırma Konuşmacı Seçim Desenleri: Desen 1: Basit işlev tabanlı seçim (önerilir) from agent_framework import GroupChatBuilder, GroupChatStateSnapshot def select_next_speaker(state: GroupChatStateSnapshot) -> str | None: # state contains: task, participants, conversation, history, round_index if state["round_index"] >= 5: return None # Finish last_speaker = state["history"][-1].speaker if state["history"] else None if last_speaker == "researcher": return "writer" return "researcher" workflow = ( GroupChatBuilder() .set_select_speakers_func(select_next_speaker) .participants([researcher_agent, writer_agent]) # Uses agent.name .build() ) Desen 2: LLM tabanlı seçim from agent_framework import ChatAgent from agent_framework.azure import AzureOpenAIChatClient manager_agent = AzureOpenAIChatClient().create_agent( instructions="Coordinate the conversation and pick the next speaker.", name="Coordinator", temperature=0.3, seed=42, max_tokens=500, ) workflow = ( GroupChatBuilder() .set_manager(manager_agent, display_name="Coordinator") .participants([researcher, writer]) # Or use dict: researcher=r, writer=w .with_max_rounds(10) .build() ) Desen 3: Konuşmanın ortasında geri bildirim için bilgi isteme from agent_framework import GroupChatBuilder # Pause before all participants workflow = ( GroupChatBuilder() .set_select_speakers_func(select_next_speaker) .participants([researcher, writer]) .with_request_info() .build() ) # Pause only before specific participants workflow = ( GroupChatBuilder() .set_select_speakers_func(select_next_speaker) .participants([researcher, writer, editor]) .with_request_info(agents=[editor]) # Only pause before editor responds .build() ) Katılımcı Belirtimi: Katılımcıları belirtmenin iki yolu: Liste formu: [agent1, agent2] - katılımcı adları için agent.name özniteliğini kullanır Dikte formu: {name1: agent1, name2: agent2} - açık ad denetimi Anahtar sözcük formu: participants(name1=agent1, name2=agent2) - açık ad denetimi Durum Anlık Görüntüsü Yapısı: set_select_speakers_func geçirilen GroupChatStateSnapshot aşağıdakileri içerir: görev: ChatMessage - Özgün kullanıcı görevi participants: dict[str, str] - Katılımcı adlarını açıklamalarla eşleme conversation: tuple[ChatMessage, ...] - Tam konuşma geçmişi history: tuple[GroupChatTurn, ...] - Konuşmacı atfı ile sıralı kayıt round_index: int - Şimdiye kadarki yönetici seçimi yuvarlamalarının sayısı pending_agent: str | Hiçbiri - Şu anda işlenmekte olan aracının adı (varsa) Önemli Kısıtlamalar: ve birleştirilemiyor set_select_speakers_funcset_manager Katılımcı adları benzersiz olmalıdır Liste formu kullanılırken, aracıların boş olmayan bir ad özniteliği olmalıdır GroupChatBuilder'ı başlatın.
GroupChatDirective	Grup sohbet yöneticisi uygulaması tarafından yayılan yönerge.
HandoffBuilder	Koordinatör ve uzman aracılarla konuşma iletimi iş akışları için akıcı oluşturucu. İletim düzeni, koordinatör aracının istekleri uzman aracılara yönlendirmesini sağlar. Etkileşim modu, iş akışının her aracı yanıtından sonra kullanıcı girişi isteyip istemediğini veya aracıların yanıt vermeyi tamamladıktan sonra otonom olarak tamamlanıp tamamlanmayacağını denetler. Sonlandırma koşulu, iş akışının ne zaman giriş isteğinde bulunup tamamlanması gerektiğini belirler. Yönlendirme Desenleri: Single-Tier (Varsayılan): Sadece koordinatör uzmanlara teslim edebilir. Varsayılan olarak, herhangi bir uzman yanıt verdikten sonra denetim daha fazla giriş için kullanıcıya geri döner. Bu döngüsel bir akış oluşturur: kullanıcı -> koordinatör -> [isteğe bağlı uzman] -> kullanıcı -> koordinatör -> ... Ek kullanıcı girişi isteme işlemini atlamak için with_interaction_mode("otonom") kullanın ve temsilci seçmeden bir aracı yanıt verdiği zaman son konuşmayı yapın. Çok Katmanlı (Gelişmiş): Uzmanlar .add_handoff() kullanarak diğer uzmanlara teslim edebilir. Bu, karmaşık iş akışları için daha fazla esneklik sağlar, ancak tek katmanlı desenden daha az denetlenebilir. Kullanıcılar, uzmandan uzmana iletimler sırasında ara adımlara ilişkin gerçek zamanlı görünürlüğü kaybeder (ancak tüm iletimler dahil olmak üzere konuşma geçmişinin tamamı korunur ve daha sonra incelenebilir). Önemli Özellikler: Otomatik iletim algılama: Düzenleyici, bağımsız değişkenleri (örneğin {"handoff_to": "shipping_agent"}) denetimi alacak uzmanı tanımlar. Otomatik oluşturulan araçlar: Oluşturucu varsayılan olarak koordinatör için handoff_to_<agent> araçlarını sentezler, böylece yer tutucu işlevleri el ile tanımlamazsınız. Tam konuşma geçmişi: Konuşmanın tamamı ( herhangi bir ChatMessage.additional_properties dahil) korunur ve her aracıya geçirilir. Sonlandırma denetimi: Varsayılan olarak, 10 kullanıcı iletisi sonrasında sonlanır. Özel mantık için .with_termination_condition(lambda conv: ...) ile geçersiz kılın (örneğin, "güle güle" algılayın). Etkileşim modları: Kullanıcılardan aracı dönüşleri arasında bilgi almak için human_in_loop (varsayılan) veya bir iletim gerçekleşene veya sonlandırma/dönüş sınırına ulaşılana kadar kullanıcı girişi istemeden aracılara yönlendirmeye devam etmek için otonom (varsayılan) seçeneğini belirleyin (varsayılan otonom dönüş sınırı: 50). Denetim noktası oluşturma: Devam ettirilebilen iş akışları için isteğe bağlı kalıcılık. Kullanım (Single-Tier): from agent_framework import HandoffBuilder from agent_framework.openai import OpenAIChatClient chat_client = OpenAIChatClient() # Create coordinator and specialist agents coordinator = chat_client.create_agent( instructions=( "You are a frontline support agent. Assess the user's issue and decide " "whether to hand off to 'refund_agent' or 'shipping_agent'. When delegation is " "required, call the matching handoff tool (for example `handoff_to_refund_agent`)." ), name="coordinator_agent", ) refund = chat_client.create_agent( instructions="You handle refund requests. Ask for order details and process refunds.", name="refund_agent", ) shipping = chat_client.create_agent( instructions="You resolve shipping issues. Track packages and update delivery status.", name="shipping_agent", ) # Build the handoff workflow - default single-tier routing workflow = ( HandoffBuilder( name="customer_support", participants=[coordinator, refund, shipping], ) .set_coordinator(coordinator) .build() ) # Run the workflow events = await workflow.run_stream("My package hasn't arrived yet") async for event in events: if isinstance(event, RequestInfoEvent): # Request user input user_response = input("You: ") await workflow.send_response(event.data.request_id, user_response) .add_handoff() ile Çok Katmanlı Yönlendirme: # Enable specialist-to-specialist handoffs with fluent API workflow = ( HandoffBuilder(participants=[coordinator, replacement, delivery, billing]) .set_coordinator(coordinator) .add_handoff(coordinator, [replacement, delivery, billing]) # Coordinator routes to all .add_handoff(replacement, [delivery, billing]) # Replacement delegates to delivery/billing .add_handoff(delivery, billing) # Delivery escalates to billing .build() ) # Flow: User → Coordinator → Replacement → Delivery → Back to User # (Replacement hands off to Delivery without returning to user) Durum Yalıtımı için Katılımcı Fabrikalarını Kullanma: Özel Sonlandırma Koşulu: # Terminate when user says goodbye or after 5 exchanges workflow = ( HandoffBuilder(participants=[coordinator, refund, shipping]) .set_coordinator(coordinator) .with_termination_condition( lambda conv: ( sum(1 for msg in conv if msg.role.value == "user") >= 5 or any("goodbye" in msg.text.lower() for msg in conv[-2:]) ) ) .build() ) Denetim noktası oluşturma: from agent_framework import InMemoryCheckpointStorage storage = InMemoryCheckpointStorage() workflow = ( HandoffBuilder(participants=[coordinator, refund, shipping]) .set_coordinator(coordinator) .with_checkpointing(storage) .build() ) Konuşma iletimi iş akışları oluşturmak için bir HandoffBuilder başlatın. Oluşturucu yapılandırılmamış bir durumda başlar ve şunları çağırmanızı gerektirir: .participants([...]) - Aracıları kaydetme veya .participant_factories({...}) - Aracı/yürütücü fabrikalarını kaydetme .set_coordinator(...) - İlk kullanıcı girişini alacak aracıyı belirleme .build() - Son İş Akışını oluşturma İsteğe bağlı yapılandırma yöntemleri bağlam yönetimini, sonlandırma mantığını ve kalıcılığı özelleştirmenize olanak tanır. Uyarı İş akışı eşlediğinden katılımcıların kararlı adları/kimlikleri olmalıdır bu tanımlayıcılara iletim aracı bağımsız değişkenleri. Aracı adları eşleşmelidir koordinatörün iletim aracı tarafından yayılan dizeler (örneğin, çıkışları {"handoff_to": "billing"} için faturalama adlı bir aracı gerekir).
HandoffUserInputRequest	İş akışının yeni kullanıcı girişi gerektiğinde gönderilen istek iletisi. Not: Yinelenenleri önlemek için konuşma alanı kasıtlı olarak denetim noktası serileştirmesinin dışında tutulur. Konuşma koordinatörün durumunda korunur ve geri yükleme işleminde yeniden oluşturulur. Sorun #2667'ye bakın.
HostedCodeInterpreterTool	Yapay zeka hizmetine, oluşturulan kodu yürütmesini sağlamak için belirtilebilen barındırılan bir aracı temsil eder. Bu araç, kod yorumlamanın kendisini uygulamaz. Hizmetin bunu yapabilmesi durumunda oluşturulan kodu yürütmesine izin verilip verilmediğini bildirmek için bir işaretçi görevi görür. HostedCodeInterpreterTool'u başlatın.
HostedFileContent	Barındırılan dosya içeriğini temsil eder. HostedFileContent örneğini başlatır.
HostedFileSearchTool	Bir yapay zeka hizmetine dosya aramaları gerçekleştirmesini sağlamak için belirtilebilen bir dosya arama aracını temsil eder. FileSearchTool'ı başlatın.
HostedMCPSpecificApproval	Barındırılan bir araç için belirli modu temsil eder. Bu modu kullanırken, kullanıcının hangi araçların her zaman veya hiçbir zaman onay gerektirmeyeceğini belirtmesi gerekir. Bu, iki isteğe bağlı anahtar içeren bir sözlük olarak temsil edilir:
HostedMCPTool	Hizmet tarafından yönetilen ve yürütülen bir MCP aracını temsil eder. Barındırılan bir MCP aracı oluşturun.
HostedVectorStoreContent	Barındırılan vektör deposu içeriğini temsil eder. HostedVectorStoreContent örneğini başlatır.
HostedWebSearchTool	Bir yapay zeka hizmetine web aramaları gerçekleştirmesini sağlamak için belirtilebilen bir web arama aracını temsil eder. HostedWebSearchTool'u başlatın.
InMemoryCheckpointStorage	Test ve geliştirme için bellek içi denetim noktası depolama alanı. Bellek depolama alanını başlatın.
InProcRunnerContext	Yerel yürütme ve isteğe bağlı denetim noktası oluşturma için işlem içi yürütme bağlamı. İşlem içi yürütme bağlamını başlatın.
MCPStdioTool	Stdio tabanlı MCP sunucularına bağlanmak için MCP aracı. Bu sınıf, genellikle yerel işlemler için kullanılan standart giriş/çıkış aracılığıyla iletişim kuran MCP sunucularına bağlanır. MCP stdio aracını başlatın. Uyarı Bağımsız değişkenler stdioServerParameters nesnesi oluşturmak için kullanılır, daha sonra bir stdio istemcisi oluşturmak için kullanılır. Bkz. mcp.client.stdio.stdio_client ve daha fazla ayrıntı için mcp.client.stdio.stdio_server_parameters.
MCPStreamableHTTPTool	HTTP tabanlı MCP sunucularına bağlanmak için MCP aracı. Bu sınıf, akışla aktarılabilir HTTP/SSE aracılığıyla iletişim kuran MCP sunucularına bağlanır. MCP akışla aktarılabilir HTTP aracını başlatın. Uyarı Bağımsız değişkenler akışla aktarılabilir bir HTTP istemcisi oluşturmak için kullanılır. Diğer ayrıntılar için bkz. mcp.client.streamable_http.streamablehttp_client. Oluşturucuya geçirilen tüm ek bağımsız değişkenler akışla aktarılabilir HTTP istemci oluşturucusu.
MCPWebsocketTool	WebSocket tabanlı MCP sunucularına bağlanmak için MCP aracı. Bu sınıf, WebSocket aracılığıyla iletişim kuran MCP sunucularına bağlanır. MCP WebSocket aracını başlatın. Uyarı Bağımsız değişkenler WebSocket istemcisi oluşturmak için kullanılır. Diğer ayrıntılar için bkz. mcp.client.websocket.websocket_client. Oluşturucuya geçirilen tüm ek bağımsız değişkenler WebSocket istemci oluşturucu.
MagenticBuilder	Magentic One çok aracılı düzenleme iş akışları oluşturmak için akıcı oluşturucu. Magentic One iş akışları, dinamik görev planlama, ilerleme izleme ve uyarlamalı yeniden planlama aracılığıyla birden çok aracıyı koordine etmek için LLM destekli bir yönetici kullanır. Yönetici planlar oluşturur, aracıları seçer, ilerleme durumunu izler ve ne zaman yeniden planlanıp tamamlanmayeceğini belirler. Oluşturucu, katılımcıları, yöneticiyi, isteğe bağlı plan gözden geçirme, denetim noktası oluşturma ve olay geri çağırmalarını yapılandırmak için akıcı bir API sağlar. Döngüdeki İnsan Desteği: Magentic, aşağıdakiler aracılığıyla özelleştirilmiş HITL mekanizmaları sağlar: .with_plan_review() - Yürütmeden önce planları gözden geçirme ve onaylama/düzeltme .with_human_input_on_stall() - İş akışı durduğunda müdahale FunctionApprovalRequestContent aracılığıyla araç onayı - Tek tek araç çağrılarını onaylama Bunlar, Magentic'in planlama tabanlı düzenlemesine uygun yapılandırılmış karar seçenekleri (ONAYLA, DÜZELT, DEVAM ET, REPLAN, REHBER) sağlayan MagenticHumanInterventionRequest olaylarını yayar. Kullanım: from agent_framework import MagenticBuilder, StandardMagenticManager from azure.ai.projects.aio import AIProjectClient # Create manager with LLM client project_client = AIProjectClient.from_connection_string(...) chat_client = project_client.inference.get_chat_completions_client() # Build Magentic workflow with agents workflow = ( MagenticBuilder() .participants(researcher=research_agent, writer=writing_agent, coder=coding_agent) .with_standard_manager(chat_client=chat_client, max_round_count=20, max_stall_count=3) .with_plan_review(enable=True) .with_checkpointing(checkpoint_storage) .build() ) # Execute workflow async for message in workflow.run("Research and write article about AI agents"): print(message.text) Özel yönetici ile: # Create custom manager subclass class MyCustomManager(MagenticManagerBase): async def plan(self, context: MagenticContext) -> ChatMessage: # Custom planning logic ... manager = MyCustomManager() workflow = MagenticBuilder().participants(agent1=agent1, agent2=agent2).with_standard_manager(manager).build()
MagenticContext	Magentic yöneticisi bağlamı.
MagenticManagerBase	Magentic One yöneticisi için temel sınıf.
ManagerDirectiveModel	Yapılandırılmış yönetici yönerge çıkışı için pydantik model. Anahtar sözcük bağımsız değişkenlerinden giriş verilerini ayrıştırarak ve doğrulayarak yeni bir model oluşturun. [ValidationError][pydantic_core yükseltir. ValidationError] giriş verileri geçerli bir model oluşturacak şekilde doğrulanamıyorsa. self , alan adı olarak self'e izin vermek için açıkça yalnızca konumsaldır.
ManagerSelectionRequest	Sonraki konuşmacı seçimi için yönetici aracısına gönderilen istek. Bu veri sınıfı, yönetici aracısının bir konuşmacı seçimi kararını çözümlemesi ve yapması için tam konuşma durumunu ve görev bağlamını paketler.
ManagerSelectionResponse	Konuşmacı seçimi kararıyla yönetici aracısından yanıt. Yönetici aracısı, kararını düzenleyiciye geri iletmek için bu yapıyı (veya uyumlu dict/JSON) üretmelidir. Anahtar sözcük bağımsız değişkenlerinden giriş verilerini ayrıştırarak ve doğrulayarak yeni bir model oluşturun. [ValidationError][pydantic_core yükseltir. ValidationError] giriş verileri geçerli bir model oluşturacak şekilde doğrulanamıyorsa. self , alan adı olarak self'e izin vermek için açıkça yalnızca konumsaldır.
Message	İş akışındaki bir iletiyi temsil eden sınıf.
OrchestrationState	Düzenleyici denetim noktası oluşturma için birleşik durum kapsayıcısı. Bu veri sınıfı, üç grup sohbeti deseninde de denetim noktası serileştirmesini standart hale getirirken meta veriler aracılığıyla desene özgü uzantılara izin verir. Ortak öznitelikler paylaşılan düzenleme endişelerini (görev, konuşma, yuvarlak izleme) kapsar. Desene özgü durum meta veri diktesine gider.
RequestInfoEvent	bir iş akışı yürütücüsü dış bilgi istediğinde tetiklenen olay. İstek bilgisi olayını başlatın.
RequestInfoInterceptor	Aracı çalışmadan önce insan girişi için iş akışını duraklatan iç yürütücü. bu yürütücü, .with_request_info() çağrıldığında oluşturucular tarafından iş akışı grafiğine eklenir. Aracı çalıştırılmadan önce AgentExecutorRequest iletilerini durdurur ve bir AgentInputRequest ile ctx.request_info() aracılığıyla iş akışını duraklatır. Yanıt alındığında, yanıt işleyicisi girişi konuşmaya kullanıcı iletisi olarak ekler ve isteği aracıya iletir. İsteğe bağlı agent_filter parametresi, duraklatma işlemini tetikleyen aracıları sınırlamaya olanak tanır. Hedef aracının kimliği filtre kümesinde değilse istek duraklatılmadan iletilir. İstek bilgisi kesme noktası yürütücüsunu başlatın.
Role	Sohbet etkileşimi içindeki bir iletinin amaçlanan amacını açıklar. Özellikler: SİSTEM: Yapay zeka sisteminin davranışını belirten veya ayarlayan rol. KULLANICI: Sohbet etkileşimleri için kullanıcı girişi sağlayan rol. YARDIMCI: Sistem tarafından yönergeli, kullanıcı tarafından istemli girişe yanıt sağlayan rol. ARAÇ: Araç kullanım isteklerine yanıt olarak ek bilgi ve başvuru sağlayan rol. Rolü bir değerle başlatın.
Runner	Pregel süpersteps'de iş akışı çalıştırmak için bir sınıf. Çalıştırıcıyı kenarlar, paylaşılan durum ve bağlamla başlatın.
RunnerContext	Çalıştırıcı tarafından kullanılan yürütme bağlamı protokolü. Mesajlaşmayı, olayları ve isteğe bağlı denetim noktası oluşturmayı destekleyen tek bir bağlam. Denetim noktası depolaması yapılandırılmamışsa denetim noktası yöntemleri tetiklenebilir.
SequentialBuilder	Paylaşılan bağlama sahip sıralı aracı/yürütücü iş akışları için üst düzey oluşturucu. participants([...]) AgentProtocol (önerilen) veya Yürütücü örneklerinin listesini kabul eder register_participants([...]) AgentProtocol için fabrikaların listesini kabul eder (önerilir) veya Yürütücü fabrikaları Yürütücüler, list[ChatMessage] kullanan ve bir liste gönderen bir işleyici tanımlamalıdır[ChatMessage] İş akışı, katılımcıları sırayla bağlayarak [ChatMessage] listesini zincirden aşağı aktarır Aracılar yardımcı iletilerini konuşmaya ekler Özel yürütücüler listeyi dönüştürebilir/özetleyebilir ve döndürebilir[ChatMessage] Son çıkış, son katılımcı tarafından oluşturulan konuşmadır Kullanım: from agent_framework import SequentialBuilder # With agent instances workflow = SequentialBuilder().participants([agent1, agent2, summarizer_exec]).build() # With agent factories workflow = ( SequentialBuilder().register_participants([create_agent1, create_agent2, create_summarizer_exec]).build() ) # Enable checkpoint persistence workflow = SequentialBuilder().participants([agent1, agent2]).with_checkpointing(storage).build() # Enable request info for mid-workflow feedback (pauses before each agent) workflow = SequentialBuilder().participants([agent1, agent2]).with_request_info().build() # Enable request info only for specific agents workflow = ( SequentialBuilder() .participants([agent1, agent2, agent3]) .with_request_info(agents=[agent2]) # Only pause before agent2 .build() )
SharedState	bir iş akışında paylaşılan durumu yönetmek için bir sınıf. SharedState, iş akışı yürütme sırasında yürütücüler arasında paylaşılması gereken iş akışı durumu verilerine iş parçacığı güvenli erişim sağlar. Ayrılmış Anahtarlar: Aşağıdaki anahtarlar iç çerçeve kullanımı için ayrılmıştır ve kullanıcı kodu tarafından değiştirilmemelidir: _executor_state: Denetim noktası oluşturma için yürütücü durumunu depolar (Çalıştırıcı tarafından yönetilir) Uyarı Alt çizgi (_) ile başlayan anahtarları, ayrılmış olabilecekleri için kullanmayın iç çerçeve işlemleri. Paylaşılan durumu başlatın.
SingleEdgeGroup	Grup API'sinin tekdüzen kalmasını sağlayarak tek bir kenar için kolaylık sarmalayıcı. İki yürütücü arasında bire bir kenar grubu oluşturun.
StandardMagenticManager	ChatAgent aracılığıyla gerçek LLM çağrıları gerçekleştiren standart Magentic yöneticisi. Yönetici, özgün Magentic One düzenlemesini yansıtan istemler oluşturur: Olgular toplanıyor Plan oluşturma JSON'da ilerleme defteri Sıfırlamada olgu güncelleştirmesi ve plan güncelleştirmesi Son yanıt sentezi Standart Eflatun Yöneticisi'ni başlatın.
SubWorkflowRequestMessage	Bilgi istemek için bir alt iş akışından üst iş akışındaki yürütücüye gönderilen ileti. Bu ileti, yürütücü tarafından alt iş akışında yayılan bir RequestInfoEvent sarmalar.
SubWorkflowResponseMessage	İstenen bilgileri sağlamak için bir üst iş akışından WorkflowExecutor aracılığıyla bir alt iş akışına gönderilen ileti. Bu ileti, yanıt verilerini alt iş akışı yürütücüsü tarafından yayılan özgün RequestInfoEvent ile birlikte sarmalar.
SuperStepCompletedEvent	Üst adım sona erdiğinde tetiklenen olay. Üst adım olayını başlatın.
SuperStepStartedEvent	Bir üst adım başlatıldığında tetiklenen olay. Üst adım olayını başlatın.
SwitchCaseEdgeGroup	Geleneksel anahtar/büyük/küçük harf kontrol akışını taklit eden fan-out değişkeni. Her durumda ileti yükü incelenir ve iletinin işlenip işlenmeyeceğine karar verir. Tam olarak bir büyük/küçük harf veya varsayılan dal, tek gönderim semantiğini koruyarak çalışma zamanında bir hedef döndürür. Tek bir kaynak yürütücü için bir anahtar/büyük/küçük harf yönlendirme yapısı yapılandırın.
SwitchCaseEdgeGroupCase	Anahtar durumundaki tek bir koşullu dalın kalıcı açıklaması. Çalışma zamanı Case nesnesinin aksine, bu serileştirilebilir değişken yalnızca hedef tanımlayıcıyı ve koşul için açıklayıcı bir adı depolar. Seri durumdan çıkarma sırasında temel alınan çağrılabilen kullanılabilir olmadığında, yüksek sesle başarısız olan bir ara sunucu yer tutucusunun yerini alır ve eksik bağımlılığın hemen görünür olmasını sağlarız. Koşullu servis talebi dalı için yönlendirme meta verilerini kaydedin.
SwitchCaseEdgeGroupDefault	Anahtar servis talebi grubunun geri dönüş dalı için kalıcı tanımlayıcı. Varsayılan dalın varolduğu garanti edilir ve diğer her büyük/küçük harf koşulu yükle eşleşmediğinde çağrılır. Varsayılan dalı verilen yürütücü tanımlayıcısının üzerine gelin.
TextContent	Sohbetteki metin içeriğini temsil eder. TextContent örneğini başlatır.
TextReasoningContent	Sohbetteki metin mantığı içeriğini temsil eder. Açıklamalar: Bu sınıf ve TextContent yüzeysel olarak benzer, ancak farklıdır. TextReasoningContent örneğini başlatır.
TextSpanRegion	Açıklama eklenmiş bir metin bölgesini temsil eder. TextSpanRegion'ı başlatın.
ToolMode	Bir sohbet isteğinde araçların kullanılıp kullanılmadığı ve nasıl kullanılacağını tanımlar. ToolMode'ı başlatın.
ToolProtocol	Genel bir aracı temsil eder. Bu protokol, aracı çerçevesiyle uyumlu olması için tüm araçların uygulaması gereken arabirimi tanımlar. HostedMCPTool, HostedWebSearchTool ve AIFunction gibi çeşitli araç sınıfları tarafından uygulanır. AIFunction genellikle ai_function dekoratörü tarafından oluşturulur. Her bağlayıcının araçları farklı ayrıştırması gerektiğinden, kullanıcılar soyutlama olmadığında hizmete özgü bir araç belirtmek için bir dikte geçirebilir.
TypeCompatibilityError	Bağlı yürütücüler arasında tür uyumsuzluğu algılandığında özel durum oluştu.
UriContent	URI içeriğini temsil eder. Önemli Bu, görüntü veya dosya gibi bir URI tarafından tanımlanan içerik için kullanılır. (ikili) veri URI'leri için bunun yerine DataContent kullanın. UriContent örneğini başlatır. Açıklamalar: Bu, görüntü veya dosya gibi bir URI tarafından tanımlanan içerik için kullanılır. (ikili) veri URI'leri için bunun yerine DataContent kullanın.
UsageContent	Sohbet isteği ve yanıtıyla ilişkili kullanım bilgilerini temsil eder. UsageContent örneğini başlatır.
UsageDetails	İstek/yanıtla ilgili kullanım ayrıntılarını sağlar. UsageDetails örneğini başlatır.
Workflow	Bağlı yürütücüleri düzenleyen graf tabanlı yürütme altyapısı. Genel Bakış İş akışı, Öngel benzeri bir model kullanarak uç gruplar aracılığıyla bağlanan yürütücülerin yönlendirilmiş bir grafiğini yürütür ve grafik boşta kalana kadar süpersteps içinde çalışır. İş akışları WorkflowBuilder sınıfı kullanılarak oluşturulur; bu sınıfı doğrudan başlatmayın. Yürütme Modeli Yürütücüler eşitlenmiş süpersteps içinde çalışır; burada her yürütücü: Bağlı kenar gruplarından ileti aldığında çağrılır ctx.send_message() aracılığıyla aşağı akış yürütücülerine ileti gönderebilir ctx.yield_output() aracılığıyla iş akışı düzeyinde çıkışlar verebilir ctx.add_event() aracılığıyla özel olaylar yayabilir Yürütücüler arasındaki iletiler her üst adımın sonunda teslim edilir ve olay akışında görünmez. Yalnızca iş akışı düzeyindeki olaylar (çıkışlar, özel olaylar) ve durum olayları arayanlar tarafından gözlemlenebilir. Giriş/Çıkış Türleri İş akışı türleri çalışma zamanında incelenerek bulunur: Giriş türleri: Başlat yürütücüsunun giriş türlerinden Çıkış türleri: Tüm yürütücülerin iş akışı çıkış türlerinin birleşimi Bunlara input_types ve output_types özellikleri aracılığıyla erişin. Yürütme Yöntemleri İş akışı, her birinin birden çok senaryoyu destekleyen iki birincil yürütme API'sini sağlar: run(): Tamamlanmak üzere yürüt, tüm olaylarla WorkflowRunResult döndürür run_stream(): Gerçekleşen olayları döndüren zaman uyumsuz oluşturucu döndürür Her iki yöntem de şu desteği sağlar: İlk iş akışı çalıştırmaları: İleti parametresi sağlama Denetim noktası geri yükleme: checkpoint_id sağlayın (ve isteğe bağlı olarak checkpoint_storage) HIL devamlılığı: RequestInfoExecutor isteklerinden sonra devam etmek için yanıtlar sağlayın Çalışma zamanı denetim noktası oluşturma: Bu çalıştırma için denetim noktası oluşturmayı etkinleştirmek/geçersiz kılmak için checkpoint_storage sağlayın Durum Yönetimi İş akışı örnekleri durumları içerir ve durumlar çalıştırılacak ve run_stream çağrılar arasında korunur. Birden çok bağımsız çalıştırma yürütmek için WorkflowBuilder aracılığıyla ayrı İş Akışı örnekleri oluşturun. Dış Giriş İstekleri bir iş akışı içindeki yürütücüler ctx.request_info() kullanarak dış giriş isteyebilir: Yürütücü giriş istemek için ctx.request_info() çağırır Yürütücü, yanıtı işlemek için response_handler() uygular İstekler, olay akışında RequestInfoEvent örnekleri olarak gönderilir İş akışı IDLE_WITH_PENDING_REQUESTS durumuna giriyor Çağıran istekleri işler ve send_responses veya send_responses_streaming yöntemleri aracılığıyla yanıtlar sağlar Yanıtlar istekte bulunan yürütücülere yönlendirilir ve yanıt işleyicileri çağrılır Denetim noktası oluşturma Denetim noktası oluşturma, derleme zamanında veya çalışma zamanında yapılandırılabilir: Derleme zamanı (WorkflowBuilder aracılığıyla): workflow = WorkflowBuilder().with_checkpointing(storage).build() Çalışma zamanı (run/run_stream parametreleri aracılığıyla): result = await workflow.run(message, checkpoint_storage=runtime_storage) Etkinleştirildiğinde, her üst adımın sonunda denetim noktaları oluşturulur ve yakalama: Yürütücü durumları İletiler aktarımda Paylaşılan durum İş akışları denetim noktası depolaması kullanılarak işlem yeniden başlatmaları arasında duraklatılabilir ve sürdürülebilir. Kompozisyon İş akışları, bir alt iş akışını yürütücü olarak sarmalayan WorkflowExecutor kullanılarak iç içe geçirilebilir. İç içe iş akışının giriş/çıkış türleri WorkflowExecutor'ın türlerinin bir parçası haline gelir. Çağrıldığında WorkflowExecutor, tamamlanmak için iç içe geçmiş iş akışını çalıştırır ve çıkışlarını işler. İş akışını bir kenar listesiyle başlatın.
WorkflowAgent	Bir iş akışını sarmalayan ve aracı olarak kullanıma sunan bir Aracı alt sınıfı. WorkflowAgent'ı başlatın.
WorkflowBuilder	İş akışları oluşturmak için bir oluşturucu sınıfı. Bu sınıf, yürütücüleri kenarlara bağlayarak ve yürütme parametrelerini yapılandırarak iş akışı graflarını tanımlamak için akıcı bir API sağlar. Sabit bir build örnek oluşturmak için çağrısıWorkflow. WorkflowBuilder'ı boş bir kenar listesiyle başlatın ve başlatan yürütücü yok.
WorkflowCheckpoint	İş akışı durumunun tam denetim noktasını temsil eder. Denetim noktaları belirli bir noktada iş akışının tam yürütme durumunu yakalar ve iş akışlarının duraklatılmasını ve sürdürülmesine olanak tanır. Uyarı shared_state dikte, çerçeve tarafından yönetilen ayrılmış anahtarlar içerebilir. Ayrılmış anahtarlarla ilgili ayrıntılar için bkz. SharedState sınıfı belgeleri.
WorkflowCheckpointSummary	İş akışı denetim noktasının okunabilir özeti.
WorkflowContext	Yürütücülerin iş akışları ve diğer yürütücülerle etkileşim kurmasını sağlayan yürütme bağlamı. Genel Bakış WorkflowContext, yürütücülerin ileti göndermesi, çıkış vermesi, durumu yönetmesi ve daha geniş iş akışı ekosistemiyle etkileşim kurması için denetimli bir arabirim sağlar. İç çalışma zamanı bileşenlerine doğrudan erişimi engellerken genel parametreler aracılığıyla tür güvenliğini zorlar. Tür Parametreleri Bağlam, farklı işlemler için tür güvenliğini zorunlu kılmak üzere parametrelendirilir: WorkflowContext (parametre yok) İleti göndermeden veya çıkışlar vermeden yalnızca yan etkiler gerçekleştiren yürütücüler için: async def log_handler(message: str, ctx: WorkflowContext) -> None: print(f"Received: {message}") # Only side effects WorkflowContext[T_Out] T_Out türünde iletilerin diğer yürütücülere gönderilmesini sağlar: async def processor(message: str, ctx: WorkflowContext[int]) -> None: result = len(message) await ctx.send_message(result) # Send int to downstream executors WorkflowContext[T_Out, T_W_Out] hem ileti göndermeyi (T_Out) hem de iş akışı çıkışlarını (T_W_Out) verir: async def dual_output(message: str, ctx: WorkflowContext[int, str]) -> None: await ctx.send_message(42) # Send int message await ctx.yield_output("complete") # Yield str workflow output Birleşim Türleri Birleşim gösterimi kullanılarak birden çok tür belirtilebilir: async def flexible(message: str, ctx: WorkflowContext[int | str, bool | dict]) -> None: await ctx.send_message("text") # or send 42 await ctx.yield_output(True) # or yield {"status": "done"} Yürütücü bağlamını verilen iş akışı bağlamıyla başlatın.
WorkflowErrorDetails	Hata olaylarında/sonuçlarında ortaya çıkarabilmek için yapılandırılmış hata bilgileri.
WorkflowEvent	İş akışı olayları için temel sınıf. İsteğe bağlı verilerle iş akışı olayını başlatın.
WorkflowExecutor	Hiyerarşik iş akışı oluşturmayı etkinleştirmek için bir iş akışını sarmalayan yürütücü. Genel Bakış WorkflowExecutor, bir iş akışının üst iş akışı içinde tek bir yürütücü olarak davranmasını sağlayarak iç içe geçmiş iş akışı mimarilerini etkinleştirir. Üst ve alt iş akışları arasında olay işleme, çıkış iletme ve istek/yanıt koordinasyonu dahil olmak üzere alt iş akışı yürütmenin tüm yaşam döngüsünü işler. Yürütme Modeli Çağrıldığında WorkflowExecutor: Sarmalanan iş akışını giriş iletisiyle başlatır Alt iş akışını tamamlamaya veya dış girişe ihtiyaç duyana kadar çalıştırır Yürütmeden sonra alt iş akışının tam olay akışını işler Çıkışları üst iş akışına ileti olarak iletir Dış istekleri üst iş akışına yönlendirerek işler Yanıtları biriktirir ve alt iş akışı yürütmeyi sürdürür Olay Akışı İşleme WorkflowExecutor, alt iş akışı tamamlandıktan sonra olayları işler: Çıkış İletme Alt iş akışındaki tüm çıkışlar otomatik olarak üst öğeye iletilir: allow_direct_output False olduğunda (varsayılan): # An executor in the sub-workflow yields outputs await ctx.yield_output("sub-workflow result") # WorkflowExecutor forwards to parent via ctx.send_message() # Parent receives the output as a regular message allow_direct_output Doğru olduğunda: İstek/Yanıt Koordinasyonu Alt iş akışlarının dış bilgilere ihtiyacı olduğunda: # An executor in the sub-workflow makes request request = MyDataRequest(query="user info") # WorkflowExecutor captures RequestInfoEvent and wraps it in a SubWorkflowRequestMessage # then send it to the receiving executor in parent workflow. The executor in parent workflow # can handle the request locally or forward it to an external source. # The WorkflowExecutor tracks the pending request, and implements a response handler. # When the response is received, it executes the response handler to accumulate responses # and resume the sub-workflow when all expected responses are received. # The response handler expects a SubWorkflowResponseMessage wrapping the response data. Durum Yönetimi WorkflowExecutor, istek/yanıt döngüleri arasında yürütme durumunu korur: bekleyen istekleri request_id izler Beklenen tüm yanıtlar alınana kadar yanıtları biriktirir Tam yanıt toplu işlemiyle alt iş akışı yürütmeyi sürdürür Eşzamanlı yürütmeleri ve birden çok bekleyen isteği işler Tür Sistemi Tümleştirmesi WorkflowExecutor, tür imzasını sarmalanan iş akışından devralır: Giriş Türleri Sarmalanan iş akışının başlangıç yürütücüsü giriş türleriyle eşleşir: # If sub-workflow accepts str, WorkflowExecutor accepts str workflow_executor = WorkflowExecutor(my_workflow, id="wrapper") assert workflow_executor.input_types == my_workflow.input_types Çıkış Türleri Alt iş akışı çıkışlarını istek koordinasyon türleriyle birleştirir: # Includes all sub-workflow output types # Plus SubWorkflowRequestMessage if sub-workflow can make requests output_types = workflow.output_types + [SubWorkflowRequestMessage] # if applicable Hata İşleme WorkflowExecutor, alt iş akışı hatalarını yar: Alt iş akışından WorkflowFailedEvent'i yakalar Üst bağlamda WorkflowErrorEvent'e dönüştürür Alt iş akışı kimliği de dahil olmak üzere ayrıntılı hata bilgileri sağlar Eşzamanlı Yürütme Desteği WorkflowExecutor birden çok eşzamanlı alt iş akışı yürütmeyi tam olarak destekler: Per-Execution Durum Yalıtımı Her alt iş akışı çağrısı yalıtılmış bir ExecutionContext oluşturur: # Multiple concurrent invocations are supported workflow_executor = WorkflowExecutor(my_workflow, id="concurrent_executor") # Each invocation gets its own execution context # Execution 1: processes input_1 independently # Execution 2: processes input_2 independently # No state interference between executions İstek/Yanıt Koordinasyonu Yanıtlar, kaynak yürütmeye doğru şekilde yönlendirilir: Her yürütme kendi bekleyen isteklerini ve beklenen yanıtları izler Yürütme isteği eşlemesi yanıtların doğru alt iş akışına ulaşmasını sağlar Yanıt birikmesi yürütme başına yalıtılır Yürütme tamamlandığında otomatik temizleme Bellek Yönetimi Desteklenen sınırsız eşzamanlı yürütme Her yürütmenin benzersiz UUID tabanlı kimliği vardır Tamamlanan yürütme bağlamlarını temizleme Eşzamanlı erişim için iş parçacığı güvenli durum yönetimi Önemli Noktalar Paylaşılan İş Akışı Örneği: Tüm eşzamanlı yürütmeler aynı temel iş akışı örneğini kullanır. Düzgün yalıtım için sarmalanan iş akışının ve yürütücülerinin durum bilgisi olmayan olduğundan emin olun. # Avoid: Stateful executor with instance variables class StatefulExecutor(Executor): def __init__(self): super().__init__(id="stateful") self.data = [] # This will be shared across concurrent executions! Üst İş Akışları ile Tümleştirme Üst iş akışları, alt iş akışı isteklerini kesebilir: Uygulama Notları Alt iş akışları, sonuçlarını işlemeden önce tamamlanmaya kadar çalışır Olay işleme atomiktir- tüm çıkışlar isteklerden önce iletilir Yanıt birikimi, alt iş akışlarının tam yanıt toplu işlemlerini almasını sağlar Yürütme durumu, dış isteklerden sonra düzgün bir şekilde sürdürülür Eşzamanlı yürütmeler tamamen yalıtılır ve birbiriyle karışmaz WorkflowExecutor'ı başlatın.
WorkflowFailedEvent	Bir iş akışı çalıştırması bir hatayla sonlandırıldığında yayılan yerleşik yaşam döngüsü olayı.
WorkflowOutputEvent	bir iş akışı yürütücüsü çıktıyı teslim ettiğinde tetiklenen olay. İş akışı çıkış olayını başlatın.
WorkflowRunResult	Akış dışı iş akışı yürütmesi sırasında oluşturulan olaylar için kapsayıcı. Genel Bakış Başlangıçtan boşta durumuna kadar oluşturulan tüm olayları içeren bir iş akışı çalıştırmasının tam yürütme sonuçlarını temsil eder. İş akışları, yürütme sırasında ctx.yield_output() çağrıları aracılığıyla artımlı olarak çıkış oluşturur. Olay Yapısı Veri düzlemi ve denetim düzlemi olayları arasındaki ayrımı korur: Veri düzlemi olayları: Yürütücü çağrıları, tamamlamalar, çıkışlar ve istekler (ana listede) Denetim düzlemi olayları: status_timeline() yöntemiyle erişilebilen durum zaman çizelgesi Temel Yöntemler get_outputs(): Yürütmeden tüm iş akışı çıkışlarını ayıklayın get_request_info_events(): Yürütme sırasında yapılan dış giriş isteklerini alma get_final_state(): Son iş akışı durumunu (IDLE, IDLE_WITH_PENDING_REQUESTS vb.) alma status_timeline(): Tam durum olay geçmişine erişin
WorkflowStartedEvent	Bir iş akışı çalıştırması başladığında yayılan yerleşik yaşam döngüsü olayı. İsteğe bağlı verilerle iş akışı olayını başlatın.
WorkflowStatusEvent	İş akışı çalıştırma durumu geçişleri için yayılan yerleşik yaşam döngüsü olayı. İş akışı durum olayını yeni bir durum ve isteğe bağlı verilerle başlatın.
WorkflowValidationError	İş akışı doğrulama hataları için temel özel durum.
WorkflowViz	graphviz ve Mermaid kullanarak iş akışlarını görselleştirmeye yönelik bir sınıf. WorkflowViz'i bir iş akışıyla başlatın.

Numaralandırmalar

MagenticHumanInterventionDecision	İnsan müdahalesi yanıtları için karar seçenekleri.
MagenticHumanInterventionKind	İstenen insan müdahalesi türü.
ValidationTypeEnum	İş akışı doğrulama türlerinin sabit listesi.
WorkflowEventSource	Bir iş akışı olayının çerçeveden mi yoksa yürütücüden mi geldiğini tanımlar. Yerleşik düzenleme yolları tarafından yayılan olaylar (onları oluşturan kod runner ile ilgili modüllerde yaşasa bile) ve geliştirici tarafından sağlanan yürütücü uygulamaları tarafından ortaya çıkan olaylar için YÜRÜTÜCÜ kullanın.
WorkflowRunState	İş akışı yürütmesinin çalışma düzeyi durumu. Anlambilim: BAŞLADI: Çalıştırma başlatıldı ve iş akışı bağlamı oluşturuldu. Bu, anlamlı bir çalışma gerçekleştirilmeden önceki bir başlangıç durumudur. Bu kod tabanında telemetri için ayrılmış bir WorkflowStartedEvent yayar ve genellikle durumu doğrudan IN_PROGRESS'a ilerletiriz. Tüketiciler, açık bir çalışma öncesi aşamasına ihtiyaç duyan durum makineleri için STARTED'i kullanmaya devam edebilir. IN_PROGRESS: İş akışı etkin bir şekilde yürütülüyor (örneğin, ilk ileti başlat yürütücüye teslim edildi veya bir üst adım çalışıyor). Bu durum bir çalıştırmanın başında yayılır ve çalıştırma ilerledikçe diğer durumlar tarafından takip edilebilir. IN_PROGRESS_PENDING_REQUESTS: Bir veya daha fazla bilgi için istek işlemi bekleyen durumdayken etkin yürütme. İstekler uçuştayken yeni çalışma zamanlanabilir. IDLE: İş akışı, bekleyen istekler ve yapılacak başka iş olmadan sessizdir. Bu, yürütmeyi bitirmiş, yol boyunca çıkışlar üretmiş olabilecek iş akışları için normal terminal durumudur. IDLE_WITH_PENDING_REQUESTS: dış giriş beklenildiğinde iş akışı duraklatılır (örneğin, bir RequestInfoEvent yayıldı). Bu, terminal dışı bir durumdur; yanıtlar sağlandığında iş akışı devam edebilir. BAŞARISIZ: Hatanın ortaya çıkarıldığını gösteren terminal durumu. Yapılandırılmış hata ayrıntılarıyla birlikte bir WorkflowFailedEvent eşlik eder. İptal EDİlDİ: Çalıştırmanın çağıran veya düzenleyen tarafından iptal edildiğine ilişkin terminal durumu. Şu anda varsayılan çalıştırıcı yolları tarafından gösterilmez, ancak iptali destekleyen tümleştiriciler/düzenleyiciler için dahil edilmiştir.

İşlevler

agent_middleware

Bir işlevi aracı ara yazılımı olarak işaretlemek için dekoratör.

Bu dekoratör, AgentRunContext nesnelerini işleyen aracı ara yazılımı olarak bir işlevi açıkça tanımlar.

agent_middleware(func: Callable[[AgentRunContext, Callable[[AgentRunContext], Awaitable[None]]], Awaitable[None]]) -> Callable[[AgentRunContext, Callable[[AgentRunContext], Awaitable[None]]], Awaitable[None]]

Parametreler

Name	Description
func Gerekli	Callable[[AgentRunContext, Callable[[AgentRunContext], Awaitable[None]]], Awaitable[None]] Aracı ara yazılımı olarak işaretlemek için ara yazılım işlevi.

Döndürülenler

Tür	Description
Callable[[AgentRunContext, Callable[[AgentRunContext], Awaitable[None]]], Awaitable[None]]	Aracı ara yazılım işaretçisiyle aynı işlev.

Örnekler

   from agent_framework import agent_middleware, AgentRunContext, ChatAgent


   @agent_middleware
   async def logging_middleware(context: AgentRunContext, next):
       print(f"Before: {context.agent.name}")
       await next(context)
       print(f"After: {context.result}")


   # Use with an agent
   agent = ChatAgent(chat_client=client, name="assistant", middleware=logging_middleware)

ai_function

İşlevi modellere geçirilebilen ve otomatik olarak yürütülebilen bir AIFunction'a dönüştürmek için süsleyin.

Bu dekoratör, işlevin imzasından bir Pydantic modeli oluşturur. Bu model, işleve geçirilen bağımsız değişkenleri doğrulamak ve işlevin parametreleri için JSON şemasını oluşturmak için kullanılır.

Parametrelere açıklama eklemek için, ikinci bağımsız değişken olarak dize açıklaması ile türünü Annotated kullanıntyping. Daha gelişmiş yapılandırma için Pydantic'in Field sınıfını da kullanabilirsiniz.

Uyarı

approval_mode "always_require" olarak ayarlandığında işlev yürütülmeyecek

açık onay verilene kadar, bu yalnızca otomatik çağırma akışı için geçerlidir.

Modelin birden çok işlev çağrısı döndürmesi durumunda, bazılarının onay gerektirdiğini de unutmayın

ve olmayan diğerleri, hepsi için onay isteyecektir.

ai_function(func: Callable[[...], ReturnT | Awaitable[ReturnT]] | None = None, *, name: str | None = None, description: str | None = None, approval_mode: Literal['always_require', 'never_require'] | None = None, max_invocations: int | None = None, max_invocation_exceptions: int | None = None, additional_properties: dict[str, Any] | None = None) -> AIFunction[Any, ReturnT] | Callable[[Callable[[...], ReturnT | Awaitable[ReturnT]]], AIFunction[Any, ReturnT]]

Parametreler

Name	Description
func	Callable[[...], <xref:agent_framework._tools.ReturnT> | Awaitable[<xref:agent_framework._tools.ReturnT>]] | None Süslemek için işlev. Default value: None
name Gerekli	str | None
description Gerekli	str | None
approval_mode Gerekli	Literal['always_require', 'never_require'] | None
max_invocations Gerekli	int | None
max_invocation_exceptions Gerekli	int | None
additional_properties Gerekli	dict[str, Any] | None

Yalnızca Anahtar Sözcük Parametreleri

Name	Description
name	İşlevin adı. Sağlanmazsa işlevin __name__ özniteliği kullanılır. Default value: None
description	İşlevin açıklaması. Sağlanmadıysa işlevin docstring'i kullanılır. Default value: None
approval_mode	Bu aracı çalıştırmak için onay gerekip gerekmediği. Varsayılan olarak onay gerekli değildir. Default value: None
max_invocations	Bu işlevin çağrılabileceği en fazla sayıdır. Hiçbiri ise, sınır yoktur, en az 1 olmalıdır. Default value: None
max_invocation_exceptions	Çağırmalar sırasında izin verilen en fazla özel durum sayısı. Hiçbiri ise, sınır yoktur, en az 1 olmalıdır. Default value: None
additional_properties	İşlevde ayarlanacağı ek özellikler. Default value: None

Döndürülenler

Tür	Description
AIFunction[Any, <xref:agent_framework._tools.ReturnT>] | Callable[[Callable[[…], <xref:agent_framework._tools.ReturnT> | Awaitable[<xref:agent_framework._tools.ReturnT>]]], AIFunction[Any, <xref:agent_framework._tools.ReturnT>]]

Örnekler

   from agent_framework import ai_function
   from typing import Annotated


   @ai_function
   def ai_function_example(
       arg1: Annotated[str, "The first argument"],
       arg2: Annotated[int, "The second argument"],
   ) -> str:
       # An example function that takes two arguments and returns a string.
       return f"arg1: {arg1}, arg2: {arg2}"


   # the same function but with approval required to run
   @ai_function(approval_mode="always_require")
   def ai_function_example(
       arg1: Annotated[str, "The first argument"],
       arg2: Annotated[int, "The second argument"],
   ) -> str:
       # An example function that takes two arguments and returns a string.
       return f"arg1: {arg1}, arg2: {arg2}"


   # With custom name and description
   @ai_function(name="custom_weather", description="Custom weather function")
   def another_weather_func(location: str) -> str:
       return f"Weather in {location}"


   # Async functions are also supported
   @ai_function
   async def async_get_weather(location: str) -> str:
       '''Get weather asynchronously.'''
       # Simulate async operation
       return f"Weather in {location}"

chat_middleware

Bir işlevi sohbet ara yazılımı olarak işaretlemek için dekoratör.

Bu dekoratör, ChatContext nesnelerini işleyen bir işlevi açıkça sohbet ara yazılımı olarak tanımlar.

chat_middleware(func: Callable[[ChatContext, Callable[[ChatContext], Awaitable[None]]], Awaitable[None]]) -> Callable[[ChatContext, Callable[[ChatContext], Awaitable[None]]], Awaitable[None]]

Parametreler

Name	Description
func Gerekli	Callable[[ChatContext, Callable[[ChatContext], Awaitable[None]]], Awaitable[None]] Sohbet ara yazılımı olarak işaretlemek için ara yazılım işlevi.

Döndürülenler

Tür	Description
Callable[[ChatContext, Callable[[ChatContext], Awaitable[None]]], Awaitable[None]]	Sohbet ara yazılım işaretçisiyle aynı işlev.

Örnekler

   from agent_framework import chat_middleware, ChatContext, ChatAgent


   @chat_middleware
   async def logging_middleware(context: ChatContext, next):
       print(f"Messages: {len(context.messages)}")
       await next(context)
       print(f"Response: {context.result}")


   # Use with an agent
   agent = ChatAgent(chat_client=client, name="assistant", middleware=logging_middleware)

create_edge_runner

Fabrika işlevi, bir kenar grubu için uygun kenar çalıştırıcısını oluşturur.

create_edge_runner(edge_group: EdgeGroup, executors: dict[str, Executor]) -> EdgeRunner

Parametreler

Name	Description
edge_group Gerekli	<xref:agent_framework._workflows._edge.EdgeGroup> Çalıştırıcı oluşturulacak kenar grubu.
executors Gerekli	dict[str, Executor] Yürütücü kimliklerinin yürütücü örnekleriyle eşle.

Döndürülenler

Tür	Description
<xref:agent_framework._workflows._edge_runner.EdgeRunner>	Uygun EdgeRunner örneği.

executor

Tek başına bir işlevi FunctionExecutor örneğine dönüştüren dekoratör.

Dekoratör @executoryalnızca tek başına modül düzeyinde işlevler için tasarlanmıştır. Sınıf tabanlı yürütücüler için, örnek yöntemleriyle @handler Yürütücü temel sınıfını kullanın.

Hem zaman uyumlu hem de zaman uyumsuz işlevleri destekler. Zaman uyumlu işlevler, olay döngüsünün engellenmesini önlemek için bir iş parçacığı havuzunda yürütülür.

Önemli

Tek başına işlevler (modül düzeyi veya yerel işlevler) için kullanın @executor

veya ile @executor KULLANMAYIN staticmethodclassmethod

Sınıf tabanlı yürütücüler için alt sınıf Yürütücüsü ve örnek yöntemlerinde kullanın @handler

Kullanım:

   # Standalone async function (RECOMMENDED):
   @executor(id="upper_case")
   async def to_upper(text: str, ctx: WorkflowContext[str]):
       await ctx.send_message(text.upper())


   # Standalone sync function (runs in thread pool):
   @executor
   def process_data(data: str):
       return data.upper()


   # For class-based executors, use @handler instead:
   class MyExecutor(Executor):
       def __init__(self):
           super().__init__(id="my_executor")

       @handler
       async def process(self, data: str, ctx: WorkflowContext[str]):
           await ctx.send_message(data.upper())

executor(func: Callable[[...], Any] | None = None, *, id: str | None = None) -> Callable[[Callable[[...], Any]], FunctionExecutor] | FunctionExecutor

Parametreler

Name	Description
func	Callable[[...], Any] | None Süsleme işlevi (parantez olmadan kullanıldığında) Default value: None
id Gerekli	str | None Yürütücü için isteğe bağlı özel kimlik. Hiçbiri ise işlev adını kullanır.

Yalnızca Anahtar Sözcük Parametreleri

Name	Description
id	Default value: None

Döndürülenler

Tür	Description
Callable[[Callable[[…], Any]], FunctionExecutor] | FunctionExecutor	bir İş Akışına bağlanabilen bir FunctionExecutor örneği.

Özel durumlar

Tür	Description
ValueError	veya staticmethod ile classmethod kullanılıyorsa (desteklenmeyen desen)

function_middleware

Bir işlevi işlev ara yazılımı olarak işaretlemek için dekoratör.

Bu dekoratör, bir işlevi FunctionInvocationContext nesnelerini işleyen işlev ara yazılımı olarak açıkça tanımlar.

function_middleware(func: Callable[[FunctionInvocationContext, Callable[[FunctionInvocationContext], Awaitable[None]]], Awaitable[None]]) -> Callable[[FunctionInvocationContext, Callable[[FunctionInvocationContext], Awaitable[None]]], Awaitable[None]]

Parametreler

Name	Description
func Gerekli	Callable[[FunctionInvocationContext, Callable[[FunctionInvocationContext], Awaitable[None]]], Awaitable[None]] İşlev ara yazılımı olarak işaretlemek için ara yazılım işlevi.

Döndürülenler

Tür	Description
Callable[[FunctionInvocationContext, Callable[[FunctionInvocationContext], Awaitable[None]]], Awaitable[None]]	İşlev ara yazılım işaretçisiyle aynı işlev.

Örnekler

   from agent_framework import function_middleware, FunctionInvocationContext, ChatAgent


   @function_middleware
   async def logging_middleware(context: FunctionInvocationContext, next):
       print(f"Calling: {context.function.name}")
       await next(context)
       print(f"Result: {context.result}")


   # Use with an agent
   agent = ChatAgent(chat_client=client, name="assistant", middleware=logging_middleware)

get_checkpoint_summary

get_checkpoint_summary(checkpoint: WorkflowCheckpoint) -> WorkflowCheckpointSummary

Parametreler

Name	Description
checkpoint Gerekli	WorkflowCheckpoint

Döndürülenler

Tür	Description
WorkflowCheckpointSummary

get_logger

Varsayılan olarak 'agent_framework' olarak belirtilen ada sahip bir günlükçü alın.

get_logger(name: str = 'agent_framework') -> Logger

Parametreler

Name	Description
name	str Günlükçü adı. Varsayılan olarak 'agent_framework'. Default value: "agent_framework"

Döndürülenler

Tür	Description
Logger	Yapılandırılan günlükçü örneği.

handler

Yürütücü için bir işleyici kaydetmek için dekoratör.

handler(func: Callable[[ExecutorT, Any, ContextT], Awaitable[Any]]) -> Callable[[ExecutorT, Any, ContextT], Awaitable[Any]]

Parametreler

Name	Description
func Gerekli	Callable[[<xref:agent_framework._workflows._executor.ExecutorT>, Any, <xref:agent_framework._workflows._executor.ContextT>], Awaitable[Any]] Süslemek için işlev. Parametresiz kullanıldığında Hiçbiri olabilir.

Döndürülenler

Tür	Description
Callable[[<xref:agent_framework._workflows._executor.ExecutorT>, Any, <xref:agent_framework._workflows._executor.ContextT>], Awaitable[Any]]	İşleyici meta verileriyle süslenmiş işlev.

Örnekler

@handler async def handle_string(self, message: str, ctx: WorkflowContext[str]) -> None:

...

@handler async def handle_data(self, message: dict, ctx: WorkflowContext[str | int]) -> None:

...

prepare_function_call_results

İşlev çağrısı sonuçlarının değerlerini hazırlayın.

prepare_function_call_results(content: TextContent | DataContent | TextReasoningContent | UriContent | FunctionCallContent | FunctionResultContent | ErrorContent | UsageContent | HostedFileContent | HostedVectorStoreContent | FunctionApprovalRequestContent | FunctionApprovalResponseContent | Any | list[TextContent | DataContent | TextReasoningContent | UriContent | FunctionCallContent | FunctionResultContent | ErrorContent | UsageContent | HostedFileContent | HostedVectorStoreContent | FunctionApprovalRequestContent | FunctionApprovalResponseContent | Any]) -> str

Parametreler

Name

Description

content Gerekli

TextContent | DataContent | TextReasoningContent | UriContent | FunctionCallContent | FunctionResultContent | ErrorContent | UsageContent | HostedFileContent | HostedVectorStoreContent | FunctionApprovalRequestContent | FunctionApprovalResponseContent | Any | list[TextContent | DataContent | TextReasoningContent | UriContent | FunctionCallContent | FunctionResultContent | ErrorContent | UsageContent | HostedFileContent | HostedVectorStoreContent | FunctionApprovalRequestContent | FunctionApprovalResponseContent | Any]

Döndürülenler

Tür	Description
str

prepend_agent_framework_to_user_agent

Üst bilgilerdeki User-Agent "agent-framework" öğesini ekleyin.

Ortam değişkeni aracılığıyla AGENT_FRAMEWORK_USER_AGENT_DISABLED kullanıcı aracısı telemetrisi devre dışı bırakıldığında, User-Agent üst bilgisi aracı çerçevesi bilgilerini içermez. Olduğu gibi veya Hiçbiri geçirildiğinde boş bir dikte olarak geri gönderilir.

prepend_agent_framework_to_user_agent(headers: dict[str, Any] | None = None) -> dict[str, Any]

Parametreler

Name	Description
headers	dict[str, Any] | None Varolan üst bilgi sözlüğü. Default value: None

Döndürülenler

Tür	Description
dict[str, Any]	Üst bilgiler Yok ise "User-Agent" ayarı "agent-framework-python/{version}" olarak ayarlanmış yeni bir dikte. "agent-framework-python/{version}" ile değiştirilen üst bilgi sözlüğü User-Agent'a eklenmiştir.

Örnekler

   from agent_framework import prepend_agent_framework_to_user_agent

   # Add agent-framework to new headers
   headers = prepend_agent_framework_to_user_agent()
   print(headers["User-Agent"])  # "agent-framework-python/0.1.0"

   # Prepend to existing headers
   existing = {"User-Agent": "my-app/1.0"}
   headers = prepend_agent_framework_to_user_agent(existing)
   print(headers["User-Agent"])  # "agent-framework-python/0.1.0 my-app/1.0"

response_handler

bir isteğin yanıtlarını işlemek üzere bir işleyici kaydetmek için dekoratör.

response_handler(func: Callable[[ExecutorT, Any, Any, ContextT], Awaitable[None]]) -> Callable[[ExecutorT, Any, Any, ContextT], Awaitable[None]]

Parametreler

Name	Description
func Gerekli	Callable[[<xref:agent_framework._workflows._request_info_mixin.ExecutorT>, Any, Any, <xref:agent_framework._workflows._request_info_mixin.ContextT>], Awaitable[None]] Süslemek için işlev.

Döndürülenler

Tür	Description
Callable[[<xref:agent_framework._workflows._request_info_mixin.ExecutorT>, Any, Any, <xref:agent_framework._workflows._request_info_mixin.ContextT>], Awaitable[None]]	İşleyici meta verileriyle süslenmiş işlev.

Örnekler

   @handler
   async def run(self, message: int, context: WorkflowContext[str]) -> None:
       # Example of a handler that sends a request
       ...
       # Send a request with a `CustomRequest` payload and expect a `str` response.
       await context.request_info(CustomRequest(...), str)


   @response_handler
   async def handle_response(
       self,
       original_request: CustomRequest,
       response: str,
       context: WorkflowContext[str],
   ) -> None:
       # Example of a response handler for the above request
       ...


   @response_handler
   async def handle_response(
       self,
       original_request: CustomRequest,
       response: dict,
       context: WorkflowContext[int],
   ) -> None:
       # Example of a response handler for a request expecting a dict response
       ...

setup_logging

Aracı çerçevesi için günlük yapılandırmasını ayarlayın.

setup_logging() -> None

Döndürülenler

Tür	Description
None

use_agent_middleware

Aracı sınıfına ara yazılım desteği ekleyen sınıf dekoratörü.

Bu dekoratör, herhangi bir aracı sınıfına ara yazılım işlevselliği ekler. Ara yazılım yürütmesi sağlamak için ve run() yöntemlerini sarmalarrun_stream().

Ara yazılım yürütmesi, özelliği True olarak ayarlanarak context.terminate herhangi bir noktada sonlandırılabilir. Ayarlandıktan sonra, denetim işlem hattına döner dönmez işlem hattı daha fazla ara yazılım yürütmeyi durdurur.

Uyarı

Bu dekoratör yerleşik aracı sınıflarına zaten uygulanmış. Yalnızca

özel aracı uygulamaları oluşturuyorsanız.

use_agent_middleware(agent_class: type[TAgent]) -> type[TAgent]

Parametreler

Name	Description
agent_class Gerekli	type[<xref:TAgent>] Ara yazılım desteğinin ekleneceği aracı sınıfı.

Döndürülenler

Tür	Description
type[~<xref:TAgent>]	Ara yazılım desteğine sahip değiştirilmiş aracı sınıfı.

Örnekler

   from agent_framework import use_agent_middleware


   @use_agent_middleware
   class CustomAgent:
       async def run(self, messages, **kwargs):
           # Agent implementation
           pass

       async def run_stream(self, messages, **kwargs):
           # Streaming implementation
           pass

use_chat_middleware

Bir sohbet istemci sınıfına ara yazılım desteği ekleyen sınıf dekoratörü.

Bu dekoratör, herhangi bir sohbet istemci sınıfına ara yazılım işlevselliği ekler. Ara yazılım yürütmesi sağlamak için ve get_response() yöntemlerini sarmalarget_streaming_response().

Uyarı

Bu dekoratör yerleşik sohbet istemci sınıflarına zaten uygulanmış. Yalnızca

özel sohbet istemcisi uygulamaları oluşturuyorsanız.

use_chat_middleware(chat_client_class: type[TChatClient]) -> type[TChatClient]

Parametreler

Name	Description
chat_client_class Gerekli	type[<xref:TChatClient>] Ara yazılım desteğinin ekleneceği sohbet istemci sınıfı.

Döndürülenler

Tür	Description
type[~<xref:TChatClient>]	Ara yazılım desteğine sahip değiştirilmiş sohbet istemci sınıfı.

Örnekler

   from agent_framework import use_chat_middleware


   @use_chat_middleware
   class CustomChatClient:
       async def get_response(self, messages, **kwargs):
           # Chat client implementation
           pass

       async def get_streaming_response(self, messages, **kwargs):
           # Streaming implementation
           pass

use_function_invocation

Sohbet istemcisi için araç çağırmayı etkinleştiren sınıf dekoratörü.

Bu dekoratör modelden gelen işlev çağrılarını otomatik olarak işlemek, yürütmek ve sonuçları daha fazla işlem için modele geri döndürmek için ve get_response yöntemlerini sarmalarget_streaming_response.

use_function_invocation(chat_client: type[TChatClient]) -> type[TChatClient]

Parametreler

Name	Description
chat_client Gerekli	type[<xref:TChatClient>] Süslemek için sohbet istemci sınıfı.

Döndürülenler

Tür	Description
type[~<xref:TChatClient>]	İşlev çağırmanın etkinleştirildiği dekore edilmiş sohbet istemci sınıfı.

Özel durumlar

Tür	Description
ChatClientInitializationError	Sohbet istemcisi gerekli yöntemlere sahip değilse.

Örnekler

   from agent_framework import use_function_invocation, BaseChatClient


   @use_function_invocation
   class MyCustomClient(BaseChatClient):
       async def get_response(self, messages, **kwargs):
           # Implementation here
           pass

       async def get_streaming_response(self, messages, **kwargs):
           # Implementation here
           pass


   # The client now automatically handles function calls
   client = MyCustomClient()

validate_workflow_graph

İş akışı grafiğini doğrulamak için convenience işlevi.

validate_workflow_graph(edge_groups: Sequence[EdgeGroup], executors: dict[str, Executor], start_executor: Executor) -> None

Parametreler

Name	Description
edge_groups Gerekli	Sequence[<xref:agent_framework._workflows._edge.EdgeGroup>] iş akışındaki kenar gruplarının listesi
executors Gerekli	dict[str, Executor] Yürütücü kimliklerini yürütücü örnekleriyle eşleme
start_executor Gerekli	Executor Başlangıç yürütücüsü (örnek veya kimlik olabilir)

Döndürülenler

Tür	Description
None

Özel durumlar

Tür	Description
WorkflowValidationError	Doğrulama başarısız olursa