Opas API-kutsuvaisten agenttien ymmärtämiseen, luomiseen ja optimointiin Tehtävien hallinta – API version: 1.0.0 paths: /tasks: post: summary: Lisää uusi tehtävä requestBody: required: true

Teknologiayritysten tekoälyrooli kehittyy nopeasti; tekoälyn soveltamiset ovat kehittyneet passiivisesta tietojen prosessoinnista proaktiivisiksi agenteiksi, jotka pystyvät suorittamaan tehtäviä. Maaliskuussa 2025 tehdyn Georgian ja NewtonX:n kansainvälisen tekoälyadoption tutkimuksen mukaan 91 % kasvuvaiheen ja yritysyritysten teknisistä johtajista käyttää tai aikoo käyttää agenteja.

API-kutsuvaisten agenteista on tärkeä esimerkki tästä siirtymästä agenteihin. API-kutsuvaisten agenteiden avulla voidaan hyödyntää suuria kielen malleja (LLM) vuorovaikuttaa ohjelmistojärjestelmiin niiden sovellusliittymien (API) kautta.

Esimerkiksi kääntämällä luonnollisen kielen komennot tarkkaan määriteltyihin API-kutsuihin, agentit voivat hakea reaaliaikaisia tietoja, automatisoida rutiinitehtäviä tai jopa ohjata muita ohjelmistojärjestelmiä. Tämä muuttaa tekoälyagentit hyödyllisiksi välittäjiksi ihmisen aikomusten ja ohjelmistotoiminnallisuuden välillä.

Yritykset käyttävät tällä hetkellä API-kutsuvaisia agenteja erilaisilla aloilla, mukaan lukien:

• Kuluttajasovellukset: Apuvälineet kuten Apple:n Siri tai Amazonin Alexa on suunniteltu yksinkertaistamaan päivittäisiä tehtäviä, kuten älykkäiden kodinkoneiden ohjausta ja varauksia.
• Yritysprosessit: Yritykset ovat käyttäneet API-agenteja automatisoimaan toistuvia tehtäviä, kuten tietojen hakemista asiakkuudenhallintajärjestelmistä, raporttien luomista tai tietojen konsolidointia sisäisistä järjestelmistä.
• Tietojen hakeminen ja analyysi: Yritykset käyttävät API-agenteja yksinkertaistamaan pääsyä omiin tietokantoihin, tilaustietoihin ja julkisiin API:hin, jotta voidaan luoda oivalluksia.

Tässä artikkelissa käytän insinöörikeskeistä lähestymistapaa API-kutsuvaisten agenttien ymmärtämiseen, luomiseen ja optimointiin. Artikkelin aineisto perustuu osittain Georgian AI Lab:n käytännön tutkimukseen ja kehitykseen. AI Lab:n tutkimuksen tärkein kysymys API-kutsuvaisten agenttien alalla on ollut: “Mikä on tehokkain tapa rakentaa agentti, joka voi käyttää luonnollista kieltä kommunikoimaan API:n kanssa, jos organisaatiolla on API?”
Selitän, miten API-kutsuvaisten agenteja voidaan rakentaa ja miten niitä voidaan suunnitella ja toteuttaa suorituskyvyltään. Lopuksi tarjoan järjestelmällisen työnkulun, jonka insinööritiimit voivat käyttää API-kutsuvaisten agenttien toteuttamiseen.

I. Avainmääritelmät:

