ورودی و خروجی هر مدلی، فهرستی از چهار نوع پیام است؛ و
content_blocksمحتوای هر ارائهدهندهای را در قالب بلوکهای تایپشدهی یکسان میخواند.
ایجنت خود را از یک ارائهدهنده به ارائهدهندهای دیگر منتقل میکنید و ناگهان کدی که متن استدلال مدل را میخواند از کار میافتد. یک ارائهدهنده آن را در بلوک thinking میگذارد و دیگری در بلوک reasoning. هر دو در واقع همان content یک AIMessage هستند، اما در دو قالب متفاوت.
در پایان این بخش، میتوانید انواع پیامها را بسازید و فراخوانی ابزار را از یک AIMessage بخوانید. همچنین میتوانید محتوا را از طریق بلوکهای استانداردی بخوانید که میان ارائهدهندههای مختلف یکسان میمانند.
چهار نوع پیام
پیام (Message): یک مدخل در گفتوگو، شامل یک نوع، یک content و یک id اختیاری.
پیام SystemMessage حاوی دستورالعملهاست، HumanMessage نوبت گفتوگوی کاربر را نگه میدارد، AIMessage خروجی مدل را در بر دارد و ToolMessage نتیجهی ابزار را ذخیره میکند. این هم یک نمونه گفتوگو در قالب دیکشنری:
{
"type": "HumanMessage",
"content": "What is 2 + 3?"
},
{
"type": "AIMessage",
"content": "",
"tool_calls": [
{
"name": "add",
"args": {
"a": 2,
"b": 3
},
"id": "call_1",
"type": "tool_call"
}
]
},
{
"type": "ToolMessage",
"content": "5",
"name": "add",
"tool_call_id": "call_1",
"status": "success"
},
{
"type": "AIMessage",
"content": "The sum is 5.",
"usage_metadata": {
"input_tokens": 12,
"output_tokens": 6,
"total_tokens": 18
}
}بخش نخست فایل. پیام SystemMessage بریده شده است.
فراخوانی ابزار (Tool call): یک مدخل در AIMessage.tool_calls شامل name، آرگومانهای پارسشده (args) و یک id. پیام ToolMessage متناظری که به آن پاسخ میدهد، همین شناسه را در tool_call_id خود دارد.
پیام AIMessage که درخواست ابزار دارد، content خالی دارد. درخواست آن در tool_calls قرار میگیرد که از متن JSON ارائهدهنده پارس شده است. فیلد usage_metadata نیز تعداد توکنها را در صورت گزارش ارائهدهنده ذخیره میکند. شکل جایگاه هر فیلد را نشان میدهد.
میتوانید دیکشنریها و تاپلهای ساده را هم پاس بدهید. create_agent و تمام مدلهای چت، ساختار {"role": "user", "content": "hi"} را به HumanMessage و ("assistant", "hello") را به AIMessage تبدیل میکنند:
{
"type": "HumanMessage",
"content": "hi"
},
{
"type": "AIMessage",
"content": "hello"
},
{
"type": "SystemMessage",
"content": "be brief"
}بلوکهای محتوا
بلوک محتوا (Content block): بخشی تایپشده از یک پیام؛ دیکشنری با یک type مانند text، reasoning، image، file یا tool_call.
مستندات میگویند که هر پیامی یک ویژگی content_blocks دارد که هنگام خواندن، content را به بلوکهای تایپشدهی استاندارد پارس میکند {{docs oss/python/langchain/messages}}. در همان صفحه آمده است که بلوکهای محتوا به content اضافه میشوند و جایگزین آن نمیشوند {{docs oss/python/langchain/messages}}. بنابراین content ساختار ارائهدهنده را حفظ میکند و content_blocks شکل استاندارد را در اختیارتان میگذارد.
کیت، یک AIMessage با ساختار محتوایی Anthropic میسازد: یک بلوک thinking با امضا (signature)، و سپس یک بلوک متنی. ویژگی content_blocks آن را به صورت بلوکهای استاندارد میخواند:
{
"type": "reasoning",
"reasoning": "Add the numbers.",
"extras": {
"signature": "sig"
}
},
{
"type": "text",
"text": "The sum is 5."
}
]
.text -> 'The sum is 5.'بلوک thinking به reasoning تبدیل شد و فیلد ارائهدهنده که نام استانداردی نداشت به extras رفت. ویژگی .text بلوکهای متنی را در قالب یک رشته به هم پیوند میدهد. این ویژگی در نسخهی پینشده یک property است. کدهایی که متد .text() را صدا میزنند همچنان کار میکنند، اما اخطار میدهند.
در یک AIMessage که حاوی فراخوانی ابزار و محتوای خالی است، content_blocks برای هر فراخوانی یک بلوک tool_call دارد. بنابراین با یک حلقه روی content_blocks، متن، استدلال و فراخوانیهای ابزار را به ترتیب وقوع میخوانید.
ورودی چندوجهی
یک HumanMessage میتواند فهرستی از بلوکهای استاندارد را در content نگه دارد. کیت یک بلوک متنی، یک تصویر با URL و یک PDF به صورت base64 ارسال میکند:
{
"type": "text",
"text": "Describe this image."
},
{
"type": "image",
"url": "https://example.com/cat.png"
},
{
"type": "file",
"base64": "JVBERi0=",
"mime_type": "application/pdf"
}لیست content پیام.
پکیج هر ارائهدهنده، این بلوکها را به فرمت درخواست خودش تبدیل میکند. مشخصات مدل (model profile) مشخص میکند که مدل چه ورودیهایی مانند image_inputs و pdf_inputs را میپذیرد. بخش 3.2 نمونهای از این مشخصات را نشان میدهد.
تکهها
تکه (Chunk): بخشی از یک پیام که مدل به صورت جریانی ارسال میکند، مانند AIMessageChunk. تکهها با عملگر + به یک پیام تبدیل میشوند.
فراخوانیهای ابزار هم تکهتکه استریم میشوند. هر tool_call_chunk تکهای از آرگومانها را در قالب متن نگه میدارد. وقتی تکهها با هم جمع میشوند، این بخشها به هم پیوند میخورند و فراخوانی پارسشده در tool_calls ظاهر میشود:
{
"tool_call_chunks": [
{
"name": "add",
"args": "{\"a\": 2, \"b\": 3}",
"id": "call_1",
"index": 0,
"type": "tool_call_chunk"
}
],
"tool_calls": [
{
"name": "add",
"args": {
"a": 2,
"b": 3
},
"id": "call_1",
"type": "tool_call"
}
]
}نسخهی 1.7.0 از langchain-core نحوهی گزارش آرگومانهای فراخوانی ابزار را در حین دریافت استریم تغییر داد. بخش 5 رویدادهای استریم مربوط به این نسخهی پینشده را نشان میدهد.
هرس کردن پیامها
تابع trim_messages پیامهای انتهایی را تا جایی که در سهمیهی توکن جا شوند نگه میدارد. با max_tokens=3 و شمارندهای که برای هر پیام یک واحد میشمارد، پیام سیستمی و دو پیام آخر حفظ شدند. با start_on="human" فقط پیام سیستمی باقی ماند، چون هیچ برشی از پیامهای حفظشده با پیام کاربر شروع نمیشد:
the same with start_on='human':
[
{
"type": "SystemMessage",
"content": "You are terse."
}
]نتیجهی اول با یک ToolMessage شروع میشود که AIMessage متناظر آن حذف شده است. بیشتر ارائهدهندهها نتیجهی ابزاری را که فراخوانیِ آن نباشد رد میکنند. بنابراین پیامها را در مرز نوبت گفتوگو هرس کنید و خروجی هرس را بسنجید.
منابع: capture/out/02-messages.txt، capture/out/06-agent-run.txt؛ docs.langchain.com در docs commit 04d4d4a (بخشهای oss/python/langchain/messages، oss/python/releases/changelog)؛ libs/core/langchain_core/messages در langchain==1.5.0.