Sebenzisa futhi Uvikele Ama-Agent e-AI nge-AI Agent Gateway

Yini i-AI Agent Gateway?

I-AI Agent Gateway iyisevisi yomthombo ovulekile ehlala phakathi kwama-agent e-AI namasistimu awabizayo. Ihlinzeka ngendawo eyodwa egunyaziwe futhi ebonakalayo yokungena kumaseva wamathuluzi e-MCP nabahlinzeki be-LLM abasekelwayo, okuhlanganisa i-Anthropic Claude, i-AWS Bedrock, i-OpenAI, ne-Gemini.

Esikhundleni sokukopisha imininingwane yamathuluzi nezilungiselelo zabahlinzeki ku-agent ngayinye, ungaphatha phakathi nendawo ukuqinisekiswa, izimfihlo, izinqubomgomo zokufinyelela, namalogi ezicelo. I-gateway isatshalaliswa njengefayela elilodwa elisebenzisekayo futhi ine-console yokuphatha eyakhelwe ngaphakathi.

Isevisi inabalaleli abathathu:

• I-MCP plane ethekwini 8080: Yamukela izicelo ze-MCP kuma-agent futhi idlulisele imisebenzi evunyelwe kumaseva amathuluzi abhalisiwe.
• I-control plane ethekwini 8081: Ibamba i-REST API ne-console yokuphatha.
• I-LLM plane ethekwini 8082: Isebenza njengommeleli wezicelo ze-LLM ezisekelwayo futhi igcine imininingwane yokusetshenziswa.

Kudingeka i-PostgreSQL. Isitolo samaseshini esihambisana ne-Redis siyazikhethela futhi sivumela i-MCP plane ukuthi isebenze ngamareplica angaphezu kweyodwa; ama-deployment ahlanganisiwe asebenzisa i-Valkey. I-ClickHouse iyazikhethela futhi inika amandla izici ezengeziwe zokuhlaziya.

Izici Ezibalulekile

• Ukuqinisekiswa kwazo zonke izicelo: Okhiye be-API abakhishwa yi-gateway baboshelwe ku-tenant nendima ethile.
• Izincwadi eziqinisekisayo ezivikelwe zezixhumi: Izincwadi eziqinisekisayo zigcinwa esitolo sezimfihlo esibethelwe futhi zifakwa ezicelweni ze-MCP eziphumayo ngaphandle kokudalulwa kumfakisicelo.
• Izinqubomgomo zamathuluzi eziqondene ne-agent: Amaphrofayela angakhawulela amathuluzi i-agent engawasebenzisa. Imikhawulo iyaphoqelelwa ngesikhathi se-tools/call, hhayi kuphela lapho amathuluzi efakwa ohlwini.
• Imiyalo nezinsiza: I-gateway idlulisa imiyalo nezinsiza zangemuva nge-namespace eyabiwe futhi isebenzise izinqubomgomo zephrofayela ezifanayo.
• Amakhono nemiyalo: Amaphrofayela angafaka umbhalo wereferensi ongasetshenziswa kabusha nezifanekiso zemiyalo ezivezwa ngezindlela zomdabu ze-MCP.
• Ummeli we-LLM wabahlinzeki abaningi: I-LLM plane isekela i-Anthropic, i-Bedrock, i-OpenAI, ne-Gemini ngesikhathi iqopha ukusetshenziswa kwamathokheni nezindleko ezilinganisiwe.
• Ukubonakala okumaphakathi: I-console inikeza ukufinyelela kumalogi okufinyelela, amalogi e-LLM, imigqa yesikhathi yamaseshini, nedeshibhodi yokuhlaziya lapho isitoreji esidingekayo sinikwe amandla.
• Ukuvikelwa kwezicelo eziphumayo: Izindawo zangaphakathi, ze-loopback, ze-link-local, nezinye eziyimfihlo zivinjelwa ngokuzenzakalelayo ukuze kuncishiswe izingozi zokukhohliswa kwezicelo ezisuka ohlangothini lweseva.

Izidingo Zokuqala

Ukusetha okushesha kakhulu kusebenzisa i-Docker Compose. Ngaphambi kokuqala, faka noma uqinisekise lokhu okulandelayo:

• I-Docker ene-Compose plugin, njenge-Docker Desktop, i-Colima, noma i-Docker Engine.
• curl yokuhlola impilo kanye ne-jq yokucubungula izimpendulo ze-API.
• Amachweba endawo amahhala 8080, 8081, kanye ne-8082.
• Ichweba 8090 uma unika amandla iphrofayela yokuhlaziya nesevisi yayo ye-Adminer.
• Okungenani u-4 GB wendawo yamahhala ye-Docker, noma u-8 GB uma wengeza ukuhlaziya kwe-ClickHouse.