• API tai sovellusliittymä: Sääntöjen ja protokollien joukko, joka mahdollistaa eri ohjelmistosovellusten viestinnän ja tietojen vaihdon.
• Agentti: Tekoälyjärjestelmä, joka on suunniteltu havaitsemaan ympäristönsä, tekemään päätöksiä ja suorittamaan toimia tiettyjen tavoitteiden saavuttamiseksi.
• API-kutsuva agentti: Erikoistunut tekoälyagentti, joka kääntää luonnollisen kielen ohjeet tarkkaan määriteltyihin API-kutsuihin.
• Koodigeneroiva agentti: Tekoälyjärjestelmä, joka auttaa ohjelmistokehityksessä kirjoittamalla, muokkaamalla ja virheenkorjaamalla koodia. Vaikka se liittyy tähän, tämän artikkelin painopiste on pääasiassa agenteissa, jotka kutsuvat API:ita, vaikka tekoäly voi myös auttaa luomaan nämä agentit.
• MCP (Malli-konteksti-protokolla): Protokolla, jota Anthropic on kehittänyt, joka määrittelee, miten LLM:t voivat muodostaa yhteyden ulkoisiin työkaluihin ja tietolähteisiin.

II. Ydin tehtävä: Kääntäminen luonnollisesta kielestä API-toimintoihin

API-kutsuvaisten agenttien perusfunktio on tulkita käyttäjän luonnollisen kielen pyyntö ja muuttaa se yhdeksi tai useammaksi tarkkaan määriteltyksi API-kutsuksi. Tämä prosessi sisältää yleensä:

1. Aikomuksen tunnistaminen: Ymmärtäminen käyttäjän tavoitteesta, vaikka se ilmoitetaan epäselvästi.
2. Työkalun valinta: Tunteminen sopivasta API-päätepisteestä (tai “työkalusta”) saatavilla olevista vaihtoehdoista, jotka voivat täyttää aikomuksen.
3. Parametrien poisto: Tunteminen ja poistaminen tarvittavista parametreista valituista API-kutsuista käyttäjän kysymyksestä.
4. Suorittaminen ja vastauksen luominen: Suorittaminen API-kutsuja, vastaanottaminen vastausta ja sitten syntetisointi tätä tietoa yhdeksi koherentiksi vastaukseksi tai suorittaminen seuraavaa toimintaa.

Tarkastellaan pyyntöä “Hei Siri, mitä säät on tänään?” Agentin on tunnistettava tarve kutsua sää-API:ta, määritettävä käyttäjän sijainti (tai sallittava sijainnin määrittäminen) ja sitten muodostettava API-kutsu hakemaan säätilan.

Pyyntö “Hei Siri, mitä säät on tänään?” voi esimerkiksi näyttää seuraavalta:

GET /v1/weather?location=New%20York&units=metric

Alkuvaiheen haasteita sisältyy tähän käännöksen prosessiin, mukaan lukien luonnollisen kielen epämääräisyys ja agentin tarve ylläpitää kontekstia usean vaiheen vuorovaikutuksissa.

Esimerkiksi agentin on usein “muistettava” aiemmat osat keskustelusta tai aiempien API-kutsujen tuloksia ohjaamaan nykyisiä toimia. Kontekstin menetys on yleinen virhetilanne, jos sitä ei hallita nimenomaisesti.

III. Arkkitehtuuri ratkaisuun: Avainkomponentit ja -protokollat

Tehokkaiden API-kutsuvaisten agenttien rakentaminen vaatii jäsenneltyä arkkitehtonista lähestymistapaa.

1. Työkalujen määrittely agentille

LLM:n käyttämiseksi API:ta on kuvauduttava sille tavalla, jota se ymmärtää. Kunkin API-päätepisteen tai toiminnon edustaa usein “työkalu”. Vankka työkalun määrittely sisältää:

• Selkeä, luonnollisen kielen kuvaus työkalun tarkoituksesta ja toiminnallisuudesta.
• Tarkka määrittely syöteparametreja (nimi, tyyppi, onko se pakollinen tai valinnainen ja kuvaus).
• Kuvaus tulosteen tai palautetun tiedon työkalun antamasta.

2. Malli-konteksti-protokollan rooli

MCP on tärkeä edistäjä LLM:ien ja ulkoisten työkalujen ja tietolähteiden käytön standardisoinnissa ja lujittamisessa.

