Agenttisilmukka ja arkkitehtuuri

Jokainen AI-agentti perustuu samaan perussilmukkaan: havainnoi, suunnittele, toimi, arvioi ja tallenna. Tämä oppitunti pureutuu silmukan rakenteeseen ja agentin arkkitehtuuriin.

Agenttisilmukka: OPAES

Agenttisilmukka (Agent Loop)

Agenttisilmukka on agentin ydinprosessi: Observe (havainnoi konteksti) → Plan (suunnittele seuraava askel) → Act (suorita työkalu) → Evaluate (arvioi tulos) → Store (tallenna opittu). Silmukkaa toistetaan, kunnes tavoite saavutetaan tai pysähtymisehto täyttyy.

Agenttisilmukkatext

Tavoite
→ Havainnoi konteksti (Observe)
→ Suunnittele seuraava askel (Plan)
→ Suorita työkalu (Act)
→ Arvioi tulos (Evaluate)
→ Tallenna muistiin (Store)
→ Jatka tai lopeta

1. Observe — Havainnoi

Agentti kerää tietoa ympäristöstään:

Lukee tiedostoja
Tarkistaa aikaisemmat tulokset
Hakee relevanttia kontekstia muistista
Tarkistaa rajoitteet (AGENTS.md)

2. Plan — Suunnittele

Agentti päättää seuraavan toiminnon:

Mikä työkalu on sopivin?
Mitä parametreja käytetään?
Mitä riskejä on?

3. Act — Toimi

Agentti suorittaa suunnitellun toiminnon:

Kutsuu työkalua (CLI, API, tiedosto-operaatio)
Vastaanottaa tuloksen

4. Evaluate — Arvioi

Agentti arvioi tuloksen:

Onnistuiko toiminto?
Edenikö tavoitteen suuntaan?
Tarvitaanko korjaavia toimenpiteitä?

5. Store — Tallenna

Agentti tallentaa oleellisen tiedon:

Päivittää työmuistia
Tallentaa pitkäkestoiseen muistiin tarvittaessa

Agentin arkkitehtuurikomponentit

Agentin perusarkkitehtuuripython

class Agent:
  """Yksinkertainen agentin perusrakenne."""

  def __init__(self, model, tools, system_prompt, max_iterations=10):
      self.model = model          # LLM-malli
      self.tools = tools          # Käytettävissä olevat työkalut
      self.system_prompt = system_prompt  # Persoonallisuus ja säännöt
      self.max_iterations = max_iterations
      self.memory = []            # Työmuisti

  async def run(self, goal: str) -> str:
      """Suorita agenttisilmukka."""
      for i in range(self.max_iterations):
          # Observe: kokoa konteksti
          context = self.observe(goal)

          # Plan + Act: LLM päättää ja suorittaa
          response = await self.model.generate(
              system=self.system_prompt,
              messages=self.memory + [context],
              tools=self.tools,
          )

          # Evaluate: tarkista tulos
          if response.is_complete:
              return response.final_answer

          # Store: tallenna muistiin
          self.memory.append(response)

          # Act: suorita työkalukutsut
          for tool_call in response.tool_calls:
              result = await self.execute_tool(tool_call)
              self.memory.append(result)

      return "Max iterations reached"

Pysähtymisehdot

Agentti tarvitsee selkeät pysähtymisehdot:

Ehto	Kuvaus	Toimenpide
Tavoite saavutettu	Kaikki AC:t täyttyvät	Palauta tulos
Iteraatioraja	Max kierrokset ylitetty	Raportoi tila
Virhe	Kriittinen virhe toiminnossa	Pysähdy ja raportoi
Käyttäjän keskeytys	Ihminen pysäyttää	Tallenna tila
Blocked	3 yrityksen sääntö	Pyydä ihmisen ohjausta
Budjetti	Token- tai kustannuskatto ylittyy	Pysähdy ja raportoi kulutus

Kaksi rajaa, ei yhtä