I-macOS ne-Linux ziyasekelwa. I-Windows ingasetshenziswa nge-WSL2, nakuba leyo ndawo ingakahlolwa okwamanje.

Ukuze wakhe ngaphandle kwe-Docker, indawo yokugcina idinga i-Go 1.27, i-Node.js 26 ye-console, kanye ne-make. Ezinye izibonelo ezisebenzayo zidinga futhi i-npx, i-Python, i-kind, i-kubectl, noma ukhiye we-API womhlinzeki.

Faka Futhi Uqalise i-Gateway

1. Klona indawo yokugcina

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

2. Qalisa i-Compose stack ejwayelekile

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

Ukuqalisa kokuqala kungathatha isikhathi ngoba i-Docker kufanele yakhe noma ilande izingxenye ezidingekayo futhi iqalise isizindalwazi.

3. Linda i-control plane

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

Leliluphu lilinda kuze kube yilapho i-endpoint yezempilo ye-control plane iphendula ngempumelelo.

4. Hlola wonke ama-plane amathathu

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

Izimpendulo eziphumelelayo ziqinisekisa ukuthi abalaleli be-MCP, control, ne-LLM bayatholakala.

Qalisa Ukufinyelela Kokuphatha

I-deployment entsha ayinabo abasebenzisi be-console futhi ayinawo ukhiye we-API. Qala ngokudala i-tenant ezenzakalelayo nokhiye we-API womlawuli:

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

Umyalo uphrinta ukhiye we-API kanye kuphela. Wugcine ngokuphephile ngoba inqubo yokuqala isebenzisa wona ukubhalisa izixhumi nokwenza imisebenzi yokuphatha ye-API.

Okulandelayo, dala umsebenzisi wokuqala we-console:

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

Lo myalo uphrinta iphasiwedi yesikhashana ezosetshenziswa kanye. Vula http://localhost:8081, ngena ngemvume njengo-admin, bese ushintsha iphasiwedi yesikhashana uma utshelwa.

Izinhlelo ngokuvamile kufanele ziqinisekise ngobokhiye be-API. I-console ingamukela nokhiye we-API njengesixazululo esiphuthumayo.

Ukusetshenziswa Okuyisisekelo: Engeza Futhi Ubize Iseva ye-MCP

Ngokwesichazamazwi se-gateway, iseva yamathuluzi ye-MCP iyi-connector ku-API futhi iyi-MCP ku-console. Ngemva kokungena ngemvume, vula MCPs → Catalog ukuze ubone amaseva e-MCP aselungiselelwe angangezwa.

Inqubo evamile yokusetshenziswa kokuqala yile:

1. Dala futhi ulondoloze ukhiye we-API womlawuli.
2. Bhalisa iseva ye-MCP njengoxhumi.
3. Lungiselela noma yiziphi iziqinisekiso ezidingwa umxhumi.
4. Dala noma ukhethe iphrofayela ye-ejenti.
5. Yenza amathuluzi omxhumi atholakale kuleyo phrofayela.
6. Shayela ithuluzi elivunyelwe usebenzisa umlaleli we-MCP wesango ku-port 8080.
7. Hlola ucingo kukhonsoli yokuphatha.

Indawo yokugcina ikhodi iqukethe umhlahlandlela ophelele osebenzisekayo ngaphansi kwe-examples/01-quickstart. Iqala i-stack, iqinisekise zonke izindiza ezintathu, isungule ukhiye womlawuli, ibhalise iseva ye-MCP yesibonelo, bese ibiza elinye lamathuluzi ayo. Landela umhlahlandlela wokuqalisa ukuze uthole izicelo eziqondile zokubhalisa umxhumi nokubiza ithuluzi.

Ukuqalisa zonke izibonelo ezingadingi iziqinisekiso zangaphandle, sebenzisa:

make examples-smoke

Amaphrofayela E-ejenti Akuphoqelela Kanjani Ukufinyelela

Amaphrofayela achaza amathuluzi, imiyalelo, izinsiza, amakhono, nemiyalo etholakala ku-ejenti. Imikhawulo yamathuluzi iyahlolwa lapho i-ejenti ibiza tools/call, ngakho ukufihla ithuluzi ku-tools/list akuwona umugqa wokuphoqelela wodwa.

