Sambaza na Ulinde Mawakala wa AI kwa AI Agent Gateway

AI Agent Gateway ni Nini?

AI Agent Gateway ni huduma ya chanzo huria inayopatikana kati ya mawakala wa AI na mifumo wanayoita. Inatoa sehemu moja ya kuingilia iliyo na uthibitishaji na ufuatiliaji kwa seva za zana za MCP na watoa huduma wa LLM wanaotumika, wakiwemo Anthropic Claude, AWS Bedrock, OpenAI, na Gemini.

Badala ya kunakili vitambulisho vya zana na mipangilio ya watoa huduma kwenye kila wakala, unaweza kudhibiti uthibitishaji, siri, sera za ufikiaji, na kumbukumbu za maombi katikati. Gateway inasambazwa kama faili moja la binary na inajumuisha dashibodi ya usimamizi iliyojengewa ndani.

Huduma hii ina wasikilizaji watatu:

• Safu ya MCP kwenye port 8080: Hupokea maombi ya MCP kutoka kwa mawakala na kusambaza shughuli zinazoruhusiwa kwa seva za zana zilizosajiliwa.
• Safu ya udhibiti kwenye port 8081: Huendesha API ya REST na dashibodi ya usimamizi.
• Safu ya LLM kwenye port 8082: Hufanya proksi ya maombi ya LLM yanayotumika na kurekodi maelezo ya matumizi.

PostgreSQL inahitajika. Hifadhi ya vipindi inayooana na Redis ni ya hiari na huruhusu safu ya MCP kuendeshwa kwa nakala zaidi ya moja; usambazaji uliounganishwa hutumia Valkey. ClickHouse ni ya hiari na huwezesha vipengele vya ziada vya uchanganuzi.

Vipengele Muhimu

• Uthibitishaji kwa kila ombi: Vifunguo vya API vinavyotolewa na Gateway huwekewa mipaka kwa mpangaji na jukumu.
• Vitambulisho vilivyolindwa vya viunganishi: Vitambulisho huhifadhiwa katika hifadhi ya siri iliyosimbwa na kuingizwa kwenye maombi ya MCP yanayotoka bila kumfichuliwa mwitaji.
• Sera za zana mahususi kwa wakala: Profaili zinaweza kuzuia zana ambazo wakala anaweza kutumia. Vizuizi hutekelezwa wakati wa tools/call, si wakati wa kuorodhesha zana pekee.
• Vidokezo na rasilimali: Gateway hupitisha vidokezo na rasilimali za nyuma kupitia nafasi ya majina iliyoshirikiwa na kutumia sera zilezile za profaili.
• Ujuzi na amri: Profaili zinaweza kujumuisha maandishi ya marejeleo yanayoweza kutumika tena na violezo vya vidokezo vinavyowasilishwa kupitia mbinu asilia za MCP.
• Proksi ya LLM ya watoa huduma wengi: Safu ya LLM inatumia Anthropic, Bedrock, OpenAI, na Gemini huku ikirekodi matumizi ya tokeni na gharama inayokadiriwa.
• Ufuatiliaji wa kati: Dashibodi hutoa kumbukumbu za ufikiaji, kumbukumbu za LLM, ratiba za vipindi, na dashibodi ya uchanganuzi wakati hifadhi inayohitajika imewezeshwa.
• Ulinzi wa maombi yanayotoka: Maeneo ya ndani, loopback, link-local, na maeneo mengine ya faragha huzuiwa kwa chaguo-msingi ili kupunguza hatari za kughushi maombi ya upande wa seva.

Mahitaji ya Awali

Usanidi wa haraka zaidi hutumia Docker Compose. Kabla ya kuanza, sakinisha au thibitisha yafuatayo:

• Docker yenye programu-jalizi ya Compose, kama vile Docker Desktop, Colima, au Docker Engine.
• curl kwa ukaguzi wa afya na jq kwa kuchakata majibu ya API.
• Porti za ndani 8080, 8081, na 8082 ziwe huru.
• Port 8090 ikiwa utawezesha profaili ya uchanganuzi na huduma yake ya Adminer.
• Angalau GB 4 za nafasi huru ya Docker, au GB 8 unapoongeza uchanganuzi wa ClickHouse.

macOS na Linux zinatumika. Windows inaweza kutumiwa kupitia WSL2, ingawa mazingira hayo bado hayajafanyiwa majaribio.

