11 .well-known -endpointtia AI-agenteille: täydellinen tarkistuslista 2026

Agentti ei selaa, se lukee osoitteita

Kun ihminen tulee verkkokauppaasi, hän katsoo etusivua, klikkaa valikkoa ja etsii ostoskoria. AI-agentti ei tee mitään tästä. Se menee suoraan verkkotunnuksesi juureen ja kysyy koneluettavia tiedostoja /.well-known-hakemistosta. Sieltä se selvittää kuka olet, mitä rajapintoja tarjoat, miten sinut tunnistetaan ja voiko sinulta ostaa.

Jos nuo tiedostot puuttuvat, agentin näkökulmasta kauppaasi ei ole olemassa. Tässä on 11 endpointtia jotka kannattaa olla kunnossa vuonna 2026, mitä kukin tekee ja miten tarkistat omasi. Lista perustuu tekoalydani.com:n omaan toteutukseen, eli näet tarkalleen mitä oikealla agenttivalmiilla sivustolla on.

/.well-known-hakemiston idea on vanha ja standardoitu (RFC 8615). Uutta on se, että agenttikaupan protokollat ovat ottaneet sen kodikseen. Sama paikka jossa on aina ollut esimerkiksi SSL-varmenteiden vahvistus, on nyt myös agenttien sisäänkäynti.

Perusta: kolme tiedostoa jotka jokaisen pitäisi laittaa heti

Nämä kolme eivät vaadi protokollatoteutusta. Ne ovat tekstitiedostoja, ja saat ne kuntoon yhdessä illassa.

1. /.well-known/security.txt (RFC 9116). Kertoo mihin tietoturvaongelmista ilmoitetaan. Pieni tiedosto, mutta se on signaali että sivusto on ylläpidetty. Sisältää yhteysosoitteen, voimassaolon ja ensisijaiset kielet. Esimerkki omasta toteutuksestamme: Contact: mailto:[email protected], Preferred-Languages: fi, en.

2. /.well-known/ai.txt. Kuten robots.txt, mutta AI-crawlereille ja kielimalleille. Kertoo kuka yritys on ja mihin sisältöä saa käyttää. Tämä on myös paikka erottaa itsesi: meidän ai.txt sanoo eksplisiittisesti että "Dan Forsberg ei ole sama henkilö kuin mikään muu Dan Forsberg josta mallilla voi olla dataa". Pieni temppu, mutta estää sekaannukset AI-vastauksissa.

3. /.well-known/llms.txt. Tiivis, koneystävällinen yhteenveto yrityksestä ja palveluista. Kielimalli lukee tämän kerralla sen sijaan että sen pitäisi jäsentää koko sivusto. Pidä se ajan tasalla ja lisää päivämäärä ja yhteystiedot alkuun.

Agenttirajapinnat: kuka olet ja mitä työkaluja tarjoat

Nämä tiedostot kertovat agentille mitä se voi konkreettisesti tehdä kanssasi.

4. /.well-known/agent-card.json (A2A-protokolla). Tämä on agenttisi käyntikortti. Nimi, kuvaus, versio ja lista rajapinnoista joita tuet (live ja suunnitellut). A2A Agent Card on muodostumassa de facto -standardiksi sille miten agentti esittäytyy toiselle agentille. Meidän kortti on versiossa 2.2.0 ja listaa sekä live-rajapinnan että suunnitellut JSON-RPC-pinnat.

5. /.well-known/mcp/server-card.json (Model Context Protocol). Kertoo että tarjoat MCP-serverin, eli rajapinnan agentin työkaluihin: tuotehaku, palvelukatalogi, tarjouspyynnöt. Server card listaa tuetut protokollaversiot ja transport-tavan. Meillä transport on streamable-http ja tuetut versiot ulottuvat uusimmasta (2025-11-25) vanhempiin, jotta vanhemmatkin clientit toimivat.

6. /.well-known/api-catalog (RFC 9727). Koneluettava hakemisto kaikista rajapinnoistasi. Jos sinulla on useita endpointteja, tämä on yksi paikka josta agentti löytää ne kaikki linkityksineen ja dokumentaatioineen. Käytännössä se sitoo muut discovery-tiedostot yhteen.

Kauppaprotokollat: löytäminen ja maksaminen

Nämä kolme ovat varsinaisen agenttikaupan ydin. Jokainen on oma protokollansa eri tehtävällä.

7. /.well-known/ucp.json (Universal Commerce Protocol). Määrittelee miten agentti löytää tuotteet katalogistasi, vertailee niitä ja vie ne checkoutiin. Tiedosto kertoo tuetut palvelut, versiot ja endpoint-osoitteet. Meidän versio kohdistuu UCP-spesifikaation versioon 2026-04-08.