Ukuze kuphoqelelwe inqubomgomo ngokuqinile, xhumanisa ukhiye we-API nephrofayela. Ngaphandle kwalokhu kuxhumanisa, oshayayo angakhomba iphrofayela ayifunayo nge-header ethi X-Agent-Profile-Name. Ukuxhumanisa ukhiye nephrofayela kuvimbela oshayayo ekukhetheni ngokukhululekile enye iphrofayela.

Lapho amaseva amaningi e-MCP eveza imiyalelo noma izinsiza, isango liwagcina endaweni yamagama efanayo. Imiyalelo ihlotshaniswa negama lomhumushi, kanti izinsiza zisebenzisa ama-URI alawulwa yisango. Imithetho efanayo yephrofayela inquma ukuthi yiziphi izinto i-ejenti engafinyelela kuzo.

Sebenzisa i-LLM Proxy

Indiza ye-LLM inikeza indlela emaphakathi eya kubahlinzeki bamamodeli abasekelwayo: Anthropic, AWS Bedrock, OpenAI, ne-Gemini. Lokhu kuvumela izinhlelo ze-ejenti ukuthumela ithrafikhi yamamodeli endaweni efanayo elawulwayo esetshenziselwa amathuluzi.

Ngocingo ngalunye oludluliswa nge-proxy, isango lingaqoqa ukusetshenziswa kwamathokheni futhi lilinganise izindleko. Ukusethwa komhlinzeki, ukumisa ukusebenzisa ukhiye wakho, izindlela zemininingwane ye-Bedrock, imizila, izilungiselelo zokuqopha, nokuziphatha kwezindleko kuchazwe kumhlahlandlela wendiza ye-LLM.

Sebenzisa i-health endpoint ukuqinisekisa umlaleli ngaphambi kokulungisa iklayenti:

curl localhost:8082/health

Nika Amandla Izibalo

Ukusatshalaliswa okujwayelekile kusekela amalogi e-LLM ngaphandle kwe-ClickHouse. Ukuze wengeze ideshibhodi Yokubuka konke, Amalogi Okufinyelela, Umugqa Wesikhathi Weseshini, nezibalo ezisekelwa yi-ClickHouse, qala i-Compose ngephrofayela ye-analytics:

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

Lokhu kulungiselelwa kudinga izinsiza eziningi zasendaweni futhi kungase kusebenzise i-port 8090.

Vikela Imizimba Yezicelo Ebucayi

I-stack yokubonisa igcina imizimba yezicelo nezimpendulo ze-LLM ku-PostgreSQL, ngayinye inomkhawulo ongu-1 MiB. Ngephrofayela ye-analytics, iphinde igcine imizimba yezicelo nezimpendulo ze-LLM ne-MCP ku-ClickHouse ukuze iboniswe kukhonsoli. Le mizimba ayiphrintwa kumalogi ama-container.

Uma imiyalelo, izimpendulo zamamodeli, noma imithwalo yamathuluzi ingase iqukathe ulwazi olubucayi, cisha ngokuphelele ukugcinwa kwemizimba:

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

Buyekeza imibhalo yokubonakala kohlelo ngaphambi kokusebenzisa izici zokuqopha ngedatha yokukhiqiza.

Xhuma Kumaseva E-MCP Asendaweni Noma Ayimfihlo Ngokuphepha

Isango livimba izindawo ze-loopback, eziyimfihlo, ze-link-local, nezinye izindawo zangaphakathi ngokuzenzakalela. Liphinde livimbe unomphela ikheli le-cloud metadata elithi 169.254.169.254. Le nqubomgomo ivimbela umxhumi, into yekhathalogi, noma okuqondiswe kukho yimodeli ekufinyeleleni ngokuthule izinsiza ezibucayi ku-host noma kunethiwekhi.

Uma igama le-host lixazululeka kuphela libe amakheli avinjiwe lapho lidalwa, isango liyalenqaba nge-400 egress_blocked. Igama le-host elingakaxazululeki lingamukelwa, kodwa liyahlolwa futhi lapho isango lizama ukuxhuma.

Ukuqalisa i-binary ngokuqondile

Lapho usebenzisa make run, vumela i-loopback ngokusobala uma iseva ye-MCP isebenza emshinini ofanayo:

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

Ukusebenzisa i-Compose stack enikeziwe