MCP:n standardisointi on hyödyllistä, koska se mahdollistaa helpomman erilaisten työkalujen integroinnin, edistää työkalumäärittelyjen uudelleenkäytön eri agenteissa tai malleissa. Lisäksi se on paras käytäntö insinööritiimeille, jotka aloittavat hyvin määritellyistä API-määrityksistä, kuten OpenAPI-määrityksestä. Työkalut kuten Stainless.ai on suunniteltu auttamaan näiden OpenAPI-määritysten muuttamisessa MCP-määrityksiksi, jolloin prosessi tehdään helpommaksi.

3. Agenttikehykset ja -toteutusvalinnat

Useat kehykset voivat auttaa agentin rakentamisessa. Niihin kuuluvat:

• Pydantic: Vaikka se ei ole yksinomaan agenttikehyksessä, Pydantic on hyödyllinen työkalujen syöte- ja tulostusmuotojen määrittelyssä, mikä on tärkeää luotettavuuden kannalta. Monet mukautetut agenttien toteutukset hyödyntävät Pydanticia tätä rakenteellista eheytymistä varten.
• LastMile:n mcp_agent: Tämä kehyksen on suunniteltu työskentelemään MCP:iden kanssa, tarjoten enemmän mielipidettä siitä, miten agenteja voidaan rakentaa MCP:iden kanssa.
• Sisäinen kehykset: On yhä yleisempää käyttää tekoälykoodigeneraattoreita (työkaluja kuten Cursor tai Cline) kirjoittamaan agentin rungon, työkalujen ja ympäröivän logiikan koodia. Georgian AI Lab:n kokemus yritysten kanssa agenteiden toteuttamisesta osoittaa, että se voi olla hyvä tapa luoda erittäin vähäisiä, mukautettuja kehyksiä.

IV. Insinööritöiden luotettavuuden ja suorituskyvyn varmistaminen

Varmistaminen, että agentti tekee API-kutsut luotettavasti ja suorittaa hyvin, vaatii kohdennettua insinööritöitä. Kaksi tapaa tehdä tämä ovat (1) tietojoukon luominen ja validointi ja (2) kehysten ja logiikan optimointi.

1. Tietojoukon luominen ja validointi

Agentin koulutus (jos sovellettavissa), testaus ja optimointi vaativat laadukkaan tietojoukon. Tämä tietojoukko koostuu edustavista luonnollisen kielen kysymyksistä ja niiden vastaavista odotetuista API-kutsuista tai tuloksista.

• Manuaalinen luominen: Manuaalinen tietojoukon luominen takaa korkean tarkkuuden ja merkityksen, mutta se voi olla työlästä.
• Synteettinen generointi: Tietojen generointi ohjelmallisesti tai LLM:ien avulla voi skaalata tietojoukon luomista, mutta tämä lähestymistapa esittää merkittäviä haasteita. Georgian AI Lab:n tutkimus osoitti, että varmistaminen synteettisesti generoiden API-kutsujen ja kysymysten oikeellisuudesta ja realistisesta monimutkaisuudesta on erittäin vaikeaa. Usein luodut kysymykset olivat joko liian triviaaleja tai mahdottoman monimutkaisia, mikä teki agentin hienovaraisen suorituskyvyn arvioinnin vaikeaksi. Huolellinen validointi synteettisistä tietoista on ehdottoman tärkeää.

Kriittisten arvioiden kannalta pieni, laadukas, manuaalisesti vahvistettu tietojoukko tarjoaa usein luotettavamman näyn kuin suuri, meluisa synteettinen tietojoukko.

2. Kehysten ja logiikan optimointi

LLM-pohjaisen agentin suorituskyky on voimakkaasti vaikuttunut kehysten avulla ohjatun logiikan avulla.