Ili kujenga nje ya Docker, hazina inahitaji Go 1.27, Node.js 26 kwa dashibodi, na make. Baadhi ya mifano ya utekelezaji pia huhitaji npx, Python, kind, kubectl, au ufunguo wa API wa mtoa huduma.

Sakinisha na Anzisha Gateway

1. Nakili hazina

git clone https://github.com/Tuskira/ai-agent-gateway.git
cd ai-agent-gateway

2. Anzisha stack ya kawaida ya Compose

docker compose -f deploy/docker-compose.yml up --build -d

Uanzishaji wa kwanza unaweza kuchukua muda kwa sababu Docker lazima ijenge au ipakue vipengele vinavyohitajika na ianzishe hifadhidata.

3. Subiri safu ya udhibiti

until curl -sf localhost:8081/api/v1/health >/dev/null; do sleep 1; done

Mzunguko huu husubiri hadi sehemu ya afya ya safu ya udhibiti ijibu kwa mafanikio.

4. Kagua safu zote tatu

curl localhost:8080/health
curl localhost:8081/api/v1/health
curl localhost:8082/health

Majibu yenye mafanikio yanathibitisha kuwa wasikilizaji wa MCP, udhibiti, na LLM wanapatikana.

Anzisha Ufikiaji wa Usimamizi

Usambazaji mpya hauna watumiaji wa dashibodi wala ufunguo wa API. Anza kwa kuunda mpangaji chaguo-msingi na ufunguo wa API wa msimamizi:

docker compose -f deploy/docker-compose.yml exec gateway /gateway bootstrap-key

Amri hii huchapisha ufunguo wa API mara moja tu. Uuhifadhi kwa usalama kwa sababu mchakato wa kuanza hutumia kuandikisha viunganishi na kutekeleza shughuli za kiutawala za API.

Kisha, unda mtumiaji wa kwanza wa dashibodi:

docker compose -f deploy/docker-compose.yml exec gateway /gateway create-user -tenant default -username admin -role admin

Amri hii huchapisha nenosiri la muda la matumizi ya mara moja. Fungua http://localhost:8081, ingia kama admin, na ubadilishe nenosiri la muda utakapoombwa.

Kwa kawaida programu zinapaswa kuthibitisha kwa kutumia funguo za API. Dashibodi pia inaweza kukubali ufunguo wa API kama njia ya dharura ya ziada.

Matumizi ya Msingi: Ongeza na Ita Seva ya MCP

Katika istilahi za Gateway, seva ya zana ya MCP ni kiunganishi katika API na MCP katika dashibodi. Baada ya kuingia, fungua MCPs → Catalog ili kuona seva za MCP zilizo tayari ambazo zinaweza kuongezwa.

Mchakato wa kawaida wa matumizi ya kwanza ni:

1. Tengeneza na uhifadhi ufunguo wa API wa msimamizi.
2. Sajili seva ya MCP kama kiunganishi.
3. Sanidi kitambulisho chochote kinachohitajika na kiunganishi.
4. Tengeneza au chagua wasifu wa wakala.
5. Fanya zana za kiunganishi zipatikane kwa wasifu huo.
6. Itishe zana iliyoruhusiwa kupitia msikilizaji wa MCP wa lango kwenye porti 8080.
7. Kagua itisho hilo katika kiweko cha usimamizi.

Hazina ina mwongozo kamili unaotekelezeka chini ya examples/01-quickstart. Huanzisha mrundikano, huthibitisha nyuso zote tatu, huanzisha ufunguo wa msimamizi, husajili seva ya mfano ya MCP, na huita mojawapo ya zana zake. Fuata mwongozo wa kuanza kwa maombi kamili ya usajili wa kiunganishi na kuita zana.

Ili kuendesha mifano yote isiyohitaji vitambulisho vya nje, tumia:

make examples-smoke

Jinsi Wasifu wa Mawakala Unavyotekeleza Ufikiaji

Wasifu hufafanua zana, vidokezo, rasilimali, ujuzi na amri zinazopatikana kwa wakala. Vikwazo vya zana hukaguliwa wakala anapoitisha tools/call, kwa hiyo kuficha zana kutoka tools/list si hatua pekee ya utekelezaji wa udhibiti.

