12-faktor AI-agent: Bygg effektive AI-systemer som skalerer

Hva kjennetegner en effektiv AI-agent?

Før vi dykker inn i faktorene, la oss avklare hva vi mener med “AI-agenter”. I bunn og grunn er dette systemer som kan tolke forespørsler på naturlig språk, ta beslutninger basert på kontekst og utføre bestemte handlinger via verktøy eller API-er – alt mens de opprettholder sammenhengende, løpende interaksjoner.

De mest kraftfulle agentene kombinerer resonneringsevnen til språkmodeller med påliteligheten til deterministisk kode. Men å finne denne balansen krever nøye designvalg – og det er nettopp det disse faktorene adresserer.

De 12 faktorene for å bygge robuste AI-agenter

1. Mestre konvertering fra naturlig språk til verktøykall

Evnen til å omgjøre forespørsler på naturlig språk til strukturerte verktøykall er kjernen i agentens funksjonalitet. Dette gjør det mulig for en agent å ta en enkel kommando som “lag en betalingslenke for 750 dollar til Terri for AI Tinkerers-møtet i februar” og gjøre det om til et korrekt formatert API-kall.

Image URL

{
  "function": {
    "name": "create_payment_link",
    "parameters": {
      "amount": 750,
      "customer": "cust_128934ddasf9",
      "product": "prod_8675309",
      "price": "prc_09874329fds",
      "quantity": 1,
      "memo": "Hey Jeff - see below for the payment link for the February AI Tinkerers meetup"
    }
  }
}

Nøkkelen til å få dette til å fungere pålitelig er å bruke deterministisk kode for å håndtere den strukturerte utdataen fra språkmodellen din. Valider alltid API-forespørsler før utførelse for å unngå feil, og sørg for at LLM-en din returnerer konsistente JSON-formater som kan parses sikkert.

2. Eie dine prompts fullt ut

Promptene dine er grensesnittet mellom applikasjonen din og språkmodellen – behandle dem som førsteklasses kode. Rammeverk som abstraherer prompts kan virke behagelige, men de skjuler ofte hvordan instruksjoner sendes til LLM-en, og gjør finjustering vanskelig eller umulig.

I stedet bør du ha direkte kontroll over promptene dine ved å skrive dem eksplisitt:

function DetermineNextStep(thread: string) -> DoneForNow | ListGitTags | DeployBackend | DeployFrontend | RequestMoreInformation {
  prompt #"
    {{ _.role("system") }}
    You are a helpful assistant that manages deployments for frontend and backend systems.
    ...
    {{ _.role("user") }}
    {{ thread }}
    What should the next step be?
  "#
}

Denne tilnærmingen gir deg flere fordeler:

• Full kontroll til å skrive presise instruksjoner tilpasset ditt spesifikke brukstilfelle
• Mulighet til å bygge evalueringer og tester for prompts som all annen kode
• Åpenhet slik at du forstår nøyaktig hva LLM-en mottar
• Frihet til å iterere basert på ytelsesmålinger

3. Design kontekstvinduet ditt strategisk

Kontekstvinduet fungerer som LLM-ens input, og omfatter prompts, samtalehistorikk og ekstern data. Optimalisering av dette vinduet forbedrer ytelse og token-effektivitet.

Image URL

Gå videre fra standard meldingsbaserte formater til egendefinerte strukturer som maksimerer informasjonsinnholdet:

<slack_message>
    From: @alex
    Channel: #deployments
    Text: Can you deploy the backend?
</slack_message>
<list_git_tags>
    intent: "list_git_tags"
</list_git_tags>
<list_git_tags_result>
    tags:
      - name: "v1.2.3"
        commit: "abc123"
        date: "2024-03-15T10:00:00Z"
</list_git_tags_result>

Denne tilnærmingen gir flere fordeler:

• Redusert token-bruk med kompakte formater
• Bedre filtrering av sensitiv data før det sendes til LLM
• Fleksibilitet til å eksperimentere med formater som forbedrer LLM-forståelse

4. Implementer verktøy som strukturerte utdata

I bunn og grunn er verktøy rett og slett JSON-utdata fra LLM-en som utløser deterministiske handlinger i koden din. Dette skaper et tydelig skille mellom AI-beslutninger og utføringslogikk.

Definer verktøyskjemaene tydelig:

class CreateIssue {
  intent: "create_issue";
  issue: {
    title: string;
    description: string;
    team_id: string;
    assignee_id: string;
  };
}

class SearchIssues {
  intent: "search_issues";
  query: string;
  what_youre_looking_for: string;
}

Bygg deretter pålitelig parsing for LLMs JSON-utdata, bruk deterministisk kode til å utføre handlingene, og følg opp med å mate resultatene tilbake i konteksten for iterativ arbeidsflyt.

5. Foren utførelses- og forretningstilstand

Mange agentrammeverk skiller mellom utførelsestilstand (f.eks. nåværende steg i en prosess) og forretningstilstand (f.eks. historikk av verktøykall og deres resultater). Dette skillet gir unødig kompleksitet.

I stedet bør all tilstand lagres direkte i kontekstvinduet, og utførelsestilstand utledes fra hendelsesrekkefølgen:

<deploy_backend>
    intent: "deploy_backend"
    tag: "v1.2.3"
    environment: "production"
</deploy_backend>
<error>
    error running deploy_backend: Failed to connect to deployment service
</error>

Denne samlede tilnærmingen gir:

• Enkelhet med én sannhetskilde for tilstand
• Bedre feilsøking med hele historikken samlet
• Enkel gjenoppretting ved å laste tråden fra et hvilket som helst punkt