Iteraatioraja ja budjettiraja eivät ole sama asia. Silmukka voi pysyä alle kymmenen kierroksen ja silti polttaa ison summan, jos jokainen kierros vetää satojatuhansia tokeneita kontekstia. Aseta molemmat: montako kierrosta ja paljonko saa kulua. Ilman jälkimmäistä “agentti jäi päälle yöksi” on laskutapahtuma, ei anekdootti.

Pro tip

Suunnitteluperiaate: jokaisen silmukan iteraation pitää olla auditoitava. Jos et voi selittää miksi agentti teki tietyn toiminnon, agentti ei ole tuotantovalmis. Kirjaa jokainen Observe → Plan → Act → Evaluate -sykli lokiin.

Agentti käytännössä: gemini_agent.py

Alla on yksinkertaistettu versio todellisesta agentista:

Agentin pääsilmukkapython

MAX_TOOL_ROUNDS = 8  # Silmukan raja — katso "Pysähtymisehdot" yllä

async def run_chat_loop(model, tools, system_prompt):
  """Agentin interaktiivinen silmukka."""
  history = []

  while True:
      user_input = input("You: ")
      if user_input.lower() in ["exit", "quit"]:
          break

      history.append({"role": "user", "content": user_input})

      # Agentti voi käyttää useita työkaluja per kierros — mutta ei rajatta
      rounds = 0
      while rounds < MAX_TOOL_ROUNDS:
          rounds += 1
          response = await model.generate(
              system=system_prompt,
              messages=history,
              tools=tools,
          )

          if response.text and not response.tool_calls:
              # Agentti on valmis vastaamaan
              print(f"Agent: {response.text}")
              history.append({
                  "role": "assistant",
                  "content": response.text
              })
              break

          # Suorita työkalukutsut
          for call in response.tool_calls:
              result = execute_tool(call.name, call.args)
              history.append({
                  "role": "tool",
                  "name": call.name,
                  "content": result
              })
              print(f"  [Tool: {call.name}] → {result[:100]}...")

      else:
          # Silmukka loppui rajaan, ei valmiiseen vastaukseen.
          # Tämä on normaali lopputulos, ei poikkeus — raportoi se.
          print(f"  [BLOCKED] {MAX_TOOL_ROUNDS} kierrosta täynnä, ei valmista vastausta")
          history.append({
              "role": "assistant",
              "content": f"Keskeytin {MAX_TOOL_ROUNDS} työkalukierroksen jälkeen.",
          })

Pro tip

Huomaa while rounds < MAX_TOOL_ROUNDS ja siihen liittyvä else. Pythonissa silmukan else ajetaan, kun silmukka päättyy ilman breakia — eli juuri silloin kun raja tuli vastaan. Se on lyhin tapa erottaa “valmis” ja “loppui kesken”, ja se ero on koko viikon toimituksen ydin: agentti, joka ei osaa kertoa kumpi tapahtui, ei ole valmis.

Arkkitehtuurin komponenttijako

Komponentti	Funktio	Tarkoitus
System prompt	`build_system_prompt()`	Agentin persoonallisuus ja säännöt
Työkalurekisteri	`build_tool_declarations()`	Mitä työkaluja on käytettävissä
Silmukkakontrolleri	`run_chat_loop()`	Observe-plan-act-sykli
Pysähtymisehdot	Iteraatioraja, exit-komento	Milloin lopettaa

Quiz

Mikä on agenttisilmukan Evaluate-vaiheen tärkein tehtävä?

Piirrä agenttisilmukka

Piirrä (paperille tai digitaalisesti) agenttisilmukkakaavio todelliselle tehtävälle, esim. 'Korjaa failaavat testit'. Merkitse jokainen vaihe (Observe → Plan → Act → Evaluate → Store) ja näytä 2–3 iteraatiota. Tunnista pysähtymisehdot.

Yhteenveto

Agenttisilmukka: Observe → Plan → Act → Evaluate → Store
Pysähtymisehdot ovat kriittiset: tavoite, iteraatioraja, virhe, blocked
Jokainen iteraatio pitää olla auditoitava
Arkkitehtuuri koostuu: system prompt, työkalut, silmukka, pysäytys
Seuraavaksi vertaamme CLI- ja MCP-työkaluja agenteille