Claude Agent SDK протык OpenAI Agents SDK протык Google ADK: адзін агент, трыя версіі
Claude Agent SDK протык OpenAI Agents SDK протык Google ADK: агент для маркірацыі паўзначэнняў праўдзівасці створаны трохце, з тым, калі кожны набор адпавядае за канкрэтныя задачы, і чым вам давялае пісаць самім.
Кожны большы выкладчык AI сэргэдзіць сяянтэкстовыя SDK для агентаў, і ўсе яны прасунуць практычна аднаковыя. Дайце нам вашы інструменты і заповедзь, і мы запускам механізм: вызовы інструментаў, структураваны выхід, сесіі і трэйсінг уключаны. Калі маркетынг такі ж аднаковы, што ж на самай справе адразняе гэтыя наборы, і на чым вам варта заснавацца?
Спосаб адкрыць гэтае — створыць той самы агент тры разы: з Claude Agent SDK ад Anthropic, з OpenAI Agents SDK і з Agent Development Kit (ADK) ад Google. Агент — гэта не іграшка. Гэта апрацоўвальнік етыкетак пахарчовых продуктав, які чытае фота, выкарыстоўвае кальку інструментаў, дае вынік і павышае свою эфектыўнасць, калі бачыць больш етыкетак. З аднім агентам і трыма SDK гэтыя разніцы ў рэзультатах апошнія адносяцца да самых SDK, а не да проблемы.
Короткая версія: усе трое практычна ўсё аб’еднваюцься ў складнай частцы – цікле аналізу, – а розходзяцца ў всім, што знаходзіцца навакола яго. Яны разлічаюцца ў спосабе задання інструмента, спосабе дадзення зображэння і тым, чы гэта дае тэкстовы выхід. Найболей значным ёсць тое, што яны разлічаюцца ў тым, чаго ніхто з іх не робіць за вас. У канцы вы зразумееце, які набор падходзіць для кожнай задачы і скількі працы застанетсяя на вас пасля выбору однаго з іх.
Ішо адна лінія супяжана з усіма трыма версіямі. Агент быў створаны, каб выучыцца на досвядзе. Ён памятае продукты, якія ўжо аналізав, і назвы добавакаў, якія ёму удалося распазнаць, і ўсё гэта зберагаецца на дыску, таму кожны наступны запуск менш паслугваецца модэлем, завершаецца быстрэй і практыкуе болей дэтэрміністычнае паведанне. Вагі модэля ніколі не зміняюцца. Саме агент накаплівае навыкі. Жадны з SDK-аў не дае гэтага з самага пачатку, што робіць яго корыстным інструментам для адгледзення таму, дзе заканчваецца готовая праграма і пачынаецца ваша саеўная праца.
Перш за ўсё, што ўважаецца агентам
Мадэль простай мовы не ўтварае агента. Яе можна спачатку уявіць як функцію, якая прымець тэкст і зярніцы і вяртае тэкст. Нічыя даны не пераходзяць між вызывамі: яна не можа выконваць код чытаць сторанку, і нават не можа зноў вызваць сябе. Калі дастаць яй етыкетку з інформацыяй пра паўжынністкі, яна скажа, як бы выконала дакладжэнне, але такога дакладжэння ніколі не выконваецца.
Агент — цэлая мадэль, якая працуе ў цікле з адпаведнымі інструментамі. Патэрн ўсё час аднаковы: вы задаеце модэлі мету і спіс інструментаў, якія яна можа выкарыстоўваць. Яна адпавядае або фінальным рэзультатам, або запітам пра выкарыстоўванне інструмента, напрыклад «знайсці E211». Калі яна запрашае інструмент, якісь чыны выконваюць яго і вяртаюць рэзультат, пасля чаго модэль зноў працуе. Цікл павтараецца, пакуль не будзе атрымана фінальная адпаведзь.
Гэты цыкл — гэта вся ідэя: мадэль прымеяе рашэнне, запускаецца інструмент, прыходзіць рэзультат, мадэль зноў прымеяе рашэнне. Наш аналізавальны прыстрой праходзіць паўтарыльна па многіх кроках: аднойчы для пошуку продукту, аднойчы для кожнага дадатку, потым для пераканання ў выборы болей здаровага варыянта, для ацэнкі якосці і для заканчальнага сінтэзу. На кожным кроцы мадэль выбірае свой наступны крок на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына на аднойчына
Зверніце ўвагу на тое, што насправды выдае мадэль: толькі „Мне хочацца вызваць check_sfa_additive з гэтымі аргументамі“. Што-то іншае павінна перэтворыць гэты бажанне на рэальны вызов функцыі і старавацца, каб усё працавало. Гэтая гэтае „што-то“ — гэта harness, і ён містыць больш складную внутрошню структуру, ніж падазроўваюць большасць людзей. Ён складаецца з трохоў слоёў. Слоў Разработка — гэта там, дзе ствараецца агент. Слоў Выконанне — гэта там, дзе агент працуе ў рэальных умовах. Слоў Контрольная плошча — гэта там, дзе керуецца цэлым флотам агентаў. Слоў Разработка ёсць тым, што запускае весь працэс, і самэ там знаходзяцца гэтыя SDK-ы.
Пачатакаеце з слоя Развіцця, дзе ствараецца адзін агент. Ён складаецца з самага цыклу (званне модэлю, выявленне запыткаў вызову інструментаў, павтарэнне пакуль не будзе завершана, безпечны выхід праз ліміт раундоў або бюджэт) і персаны, тыям самым — прапануе сістэмы, якое паведамляе модэлю, каму ён належыць і як яго дзеяць. Акола іх знаходзяцца схемы інструментаў, якія опісваюць кожны інструмент для модэлю у фармаце, які ён чакае, і выкананне інструментаў, якіе насправды запускаюць вашу функцыю, сервер MCP або вбудованыя элементы, такія як чытанне файлаў, і фіксуюць выходны рэзультат. Кліент MCP дазволяе агенту падключыцца да сервераў трэціх сторон. Калектывнае кераванне кантэкстам зберагае ход выканання, карацецца з імажынамі і адсекае часткі, калі трыбунал стане занадта дзьвігучы. Падключэнне прадаўцоў включае аўтэнтыфікацыю, канцэнтры канектаў і фарматы запыткаў для конкрэтнага прадаўцы. Крэму да гэтага існуе структураваны выхад, які прымушвае і пераканальвае фінальны адказ па адзінаковай форме, а таксама рабочыя працэсы з калькамі, якія сумяжнуюць калькі ў рэчыпе, паралельна або цыклічна.
SDK-ы спрыяюць таму, што ўсё гэта стае простым. Калі пераходзіце з выканання скрыпта да керавання сервісам, з’яўляецца шар Runtime, а разам з яным і дыялог з большым спіскам трэбаванняў. Агенту патрэбна можлівасць выканання на серверэ, тое ўзлокалена точка прыёму з ізоляцыяй сесій, якую могуць вызваць іншыя сістэмы. Ёму таксама патрэбны інструменты для канектавання, механізмы павторных спроб, таймауты і апрацоўка аутантыкацыйных дадзеных, якія забезпечваюць надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надз Дадзіце песчаныя яшчыкі для сэрвысу агента для яго сэнсабу коду чыстаінструментаў прыгледзача, стойкія цыклы, якія пры продзею працяваюць даўжэй, пачынаючы з апошньага завершанага крока, а таксама можлівасць масштабавання за дапамой канкурэнцыі і аўтамасштабавання за спінам адпаведнага канцэнтрапту.
Пад тым знаходзіцца Control Plane, які адмініструець многа агенты адночасна. Рэжыстры дазваляюць публікуваць і аднаходзіць агенты пад час выканання, замест таго каб яны былі з’яўлены ў кодзе. Кожны агент патрэбуе ідэнтыфікатора як власнай, атрыбуабельнай ентытэт у каталозе, а таксама праваў, якія ўжо ўтымачваюцца, а не проста прыпускаюцца. Пасля выканання патрэбны логі аўдыту і састаноўчаснасці, якія паказваюць, што зрабіла група агентоў, кераванне дадзеннямі ў чыненні таго, што можа быць зберажана і адкрыта ў спільнай памяці, а таксама контроль за косцамі і квотамі з бюджэтамі і лімітамі частоты. Агенты могу спілкувацца адзін з іншым праз адкрыты пратакол, такі як A2A. Паколькі выходны даныя з інструментаў прайходзяць прымусова назад у модэль, важлівыя ўмовы безпекі і захіст ад втручання, а адлікаванне паказвае, чы рашэнні правыя, а не проста чы завершылася праца. Рэжыстры для інструментаў і сервераў MCP абавязваюцца каталогізацыяй, версіяваннем, аднаходжэннем, аб’еднаннем і аутэнтыфікацыяй па кожным серверу, а шырока падтрымка версіявання дазволяе фіксавацыю, параболічны аналіз і вярнэнне да пярэдней версіі запросаў, ўнаследке чаго выкананні застаецца воспаміннае. Корача кажучы, кожны з гэтых набораў — гэта готовы комплект. Claude, OpenAI і Google забезпечваюць весь неабходны механізм: інструменты, апрацоўку кантэксту і під’язды да прадаўцоў, тады як вам застаецца напісаць самыя цікавыя часткі: вашы інструменты, вашы запросы і фармат выходных даных. ADK — гэта адзін нестандартны прыклад, хоць ён таксама выконвае тую ж задачу, таму "SDK-ы" ніжэй узагальнена паводзяцься пра ўсе тры.
У іхніх падчынных падходах розлікваецца тое, якія часткі прыстрою яны запрошваюць, насколькі кожная з іх ёсць самавпэўненай, і дзе прыстрой проста заканчываецца, а ваш код павінен прыйняць кераванне. Найчыстэйшы спосаб прыдумаць гэта ў тым, каб створыць по аднам агенту ў кожным з іх. Калі ўсе трое будуць створаныя, можна будзе практычна паказаць весь прыстрой і пазначыць, што дае кожны набор і што ён залішае вам.
Агент, які тэстуецца: дакладчык этыкетакі санітарнага харчавання
Справядлівы тэст павінен прабавіць гэтыя наборы у тых задачах, для якіх яны створаныя: гэта цыкл аналізу за дапамою калькольнікаў, пры яком кожны наступны крок залежыць ад рэзультатаў пярэдньага. Одна толькі вызов модэлю ў межах фрэймворку не будзе раслічвацца. Справжню працу выканае дакладчык. Як толькі яму пакажуць фота этыкеткі санітарнага харчавання, ён адмахваецца пяцьма задачамі.
- Ён чытае атлас за дапамою сэрбера самага модэлю, выявляючы назва продукту, пэўны спіс інгрэдыянтов і аддытываў, колькасць цукру і насыцаных жыра на 100 мл, а таксама выявляючы, чы ўтварэнне ўжо ў вялікай меры напой. Фота ёсць едыным адказным джэрэлам, так як няма базы дадзеных пра продукты, на якую можна было бы сацягнуцца.
- Для кожнага знайдзенага аддытыва, незалежна ад таго, чы на атласе пісана
E471чы «Соявая лецытын», ён абмовляецца з спісам разрэшаных аддытываў SFA з Сінгапуру і паведамляе пра статус і будзь-якія паведамленні для спожыццаўцаў. - Ён запытвае базу дадзеных HPB на сайце data.gov.sg, каб выявіць, чы продукт мае Сімвал здаровейшага выбору.
- Для напоў ён вылічвае прыбліжны ранг пашановання здаров’ю A/B/C/D на адной з аснов цукру і насыцаных жыра.
- Ён аб’еднвае усё гэта ў класыфікацыю — ЗЕЛЕНЫЙ, ЯНТАРНЫЙ чы ЧАРНЫЙ — па кожнай знаходцы, паказваючы інструмент чы атлас, які ўзяў удзел у вылічэннях, а таксама прыводзячы аргументы модэлю ў пачатку.
Ён таксама не запускаецца з нуля ў кожны раз. Ён памятае тое, што відбіваў, і выучаецца па ходу, таму і прылад, які аналізався ўчора, і назва аддытыва, якую раней было трудна з’ясаваць, будуць у наявнасці наступны раз. Аб этам больш пазней.
Такім чынам, тэстовая платформа прысвячае інструменты з мянючымся дзейсніцтваў, справжнія крыніцы дадзенаў з Сінгапура, можлівасць вводу зображэнняў, рэшэнне, якое можна пераканацца ў супермаркеце, а таксама агента, які трохі падтрымліваецца з кожнага запуску.
Забэрэжыць справядлівасць параванення
Усе, што не ўскладненая сістэма развіццы (SDK), павінна была застацца ідэнтычной. Усе тры дэманстрацыі выклікаюць аднаго проксі LiteLLM — шлюз, сумесны з OpenAI, які таксама обслугоўвае канец-пункт /v1/messages ад Anthropic для SDK Claude. Адны файл .env зберагае ключ, базовую URL і назву модэлю для кожнага з іх; модэлі – гэта Claude Sonnet 4.6, GPT-5.4 і Gemini 3.5 Flash. Спосаб, якім кожна SDK націленая на гэты проксі, дазволяе дастаць многа інфармацыі.
Кожны дэма знаходзіцца у сваём сабе uv праекце, таму вы можэце запусціць адзін з іх без установкі залежнасцяў іншых. Таблыцу дадатакаў SFA была створана аднойчы на адной з падстав — PDF-файле «permitted-additives», які публікуе агэнцыя з пытанняў ахвоты Сінгапура, і ў выніку быў створаны файл sfa_additives.json (прыблізна 540 ентры, з якіх адпаведна 270 маюць номеры E), пасля чаго яна была без змян скопіявана ў кожны праект. Апісныя зображэнні таксама былі ідэнтычныя: два рэальных продукты з Сінгапура — пакетык Milo 3in1 і коробка з молаком Marigold HL.
Тады застаецца толькі тое, што ёсць справжнім рашэннем SDK: як візначаецца інструмент, як дадаецца зображэнне, як під’еднуецца модэль, чы існуе тэкстовы выхід і як можна бачыць, што адбылося.
Парадынг пры выкарыстоўванні коду. У прыкладах ніжэй ўключаны інструмент recall_product і параметр e_number_hint. Яны апрацоўваюць даны з памяці і спрыяюць самапраграсці, пра якія пішацца далей, таму наразе можаце іх ігнараваць.
SDK Claude Agent ад Anthropic
SDK Claude Agent стоіць непасярэдна на базе Claude Code — агента, які багато людзей вядома выкорыстоўваюць у тэрмінале, і самэ гэта рашэнні вплывае на усё. Вы не складаеце ціклы з прымітываў; вы керуеце готовым, апробаваным у практыцы агентам і даёце яму свае інструменты і запіты. Вбудованыя інструменты (Read, Write, Edit, Bash, WebFetch) вялікі час вучыцца ўжо ёсць, модэль праваў і кантэкстнае адарожненне таксама ўжо рэшаныя, а вашы спецыяльныя інструменты падключаюцца праз сервер MCP, які працуе ўнутрь вашага сабе процэса. Усё працюе асінхронна за дапамогою anyio.
Тое, што вы купляеце, — гэта справжній агент для работы з камп’ютарам, готавы да вжытку. Усе, што трэба для чытання файлаў, запуску команд шэлу, рэдагавання коду або прасачвання інфармацыі, прыходзіць у фармаце, падходзячым для практычнага вжытку, вярху жаданага дня, адколі гэта тая ж самая тэхналогія, якая працуе ў Claude Code. MCP ўважаецца агентам першага класу, таму спецыяльны інструмент, які вы напісалі, будзе працаваць без змян у Claude Code, у Claude Desktop і ў вашай сабее прыкладнай програме. З усіх трох, гэты агент работае на найболей зрэлай сістэме екзекуцыі агентаў.
Косц адбіваецца ў самых інструментах, дзе вы вручную запісваеце назву, апісанне і схему:
@tool(
"check_sfa_additive",
"Check whether a food additive is permitted by the Singapore Food Agency, "
"using the full SFA permitted-additives list parsed from the official PDF. "
"Accepts an E-number ('E211') OR a name ('Sodium Benzoate', 'Soy Lecithin'). "
"If you pass a name and also know its E/INS number, set e_number_hint — an "
"unrecognised name that the hint resolves is REMEMBERED for next time.",
{"additive": str, "e_number_hint": str},
)
async def check_sfa_additive(args: dict) -> dict:
raw = args["additive"].strip()
hint = args.get("e_number_hint", "").strip()
entry = _resolve_additive(raw)
if not entry and hint:
entry = _resolve_additive(hint)
if entry: # learn: this label name -> this number, persisted to disk
num = entry["e_number"] or entry.get("ins") or ""
_MEMORY["learned_aliases"][_norm(raw)] = re.sub(r"\(.*\)", "", num).lower()
_save_memory(_MEMORY)
return _ok(_format_entry(entry, raw))
Той {arg: type} слоўнік выклікае большую колькасць запісаў, чым трэба для іншых двух набораў, пры тым не залешаючы ніякіх абмовк. Адзінкі потым выклікаюцца праз сервер MCP унутранічна, а модэль абырае іх за дапамогою прыметніка mcp__<server>__<tool>; яго неабходна памятаць пад час заповнення параметра allowed_tools:
server = create_sdk_mcp_server(
name="sg-nutrition-tools",
version="1.0.0",
tools=[recall_product, check_sfa_additive, check_hcs, calculate_nutri_grade],
)
options = ClaudeAgentOptions(
system_prompt=SYSTEM_PROMPT,
mcp_servers={"sg": server},
allowed_tools=[
"mcp__sg__recall_product",
"mcp__sg__check_sfa_additive",
"mcp__sg__check_hcs",
"mcp__sg__calculate_nutri_grade",
],
model=CLAUDE_MODEL,
permission_mode="bypassPermissions",
max_turns=20,
# Point the bundled CLI at the LiteLLM proxy's Anthropic endpoint.
env={
**os.environ,
"ANTHROPIC_BASE_URL": BASE_URL,
"ANTHROPIC_AUTH_TOKEN": API_KEY,
},
)
Зявы калічуцца такім жа спосабам, калі і іншы элементы. Не існуе параметра image=. Функцыя query() прымея асінхронны ітэрабель з слоўнікамі паведамленняў, таму вы самі ствараеце первісныя блакі контэнту, прыемліваныя Claude, — блак аб тэксты разам з блакам аб зяве:
async def message_stream():
yield {
"type": "user",
"message": {"role": "user", "content": [
{"type": "text", "text": "Investigate this nutrition label."},
{"type": "image", "source": {"type": "base64", "media_type": mime, "data": b64}},
]},
}
async with ClaudeSDKClient(options=options) as client:
await client.query(message_stream())
async for message in client.receive_response():
... # stream ToolUseBlock / TextBlock as they arrive
Актуальным рашэнем ёсць наладка працы модэля. SDK запускае ўключаны Claude Code CLI, які вікорыстоўвае фармат паведамленняў Anthropic, таму вы можэце перадаць ўсё праз проксі за дапамогою зменных сяродовыша (ANTHROPIC_BASE_URL і ANTHROPIC_AUTH_TOKEN). Не трэба перадаваць жадных об’ектаў кліента. Працоўны прынт: кожны ToolUseBlock выдруковываецца ў момент яго прыбыці, таму вы можэце жыва спазірваць, як розвіваецца кожны цыкл дадаўання інфармацыі. Ёсць прыклад работы з пакетам Milo:
sausheong claude-demo % uv run python main.py ../milo.jpeg
Investigating image: ../milo.jpeg
────────────────────────────────────────────────────────────
I'll start by reading the label carefully, then run all checks in parallel.
**Reading from the label:**
- **Product:** Nestlé MILO 3in1
- **Net weight:** 27g powder sachet (add hot water to prepare — this is a **powder, not a ready-to-drink beverage**)
- **Ingredients:** Sugar, PROTOMAL® Malt Extract (Contains Barley), Skimmed Milk (Cow's Milk), Cocoa, Palm Oil, Minerals (Dicalcium Phosphate, Disodium Phosphate, Ferric Pyrophosphate), Resistant Dextrin, Flavourings, Vitamins (C, B3, D, B6, B2, B12)
- **Identifiable additives:** Dicalcium Phosphate (E341), Disodium Phosphate (E339), Ferric Pyrophosphate; Flavourings (generic — cannot identify specific ones)
Kicking off recall + HCS check + all additive checks simultaneously:
→ tool: recall_product({'product_name': 'Nestlé MILO 3in1'})
→ tool: check_hcs({'product_name': 'MILO 3in1'})
→ tool: check_sfa_additive({'additive': 'Dicalcium Phosphate', 'e_number_hint': 'E341'})
→ tool: check_sfa_additive({'additive': 'Disodium Phosphate', 'e_number_hint': 'E339'})
→ tool: check_sfa_additive({'additive': 'Ferric Pyrophosphate', 'e_number_hint': 'E450'})
All checks returned. Note: this is a **powder**, not a ready-to-drink beverage, so Nutri-Grade (which requires per-100ml liquid values) does **not apply** — I will skip `calculate_nutri_grade`.
---
## Reasoning
**Step 1 — Product recall.** This product has been seen before. The prior verdict is consistent with what I read now — I'll treat this fresh investigation as the authoritative one and use the prior as a cross-check.
**Step 2 — Label reading.**
- MILO 3in1 is a **27g powder sachet** — you add hot water to make a drink. It is classified as a "Tonic Food Drink" on the label. Because it is sold as a dry powder (not a pre-packaged ready-to-drink liquid), Nutri-Grade per-100ml calculation does not apply.
- Nutritional values per serving (27g): Energy 110 kcal, Total Fat ~2.4g, Saturated Fat ~1.2g, Total Sugars ~13.8g (of which Added Sugars ~10g), Sodium ~38mg.
- **Sugar is the #1 ingredient** — it appears first in the ingredient list, before the malt extract.
**Step 3 — Additives.**
- **Dicalcium Phosphate (E341):** SFA-permitted ✅ — used as a mineral/calcium source.
- **Disodium Phosphate (E339):** SFA-permitted ✅ — used as an acidity regulator/mineral.
- **Ferric Pyrophosphate:** SFA-permitted ✅ — used as an iron supplement/mineral source.
- **Resistant Dextrin:** A dietary fibre ingredient (prebiotic fibre), not a regulated additive — no E number, no SFA check needed.
- **Flavourings:** Generic label — cannot identify specific flavouring compounds; SFA check not possible.
- **Vitamins (C, B3, D, B6, B2, B12):** Added as nutritional fortification, not food additives in the regulatory sense. Riboflavin (B2) carries E101 when used as a colourant, but here it's explicitly declared as a vitamin supplement — standard and expected.
**Step 4 — Healthier Choice Symbol.** HCS certified ✅ (MILO 3in1 Activ-Go appears multiple times in the HPB dataset — `check_hcs`).
**Step 5 — Sugar content reality check.** Each 27g sachet contains ~13.8g total sugars (~10g added sugars). That's more than **half the sachet's weight is sugar**, and exceeds the WHO daily added-sugar guideline of 25g in less than one cup. This is label-read, not a tool finding.
---
## Verdict
### 🟢 GREEN — No Concern
- **All three declared additives are SFA-permitted** (Dicalcium Phosphate E341, Disodium Phosphate E339, Ferric Pyrophosphate) — `check_sfa_additive` ×3.
- **Carries the Healthier Choice Symbol** — HPB has certified MILO 3in1 Activ-Go — `check_hcs`.
- **Vitamins and minerals fortified** — B2, B3, B6, B12, C, D, plus calcium and iron — label.
- **Contains barley malt extract** — a whole-grain source of energy — label.
- **Resistant Dextrin** (prebiotic dietary fibre) is a functional ingredient, not a concern — label.
### 🟡 AMBER — Worth Knowing
- **Palm Oil present** — a saturated fat source. Saturated fat is 1.2g per sachet (~4.4g per 100g of powder). Not alarming at one serving, but worth knowing if you have multiple cups a day — label.
- **"Flavourings" are not specified** — cannot determine whether natural or artificial. No SFA check was possible — label.
- **Nutri-Grade does not apply here** — this is sold as a powder. If you reconstitute it and compare the drink to ready-to-drink alternatives, it would likely land in Grade C or D territory based on sugar content, but no regulatory grade is required on the packet.
### 🔴 RED — Genuinely Concerning
- **Sugar is the #1 ingredient** — it appears first in the list, meaning it is the dominant ingredient by weight. Each sachet delivers **~13.8g total sugars / ~10g added sugars** — label. That's 40% of the WHO's recommended 25g/day added-sugar limit in a single cup. If you're drinking 2–3 sachets a day (as Nestlé's own label suggests for daily energy), you are consuming **20–30g of added sugar from MILO alone**, likely exceeding the daily limit.
- **Marketing framing vs. nutritional reality:** The packet prominently says "Nourishing Energy" and shows vitamins, but the sugar load is the dominant nutritional feature. The fortification (vitamins, minerals) does not offset this — label.
**Bottom line for a Singapore shopper:** MILO 3in1 is safe from an additives and regulatory standpoint — everything checks out with SFA and HPB. But it is a **sugar-heavy product** dressed up in health language. Treat it as an occasional treat rather than a daily nutritious breakfast drink, especially for children.
Дзе яе наследкі. Не існуе вбудованага структураванага выходу, таму вы отрымляеце тэкст і або павінаватэсе яго аналізаваць, або прымусова патрабаваеце інфармацыю пра яго форму, што ўсё большая ўпорчанасць у паўсядневнай рабоце па асоўнасці з SDK OpenAI. Схемы ствараюцца ручна, таму трэба пісаць больш і падтрымліваць сінхронізацію з кожной функцыяй. Падключэнне модэля адбываецца праз сэрвісную срэду, а проксі, які вы выбіраеце, павінен запрошваць канцэнтры з фарматам Anthropic /v1/messages, таму што сам канцэнтр, сумесны з OpenAI, недастатковы. Спрыяйце, каб спіс allowed_tools вважаліся прадзеянай згодай, а не сандбоксам: гэта значыць «праяшчыце патрабаванне на парадакт для гэтых», а не «агент можа бачыць толькі гэтыя», і тыя, хто спрыяеце гэты спіс як спісак дазволеных інструментоў, будуць здзівлены. Забудзіце пра прыметнік mcp__sg__ — інструмент проста застанеся незатверджаным, без жадных памылак. Адыяг таксама большы, калі вы запускаеце рантайм Claude Code пад капотам, а не выконваеце просты вызов API.
Выберыце яго тады, калі агенту трэба кераваць апаратам. Гэта значыць чытанне і запіс файлаў, выкананне команд шэлу, рэдагаванне кодавой базы чыста праерання — будзь-яя задача, дзе вбудованыя інструменты Claude Code захоўваюць вас ад патрэбы ствараць сэндбокс. Гэта таксама натуральны выбар, калі вы ужо выкарыстоўваеце MCP або ствараеце ўтварэнне, якое должна адчувацца як Claude Code. Цікавае ўвесь час адбываецца стрымінгавае цыкл, што ўжо прыемна для агентаў, якія працуюць дзяўно.
Выберыце гэты варыянт, калі вам трэба лёгкі цыкл вызова функцый, які вяртае структураваны об’ект, адказнае за гэта ўсё — SDK OpenAI. Выберыце іншы варыянт, калі не можэце запроцесаваць канец-пункт у фармаце Anthropic або калі важна мінімальная колькасць залежнасцей. Такая простая задача, як „звярнуцца да трохо аб’ектаў, вярнуць об’ект Pydantic“, выконваецца з значна меншым колікствам рэсурсаў.
SDK OpenAI Agents
SDK ад OpenAI — гэта лёгкі, спецыяльна падобны Python-коду абгарод наваколо ціклу, і ён цалкам прыкладзены да самага языка. Падказкі тыпаў ператвараюцца на схемы інструментаў, анотацыі на опісы інструментаў, а мадэлі Pydantic — на контракт выходных дадзеных. Нічога не прызначае структуру праекта, няма окалічнага часу выканання і няма адхылення праз MCP. Вы пішаеце функцыі і мадэлі, ствараеце Agent і перэдаеце яго Runner.run. Мета — мінімальны абстанак межа функцыяй на Python і рабочым агентам.
Ёйны ўлучшаныя можлівасці — гэта возможнасць адправкі і прыемкі дадзенняў у фармаце тэксту. Указаць output_type=YourModel, і тады будзе атрымана перакананая Python-об’ект, а не блок дадзенняў, які можна было б спачатку супадзеліць з JSON; SDK запішае запіт, распакуе адпаведны адказ, пераканае яго і, калі фармат не паспявае, вярнёцца да модэлю. Схемы, якія даўна існуюць у відгукіх на тыпы, а таксама бесплатны панель керування для трэйсінгу на власным бэкендзе OpenAI, робяць гэты спосаб самым быстрым для стварэння структураванага, спостэрагаемага агента. Калі задача — „взяць гэты вхідны дадзенне і даць мне рэзультат у фармаце тэксту“, ніякі іншы інструмент не ўсунецца так проста.
Для этых інструментоў абавесны створэння схем абсалютна не патрабуецца:
@function_tool
async def check_sfa_additive(additive: str, e_number_hint: str = "") -> str:
"""Check whether a food additive is permitted by the Singapore Food Agency.
Looks the additive up in the full SFA permitted-additives list (parsed from
the official SFA PDF). Accepts either an E-number or a plain-English name as
printed on a Singapore label.
Args:
additive: An E-number ('E211', 'e211', 'en:e211') OR an additive name
('Sodium Benzoate', 'Soy Lecithin', 'MSG').
e_number_hint: Optional. If you pass a name and also know its E/INS
number, supply it here. If the name isn't recognised but the number
is, the mapping is REMEMBERED so the name resolves directly next time. """
...
Дэкаратар чытае падказкі пра тып і раздзел Args у докстрынгу, і стварае схему JSON, таму няма нічога, што трэба падтрымваць вручную.
Найбольша практычна карысць даесяць у выходным выніку. Рашчынанне выдаецца як модэль Pydantic:
class NutritionVerdict(BaseModel):
reasoning: str # declared first: the model works out loud before committing
product_name: str
summary: str
green: list[Finding]
amber: list[Finding]
red: list[Finding]
recommendation: str
За дапамою output_type=NutritionVerdict мадэль вяртае апрацаваны об’ект, без жадных крокаў парсінгу і без дадатковых рызыкаў. Цікавы трук — ставіць reasoning першым: структураваны выхід служыць сваерадушным місцам для запісаў, таму мадэль можа «голасна» размышляць пры вырабаткі вынікаў, а вы залішаецеся з апрантным об’ектам і аргументамі разам.
Падключэнне модэлі і ввод зображэння ўсё апрантнейшыя з трох:
client = AsyncOpenAI(base_url=BASE_URL, api_key=API_KEY)
model = OpenAIChatCompletionsModel(model=OPENAI_MODEL, openai_client=client)
agent = Agent(name="SG Nutrition Investigator", model=model,
instructions=INSTRUCTIONS, output_type=NutritionVerdict,
tools=[recall_product, check_sfa_additive, check_hcs, calculate_nutri_grade])
user_input = [{"role": "user", "content": [
{"type": "input_text", "text": "Investigate this nutrition label."},
{"type": "input_image", "image_url": _data_url(image_path)}, # base64 data URL
]}]
result = await Runner.run(agent, input=user_input)
verdict: NutritionVerdict = result.final_output
Гэта кліент AsyncOpenAI, прызначаны для проксі, абгорнуты ў OpenAIChatCompletionsModel, з элементам input_image, які несе фота. Няма жадных складнасцей.
Аспекты, на якія трэба зважаць. За замовчаннем вызовы інструментаў выконваюцца паралельна, таму модэль з задоволеннем запускае калькі check_sfa_additive адразу. Нашы інструменты ўявляюць сабою асінхронныя працэсы без побачных эфектаў, што ўзято за перавагу. Інструменты, якія мутуюць спільны стан, падтрымліваюць не-рэентрантныя з’ѐеднанні або залежнаць ад парадку, будуць працаваць некорэктна, а аблыкі з’являюцца перыядычна і залежнаць ад часу — гэта найгоршы варыант. Трэба або зробіць інструменты безпечнымі для канкурэнціі, або обмежыць дзеяння модэля.
Тракарынг таксама мае сваія прыемкі. Панель керування чырвоная, але тракары прыходзяць да сэрвіса абрабаткі дадзеных самай OpenAI, і за проксі трэцьяго сторонньага адузле ключ, выданы проксі, не можа аўтэнтыфікацыявацца там. Таму вызначэнне set_tracing_disabled(True) прыводзіць да таго, што вашы найлепшыя інструменты для аналізу стану сістэмы знікаюць за адну лінію коду. За межамі api.openai.com трэба паслацца на OpenTelemetry або власныя механізмы логавання. Існуюць ўсё большыя прыемкі: за проксі патрэбен OpenAIChatCompletionsModel, калі ўжо стандартны маршрут API Responses намячае сэрвісы OpenAI, і неправы выбор прыводзіць да незрозумелых калякоў. Схема output_type должна адпавядаць правілам строгага рэжыму, таму мадэлі з глыбокай іерархіяй або большам чыслаю з’еднанняў можу спрычыніць павтарную пераверку; з гэтай прычыны Finding і NutritionVerdict застаюць простымі. І ў коробцы няма жадных адзінакоў для работы з камп’ютарам, таму няма файловай сістэмы, шэлу чыраўніцы, як толькі вы іх не дадзеце.
Ось рэзультат для пакета Milo:
sausheong openai-demo % uv run python main.py ../milo.jpeg
Investigating image: ../milo.jpeg
────────────────────────────────────────────────────────────
Product: Nestlé MILO 3 in 1 Activ-Go
Reasoning: I read the sachet as **Nestlé MILO 3 in 1 Activ-Go**. The front says “goodness of malt, milk & cocoa” and the back says “MILO Ionic Food Drink,” so this is a **powdered drink mix**, not a ready-to-drink beverage. Because it is not sold as a beverage with per-100ml nutrition for the prepared drink as consumed, I did **not** calculate Nutri-Grade; that tool is only for beverages.
I first checked whether this product had been investigated before. A prior record existed, and it broadly matched what I can read here: a sweetened powdered malt-cocoa-milk drink sachet with permitted phosphate additives, relatively high in sugar for a single sachet, and not found in the HCS database. I used that only as background and then re-read this label fresh.
From the nutrition panel, I can read:
- Serving size: **1 sachet (27g)**
- Servings per package: **1**
- Per 100g / per serving shown side by side
- **Total sugars: 50.1g per 100g; 13.8g per serving**
- **Saturated fat: 0.5g per 100g; 1.2g per serving**
This is a powder, so the relevant direct reading is per 100g, not per 100ml.
I can read the ingredient list as:
**Sugar, Protomalt™ Malt Extract (contains barley), skimmed milk/cow’s milk, cocoa, palm oil, minerals (dicalcium phosphate, disodium phosphate), fibre (pyrophosphate), resistant dextrin, flavourings, vitamins (C, B3, D, B6, B2, B12).**
For additives, I checked each identifiable additive individually where possible:
- **Dicalcium phosphate**: checked and found **permitted by SFA**. That lands in GREEN.
- **Disodium phosphate**: checked and found **permitted by SFA**. That also lands in GREEN.
- The label also contains the broader terms **“phosphates”** and **“pyrophosphate”/“fibre (pyrophosphate)”** in wording around ingredients, but the image does not clearly identify a specific additive code for the pyrophosphate entry, and the generic umbrella term “phosphates” is not reliable enough on its own. I therefore do not treat the generic term as confirmed permitted just from the broad word alone. I only rely on the specifically named phosphates I could check.
- **Flavourings** is too generic to identify a specific additive, so I could not check it individually.
- The vitamins and minerals are nutrients rather than red-flag food additives in the SFA additive sense.
I also checked for the **Healthier Choice Symbol** using the product name. It was **not found** in the HCS database.
Main nutritional takeaways from the label:
- Sugar is the **first ingredient**, which usually means it is the largest ingredient by weight.
- The product contains **50.1g sugar per 100g** powder, and **13.8g sugar per 27g sachet**. That is quite a lot for one small sachet drink.
- Saturated fat is **1.2g per sachet**, which is not extreme, but the bigger concern here is sugar.
So the overall picture is: the identifiable phosphate additives appear permitted, but nutritionally this is still a **sweetened convenience drink mix** rather than a lower-sugar everyday option.
Summary: This is a powdered MILO drink sachet, not a ready-to-drink beverage. The clearly identifiable phosphate additives on the label are permitted by SFA, but sugar is the first ingredient and the product contains 50.1g sugar per 100g, or 13.8g per 27g sachet. It was not found in the Healthier Choice Symbol database.
🟢 Dicalcium phosphate is permitted by SFA. [check_sfa_additive]
🟢 Disodium phosphate is permitted by SFA. [check_sfa_additive]
🟢 This is a powdered drink mix rather than a ready-to-drink beverage, so Nutri-Grade was not applicable here. [label]
🟡 Generic terms such as “flavourings” and the unclear “fibre (pyrophosphate)” wording are not specific enough to confirm exact additive identities from the image alone. [label]
🟡 The product was not found in the Healthier Choice Symbol database. [check_hcs]
🟡 Saturated fat is 1.2g per 27g sachet (0.5g per 100g listed on the label panel image). [label]
🔴 Sugar is the first ingredient on the label. [label]
🔴 Total sugars are 50.1g per 100g and 13.8g per 27g sachet, which is high for a small single-serve drink mix. [label]
Recommendation: Fine as an occasional sachet drink if convenience matters, but not the best everyday choice if you are trying to reduce sugar. If you drink MILO often, consider using plain MILO powder with your own milk and less sugar, or choose a lower-sugar version.
Выберыце яго, калі задача структуравана як зсерэды, так і ззовні, напрыклад, класыфікацыя, выкарыстоўванне інфармацыі, атрыбутаванне балоў чы вынесенне рашэнняў, там, дзе тэкставыя об’екты лепшыя за прозу, і калі вам патрэбен мінімальны варыянт Python. Команды, якія любяюць падказкі тыпаў, будуць задоволеныя ягою, а завдзяк бэкенду OpenAI безкоштовны трэйсінг робіць дэбаггін багатоэтапных агентаў прыемным.
Адказыце ад яго, калі вашы інструменты не можна зробіць безпечнымі для паралельнай працы, і вам не хочацца борацца з паралельным стандартным рэжымам, калі вам патрэбна можлівасць назірання, але вы знаходзіцеся за не-OpenAI шлюзам (тады трэйсінг знікае), або калі агент павінен без дадатковых налаштаванняў выкарыстоўваць інструменты файловай сістэмы і шэлу, што ёсць сферай дзеяння Claude. Для калькі агентаў, якія саўместна працуюць пад чыткым кераваннем потокамі, ADK падходзіць лепшая, і гэта ўжо трэці набор.
Google's Agent Development Kit (ADK)
З трох ягоў ADK — гэты, які практычна ўсё ж такі фрэймворк з чыста візначаным падходам, на вядзме з іншымі, якія залічваюцца простымі. Ён включае агенты, сесіі, Runner, SessionService асоцьяваныя з явнымі мульты-агентнымі праблемамі праз SequentialAgent, ParallelAgent і агенты-ціклы. Заданая структура праекта дапамагае інструментам знаходзіць ваш агент, а adk web адкрывае локальны інтэрфейс чату з інспектаром падзеяў. Інструменты — цэлаком звычныя функцыі Python, задокументаваныя у стылі Google docstrings, без дэкаратараў і слоўнікаў схем, а кэйс LiteLlm робіць яго найболей незалежным ад конкрэтных прадаўцоў варыянтом.
ADK — гэта архітэктура для сістэм, а не для скрыптавання. Калі „агент“ на самай працоўны момент означае калькольку агентаў, напрыклад планавальніка, які перадае задачы працавнікам, або последовную ланцюговую структуру, або паралельную структуру распаду, ADK прыменяе іх як складальныя элементы першага класу, чым захоўвае вас ад неабходнасці ручнага стварэння логікі керування. Сесіі ўбудованы, інтэрфейс для дэбагу ёсць найкрашчым у групе, а мадэль, незалежная ад прадаўця, не змушвае вас прыкрэпляцца да аднаго прадаўцы. Ён створаны так, каб развівацца ў складную, з станамі, багатаагентную аплікацыю.
Тут вакладзенні інструментаў ёсць найпростэйшымі:
async def check_sfa_additive(additive: str, e_number_hint: str = "") -> dict:
"""Check whether a food additive is permitted under Singapore Food Agency rules.
Looks the additive up in the full SFA permitted-additives list (parsed from
the official SFA PDF). Accepts either an E-number or a plain-English name as
printed on a Singapore label.
Args:
additive: An E-number ('E211', 'e211', 'en:e211') OR an additive name
('Sodium Benzoate', 'Soy Lecithin', 'MSG').
e_number_hint: Optional E/INS number for when you pass a name. If the
name isn't recognised but the number is, the mapping is REMEMBERED
so the name resolves directly next time.
Returns:
dict with the input, resolved e_number/name, permitted status, schedule
and any consumer note. found=False if it is not in the SFA list.
"""
...
Схема ствараецца на адказе да Google-стылю докстрынгу Args і Returns, таму яе якосць мае вялікую значымасць. Нечысты докстрынг безпасебна пагубяе выбір інструментаў для модэлю, таму докстрынг ёсць фактычным контрактом.
Каб adk web знайшоў ваш root_agent, праекту патрэбна певная структура пакетаў:
adk-demo/
sg_nutrition_investigator/
__init__.py # from . import agent
agent.py # tools + root_agent
main.py # standalone Runner + InMemorySessionService
root_agent = LlmAgent(
name="sg_nutrition_investigator",
model=LiteLlm(model="openai/" + GEMINI_MODEL, api_base=BASE_URL, api_key=API_KEY),
instruction=INSTRUCTION,
tools=[FunctionTool(recall_product), FunctionTool(check_sfa_additive),
FunctionTool(check_hcs), FunctionTool(calculate_nutri_grade)],
)
# image input — the cleanest of the three:
message = types.Content(role="user", parts=[
types.Part(text="Investigate this nutrition label."),
types.Part.from_bytes(data=Path(image_path).read_bytes(), mime_type=mime),
])
Мадэль перадаецца праз кэшэўкі LiteLlm ад ADK, дзе прыметака openai/ змагчывае LiteLlm выкорыстоўваць протакол, сумэжны з протаколам OpenAI, для звязку з проксі. Перадача зяўроў за дапамогою types.Part.from_bytes ёсць найболей эфектыўным з трох спосабаў, а adk web праставляе сабою найкрашчы вбудованы інструмент для разработкі сярод усіх расследаваных варыянтаў.
Аспекты, якія трэба врачыць. Найбольшая проблема — вага. За межам adk web пярэд тым, як будзе адправлены першыя паведамленні, неабходна наладка Runner, SessionService а таксама явных ID прыложэння, карыстальніка і сесіі; гэта вялікі працэс у пораўнанні з калькамі ліній коду, якія трэба іншым рашэнням. Канструкцыя таксама мае важлівую ролю. Лінія from . import agent у файле __init__.py ёсць спосабом, якім adk web выканалявае root_agent, і будзь-якая адхіленацыя ад гэтай структуры спаказвае працэс выканалявання. litellm стварае паведамленні пра невыкарыстоўваныя бэкенды (безнэпакойныя паведамленні пра bedrock і sagemaker, а таксама паведамленні „no module named botocore“), а ADK дадае паведамленне пра схему [EXPERIMENTAL], і ў рэзультаце як litellm, так і ADK перакрываюцься пад час імпорту. Структураваны выхід таксама ўскладнены, таму ў Gemini response_schema ёсць болей чутлівым за проксі, чым output_type у OpenAI, таму ў гэтым дэмане вікорыстоўваецца вердыкт на адповедзь на запіт. Справядліва будзе сказаць, што проксі вплывае на гэта так сама, як і ADK. Ішчо адна прымета: у варыянцы LiteLlm плюс Gemini-flash агент менш часта опісваў своіе думкі, чым іншыя, калі ў яных быў той самы запіт, што паказвае, што такое поведзенне залежыць ад модэлю і способу ўзаўмадзеяння, а не толькі ад SDK.
Выхід для Milo sachet:
sausheong adk-demo % uv run python main.py ../milo.jpeg
Investigating image: ../milo.jpeg
────────────────────────────────────────────────────────────
→ tool: recall_product({'product_name': 'Nestle MILO 3 in 1'})
→ tool: check_sfa_additive({'e_number_hint': 'E341', 'additive': 'Dicalcium Phosphate'})
→ tool: check_sfa_additive({'additive': 'Disodium Phosphate', 'e_number_hint': 'E339'})
→ tool: check_sfa_additive({'additive': 'Ferric Pyrophosphate'})
→ tool: check_hcs({'product_name': 'Nestle MILO 3 in 1'})
→ tool: calculate_nutri_grade({'saturated_fat_per_100ml': 0.5, 'sugar_per_100ml': 6.1})
## Reasoning
We investigated the label of **Nestle MILO 3 in 1 (with Activ-Go)**. Here is our step-by-step analysis:
1. **Product Categorisation & Reconstitution**:
* This is a dry beverage powder sold in single-serving 27g sachets.
* The nutritional information panel provides two columns: "Per Serving 27g" (the dry sachet) and "Per 100ml*" (as reconstituted by adding 200ml of hot water).
* For the **Singapore Nutri-Grade** system, the grading is calculated based on the beverage *as reconstituted* according to the directions.
2. **Sugar & Saturated Fat Analysis (Per 100ml prepared)**:
* **Total Sugars**: **6.1g per 100ml** (of which 4.8g is Added Sugar).
* **Saturated Fat**: **0.5g per 100ml**.
* Feeding these values into the Nutri-Grade calculator yields **Nutri-Grade C** (due to the sugar content being > 5g/100ml). Grade C beverages are classified as "less healthy" and must display the Nutri-Grade label at retail.
3. **Ingredients & Additives Analysis**:
* **Sugar is the #1 Ingredient**: Refined sugar is listed first on the ingredients list, meaning it is the largest ingredient by weight in this packet—even ahead of malt extract and milk powder.
* **Additives**:
* **Dicalcium Phosphate** (E341(ii)) and **Disodium Phosphate** (E339(ii)) are SFA-approved food additives used as stabilizers and emulsifiers.
* **Ferric Pyrophosphate** is an SFA-approved mineral nutrient used to fortify the drink with Iron.
* **Healthier Choice Symbol (HCS)**: The packet displays the red HCS logo. This is because it is formulated to be "25% lower in sugar" *compared to regular malted beverages*. However, in absolute terms, it still carries enough sugar to land in Nutri-Grade C.
---
## Verdict
### 🟢 Green Findings
* **Fortified with Vitamins & Minerals** `[label]`: Contains B-vitamins (B2, B3, B6, B12), Vitamin C, Vitamin D, Calcium, and Iron (via *Ferric Pyrophosphate* `[check_sfa_additive]`).
* **Contains Soluble Fibre** `[label]`: Features *Resistant Dextrin*, a prebiotic soluble dietary fibre (1.1g per serving) that supports gut health.
* **SFA-Approved Additives** `[check_sfa_additive]`: Phosphates used for stabilizing and emulsifying (*Dicalcium Phosphate* and *Disodium Phosphate*) are fully permitted.
* **Healthier Choice Certified** `[check_hcs]`: Carries Singapore's HCS logo for having at least 25% less sugar than standard malted chocolate drinks.
### 🟡 Amber Findings
* **Nutri-Grade C** `[calculate_nutri_grade]`: When prepared as instructed, it gets a **Grade C** because of its **6.1g of sugar per 100ml**. Grade C drinks are in the "less healthy" bracket.
* **Contains Palm Oil** `[label]`: Palm oil is added to give a rich mouthfeel, contributing **1.2g of saturated fat per serving** (0.5g/100ml).
### 🔴 Red Findings
* **Sugar is the Main Ingredient** `[label]`: Sugar is listed as the very first ingredient on the label, which means there is more plain sugar by weight than malt extract (*PROTOMALT*) or milk powder.
* **High Sugar Load per Cup** `[label]`: A single small 27g sachet contains **13.8g of total sugar** (equivalent to about **3 teaspoons of sugar**), of which **10.8g** (approx. 2.5 teaspoons) is added refined sugar. Drinking multiple cups a day can quickly max out your recommended daily limit for added sugars.
Выберыце ADK тады, калі ствараеце сістэму: з множыццю саўместна працуючых агентаў, чытрако выражанымі последовымі, паралельнымі або цыклічнымі працэсамі, справжнім станам сесіі і можлівасцю замены модэляў між прадаўцамі. Інспектар adk web практычна сам сабе пакрывае расходы пад час разработкі, а архітэктура вяртае свою пачатковую вартасць па меры розбігу праекту.
Адказіце ад яго тады, калі ёсць адзін просты агент. Код для запуску і сесіі, а таксама заданыя структуры, ўсё гэта ўскладнення, якія вы ніколі не зможаце компенсаваць. Для найшырэйшага рэзультата за лічыцоў выкорыстайце SDK OpenAI, а для агента, які выкарыстоўвае камп’ютар з вбудованымі інструментамі, — SDK Claude. ADK мае сэнс толькі у велікых масштабах, а ў меньшых случаях ён ёсць больш фрэймворкам, чым вам трэба.
Запуск дэманаў
Калі ўсе тры агенты створэны, ось як іх запускаць. Кожны з іх — гэта праект uv, і кожны з іх чытае корневы файл .env, у яком знаходзяцца ключ проксі, базовы URL і назвы трохоў модэляў:
cd openai-demo # or claude-demo, or adk-demo
uv run python main.py ../milo.jpeg
uv run python main.py ../hl.jpeg
Ёнколі павернуць таблыцу SFA з PDF, запускайце uv run --with pdfplumber python build_additives.py. Падаеце сваю фотаграфію этыкеткі, паслаўшы шлях да яе. Две этыкеткі, якія ўключаны, ўсунуткі сінгапурскія продукты і атрымуюць оцэнкі, якія і былі чаканы: млако атрымвае ранг Nutri-Grade B, а Milo, як у тваро, пасля прыготававання атрымвае ранг C.
Адхіленне ад простага працэсу
Дэман, які выкананы ў аднам працэсе, закрывае цікавыя аспекты. Тры дадаткі, ідэнтычныя па форме ў усіх SDK, робяць агентаў болей рэалістычнымі, і кожны з іх сведчыць пра SDK, які яго стварыў.
Рэальныя даны. Пераконтрольвацельны прыем не ўжо той іграшковы слоўнік з семью ступенямі. Файл build_additives.py парсуе офіцыйны PDF SFA, у яком тры табелі выкарыстоўваюць трохі разныя распакоўкі столбцоў (што сама па сабе ёсць спецыяльныяя задача), і ператварае іх у адпрыязно 540 аддытываў. Пад час запуску кожны дэман стварае нормалізаваны індэкс імен, так што абазаванне „монанатрыям глутамат“ паспраўдзяеся з формальным абазаваннем з PDF – „Monosodium L-glutamate“. Індэкс номераў E/INS, базаваны на базовым номерэ, дазволяе „500“ застаўціся такім жа, як і „500(ii)“. Короткі карточны апісак пераканае справжні слэнг, якога няма ў PDF, такі як „MSG“ і „вітамін C“. Усё, што сапраўды ня ў спісе, паказваецца як проста „нэў спісе“, а ніколі як хыбнае „дазволенае“.
Памяць і навучэнне. Што стосуецца гэтых двух аспектаў, іх лепш розглядаць разам:
- Адказаць. Кожны агент паказвае свае абясненні: у случае OpenAI — у віддзеле
reasoning, а ў Claude і ADK — у роздзеле## Reasoning. - Працавае памяць. Спачатку запускаецца інструмент
recall_product, які выклікае будзь-яе ранейшае рашэнне па там самым продукце, пры чым кожны запуск зафіксавае свае рашэнне. Калі адзін пазнак працавае два разы, другі запуск практычна перапрацоўвае ранейшыя рашэнні. - Навучэнне. Калі пазнак выдае назву, якую табліца не впішае, а мадэль прадае правільную цыфру праз
e_number_hint, пара «назва-цыфра» зберагаецца ў файлеagent_memory.json. У наступным запуске гэтае імя будзе распазнавана без падтрымкі мадэлі.
Гэта ўчэнне на рэвэлі сістэмы. Вагі ніколі не зміняюцца, пры тым як агент на адоўжэнні практыкі удосконаляе свае сабеўтары дадзеныя і інструменты. Гэта практычны, доступны ад ўчэння, на адміну ад тонкай налашоўкі, яку жадны з гэтых кітакоў не выканае пад час працы. Кожны з іх уключае власны шар сэсій, які можна выкарыстоўваць для памяці у працэсе (OpenAI’s SQLiteSession, сховішча сэсій у Claude, SessionService у ADK), а файл JSON проста дапамагае робіць дэман портатыбным і лёгкім да аналізу.
Чым большае колічэство атрыбутаў яно чытае, тым лепей стае. Фота, у яком назвы складовых модэль перакладае ў цыфры, навучае сістэму пошуку новага псевданіма, і кожны аналізаваны продукт стае чымось, што можа быць запам’ятана ў наступным запуске. Калі першы раз з’являецца «дысодны фосфат», запуск паводзіцца за модэлью, якая перакладае яго ў E339; пасля чаго дэтэрміністычная табліцы проста знае гэта, таму усё вядзецца быстрэй, дэшавае і можа выконвацца без пакрычэння модэлі. На працягу весьго раду продуктаў agent_memory.json ператвараецца на словнік псевданімаў і історыю рашэнняў, якія сам агент скомпіляваў. Калі направіць групу агентаў на адні файл спольнай памяці, то назва, якую выучыў адны агент, стане вядомаю для всіх. Модэль застаецца незменнай, а агент — ні.
Пасляплановы тычок з рэальных тэстаў: калі было патрэбна перадаць номер E з назвай, усе тры модэлі надзеямо выпалі, самыя ператворыўшы „Дысодыумфосфат“ на E339 без жадных дапамог. Гэта як раз праця ціклу — загальныя знанні пра модэлі падкрываюць тое, чаго не можа даць дэтэрміністычны пошук, а сістэма запам’ячвае рэзультат.
Хто чаго задае
Калі ўсе тры агента будуць створаны, запрацаваны і расшыраны, весь канструкт можна будзе практычна паказаць, пазначыўшы, што саме задае кожны SDK, а што павінна быць створана вручную. Уявіце сятку, дзе зелены колер означае, што SDK гэта задае, жоўты — часткова, а чырвоны — што трэба стварыць самому. Компаненты дзеляцца на тыя ж тры слоі: развіццё для стварэння агента, час адчынення для яго керавання і план керавання для керавання цэлым флотам. SDK-ы знаходзяцца ў першым слое.
Якшча паглядзеце на слой Развітчыка, то майжэ усё ў зеленом кольцы; усі кіты практычна абсалютна згодны ў пытанні стварэння агента. Але калі паглядзеце на два слоі ніжэй, то сітуацыя змінюецца: калькі зелёных чы ружовых клетак у канцах (рабочыя працэсы і ацэнка ADK, трэйсінг OpenAI) знаходзяцца на морзе чырвонага кольцы, якое ўсі тры слоі маюць. Самэй значным ўыводам яўляецца самэй гэты контраст. У стварэнні агента ўсі згодны, але кантроль яго працы і адпаведнае кераванне залішаюцца на вас.
Прасоцінкі ў SDK-ах
Слой Развітчыка – гэта тое, што SDK-ы робяць простым. Слойы Рэальнага часу і Керавання большаваючым чынам у ўсіх SDK-ах відсутны, і, на практыцы, гэта не тое, што SDK-ы мяжусяць запрошваць.
Пачніце з проблем, які з’явіліся толькі падзе дэмавайскага будавання. Аднай з іх — tool gateway, які рантайм-шар адзначае як нешто адзінаковае ад звычайнага запуску інструмента. Конфігурацыйны файл верная вызывае ваш інструмент, але нічога не робіце, каб яго працэўнасць была надзеяна. Напрыклад, API HCS з сайту data.gov.sg іноды вяртае код 503 разам з тэкстам у фармаце HTML, і простае выкарыстоўванне response.json() прыводзіце да зупінкі всіго запуску (гэтага мы научыліся на болючым дзеўянні). Дапаможнік _safe_json, таймауты на дзесяць секунд і альтэрнатыўны варыянт «не ў спіску» вырашылі гэту проблему, такім чынам нестабільны інструмент стаў простаю прычынай для аналізу, а не прыводзіць да зупінкі всіго працэсу. Перапрыбуткі, паўтарэнні запуску і фарматаванне адзяўок у самых інструментах — усё гэта на вашай адпаведальнасці, хоця самэ гэта і ёсць задачамі, якія павінен выконваць gateway.
Другій прагой ёсць управляемая памяць. Усі тры варыянты маюць шар сэсіі, які являе сабою стан кантакту на аднам узле, але гэта не тое ж самае, як прыкладкі, якія зберагаюць даныя у памяці, да якіх можа дасягнуць увесь кластэр. Файл agent_memory.json, створаны тут (засвоеныя аліясы, історыя recall_product, даныя, якія павышаюць кароткаспрэтнае мышленье агента з кожным пазначэннем), ўоснованы на логіцы домэны і знаходзіцца на верхнім роўні, таму фраза «чым больш вы яго запускаеце, тым лепш» не ўскладнюецца прыладамі для керавання. Падобнае становішча і з вікорыстаннем рэальных дадзеных: парсінг PDF-файла SFA у падметы з структурамі, колькасцю пад 540, стварэнне нормалізаванага індэкса і справачнага каталогу — нічога з гэтага не ўхоўваецца ў межах функцый SDK, а падача рэальных дадзеных агенту — гэта патэрн, які трэба самостоятэльна настроіць, а не кран, які трэба перакрыць.
Безпека канкерэнцыі для адзінакоў горшая, чым проста ўзнекананне проблем, адтуды што сама платформа стварае абліканне. По значэнню SDK OpenAI адрабатвае незалежныя вызовы адзінакоў паралельна, і ваша задача — зробіць вашы адзінакі безпечнымі ў такіх умовах. Ішчо адна звычайная дэталь: атрыманне рэшэння і яго зберэжчына ў будзь-ям месцы — гэта звычайны код прыемліка, які SDK не чыніць ніякіх змян.
Якшча адаптавацься да слоя выканання, агенту спачатку патрэбна выконанне на хосце — спосаб выклікання з чаго-небудзь, кроме сесіі тэрміналу, з можлівасцю адзіночных выконанняў і ўможлівасцю масштабавання. Йому таксама патрэбна ідэнтыфікацыя завады — аўтэнтыфікацыйныя даны, якія прадаюцца інструментам, каб вызовы выконваліся як для конкрэтной завады, а не праз ключ API, які ховаецца ў зменнай сераўіса. Кроме таго, агенту патрэбны трывалыя, можлівыя да продажы ціклы — каб падчас збою выканання можна было працаваць далей, а не пачынаць яго занова. Нічога з гэтага няма ў скрыптах на ноутбуку, і нічога з гэтага SDK не абяцвае запростаць. Слой выканання таксама павінен масштабавацься па меры зростання навантажэння.
У плане каналу керування ўсе трыя практычна нічага не рабяць. Ацэнка — гэта першы прыклад: фраза "яно запрацавало без адзінаго бяга" не значыць "яно было правым", а правільная ацэнка якосці агента здэбольшай залежыць ад вас. ADK ўжо часткова ўз’яў застосунак завдаку сваей рамкі ацэнкі, тады як два іншыя застатковы залішаюць гэты пытанне нерашаным.
Далей — захаванне ад несанкціонаваных дзеянь і захаванне ад втрымкі інструкцый. Кожны рэзултат інструмента ёсць ненадзеяным дадзеннем, якое вяртаецца да модэлю, а фота з атрыбутамі аб адпаведным адпаведзеннем API можа міць інструкцыю на кшталт "ігноравайце свае правілы". Крытычна глыбіна захавання ёсць неравнамірная, і нічога не адбываецца аўтаматычна, таму модэль абаранення застаецца у вашай адпаведальнасці.
Потым выклікаецца ідэнтыфікацыя агента з вызначэннем дапуску. Кіты дазваляюць задаць персанажа, але не адказваюць на пытанні пра статус агента як главнага элемента каталогу і пра тое, да чаго ёму дазволена доступ, таму прыўязка яго да рэальнага власніка і обмежэнне яго доступу лягае на вас.
З’яўленне на аднам серверэ MCP — гэта іншая історыя, адколькі всі трое запрошваюць для цьяго кліента. Аднак інструменты і рэжыстры MCP, які каталогізуе і версіявае інструменты, а таксама керуе скупай сервераў MCP з функціямі адкрыцця, аб’еднання, настройкі доступу для кожнага сервера і перагляду стану, зноў застаецца на вашай адпаведальнасці.
Той самы недагляд выклікаецца на аднам рэвэлі вышэй у рэжыстрэ агентаў, дзе агенты публікуюцца, каб іншыя моглі іх адкрыць і вызваць пад час выканання, а не праз жорстко заданыя настройкі. ADK ўзьмае частковае адхыленне, падтрымляючы A2A і карткі агентаў, тады як два іншыя залішаюць гэта на вашай адпаведальнасці.
Нарэшце ёсць кантроль віткоў і квот — лог аўдыту, які падтверджае, што здарылася з флотам, кантроль спільнага хранілішча дадзэнняў і шырока падтрымка версіявання. Сістэмны запрос — гэта проста строка, якая належыць вам, а мадэль ёсць стахастычной, таму фіксацыя, аналіз разніцы і вярнэнне да пярэдней версіі запросаў — гэта правіла, якія вы самі должны сабе навярнуць.
Усё гэта не ўзрада. Дастатнька будзе зупінка на цыкле агента і супаўзданых элементах, якія з’яўляюцца праз яго. Але гэта значыць, што выбір SDK рашае, можа, палову таго, што трэба для продакшн-агента.
Тады які SDK вам следуе выбраць?
Ёсць кілька слоў пра самыя кіты: Claude Agent SDK падходзіць тады, калі агент павінен кераваць камп’ютарам, працаваць з файламі, шэлем, кодам і веб-серфінгам; гэта найболей розвіты варыант, які праглытае грошы за допамогу ручных схем, не падтрымлівае тыпаванага выходу і налаштавання зменных сераўніка. OpenAI Agents SDK падходзіць для структураванага вводу і выходу з мінімальным вікорыстоўванням Python; ён забезпечвае найшырэйшы цыкл ввод-выход з тыпаванымі дадзеннямі, пры тым што трэба ўрахоўваць стандартны вікорыстоўвання паралельных інструментоў і відсутнасць возможнасці трэйсінгу за проксі. Google ADK падходзіць, калі калькі агентоў должны саўместна працаваць за дапамогай чыста вызначаных рабочых пралэцэсаў, падтрымліваных справжнімі сесіямі; яго інтэрфейс для распрацоўшчыкаў ёсць наймоцнейшым, а выбор модэляў — найшырэйшым, хоць просты агент сам будзе адчуваць яго важар.
Парадоксальна гэта розніца: гэта разныя інструменты, а не тры варыянты аднаго прыладу. У всіх іх можа быць аднаковы агент, калі толькі ядро, цікл выканання задач з вікорыстаннем інструментаў, застаецца спакойным. Разніця крыўціцца ў дадатковых элементах, якія ўтвараюць „каркас“ навакола гэтага ядра, і самэ гэта павінна вабіць вашы выбор.
Што паказала тройная розработка
Тройная розработка агента дала ясны вывад: цікл агента — гэта ужо рашаная, стандартызаваная проблема, і всі тры наборы яе рэшаюць эфектыва. Рэальныя разніцы крыўціцца ў дадатковых элементах: ручна напісаныя чы розрахаваныя схемы, вольны тэкст чы введзены выхід, а таксама ў тым, чы ёсць ўсе разам у аднам пакеце, чы гэта лёгкі кліент чы цэлы фрэймворк. Гэтыя пытанні стосуюцца падходжання, а не якосці. Падберыце SDK, які падходзіць для вашай задачы — будзь то Claude для керавання камп’ютарам, OpenAI для введзенага выхідна масы чы ADK для багатаагентных сістэм — і будзь-кой з гэтых трох будзе вам корыстны.
Важным урокам являюць межы, а трыя шары паказваюць, дзе яны знаходзяцца. У комплектах ёсць шар Развітчыка, і ён даецца вам за адзін дзень. Шары Работы і Кантролю, тое есць кераванне рэальным агентам і управлінне флотам, належаць вам, і самэўсюды тут і знаходзіцца большая частка інжынерных зусіль. Аналізавацель стаў корыстным толькі пасля дадання таго, чаго не прадае жадны SDK: апрацаванай табелі SFA для базавання, інструмента для карыстоўвання пад час аптакоўкаў, які зазвычай належыць гэтаму інструменту, а таксама памяці, якая павышае яго эфектыўнасць з кожным пазначэннем. Таму выберыце SDK за ўзмоўкам да шара Развітчыка, а потым запланаваце бюджэт на два шары, якія знаходзяцца ніжэй.
За гэтым матэрыялам крыўцяюць большыя історыі, якія знаходзяцца ў ніжэйшых слоях. Калі стварэнне агентаў адзінам чалавекам стала звычайной практыкай, конкурэнція перасунулася на рэвалюцыю ў тым, хто керуе агентамі і хто іх рэгулюе. Там формуюцца новыя продукты: асяроддзя выканання, такія як AWS Bedrock AgentCore і Google's Gemini Enterprise Agent Runtime, якія можуць падтрымляць все, што ствараецца за дапамой трохох набораў, а таксама сістэмы керування, як Microsoft's Agent 365 і Google Enterprise, якія рэўіструюць, ідэнтыфікуюць і контролююць цэлыя флоты агентаў. Яны продаюць, практычна слоўна, элементы гэтай сеткі. Проблема заключаецца у тым, што кожны хмарны сервіс хочаць усіх трохох слоёў, таму SDK, які вы выберазе сёння, завтра будзе спрыяць вам у выборы асяроддзя выканання і сістэмы керування ад адного з постаўчыкаў.
Спадневанае чытанне
- Стварэнне самакорэктуючых агентаў з LangGraph: пяць практычных парад — Створыце агента для пошуку на базе LangGraph, які перазначае спробы пасля неудачы, з падтрымкай стану, умовнымі рэшткамі, функцыяй перазбірання стану, парадзеннем чалавека і адгукамі, а таксама з поясненням малых вузлаў за дапамою працуючага коду.
- 10 фрэймворкаў агентаў AI, якія трэба ведаць у 2026 годзе: LangGraph, CrewAI і іншыя — Дзесяць фрэймворкаў агентаў, сортаваных па спосабе ўзаінтэграцыі агентаў, з аналізам плюсоў і мінусоў, найбольш прыдатных сцэнарыяў і парадамі па выбору прыдатнага фрэймворка для вашай команды.