Ta AI-agenter til produksjon

6. Design API-er for start, pause og gjenopptakelse

Produksjonsklare agenter må kunne integreres sømløst med eksterne systemer, pause for langvarige oppgaver og gjenoppta når de trigges av webhooks eller andre hendelser.

Implementer API-er som tillater oppstart, pausing og gjenopptakelse av agenter, med robust lagring av tilstand mellom operasjoner. Dette muliggjør:

• Fleksibel støtte for asynkrone arbeidsflyter
• Ren integrasjon med webhooks og andre systemer
• Pålitelig gjenopptakelse etter avbrudd uten omstart

7. Tilrettelegg for menneskelig samarbeid via verktøykall

AI-agenter trenger ofte menneskelig inngripen for viktige beslutninger eller tvetydige situasjoner. Ved å bruke strukturerte verktøykall blir denne interaksjonen sømløs:

class RequestHumanInput {  
  intent: "request_human_input";  
  question: string;  
  context: string;  
  options: {  
    urgency: "low" | "medium" | "high";  
    format: "free_text" | "yes_no" | "multiple_choice";  
    choices: string[];  
  };  
}

Image URL

Denne tilnærmingen gir tydelig spesifikasjon av interaksjonstype og hastegradsnivå, støtter input fra flere brukere, og kombineres godt med API-er for varige arbeidsflyter.

8. Kontroller agentens flyt

Egendefinert kontrollflyt lar deg pause for menneskelig godkjenning, cache resultater eller implementere rate limiting – slik at agentens oppførsel skreddersys til dine behov:

Image URL

async function handleNextStep(thread: Thread) {
  while (true) {
    const nextStep = await determineNextStep(threadToPrompt(thread));
    if (nextStep.intent === 'request_clarification') {
      await sendMessageToHuman(nextStep);
      await db.saveThread(thread);
      break;
    } else if (nextStep.intent === 'fetch_open_issues') {
      const issues = await linearClient.issues();
      thread.events.push({ type: 'fetch_open_issues_result', data: issues });
      continue;
    }
  }
}

Med denne tilnærmingen får du:

• Avbrytbarhet for å pause for menneskelig gjennomgang før kritiske handlinger
• Tilpasningsmuligheter for logging, caching eller oppsummering
• Pålitelig håndtering av langvarige oppgaver

9. Komprimer feil i konteksten for selvhelbredelse

Å inkludere feil direkte i kontekstvinduet gjør at AI-agenter kan lære av feil og justere tilnærmingen:

try {
  const result = await handleNextStep(thread, nextStep);
  thread.events.push({ type: `${nextStep.intent}_result`, data: result });
} catch (e) {
  thread.events.push({ type: 'error', data: formatError(e) });
}

For at dette skal fungere effektivt:

• Begrens antall forsøk for å unngå uendelige løkker
• Eskaler til mennesker etter gjentatte feil
• Formater feil tydelig slik at LLM forstår hva som gikk galt

Arkitektoniske beste praksiser

10. Bygg små, fokuserte agenter

Små agenter som håndterer 3–20 steg opprettholder håndterbare kontekstvinduer, noe som gir bedre ytelse og pålitelighet for LLM. Dette gir:

• Klarhet med veldefinert omfang for hver agent
• Redusert risiko for at agenten mister fokus
• Enklere testing og validering av spesifikke funksjoner

Image URL

Etter hvert som LLM-er forbedres, kan disse små agentene utvide sitt ansvarsområde mens kvaliteten beholdes – og sikrer skalerbarhet på lang sikt.

11. Muliggjør triggere fra flere kilder

Gjør agentene dine tilgjengelige ved å la dem trigges fra Slack, e-post eller hendelsessystemer – slik at du møter brukerne der de allerede jobber.

Implementer API-er som starter agenter fra ulike kanaler og svarer via samme medium. Dette muliggjør:

• Bedre tilgjengelighet gjennom integrasjon mot brukerforetrukne plattformer
• Støtte for hendelsesbaserte automatiserings-arbeidsflyter
• Arbeidsflyter med menneskelig godkjenning for kritiske operasjoner

12. Design agenter som tilstandsfrie “reducers”

Behandle agenter som tilstandsfrie funksjoner som omformer inngangskontekst til utgangshandlinger – dette forenkler tilstandshåndteringen, gjør dem forutsigbare og lettere å feilsøke.

Image URL

Denne konseptuelle tilnærmingen ser på agenter som rene funksjoner uten intern tilstand, og gir:

• Forutsigbar oppførsel for gitte input
• Enklere sporing av feil via konteksthistorikk
• Enklere testing og validering

Bygg for fremtiden

Feltet AI-agenter utvikler seg raskt, men disse kjerneprinsippene vil være relevante selv etter hvert som underliggende modeller forbedres. Ved å starte med små, fokuserte agenter som følger disse prinsippene, kan du lage systemer som gir verdi i dag og tilpasser seg fremtidige fremskritt.

Husk at de mest effektive AI-agentene kombinerer resonneringsevnen til språkmodeller med påliteligheten til deterministisk kode – og disse 12 faktorene hjelper deg å finne den balansen.

Hvordan FlowHunt brukte 12-faktor-metodikken

Hos FlowHunt har vi satt disse prinsippene ut i livet ved å utvikle vår egen AI-agent som automatisk lager arbeidsflytautomatiseringer for kundene våre. Slik brukte vi 12-faktor-metodikken for å bygge et pålitelig, produksjonsklart system