Ukucushwa kwe-Compose okufakiwe sekuvele kuvumela host.docker.internal nama-CIDR e-loopback. Ngakho iseva esebenza kwi-laptop yakho ingafinyelelwa nge-host.docker.internal. Susa lezi zimvume ezindaweni ezabiwe ngaphandle uma zidingeka.

Ukusebenzisa i-Kubernetes noma amanethiwekhi ayimfihlo

Enkonzweni ye-Kubernetes yangaphakathi kwe-cluster, vumela kuphela igama le-DNS elibizwayo, isibonelo:

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

Ngokunye, ungavumela i-CIDR ye-pod noma yesevisi efanele. Kumaseva e-VPN kuphela noma akunethiwekhi eyimfihlo, engeza igama le-host elithile noma i-CIDR encane esikhundleni sokuvumela lonke uhla lwamakheli ayimfihlo.

Gcina uhlu lwabavunyelwe oluphumayo luncane ngangokunokwenzeka. Ungacimi ukuvikelwa ukuze wenze ukuhlola kokuqala kube lula.

Amathiphu Okusebenza Athuthukile

• Hlukanisa ukufinyelela kwabantu nokwezinhlelo: Sebenzisa ama-akhawunti ekhonsoli kubaphathi, nama-API key akhishwa yi-gateway kuma-agent nakumathuluzi azenzakalelayo.
• Bopha ama-key kumaphrofayela: I-key eboshwe kuphrofayela inikeza iziqinisekiso eziqinile kunokuvumela abafonayo bakhethe iphrofayela nge-request header.
• Gcina iziqinisekiso ku-gateway: Lungisa iziqinisekiso zama-connector endaweni eyodwa ukuze ama-agent angatholi izimfihlo eziyisisekelo.
• Shintsha iziqinisekiso zama-connector: Sebenzisa izici zokuphatha ama-connector neziqinisekiso esikhundleni sokubuyekeza i-agent ngayinye ngokuzimela.
• Lawula ukuqoqwa kwedatha: Nquma ukuthi ama-request body nama-response body kufanele agcinwe yini ngaphambi kokucubungula ama-prompt ayimfihlo noma imiphumela yamathuluzi.
• Hlela ama-replica amaningi: Lungisa i-session store esebenzisa iphrothokholi ye-Redis ngokuzithandela lapho wandisa i-MCP plane ibe ngaphezu kwe-replica eyodwa.
• Sebenzisa imithetho emincane ye-egress: Vumela ama-host noma ama-CIDR ngamunye esikhundleni samabanga abanzi ayimfihlo.
• Bheka izibonelo ezinemininingwane: Izibonelo ngazinye zichaza ezinye izimo futhi zibala amathuluzi adingekayo noma ama-key abathengisi kumafayela azo e-README.
• Lindela izinguquko: Le phrojekthi iyisofthiwe ye-alpha engakafiki ku-1.0, ngakho ama-API nokucushwa kungashintsha phakathi kwezinguqulo ezincane.

Ukwakha Ngaphandle Kwe-Docker

Ukuze uthuthukise endaweni yangakini, faka i-Go 1.27, i-Node.js 26, kanye ne-make. I-repository inikeza izinqubo ze-make build ne-make run. Amathuluzi okuzikhethela okuthuthukisa nawokukhipha afaka i-golangci-lint, i-govulncheck, kanye ne-goreleaser.

Ukuze uthole izimiso zokuthuthukisa, imiyalo yokuhlola, ukuqondiswa kwama-pull request, kanye nezindawo zokwandisa zama-store, ama-sink, nabahlinzeki, bheka umhlahlandlela wokufaka isandla.

Isiphetho

AI Agent Gateway ihlanganisa ukufinyelela kumathuluzi e-MCP nakubahlinzeki abaningi be-LLM ngama-endpoint aqinisekisiwe. Ukuphoqelelwa kwamaphrofayela, ukufakwa kweziqinisekiso, izilawuli zenethiwekhi ephumayo, nezici zokubonakala kwayo kusiza ukugcina izinqubomgomo nezimfihlo zingangeni ekucushweni kwama-agent ngamanye.

Qala nge-Docker Compose quickstart, gcina i-key yomphathi ekhiqiziwe, dala umsebenzisi wekhonsoli, bese uqedela inqubo yokuqala ye-connector. Ngemva kwalokho, engeza ama-API key aboshelwe kumaphrofayela, lungisa ukufinyelela kwabahlinzeki, khetha inqubomgomo efanele yokuthwebula imizimba, futhi uvule izibalo ze-ClickHouse kuphela lapho ukubonakala okwengeziwe kudingeka.