Den 12-faktors AI-agenten: Bygg effektiva AI-system som skalar

Vad kännetecknar en effektiv AI-agent?

Innan vi dyker ner i faktorerna, låt oss klargöra vad vi menar med “AI-agenter”. I grunden är detta system som kan tolka naturliga språkbegäranden, fatta beslut baserat på kontext och utföra specifika åtgärder via verktyg eller API:er – allt samtidigt som de upprätthåller sammanhängande, pågående interaktioner.

De mest kraftfulla agenterna kombinerar språkmodellernas resonemangsförmåga med deterministisk kods tillförlitlighet. Men att hitta denna balans kräver noggranna designval, vilket är precis vad dessa faktorer adresserar.

De 12 faktorerna för att bygga robusta AI-agenter

1. Behärska konvertering från naturligt språk till verktygsanrop

Förmågan att omvandla naturliga språkbegäranden till strukturerade verktygsanrop är kärnan i agentens funktionalitet. Det är detta som gör det möjligt för en agent att ta ett enkelt kommando som “skapa en betalningslänk på 750 $ till Terri för AI Tinkerers-träffen i februari” och omvandla det till ett korrekt formaterat API-anrop.

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

Nyckeln till att detta fungerar pålitligt är att använda deterministisk kod för att hantera det strukturerade svaret från din språkmodell. Validera alltid API-payloads innan körning för att förebygga fel, och säkerställ att din LLM returnerar konsekventa JSON-format som kan tolkas pålitligt.

2. Äg dina prompts helt och hållet

Dina prompts är gränssnittet mellan din applikation och språkmodellen – behandla dem som förstklassig kod. Även om ramverk som abstraherar prompts kan verka bekväma, döljer de ofta hur instruktioner skickas till LLM, vilket gör finjustering svårt eller omöjligt.

Behåll istället direkt kontroll över dina prompts genom att skriva dem explicit:

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?
  "#
}

Denna metod ger dig flera fördelar:

• Full kontroll att skriva precisa instruktioner anpassade till ditt specifika användningsområde
• Möjlighet att bygga utvärderingar och tester för dina prompts som för all annan kod
• Transparens så att du exakt ser vad LLM tar emot
• Frihet att iterera utifrån prestandamått

3. Designa ditt kontextfönster strategiskt

Kontextfönstret fungerar som LLM:ens indata, inklusive prompts, konversationshistorik och extern data. Optimering av detta fönster förbättrar prestanda och token-effektivitet.

Image URL

Gå bortom standardiserade meddelandeformat till egna strukturer som maximerar informationsdensitet:

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

Denna metod erbjuder flera fördelar:

• Minskad token-användning med kompakta format
• Bättre filtrering av känslig data innan det skickas till LLM
• Flexibilitet att experimentera med format som förbättrar LLM-förståelsen

4. Implementera verktyg som strukturerade utdata

I grunden är verktyg helt enkelt JSON-utdata från LLM som triggar deterministiska åtgärder i din kod. Detta skapar en tydlig separation mellan AI-beslutsfattande och exekveringslogik.

Definiera verktygsscheman tydligt:

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 sedan pålitlig tolkning av LLM:s JSON-utdata, använd deterministisk kod för att utföra åtgärderna och mata tillbaka resultaten i kontexten för iterativa arbetsflöden.

5. Ena exekverings- och affärstillstånd

Många agentramverk separerar exekveringstillstånd (t.ex. aktuell steg i ett flöde) från affärstillstånd (t.ex. historik av verktygsanrop och deras resultat). Denna separation tillför onödig komplexitet.

Spara istället allt tillstånd direkt i kontextfönstret, och härled exekveringstillståndet från sekvensen av 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>

Detta enade arbetssätt ger:

• Enkelhet med en enda sanningskälla för tillstånd
• Bättre felsökning med hela historiken på ett ställe
• Enkel återhämtning genom att återuppta från valfri punkt genom att ladda tråden

Att ta AI-agenter till produktion

6. Designa API:er för start, paus och återuppta