Kwa utekelezaji thabiti zaidi wa sera, funga ufunguo wa API kwenye wasifu. Bila ufungaji huo, mpigaji anaweza kutambua wasifu anaoutaka kupitia kichwa cha X-Agent-Profile-Name. Ufungaji wa ufunguo kwa wasifu humzuia mpigaji kuchagua kwa uhuru wasifu mwingine.

Seva kadhaa za MCP zinapowasilisha vidokezo au rasilimali, lango huzihifadhi katika nafasi ya majina ya pamoja. Vidokezo hupewa sifa kwa jina la kiunganishi chake, huku rasilimali zikitumia URI zinazosimamiwa na lango. Sheria zilezile za wasifu huamua maingizo ambayo wakala anaweza kufikia.

Tumia Wakala wa LLM

Nyuso ya LLM hutoa njia ya kati ya kufikia watoa huduma wa miundo wanaoungwa mkono: Anthropic, AWS Bedrock, OpenAI na Gemini. Hii huruhusu programu za mawakala kutuma trafiki ya miundo kupitia sehemu ileile inayodhibitiwa inayotumiwa na zana.

Kwa kila itisho linalopitishwa kwa wakala, lango linaweza kurekodi matumizi ya tokeni na kukadiria gharama. Usanidi wa mtoa huduma, usanidi wa kutumia ufunguo wako mwenyewe, hali za vitambulisho vya Bedrock, njia, mipangilio ya kunasa na mwenendo wa gharama umeandikwa katika mwongozo wa nyuso ya LLM.

Tumia kituo cha afya kuthibitisha msikilizaji kabla ya kusanidi mteja:

curl localhost:8082/health

Washa Takwimu za Uchanganuzi

Usambazaji wa kawaida unaunga mkono kumbukumbu za LLM bila ClickHouse. Ili kuongeza dashibodi ya Muhtasari, Kumbukumbu za Ufikiaji, Ratiba ya Kipindi na uchanganuzi unaotumia ClickHouse, anzisha Compose kwa wasifu wa analytics:

GATEWAY_SINKS_CLICKHOUSE_ENABLED=true docker compose -f deploy/docker-compose.yml --profile analytics up --build -d

Usanidi huu unahitaji rasilimali zaidi za ndani na unaweza kutumia porti 8090.

Linda Miili Nyeti ya Maombi

Mrundikano wa onyesho huhifadhi miili ya maombi na majibu ya LLM katika PostgreSQL, ikiwa imewekewa kikomo cha MiB 1 kila mmoja. Ukiwa na wasifu wa uchanganuzi, pia huhifadhi miili ya maombi na majibu ya LLM na MCP katika ClickHouse ili iweze kuonyeshwa kwenye kiweko. Miili hii haichapishwi kwenye kumbukumbu za kontena.

Iwapo vidokezo, majibu ya miundo au mizigo ya zana vinaweza kuwa na taarifa nyeti, zima kabisa uhifadhi wa miili:

GATEWAY_LLM_PROXY_CAPTURE_STORE_BODIES=false GATEWAY_CAPTURE_STORE_BODIES=false docker compose -f deploy/docker-compose.yml up --build -d

Kagua nyaraka za uonekano kabla ya kutumia vipengele vya kunasa kwenye data ya uzalishaji.

Unganisha kwa Usalama kwenye Seva za MCP za Ndani au za Kibinafsi

Lango huzuia kwa chaguo-msingi maeneo lengwa ya loopback, ya kibinafsi, ya kiungo cha ndani na maeneo mengine ya ndani. Pia huzuia kabisa anwani ya metadata ya wingu 169.254.169.254. Sera hii huzuia kiunganishi, ingizo la katalogi au lengwa la modeli kufikia kwa siri huduma nyeti kwenye seva pangishi au mtandao.

Jina la seva linapotatua tu kuwa anwani zilizozuiwa linapoundwa, lango hulikataa kwa 400 egress_blocked. Jina la seva ambalo bado halitatui linaweza kukubaliwa, lakini hukaguliwa tena lango linapojaribu kuunganisha.

Kuendesha jozi moja kwa moja

Unapoendesha kwa make run, ruhusu loopback waziwazi ikiwa seva ya MCP inaendesha kwenye mashine hiyo hiyo:

GATEWAY_EGRESS_ALLOWED_CIDRS=127.0.0.0/8,::1/128 make run

Kutumia mrundikano wa Compose uliotolewa

