Sezgisel Kodlama Yapay Zeka Ajanları: Ajan Yaşam Döngüsünü Agents CLI ve ADK 2.0 ile Yönetme

1. Genel Bakış

Bu codelab'de, yapay zeka aracısının yerel geliştirme yaşam döngüsünün tamamını yönetmek için Agents CLI'yı nasıl kullanacağınızı öğreneceksiniz. İster mevcut Gemini modellerini sarmalıyor ister Agent Development Kit (ADK 2.0) ile sıfırdan özel aracılar oluşturuyor olun, Agents CLI, aracınızı yerel olarak iskeletini oluşturmak, derlemek, lint uygulamak ve test etmek için gerekli araçları sağlar.

Neler öğreneceksiniz?

  • agents-cli ve ilişkili becerileri yükleme ve ayarlama
  • Yeni bir aracı projesi oluşturma
  • ADK 2.0 grafik iş akışı aracısı projesinin yapısı ve temel dosyaları.
  • Otomatik linting ve kod temizleme işlemlerini çalıştırma
  • Otomatik yeniden yükleme ile etkileşimli test için yerel web playground'u başlatma ve kullanma

İhtiyacınız olanlar

  • Python 3.11 veya sonraki sürümler
  • uv paket yöneticisi
  • Node.js 18+ (kodlama aracısı becerilerini kullanıyorsanız)
  • Antigravity IDE (Google Antigravity'den yükleyip yapılandırın)

Ön koşullar

Bu Codelab'de aşağıdaki konularda bilgi sahibi olduğunuz varsayılmaktadır:

  • Terminal ve komut satırını kullanma

Yapay zeka sistemleri veya ADK 2.0 ile ilgili deneyiminiz olmasına gerek yok.

2. Kimlik Doğrulama ve Ortam Ayarlarını Yapma

Temsilcinin Gemini modellerini çağırması için kimlik doğrulama kimlik bilgilerinizi sağlayın.

1. seçenek: Gemini API anahtarı (Google AI Studio)

Standart bir Gemini API anahtarı kullanıyorsanız (Google AI Studio'dan edinebilirsiniz) IDE terminal oturumunuzda dışa aktarın:

export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE

2. seçenek: Google Cloud Uygulaması Varsayılan Kimlik Bilgileri

Google Cloud'da Vertex AI kullanıyorsanız Google Cloud Uygulama Varsayılan Kimlik Bilgileri (ADC) ile kimlik doğrulayın ve etkin Google Cloud projenizi ayarlayın:

gcloud auth application-default login
gcloud config set project <YOUR_PROJECT_ID>
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=REPLACE-WITH-YOUR-PROJECT_ID # Replace with your project ID
export GOOGLE_CLOUD_LOCATION=REPLACE-WITH-LOCATION # Replace the location

3. Agents CLI ve becerileri ayarlama

İlk adım, agents-cli aracını yüklemektir. Bu araç, temsilci proje yönetiminin zorlu kısımlarını halleder.

Antigravity yüklendikten sonra kurulum komutunu doğrudan terminalinizde çalıştırın.

👉 Bir terminal açıp şunu çalıştırın:

uvx google-agents-cli setup

Bu komut şunları otomatik olarak yükler:

  1. Agents CLI aracını sisteminize global olarak yükleyin.
  2. Antigravity'nin aracı oluşturmanıza, iskeletini oluşturmanıza, değerlendirmenize ve dağıtmanıza yardımcı olmak için kullanabileceği, alana özgü yedi kodlama asistanı becerisi. Bu beceriler ~/.agents/skills/'ye bir kez küresel olarak yüklenir ve Antigravity tarafından otomatik olarak keşfedilir.

Not: Beceriler ~/.agents/skills/ konumuna yüklenir ve Antigravity tarafından otomatik olarak alınır. Bunu /skills komutunu veya Antigravity ayarlarınızı kullanarak doğrulayabilirsiniz.

Beklenen çıktı (kırpılmış):

█▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀ █▀▀ █ █`
`█▀█ █▄█ ██▄ █ ▀█ █ ▄█ █▄▄ █▄ █`

`Your coding agent just got an upgrade.`

`1. Authentication`

`─────────────────`

`✓ Authenticated with Google Cloud`

`2. CLI Installation`

`───────────────────`

`▸ uv tool install google-agents-cli`

`✓ Installed google-agents-cli`

`3. Skills Installation`

`──────────────────────`

`▸ npx -y skills add https://github.com/google/agents-cli -y --all -g`

`◇ Found 7 skills`

`~/.agents/skills/google-agents-cli-adk-code`

`~/.agents/skills/google-agents-cli-deploy`

`~/.agents/skills/google-agents-cli-eval`

`~/.agents/skills/google-agents-cli-observability`

`~/.agents/skills/google-agents-cli-publish`

`~/.agents/skills/google-agents-cli-scaffold`

`~/.agents/skills/google-agents-cli-workflow`

4. Aracı projenizi oluşturma

Bu bölümde, prototip şablonunu kullanarak tamamen yapılandırılmış bir proje dizini oluşturacaksınız.

👉 Antigravity'yi isteme:

Use ADK 2.0 to create a new graph workflow agent project called
customer-support-agent. I don't want to deploy this agent, so you can skip
the deployment files. The workflow should act as a customer support
representative for a shipping company. It should first classify if the user
query is related to shipping (rates, tracking, delivery, returns) or
unrelated. If it is related to shipping, route to a shipping FAQ agent to
answer the question. If it is unrelated, route to a node that politely
declines to answer.

Antigravity, iskele komutunu (agents-cli scaffold create customer-support-agent --prototype --yes) otomatik olarak çalıştırır ve proje dosyalarını sizin için ayarlar.

5. Agent Code'u keşfetme

👉 Antigravity'den oluşturulan kodu açıklamasını isteyin:

Read and explain the project structure of my new agent project. Walk me
through how `app/agent.py` is configured, highlighting the role of the
tools, nodes, edges, and the root Workflow.

Antigravity IDE'de yeni oluşturulan proje dosyaları ve yapılar doğrudan yardımcı bölmede (sol taraf) gösterilir. app/agent.py konumunda görüntüleyebilir veya iskelet kodu incelemek için IDE dosya gezgininden açabilirsiniz.

# app/agent.py

from __future__ import annotations

from typing import Any, Literal

from google.adk.agents.context import Context
from google.adk.apps.app import App
from google.adk.events.event import Event
from google.adk.workflow import Edge
from google.adk.workflow import Workflow
from google.adk.workflow.agents.llm_agent import LlmAgent
from google.adk.workflow.node import node
from pydantic import BaseModel
from pydantic import Field


class InquiryCategory(BaseModel):
  category: Literal['shipping', 'unrelated'] = Field(
      description=(
          'Determine if the user query is related to shipping (rates, tracking,'
          ' delivery times, returns) or unrelated.'
      )
  )


def save_query(node_input: str):
  """Saves user query in state for downstream nodes."""
  yield Event(data=node_input, state={'user_query': node_input})


categorize_agent = LlmAgent(
    name='categorize',
    model='gemini-3.1-flash-lite',
    instruction='You are an expert classifier. Categorize the user query.',
    output_key='inquiry_category',
    output_schema=InquiryCategory,
)


@node
def route_inquiry(ctx: Context, node_input: Any):
  """Routes the workflow based on the classified category."""
  category_data = ctx.state.get('inquiry_category', {})
  category = category_data.get('category', 'unrelated')
  query = ctx.state.get('user_query', '')
  yield Event(data=query, route=category)


faq_agent = LlmAgent(
    name='shipping_faq',
    model='gemini-3.1-flash-lite'',
    instruction="""You are a customer support representative for a shipping company. Answer user questions based ONLY on the shipping FAQ below. Do not answer questions outside of the FAQ.
    
    SHIPPING FAQ:
    - Rates: Standard shipping is $5.99. Express shipping is $12.99. Orders
      over $50 qualify for free standard shipping.
    - Tracking: You can track your order by entering your tracking number on
      our website's tracking page.
    - Delivery Times: Standard delivery takes 3-5 business days. Express
      delivery takes 1-2 business days.
    - Returns: We offer free returns within 30 days of delivery. Please make
      sure the item is in its original condition.
    """,
)


@node
def handle_unrelated(ctx: Context, node_input: Any):
  """Handles unrelated inquiries politely."""
  yield Event(
      data=(
          'I am sorry, I am a shipping customer support assistant and can only'
          ' answer questions related to our shipping FAQ.'
      )
  )


root_agent = Workflow(
    name='customer_support_workflow',
    edges=[
        *Edge.chain('START', save_query, categorize_agent, route_inquiry),
        (route_inquiry, faq_agent, 'shipping'),
        (route_inquiry, handle_unrelated, 'unrelated'),
    ],
)

app = App(
    name='customer_support_agent',
    root_agent=root_agent,
)

Temel Kavramlar

  • İş Akışı ve Kenarlar: ADK 2.0'da aracı uygulamaları, Workflow kullanılarak grafik olarak düzenlenir. edges listesi, yürütme akışını tanımlar, düğümleri START ile birbirine bağlar ve rotalara göre koşullu dallanmayı etkinleştirir (ör. "shipping" üzerinde faq_agent veya "unrelated" üzerinde handle_unrelated yönlendirmesi).
  • LlmAgent: Belirli talimatlar, modeller ve yapılandırılmış çıkışlarla (output_schema) LLM destekli görevleri tanımlayan bildirimsel düğümler.
  • Düğümler ve Bağlam: @node ile süslenmiş (veya standart) Python işlevleri. Bu işlevler mantık yürütür, Context aracılığıyla yürütme durumuna erişir ve verileri iletmek ve yönlendirme sinyallerini grafikte geçirmek için Event nesneleri oluşturur.
  • Model: Varsayılan hızlı akıl yürütme modeli olarak "gemini-3.1-flash-lite" kullanılır.
  • Uygulama sarmalayıcısı: En üst düzeydeki App nesnesi, kök iş akışını sarmalar. Yerel playground, ADK değerlendirme koşumları ve Agent Runtime gibi harici araçlar, iş akışınızı bu standartlaştırılmış app arayüzü üzerinden keşfedip yürütür.

6. Otomatik Linting

Aracınızı çalıştırmadan veya test etmeden önce kodunuzun temiz olduğundan ve doğru şekilde biçimlendirildiğinden emin olmanız iyi bir uygulamadır.

👉 Antigravity istemi:

Run linting on my agent project to verify its health.

Antigravity, dosyalarınızdaki içe aktarma, söz dizimi ve biçimlendirme tutarlılığını doğrulayan, önceden yapılandırılmış kontrolleri çalıştırmak için agents-cli lint komutunu arka planda yürütür.

7. Playground ile etkileşimli test

Yerel web playground, temsilcinizin davranışını doğrulamanın en hızlı yoludur. Bu arayüzde, aracınızla sohbet edebilir ve araç yürütmelerini anlık olarak inceleyebilirsiniz.

👉 Antigravity istemi:

Launch the local development playground for my agent.

Antigravity, yerel geliştirme sunucusunu (agents-cli playground) başlatır. Web tarayıcınızda sağlanan URL'yi (genellikle http://127.0.0.1:8080/dev-ui/?app=app) açın, açılır listeden app klasörünü seçerek temsilcinizle sohbet etmeye başlayın.

Web arayüzünde temsilcinizle sohbet etmeye başlayın. Kargoyla ilgili bir soru sormayı deneyin:

How much is standard shipping?

İş akışının, yanıtlamak için faq_agent'ya başarılı bir şekilde nasıl sınıflandırdığını ve yönlendirdiğini inceleyin. Ayrıca, iş akışının handle_unrelated yönlendirdiğini ve yanıt vermeyi doğru şekilde reddettiğini doğrulamak için alakasız bir soru sormayı deneyin:

What is the weather like?

Gerçek zamanlı otomatik yeniden yüklemeyi test etme

Ajanınızda yapılan gerçek zamanlı düzenlemelerin Playground'a nasıl yansıdığını görebilirsiniz.

  1. Antigravity'ye sorarak app/agent.py içindeki faq_agent talimatını değiştirin: 
    Modify the faq_agent instruction in app/agent.py to make the shipping rates
response more playful and enthusiastic. Add some emojis and highlight the
free shipping threshold.
  2. Otomatik yeniden yüklemeyi test etmek için oyun alanındaki aracıya yeni bir mesaj gönderin: 
    How much is standard shipping?
    Playground, sunucuyu yeniden başlatmaya gerek kalmadan güncellenen kodunuzu otomatik olarak yeniden yükler ve anında yürütür. Yanıtı aldığınızda bazı emojiler görürsünüz.

8. Komut Satırı Yürütme

Hızlı testler, otomasyon veya komut dosyası oluşturma için Antigravity'den aracınızı doğrudan terminalden çalıştırmasını isteyebilirsiniz.

👉 Antigravity'yi isteme:

Run a CLI query asking my agent how long standard delivery takes.

Antigravity, sorgu komutunu (agents-cli run "How long does standard delivery take?") yürütür. Bu işlem, hızlı bir tek dönüşlü çıkarım gerçekleştirir ve aracının son yanıtını araç yürütme ayrıntılarıyla birlikte yazdırır.

9. Temizleme

Yerel ortamınızda istenmeyen kaynaklar bırakmamak için aşağıdaki temizleme adımlarını uygulayın:

  1. Yerel sunucuları durdurma: agents-cli playground sunucunuz hâlâ çalışıyorsa terminalinizde Ctrl + C tuşuna basarak durdurun.
  2. Yerel Proje Dosyalarını Kaldırın: İskele oluşturulmuş aracı proje dizinini yerel makinenizden silin.
rm -rf customer-support-agent

10. Özet ve Sonraki Adımlar

Tebrikler! Agents CLI ve ADK 2.0'ı kullanarak bir yapay zeka aracının uçtan uca yerel geliştirme yaşam döngüsünü başarıyla yönetmiş olmalısınız.

Öğrendikleriniz

  • Araçlarınızı ayarlama: Agents KSA'yı yükledik ve Antigravity için alana özel iş akışı becerilerini yapılandırdık.
  • Proje iskeleti oluşturma: Standartlaştırılmış şablonları kullanarak tamamen yapılandırılmış bir customer-support-agent projesi oluşturma.
  • ADK 2.0 Yapısını Analiz Etme: Grafik iş akışlarını, LLM aracılarını, düğümleri, kenarları ve koşullu yönlendirmeyi inceledim.
  • Yönetilen Yerel Sağlık: agents-cli lint kullanarak otomatik kod kalitesi kontrolleri gerçekleştirdi.
  • Doğrulanmış Davranış: Aracı, oyun alanı üzerinden gerçek zamanlı olarak yeniden yükleyerek etkileşimli bir şekilde test ettim ve komut satırında hızlı testler gerçekleştirdim.

Sırada ne var?

Yerel geliştirme döngüsünde ustalaştığınıza göre, aracınızı nasıl genişletebileceğiniz ve üretime hazır hale getirebileceğiniz aşağıda açıklanmıştır:

  • Değerlendirme: Doğruluğu ölçmek ve gerilemeleri bulmak için agents-cli eval run kullanarak aracınızı bir değerlendirme grubuyla karşılaştırın.
  • Kurumsal ölçekte bulut: Dağıtım ve Gözlemlenebilirlik: agents-cli deploy kullanarak aracınızı Agent Runtime veya Cloud Run gibi üretim ortamlarına paketleyin ve dağıtın. Günlükleri ve yürütme izlerini Cloud Trace ve BigQuery'ye aktarmak için üretim telemetrisini ayarlayın.

Ek Kaynaklar