Produktionsklara agenter måste integreras sömlöst med externa system, kunna pausas för långvariga uppgifter och återupptas när de triggas av webhooks eller andra händelser.

Implementera API:er som möjliggör start, paus och återuppta av agenter, med robust lagring av tillstånd mellan operationer. Detta möjliggör:

• Flexibelt stöd för asynkrona arbetsflöden
• Smidig integration med webhooks och andra system
• Tillförlitlig återupptagning efter avbrott utan omstart

7. Möjliggör mänskligt samarbete via verktygsanrop

AI-agenter behöver ofta mänsklig input vid viktiga beslut eller otydliga situationer. Med strukturerade verktygsanrop blir denna interaktion smidig:

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

Denna metod ger tydlig specificering av interaktionstyp och brådska, stödjer input från flera användare och kombineras väl med API:er för hållbara arbetsflöden.

8. Kontrollera din agents flöde

Egen kontroll av flödet ger dig möjlighet att pausa för mänskligt godkännande, cacha resultat eller införa ratenbegränsning – och därmed anpassa agentens beteende till dina 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 detta tillvägagångssätt får du:

• Avbrottsmöjlighet för att pausa för mänsklig granskning före kritiska åtgärder
• Anpassningsmöjligheter för loggning, cachning eller summering
• Tillförlitlig hantering av långvariga uppgifter

9. Komprimera fel i kontexten för självläkning

Att inkludera fel direkt i kontextfönstret gör att AI-agenter kan lära sig av misslyckanden och justera sitt arbetssätt:

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

För att detta ska fungera effektivt:

• Begränsa antalet försök för att undvika oändliga loopar
• Eskalera till människor efter upprepade fel
• Formatera fel tydligt så att LLM förstår vad som gick fel

Arkitektonisk bästa praxis

10. Bygg små, fokuserade agenter

Små agenter som hanterar 3–20 steg bibehåller överskådliga kontextfönster, vilket förbättrar LLM-prestanda och tillförlitlighet. Detta ger:

• Tydlighet med väldefinierat omfång för varje agent
• Minskad risk att agenten tappar fokus
• Enklare testning och validering av specifika funktioner

Image URL

I takt med att LLM:er fortsätter förbättras kan dessa små agenter utöka sitt omfång samtidigt som kvaliteten bibehålls, vilket garanterar långsiktig skalbarhet.

11. Möjliggör triggers från flera källor

Gör dina agenter tillgängliga genom att tillåta triggers från Slack, e-post eller eventsystem – och möt användarna där de redan arbetar.

Implementera API:er som startar agenter från olika kanaler och låter dem svara via samma medium. Detta möjliggör:

• Bättre tillgänglighet genom integration med användarens föredragna plattformar
• Stöd för händelsedriven automation
• Mänskliga godkännandeflöden för viktiga operationer

12. Designa agenter som stateless reducers

Behandla agenter som stateless-funktioner som omvandlar indata-kontext till utdata-åtgärder för att förenkla tillståndshanteringen, vilket gör dem förutsägbara och enklare att felsöka.

Image URL

Detta konceptuella tillvägagångssätt ser agenter som rena funktioner utan internt tillstånd och ger:

• Förutsägbart beteende för givna indata
• Enklare spårning av problem genom kontexthistorik
• Smidigare testning och validering

Bygg för framtiden

Fältet AI-agenter utvecklas snabbt, men dessa grundprinciper kommer vara relevanta även när underliggande modeller förbättras. Genom att börja med små, fokuserade agenter som följer dessa principer kan du skapa system som levererar värde idag och anpassar sig till framtida framsteg.

Kom ihåg att de mest effektiva AI-agenterna kombinerar språkmodellernas resonemangsförmåga med deterministisk kods tillförlitlighet – och dessa 12 faktorer hjälper dig att hitta den balansen.

Så använde FlowHunt 12-faktorsmetodiken

På FlowHunt har vi omsatt dessa principer i praktiken genom att utveckla vår egen AI-agent som automatiskt skapar arbetsflödesautomationer för våra kunder. Här är hur vi tillämpade 12-faktorsmetodiken för att bygga ett tillförlitligt, produktionsklart system