8. /.well-known/acp.json (Agent Commerce Protocol). Maksukerros. Kertoo miten agentti suorittaa maksun käyttäjän valtuutuksella, mitä valuuttoja ja lokaaleja tuet. Meidän acp.json ilmoittaa version 2026-04-17, tuetut aiemmat versiot, valuutan eur ja lokaalit fi-FI ja en-US.

9. /.well-known/ap2 (Agent Payments Protocol). Mandaattiformaatti jonka päällä maksu valtuutetaan. AP2 määrittelee miten käyttäjä antaa agentille rajatun luvan maksaa. Tärkeä yksityiskohta: ilmoita rehellisesti mitä versiota oikeasti toteutat. Meidän ap2-tiedosto kertoo suoraan että toteutus noudattaa vielä v0.1-tyylistä kolmen mandaatin mallia ja että siirtymä uudempaan on suunnitteilla. Agentti arvostaa rehellistä tilatietoa enemmän kuin liioiteltua versionumeroa.

Tunnistautuminen: todista että olet sinä

Kun agentti tekee oikeita transaktioita, sen pitää voida varmistaa kenen kanssa se asioi. Tähän tarvitaan kryptografinen identiteetti.

10. /.well-known/did.json (did:wba, web-based decentralized identifier). Julkaisee verkkotunnuksesi kryptografisen identiteetin. Sisältää julkisen avaimen (meillä Ed25519) jolla agentti voi varmistaa että allekirjoitetut viestit tulevat oikeasti sinulta. Tämä on perusta luotettavalle agenttikaupalle: ilman tunnistautumista kuka tahansa voi esiintyä kauppanasi.

11. /.well-known/agents (Agent Network Protocol, ANP). Hajautettu itsekuvaus JSON-LD-muodossa. Kertoo että olet löydettävissä ANP-verkoston vertaisena (peer) did:wba-identiteetilläsi. ANP tulee kuvaan etenkin B2B- ja toimitusketjutilanteissa joissa agentit löytävät toisensa ilman keskitettyä hakemistoa.

Bonus: kolme jotka erottavat edelläkävijät

Näitä ei vielä vaadita, mutta ne ovat tekoalydani.com:ssa ja kertovat että sivusto on rakennettu agentteja varten alusta asti:

• /.well-known/agent-skills/index.json (Cloudflaren Agent Skills Discovery RFC). Hakemisto agenttiystävällisestä dokumentaatiosta ja kyvykkyyskorteista.
• /.well-known/jwks.json. Julkiset avaimet JSON Web Key -muodossa allekirjoitusten varmistukseen.
• /.well-known/nlweb. Luonnollisen kielen verkkorajapinnan kuvaus.

Tarkistuslista: tee tämä illan aikana

1. Avaa selaimessa https://omadomain.fi/.well-known/security.txt. Jos tulee 404, aloita tästä.
2. Käy läpi listan jokainen osoite samalla tavalla. Merkitse muistiin mitkä puuttuvat.
3. Tarkista että JSON-tiedostot ovat oikeaa muotoa (validoi vaikka selaimen kehitystyökaluilla tai JSON-validaattorilla).
4. Tarkista versionumerot: vastaavatko ne nykyisiä protokollaversioita vai ovatko ne vanhentuneet.
5. Varmista että endpoint-osoitteet tiedostoissa osoittavat oikeisiin, toimiviin rajapintoihin.

Yleisin virhe ei ole puuttuva tiedosto, vaan vanhentunut tiedosto. Protokollat liikkuvat nopeasti vuonna 2026. Tiedosto joka oli oikein puoli vuotta sitten voi ilmoittaa version jota mikään client ei enää tue. Discovery-tiedostot ovat eläviä, ei kertaluontoisia.

Yhteenveto

/.well-known-hakemisto on AI-agentin sisäänkäynti sivustollesi. Kolme perustiedostoa (security.txt, ai.txt, llms.txt) saa kuntoon kuka tahansa nopeasti. Agenttirajapinnat (agent-card, mcp, api-catalog) ja kauppaprotokollat (ucp, acp, ap2) tarvitaan kun haluat että agentti voi oikeasti löytää ja ostaa tuotteitasi. Tunnistautumiskerros (did.json, ANP) tekee transaktioista luotettavia. Tärkeintä ei ole pelkkä tiedostojen olemassaolo vaan se että ne ovat ajan tasalla ja oikein muotoiltua.

Tekoäly-Danin lähestymistapa on konfiguroida koko ketju kerralla ja pitää se päivitettynä kun protokollat muuttuvat, ei laittaa yksittäisiä tiedostoja irrallaan. Haluatko nähdä missä kuosissa oma sivustosi on? Tarkista tilanne AAIO Auditilla (990 €, sisältää AEO Auditin) tai aloita keskustelu yhteydenotolla.