• Tehtävän määrittely, työkalujen kuvaus ja kehysten rakenne ohjataan tarkasti oikean parametrin poistoon.
• Järjestelmällinen optimointi DSPy-kehyksen avulla voi parantaa suorituskykyä merkittävästi. DSPy sallii määritellä agentin komponentit (esim. moduulit ajatusten luomiseen, työkalujen valintaan, parametrin muotoiluun) ja sitten käyttää kääntäjän kaltainen lähestymistapa, jolla löydetään optimoidut kehykset tai konfiguraatiot näille komponenteille tietojoukon avulla.

V. Suositeltu polku tehokkaiden API-agenttien luomiseen

Vakaiden API-kutsuvaisten tekoälyagenttien kehittäminen on iteratiivinen insinööritieteellinen taito. Georgian AI Lab:n tutkimuksen tulosten perusteella tulokset voidaan parantaa merkittävästi järjestelmällisellä työnkululla, kuten seuraavalla:

1. Aloita selkeillä API-määrityksillä: Aloita hyvin rakennetuilla OpenAPI-määrityksillä API:ille, joilla agentti vuorovaikuttaa.
2. Standardisoi työkalujen käyttö: Muunna OpenAPI-määrityksesi MCP:ksi. Työkalut kuten Stainless.ai voivat helpottaa tätä, luomalla standardoidun tavan agentin ymmärtää ja käyttää API:ita.
3. Toteuta agentti: Valitse sopiva kehykset tai lähestymistapa. Tämä voi vaatia Pydanticia datamallien määrittelyyn agentin rakenteessa tai hyödyntää kehyksetä, joka on suunniteltu MCP:iden kanssa työskentelemiseen, kuten LastMile:n mcp_agent, joka on suunniteltu MCP:iden kanssa työskentelemiseen.
4. Luota laadukas arviointitietojoukko: Luo manuaalisesti tai tarkastaa tarkkaan tietojoukkoa, joka koostuu edustavista luonnollisen kielen kysymyksistä ja niiden vastaavista odotetuista API-viesteistä tai tuloksista. Tämä on kriittistä luotettavan testauksen ja optimoinnin kannalta.
5. Optimoi agentin kehykset ja logiikka: Käytä kehyksiä kuten DSPy kehysten ja logiikan parantamiseen tietojoukon avulla.

VI. Esimerkki työnkulusta

Tässä on yksinkertainen esimerkki suositellusta työnkulusta API-kutsuvaisten agenttien luomiseen:

Vaihe 1: Aloita selkeillä API-määrityksillä

Oletetaan yksinkertainen API tehtävien hallintaan, määritelty OpenAPI:ssa:

openapi: 3.0.0

info:
application/json:

schema:

type: object

properties:

description:

type: string

responses:

‘201’:

description: Tehtävä luotu onnistuneesti

get:

summary: Hae kaikki tehtävät

responses:

‘200’:

description: Luettelo tehtävistä

Vaihe 2: Standardisoi työkalujen käyttö

Muunna OpenAPI-määritys Model Context Protocol (MCP) -määrityksiksi. Käyttäen työkalua kuten Stainless.ai, tämä saattaa tuottaa:

Vaihe 3: Toteuta agentti

Käyttäen Pydanticia datamallien määrittelyyn, luo funktiot, jotka vastaavat MCP-työkaluja. Sitten käytä LLM:ia tulkitsemaan luonnollisen kielen kysymyksiä ja valitsemaan sopivan työkalun ja parametrit.

Vaihe 4: Luota laadukas arviointitietojoukko

Luo tietojoukko:

Vaihe 5: Optimoi agentin kehykset ja logiikka

Käytä DSPy:ta kehysten ja logiikan parantamiseen tietojoukon avulla, keskittyen selkeisiin ohjeisiin, työkalujen valintaan ja parametrin poistoon.

Yhdistämällä nämä rakennuspalat – rakenteelliset API-määritykset, standardoidut työkaluprotokollat, tarkat tietojoukot ja järjestelmällinen optimointi – insinööritiimit voivat luoda kykympiä, luotettavampia ja ylläpidettävämpiä API-kutsuvaisia tekoälyagenteja.