Den 12-faktor AI-agent: Byg effektive AI-systemer, der kan skaleres

Hvad gør en AI-agent effektiv?

Inden vi går i dybden med faktorerne, lad os afklare, hvad vi mener med “AI-agenter.” Grundlæggende er det systemer, der kan fortolke anmodninger i naturligt sprog, træffe beslutninger baseret på kontekst og udføre specifikke handlinger via værktøjer eller API’er – alt sammen mens de opretholder sammenhængende, løbende interaktioner.

De mest kraftfulde agenter kombinerer sprogmodellernes ræsonnement med deterministisk kodes pålidelighed. At ramme denne balance kræver omhyggelige designvalg, og det er netop det, disse faktorer adresserer.

De 12 faktorer til at bygge robuste AI-agenter

1. Mestre konvertering fra naturligt sprog til værktøjskald

Evnen til at omdanne anmodninger i naturligt sprog til strukturerede værktøjskald er kernen i agentens funktionalitet. Det er det, der gør det muligt for en agent at tage en simpel kommando som “opret et betalingslink på 750 kr. til Terri for AI Tinkerers meetup i februar” og konvertere det til et korrekt formateret API-kald.

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øglen til at få dette til at fungere pålideligt er at bruge deterministisk kode til at håndtere det strukturerede output fra din sprogmodel. Validér altid API-payloads før udførelse for at forhindre fejl, og sørg for, at din LLM returnerer konsistente JSON-formater, der kan parses pålideligt.

2. Hav fuldt ejerskab over dine prompts

Dine prompts er grænsefladen mellem din applikation og sprogmodellen – behandl dem som first-class kode. Frameworks, der abstraherer prompts, kan virke bekvemme, men de skjuler ofte, hvordan instruktioner videregives til LLM’en, hvilket gør finjustering svært eller umuligt.

I stedet bør du have direkte kontrol over dine prompts ved at skrive dem eksplicit:

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 tilgang giver dig flere fordele:

• Fuld kontrol til at skrive præcise instruktioner tilpasset din specifikke brugssag
• Mulighed for at opbygge evalueringer og tests for prompts som enhver anden kode
• Gennemsigtighed, så du forstår præcis, hvad LLM’en modtager
• Frihed til at iterere baseret på performancemålinger

3. Design dit kontekstvindue strategisk

Kontekstvinduet fungerer som LLM’ens input og omfatter prompts, samtalehistorik og eksterne data. Optimering af dette vindue forbedrer ydeevne og token-effektivitet.

Image URL

Gå ud over standard meddelelsesbaserede formater og brug brugerdefinerede strukturer, der maksimerer informationsdensiteten:

<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 tilgang giver flere fordele:

• Mindre tokenforbrug med kompakte formater
• Bedre filtrering af følsomme data før de gives videre til LLM’en
• Fleksibilitet til at eksperimentere med formater, der forbedrer LLM-forståelsen

4. Implementér værktøjer som strukturerede outputs

I sin kerne er værktøjer blot JSON-outputs fra LLM’en, der udløser deterministiske handlinger i din kode. Dette skaber en klar adskillelse mellem AI-beslutningstagning og udførselslogik.

Definér værktøjsskemaer tydeligt:

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;
}

Byg derefter pålidelig parsing af LLM JSON-outputs, brug deterministisk kode til at udføre handlingerne, og giv resultater tilbage til konteksten for iterative workflows.

5. Forén eksekverings- og forretningstilstand

Mange agent-frameworks adskiller eksekveringstilstand (fx nuværende trin i en proces) fra forretningstilstand (fx historik over værktøjskald og deres resultater). Denne adskillelse tilføjer unødvendig kompleksitet.

I stedet bør du gemme al tilstand direkte i kontekstvinduet og udlede eksekveringstilstand ud fra rækkefølgen af hændelser:

<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 forenede tilgang giver:

• Enkelhed med én sandhedskilde for tilstand
• Bedre fejlsøgning med hele historikken samlet ét sted
• Nem gendannelse ved at genoptage fra et vilkårligt punkt ved at indlæse tråden

AI-agenter i produktion

6. Design API’er til start, pause og genoptag

