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

Pro-vinkki

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

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
      while True:
          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]}...")

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

Tietovisa

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