Usanidi wa Compose uliojumuishwa tayari unaruhusu host.docker.internal na CIDR za loopback. Kwa hiyo seva inayoendesha kwenye kompyuta yako ya mkononi inaweza kufikiwa kupitia host.docker.internal. Ondoa ruhusa hizi katika mazingira yanayoshirikiwa isipokuwa zinahitajika.

Kutumia Kubernetes au mitandao ya kibinafsi

Kwa huduma ya Kubernetes iliyo ndani ya klasta, ruhusu jina la DNS linaloitwa pekee, kwa mfano:

GATEWAY_EGRESS_ALLOWED_HOSTS=my-mcp-server.my-ns.svc

Vinginevyo unaweza kuruhusu CIDR husika ya podi au huduma. Kwa seva zinazopatikana kupitia VPN pekee au mitandao ya kibinafsi, ongeza jina mahususi la seva au CIDR finyu badala ya kuwezesha kila anuwai ya anwani za kibinafsi.

Weka orodha za ruhusa za trafiki inayotoka zikiwa finyu iwezekanavyo. Usizime ulinzi huo kwa madhumuni ya kurahisisha majaribio ya awali.

Vidokezo vya Juu vya Uendeshaji

• Tenganisha ufikiaji wa binadamu na programu: Tumia akaunti za kiweko kwa wasimamizi na funguo za API zinazotolewa na lango kwa mawakala na otomatiki.
• Fungamanisha funguo na wasifu: Ufunguo uliofungamanishwa na wasifu hutoa uhakikisho thabiti zaidi kuliko kuruhusu wapigaji kuchagua wasifu kwa kichwa cha ombi.
• Hifadhi vitambulisho kwenye lango: Sanidi vitambulisho vya viunganishi katikati ili mawakala wasipokee siri zinazotumika msingi.
• Badilisha vitambulisho vya viunganishi mara kwa mara: Tumia vipengele vya usimamizi wa viunganishi na vitambulisho badala ya kusasisha kila wakala mmoja mmoja.
• Dhibiti kunasa data: Amua ikiwa miili ya ombi na jibu inapaswa kuhifadhiwa kabla ya kuchakata vidokezo vya siri au matokeo ya zana.
• Jipange kwa nakala nyingi: Sanidi hifadhi ya hiari ya vipindi inayotumia itifaki ya Redis unapopanua safu ya MCP zaidi ya nakala moja.
• Tumia sheria finyu za egress: Ruhusu wapangishi au CIDR binafsi badala ya safu pana za faragha.
• Rejelea mifano iliyofafanuliwa: Mifano binafsi inashughulikia hali za ziada na kuorodhesha zana au funguo za wauzaji zinazohitajika katika faili zao za README.
• Tarajia mabadiliko: Mradi huu ni programu ya alpha ya kabla ya 1.0, kwa hivyo API na usanidi vinaweza kubadilika kati ya matoleo madogo.

Kuunda Nje ya Docker

Kwa ajili ya uundaji wa ndani, sakinisha Go 1.27, Node.js 26, na make. Hifadhi hii inatoa mtiririko wa kazi wa make build na make run. Zana za hiari za uundaji na utoaji zinajumuisha golangci-lint, govulncheck, na goreleaser.

Kwa kanuni za uundaji, amri za majaribio, mwongozo wa maombi ya kuvuta, na sehemu za upanuzi za hifadhi, sinks, na watoa huduma, tazama mwongozo wa kuchangia.

Hitimisho

AI Agent Gateway huweka pamoja ufikiaji wa zana za MCP na watoa huduma wengi wa LLM nyuma ya vituo vilivyo na uthibitishaji. Utekelezaji wake wa wasifu, uingizaji wa vitambulisho, vidhibiti vya mtandao wa kutoka, na vipengele vya ufuatiliaji husaidia kuweka sera na siri nje ya usanidi wa mawakala binafsi.

Anza na mwongozo wa haraka wa Docker Compose, hifadhi ufunguo wa msimamizi uliotengenezwa, unda mtumiaji wa kiweko, na ukamilishe mtiririko wa kwanza wa kazi wa kiunganishi. Kuanzia hapo, ongeza funguo za API zilizofungamanishwa na wasifu, sanidi ufikiaji wa mtoa huduma, chagua sera inayofaa ya kunasa miili, na wezesha uchanganuzi wa ClickHouse pale tu mwonekano wa ziada unapohitajika.