[{"data":1,"prerenderedAt":875},["ShallowReactive",2],{"navigation_docs":3,"-guide-agents":72,"-guide-agents-surround":870},[4,40],{"title":5,"path":6,"stem":7,"children":8,"icon":39},"Guide","\u002Fguide","1.guide\u002F1.index",[9,11,15,19,23,27,31,35],{"title":10,"path":6,"stem":7},"Getting Started",{"title":12,"path":13,"stem":14},"PURLs","\u002Fguide\u002Fpurl","1.guide\u002F2.purl",{"title":16,"path":17,"stem":18},"Lookups","\u002Fguide\u002Flookups","1.guide\u002F3.lookups",{"title":20,"path":21,"stem":22},"Caching","\u002Fguide\u002Fcache","1.guide\u002F4.cache",{"title":24,"path":25,"stem":26},"CLI","\u002Fguide\u002Fcli","1.guide\u002F5.cli",{"title":28,"path":29,"stem":30},"Agents","\u002Fguide\u002Fagents","1.guide\u002F6.agents",{"title":32,"path":33,"stem":34},"Custom Registries","\u002Fguide\u002Fcustom","1.guide\u002F7.custom",{"title":36,"path":37,"stem":38},"Explorer","\u002Fguide\u002Fexplorer","1.guide\u002F8.explorer","i-lucide-book-open",{"title":41,"path":42,"stem":43,"children":44,"icon":71},"Registries","\u002Fregistries","2.registries\u002F0.index",[45,47,51,55,59,63,67],{"title":46,"path":42,"stem":43},"Overview",{"title":48,"path":49,"stem":50},"npm","\u002Fregistries\u002Fnpm","2.registries\u002F01.npm",{"title":52,"path":53,"stem":54},"crates.io","\u002Fregistries\u002Fcargo","2.registries\u002F02.cargo",{"title":56,"path":57,"stem":58},"PyPI","\u002Fregistries\u002Fpypi","2.registries\u002F03.pypi",{"title":60,"path":61,"stem":62},"RubyGems","\u002Fregistries\u002Frubygems","2.registries\u002F04.rubygems",{"title":64,"path":65,"stem":66},"Packagist","\u002Fregistries\u002Fpackagist","2.registries\u002F05.packagist",{"title":68,"path":69,"stem":70},"Arch Linux","\u002Fregistries\u002Falpm","2.registries\u002F06.alpm","i-lucide-library",{"id":73,"title":28,"body":74,"description":863,"extension":864,"links":865,"meta":866,"navigation":158,"path":29,"seo":868,"stem":30,"__hash__":869},"docs\u002F1.guide\u002F6.agents.md",{"type":75,"value":76,"toc":856},"minimark",[77,82,249,264,376,379,383,406,413,417,441,445,454,462,466,473,845,852],[78,79,81],"h2",{"id":80},"one-tool-five-operations","One tool, five operations",[83,84,89],"pre",{"className":85,"code":86,"language":87,"meta":88,"style":88},"language-ts shiki shiki-themes github-light github-light poimandres","import { generateText } from \"ai\";\nimport { packageTool } from \"@agntn\u002Fregistries\u002Fai\";\n\nconst { text } = await generateText({\n  model: yourModel,\n  tools: { packageRegistry: packageTool },\n  prompt: \"What is the latest version of pkg:npm\u002Flodash and who maintains it?\",\n});\n","ts","",[90,91,92,130,153,160,190,206,226,243],"code",{"__ignoreMap":88},[93,94,97,101,105,109,112,116,120,124,127],"span",{"class":95,"line":96},"line",1,[93,98,100],{"class":99},"sP0CR","import",[93,102,104],{"class":103},"sKlNE"," {",[93,106,108],{"class":107},"snHMy"," generateText",[93,110,111],{"class":103}," }",[93,113,115],{"class":114},"stCPd"," from",[93,117,119],{"class":118},"scVjq"," \"",[93,121,123],{"class":122},"sQ7BG","ai",[93,125,126],{"class":118},"\"",[93,128,129],{"class":103},";\n",[93,131,133,135,137,140,142,144,146,149,151],{"class":95,"line":132},2,[93,134,100],{"class":99},[93,136,104],{"class":103},[93,138,139],{"class":107}," packageTool",[93,141,111],{"class":103},[93,143,115],{"class":114},[93,145,119],{"class":118},[93,147,148],{"class":122},"@agntn\u002Fregistries\u002Fai",[93,150,126],{"class":118},[93,152,129],{"class":103},[93,154,156],{"class":95,"line":155},3,[93,157,159],{"emptyLinePlaceholder":158},true,"\n",[93,161,163,167,170,174,177,180,184,187],{"class":95,"line":162},4,[93,164,166],{"class":165},"s1TYA","const",[93,168,169],{"class":103}," { ",[93,171,173],{"class":172},"saoiD","text",[93,175,176],{"class":103}," } ",[93,178,179],{"class":165},"=",[93,181,183],{"class":182},"sZW6a"," await",[93,185,108],{"class":186},"sULi6",[93,188,189],{"class":103},"({\n",[93,191,193,196,199,203],{"class":95,"line":192},5,[93,194,195],{"class":107},"  model",[93,197,198],{"class":103},":",[93,200,202],{"class":201},"spVlQ"," yourModel",[93,204,205],{"class":103},",\n",[93,207,209,212,214,216,219,221,223],{"class":95,"line":208},6,[93,210,211],{"class":107},"  tools",[93,213,198],{"class":103},[93,215,104],{"class":103},[93,217,218],{"class":107}," packageRegistry",[93,220,198],{"class":103},[93,222,139],{"class":201},[93,224,225],{"class":103}," },\n",[93,227,229,232,234,236,239,241],{"class":95,"line":228},7,[93,230,231],{"class":107},"  prompt",[93,233,198],{"class":103},[93,235,119],{"class":118},[93,237,238],{"class":122},"What is the latest version of pkg:npm\u002Flodash and who maintains it?",[93,240,126],{"class":118},[93,242,205],{"class":103},[93,244,246],{"class":95,"line":245},8,[93,247,248],{"class":103},"});\n",[250,251,252,255,256,259,260,263],"p",{},[90,253,254],{},"packageTool"," is a ",[90,257,258],{},"tool()"," from the AI SDK, ready to hand to a model, with a discriminated input schema. The model picks an ",[90,261,262],{},"operation"," and the tool routes it to the matching helper:",[265,266,267,284],"table",{},[268,269,270],"thead",{},[271,272,273,278,281],"tr",{},[274,275,276],"th",{},[90,277,262],{},[274,279,280],{},"Input",[274,282,283],{},"Returns",[285,286,287,305,321,338,354],"tbody",{},[271,288,289,295,300],{},[290,291,292],"td",{},[90,293,294],{},"package",[290,296,297],{},[90,298,299],{},"purl",[290,301,302],{},[90,303,304],{},"Package",[271,306,307,312,316],{},[290,308,309],{},[90,310,311],{},"versions",[290,313,314],{},[90,315,299],{},[290,317,318],{},[90,319,320],{},"Version[]",[271,322,323,328,333],{},[290,324,325],{},[90,326,327],{},"dependencies",[290,329,330,332],{},[90,331,299],{}," with a version",[290,334,335],{},[90,336,337],{},"Dependency[]",[271,339,340,345,349],{},[290,341,342],{},[90,343,344],{},"maintainers",[290,346,347],{},[90,348,299],{},[290,350,351],{},[90,352,353],{},"Maintainer[]",[271,355,356,361,370],{},[290,357,358],{},[90,359,360],{},"bulk-packages",[290,362,363,366,367],{},[90,364,365],{},"purls",", 1 to 50, optional ",[90,368,369],{},"concurrency",[290,371,372,375],{},[90,373,374],{},"Record\u003Cstring, Package>"," keyed by PURL, failed ones absent",[250,377,378],{},"The AI SDK's abort signal is passed through to every registry call, so cancelling the generation cancels the HTTP request.",[78,380,382],{"id":381},"install-the-peers","Install the peers",[83,384,388],{"className":385,"code":386,"language":387,"meta":88,"style":88},"language-bash shiki shiki-themes github-light github-light poimandres","pnpm add ai zod\n","bash",[90,389,390],{"__ignoreMap":88},[93,391,392,396,400,403],{"class":95,"line":96},[93,393,395],{"class":394},"sseY5","pnpm",[93,397,399],{"class":398},"sX7Zv"," add",[93,401,402],{"class":398}," ai",[93,404,405],{"class":398}," zod\n",[250,407,408,409,412],{},"Both are optional peer dependencies. The main entry never imports them; only the ",[90,410,411],{},"\u002Fai"," subpath does.",[78,414,416],{"id":415},"the-schema-in-words","The schema, in words",[250,418,419,420,422,423,426,427,430,431,434,435,437,438,440],{},"The model sees one description and five input shapes. Each ",[90,421,299],{}," field carries an example in its description (",[90,424,425],{},"pkg:npm\u002Flodash or pkg:cargo\u002Fserde","; ",[90,428,429],{},"pkg:pypi\u002Fflask@3.1.1"," for dependencies), which is what keeps a model from sending ",[90,432,433],{},"lodash"," on its own. ",[90,436,365],{}," is capped at fifty and ",[90,439,369],{}," at fifty.",[78,442,444],{"id":443},"what-the-answer-is","What the answer is",[250,446,447,448,453],{},"The tool returns the normalized objects, not prose. A model summarizing them should say what the registry said; the ",[449,450,452],"a",{"href":451},"\u002Flookup","Lookup"," explorer shows the same objects for any PURL, which is a quick way to check a summary against the source.",[455,456,457,458,461],"caution",{},"Descriptions, keywords and maintainer names are published by whoever owns the package. They are data to report, not instructions to follow. An agent that reads ",[90,459,460],{},"description: \"ignore previous instructions\""," has learned one thing about the package, and nothing about what to do next.",[78,463,465],{"id":464},"rolling-your-own","Rolling your own",[250,467,468,469,472],{},"The tool is thin by design. If your framework is not the AI SDK, the same five operations are one ",[90,470,471],{},"switch"," over the helpers:",[83,474,476],{"className":85,"code":475,"language":87,"meta":88,"style":88},"import {\n  bulkFetchPackages,\n  fetchDependenciesFromPURL,\n  fetchMaintainersFromPURL,\n  fetchPackageFromPURL,\n  fetchVersionsFromPURL,\n} from \"@agntn\u002Fregistries\";\n\nexport async function run(input: { operation: string; purl?: string; purls?: string[] }, signal?: AbortSignal) {\n  switch (input.operation) {\n    case \"package\":\n      return fetchPackageFromPURL(input.purl!, signal);\n    case \"versions\":\n      return fetchVersionsFromPURL(input.purl!, signal);\n    case \"dependencies\":\n      return fetchDependenciesFromPURL(input.purl!, signal);\n    case \"maintainers\":\n      return fetchMaintainersFromPURL(input.purl!, signal);\n    case \"bulk-packages\":\n      return Object.fromEntries(await bulkFetchPackages(input.purls!, { signal }));\n  }\n}\n",[90,477,478,485,492,499,506,513,520,536,540,608,626,641,669,682,706,719,743,756,780,793,833,839],{"__ignoreMap":88},[93,479,480,482],{"class":95,"line":96},[93,481,100],{"class":99},[93,483,484],{"class":103}," {\n",[93,486,487,490],{"class":95,"line":132},[93,488,489],{"class":107},"  bulkFetchPackages",[93,491,205],{"class":103},[93,493,494,497],{"class":95,"line":155},[93,495,496],{"class":107},"  fetchDependenciesFromPURL",[93,498,205],{"class":103},[93,500,501,504],{"class":95,"line":162},[93,502,503],{"class":107},"  fetchMaintainersFromPURL",[93,505,205],{"class":103},[93,507,508,511],{"class":95,"line":192},[93,509,510],{"class":107},"  fetchPackageFromPURL",[93,512,205],{"class":103},[93,514,515,518],{"class":95,"line":208},[93,516,517],{"class":107},"  fetchVersionsFromPURL",[93,519,205],{"class":103},[93,521,522,525,527,529,532,534],{"class":95,"line":228},[93,523,524],{"class":103},"}",[93,526,115],{"class":114},[93,528,119],{"class":118},[93,530,531],{"class":122},"@agntn\u002Fregistries",[93,533,126],{"class":118},[93,535,129],{"class":103},[93,537,538],{"class":95,"line":245},[93,539,159],{"emptyLinePlaceholder":158},[93,541,543,546,549,552,556,559,563,565,567,570,572,576,578,580,583,585,587,589,591,593,596,599,601,605],{"class":95,"line":542},9,[93,544,545],{"class":99},"export",[93,547,548],{"class":99}," async",[93,550,551],{"class":165}," function",[93,553,555],{"class":554},"scZRh"," run",[93,557,558],{"class":103},"(",[93,560,562],{"class":561},"s1jWp","input",[93,564,198],{"class":165},[93,566,169],{"class":103},[93,568,262],{"class":569},"s0VbO",[93,571,198],{"class":165},[93,573,575],{"class":574},"s8yaW"," string",[93,577,426],{"class":103},[93,579,299],{"class":569},[93,581,582],{"class":165},"?:",[93,584,575],{"class":574},[93,586,426],{"class":103},[93,588,365],{"class":569},[93,590,582],{"class":165},[93,592,575],{"class":574},[93,594,595],{"class":103},"[] }, ",[93,597,598],{"class":561},"signal",[93,600,582],{"class":165},[93,602,604],{"class":603},"sCrqT"," AbortSignal",[93,606,607],{"class":103},") {\n",[93,609,611,614,617,619,622,624],{"class":95,"line":610},10,[93,612,613],{"class":114},"  switch",[93,615,616],{"class":103}," (",[93,618,562],{"class":201},[93,620,621],{"class":103},".",[93,623,262],{"class":201},[93,625,607],{"class":103},[93,627,629,632,634,636,638],{"class":95,"line":628},11,[93,630,631],{"class":114},"    case",[93,633,119],{"class":118},[93,635,294],{"class":122},[93,637,126],{"class":118},[93,639,640],{"class":103},":\n",[93,642,644,647,650,652,654,656,658,661,664,666],{"class":95,"line":643},12,[93,645,646],{"class":182},"      return",[93,648,649],{"class":186}," fetchPackageFromPURL",[93,651,558],{"class":103},[93,653,562],{"class":201},[93,655,621],{"class":103},[93,657,299],{"class":201},[93,659,660],{"class":165},"!",[93,662,663],{"class":103},", ",[93,665,598],{"class":201},[93,667,668],{"class":103},");\n",[93,670,672,674,676,678,680],{"class":95,"line":671},13,[93,673,631],{"class":114},[93,675,119],{"class":118},[93,677,311],{"class":122},[93,679,126],{"class":118},[93,681,640],{"class":103},[93,683,685,687,690,692,694,696,698,700,702,704],{"class":95,"line":684},14,[93,686,646],{"class":182},[93,688,689],{"class":186}," fetchVersionsFromPURL",[93,691,558],{"class":103},[93,693,562],{"class":201},[93,695,621],{"class":103},[93,697,299],{"class":201},[93,699,660],{"class":165},[93,701,663],{"class":103},[93,703,598],{"class":201},[93,705,668],{"class":103},[93,707,709,711,713,715,717],{"class":95,"line":708},15,[93,710,631],{"class":114},[93,712,119],{"class":118},[93,714,327],{"class":122},[93,716,126],{"class":118},[93,718,640],{"class":103},[93,720,722,724,727,729,731,733,735,737,739,741],{"class":95,"line":721},16,[93,723,646],{"class":182},[93,725,726],{"class":186}," fetchDependenciesFromPURL",[93,728,558],{"class":103},[93,730,562],{"class":201},[93,732,621],{"class":103},[93,734,299],{"class":201},[93,736,660],{"class":165},[93,738,663],{"class":103},[93,740,598],{"class":201},[93,742,668],{"class":103},[93,744,746,748,750,752,754],{"class":95,"line":745},17,[93,747,631],{"class":114},[93,749,119],{"class":118},[93,751,344],{"class":122},[93,753,126],{"class":118},[93,755,640],{"class":103},[93,757,759,761,764,766,768,770,772,774,776,778],{"class":95,"line":758},18,[93,760,646],{"class":182},[93,762,763],{"class":186}," fetchMaintainersFromPURL",[93,765,558],{"class":103},[93,767,562],{"class":201},[93,769,621],{"class":103},[93,771,299],{"class":201},[93,773,660],{"class":165},[93,775,663],{"class":103},[93,777,598],{"class":201},[93,779,668],{"class":103},[93,781,783,785,787,789,791],{"class":95,"line":782},19,[93,784,631],{"class":114},[93,786,119],{"class":118},[93,788,360],{"class":122},[93,790,126],{"class":118},[93,792,640],{"class":103},[93,794,796,798,801,803,806,808,811,814,816,818,820,822,824,827,830],{"class":95,"line":795},20,[93,797,646],{"class":182},[93,799,800],{"class":201}," Object",[93,802,621],{"class":103},[93,804,805],{"class":186},"fromEntries",[93,807,558],{"class":103},[93,809,810],{"class":182},"await",[93,812,813],{"class":186}," bulkFetchPackages",[93,815,558],{"class":103},[93,817,562],{"class":201},[93,819,621],{"class":103},[93,821,365],{"class":201},[93,823,660],{"class":165},[93,825,826],{"class":103},", {",[93,828,829],{"class":201}," signal",[93,831,832],{"class":103}," }));\n",[93,834,836],{"class":95,"line":835},21,[93,837,838],{"class":103},"  }\n",[93,840,842],{"class":95,"line":841},22,[93,843,844],{"class":103},"}\n",[250,846,847,848,851],{},"Wrap the registry in ",[90,849,850],{},"createCached"," first if the agent will ask about the same packages more than once.",[853,854,855],"style",{},"html pre.shiki code .sP0CR, html code.shiki .sP0CR{--shiki-light:#D73A49;--shiki-default:#D73A49;--shiki-dark:#5DE4C7}html pre.shiki code .sKlNE, html code.shiki .sKlNE{--shiki-light:#24292E;--shiki-default:#24292E;--shiki-dark:#A6ACCD}html pre.shiki code .snHMy, html code.shiki .snHMy{--shiki-light:#24292E;--shiki-default:#24292E;--shiki-dark:#ADD7FF}html pre.shiki code .stCPd, html code.shiki .stCPd{--shiki-light:#D73A49;--shiki-default:#D73A49;--shiki-dark:#A6ACCD}html pre.shiki code .scVjq, html code.shiki .scVjq{--shiki-light:#032F62;--shiki-default:#032F62;--shiki-dark:#A6ACCD}html pre.shiki code .sQ7BG, html code.shiki .sQ7BG{--shiki-light:#032F62;--shiki-default:#032F62;--shiki-dark:#5DE4C7}html pre.shiki code .s1TYA, html code.shiki .s1TYA{--shiki-light:#D73A49;--shiki-default:#D73A49;--shiki-dark:#91B4D5}html pre.shiki code .saoiD, html code.shiki .saoiD{--shiki-light:#005CC5;--shiki-default:#005CC5;--shiki-dark:#E4F0FB}html pre.shiki code .sZW6a, html code.shiki .sZW6a{--shiki-light:#D73A49;--shiki-default:#D73A49;--shiki-dark:#5DE4C7C0}html pre.shiki code .sULi6, html code.shiki .sULi6{--shiki-light:#6F42C1;--shiki-default:#6F42C1;--shiki-dark:#E4F0FBD0}html pre.shiki code .spVlQ, html code.shiki .spVlQ{--shiki-light:#24292E;--shiki-default:#24292E;--shiki-dark:#E4F0FB}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sseY5, html code.shiki .sseY5{--shiki-light:#6F42C1;--shiki-default:#6F42C1;--shiki-dark:#91B4D5}html pre.shiki code .sX7Zv, html code.shiki .sX7Zv{--shiki-light:#032F62;--shiki-default:#032F62;--shiki-dark:#ADD7FF}html pre.shiki code .scZRh, html code.shiki .scZRh{--shiki-light:#6F42C1;--shiki-default:#6F42C1;--shiki-dark:#ADD7FF}html pre.shiki code .s1jWp, html code.shiki .s1jWp{--shiki-light:#E36209;--shiki-default:#E36209;--shiki-dark:#E4F0FB}html pre.shiki code .s0VbO, html code.shiki .s0VbO{--shiki-light:#E36209;--shiki-default:#E36209;--shiki-dark:#A6ACCD}html pre.shiki code .s8yaW, html code.shiki .s8yaW{--shiki-light:#005CC5;--shiki-default:#005CC5;--shiki-dark:#A6ACCDC0}html pre.shiki code .sCrqT, html code.shiki .sCrqT{--shiki-light:#6F42C1;--shiki-default:#6F42C1;--shiki-dark:#A6ACCDC0}",{"title":88,"searchDepth":132,"depth":132,"links":857},[858,859,860,861,862],{"id":80,"depth":132,"text":81},{"id":381,"depth":132,"text":382},{"id":415,"depth":132,"text":416},{"id":443,"depth":132,"text":444},{"id":464,"depth":132,"text":465},"The Vercel AI SDK tool on the \u002Fai subpath, its five operations, and what an agent should and should not do with the answer.","md",null,{"icon":867},"i-lucide-bot",{"title":28,"description":863},"3V-R_Aab6TwB0cLSefD8lHGALjSE1bIFHMhk_gI9H3g",[871,873],{"title":24,"path":25,"stem":26,"description":872,"children":-1},"The registries command, its four lookups, the cache subcommands, and the flags.",{"title":32,"path":33,"stem":34,"description":874,"children":-1},"Extend the base class, map the registry's API onto the shared types, register the ecosystem, and every helper picks it up.",1788462724332]