Produktionsklare agenter skal kunne integreres problemfrit med eksterne systemer, holde pause ved langvarige opgaver og genoptage, når de udløses af webhooks eller andre events.

Implementér API’er, der muliggør start, pause og genoptagelse af agenter, med robust tilstandslagring mellem operationer. Dette muliggør:

• Fleksibel understøttelse af asynkrone workflows
• Ren integration med webhooks og andre systemer
• Pålidelig genoptagelse efter afbrydelser uden genstart

7. Muliggør menneskeligt samarbejde via værktøjskald

AI-agenter har ofte brug for menneskelig input til vigtige beslutninger eller uklare situationer. Ved at bruge strukturerede værktøjskald bliver denne interaktion problemfri:

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 tilgang giver klar specificering af interaktionstype og hast, understøtter input fra flere brugere og kombineres godt med API’er til holdbare workflows.

8. Kontrollér agentens flow

Brugerdefineret kontrolflow giver dig mulighed for at holde pause for godkendelse fra mennesker, cache resultater eller implementere rate limiting – så agentens adfærd tilpasses 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 tilgang får du:

• Mulighed for at afbryde for menneskelig gennemgang før kritiske handlinger
• Tilpasningsmuligheder til logging, caching eller opsummering
• Pålidelig håndtering af langvarige opgaver

9. Inkludér fejl kompakt i konteksten for selvhelbredelse

Ved at inkludere fejl direkte i kontekstvinduet kan AI-agenter lære af fejl og tilpasse deres tilgang:

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 fungerer effektivt:

• Begræns antal forsøg for at forhindre uendelige loops
• Eskalér til mennesker efter gentagne fejl
• Formater fejl tydeligt, så LLM’en forstår, hvad der gik galt

Arkitektoniske best practices

10. Byg små, fokuserede agenter

Små agenter, der håndterer 3–20 trin, holder kontekstvinduet overskueligt og forbedrer LLM-ydeevnen og pålideligheden. Denne tilgang giver:

• Klarhed med veldefineret scope for hver agent
• Mindre risiko for, at agenten mister fokus
• Nem test og validering af specifikke funktioner

Image URL

Efterhånden som LLM’er bliver bedre, kan disse små agenter udvide deres scope og samtidig bevare kvaliteten og sikre langtidsskalérbarhed.

11. Muliggør triggere fra flere kilder

Gør dine agenter tilgængelige ved at tillade triggere fra Slack, e-mail eller event-systemer – mød brugerne, hvor de allerede arbejder.

Implementér API’er, der starter agenter fra forskellige kanaler og svarer via samme medie. Dette giver:

• Bedre tilgængelighed via integration med brugerens foretrukne platforme
• Understøttelse af eventdrevne automatiserings workflows
• Menneskelig godkendelses-workflows til vigtige operationer

12. Design agenter som stateless reducers

Behandl agenter som stateless funktioner, der omdanner input-kontekst til output-handlinger – det forenkler tilstandshåndtering og gør dem forudsigelige og nemme at fejlfinde.

Image URL

Denne konceptuelle tilgang ser agenter som rene funktioner uden intern tilstand, hvilket giver:

• Forudsigelig adfærd for givne inputs
• Nem fejlsporing gennem konteksthistorikken
• Simpel test og validering

Byg til fremtiden

Feltet for AI-agenter udvikler sig hurtigt, men disse kerneprincipper vil forblive relevante, selv når modellerne forbedres. Ved at starte med små, fokuserede agenter, der følger disse principper, kan du skabe systemer, der leverer værdi i dag og tilpasser sig fremtidens udvikling.

Husk, at de mest effektive AI-agenter kombinerer sprogmodellernes ræsonnement med deterministisk kodes pålidelighed – og disse 12 faktorer hjælper dig med at finde balancen.

Sådan brugte FlowHunt 12-faktor metoden

Hos FlowHunt har vi omsat disse principper til praksis ved at udvikle vores egen AI-agent, der automatisk skaber workflow-automatiseringer for vores kunder. Her er, hvordan vi brugte 12-faktor metoden til at bygge et pålideligt, produktionsklart system