ADK ile prototiplerden temsilcilere

1. Genel Bakış

Yapay zeka ile geliştirme yolculuğuna bugün nereden başlayabilirsiniz? Çoğumuz için bu süreç genellikle basit bir soruyla başlar: "Model, üzerinde düşündüğüm bu sorunu çözmeme gerçekten yardımcı olabilir mi?" Google AI Studio tam da bu noktada devreye girer. Bu platformda her şeyin prototipini hızlıca oluşturabilirsiniz. Mutfak tadilatı yapmak istiyorum ve Gemini'ın bu konuda yardımcı olabileceğini düşünüyorum. Ancak mühendis olduğum için genel yüklenici olarak çalışmıyorum. Ne isteyeceğimi bile bilmiyorum. Yönetmelikler, armatürler vb. gibi dikkate alınması gereken çok fazla şey var. Bu nedenle, Gemini'ın bizim için süper ayrıntılı bir istem oluşturmasını, ardından tam bir yenileme planı oluşturmasını ve yeniden modellemeyi görselleştirmesini sağlayalım. Ama bir saniye. Bu noktadan sonra işletmelerin ölçeklenmesine nasıl yardımcı olabilirim? AGENTS!!! yazın.

Temsilci, sahip olduğu araçları ve bağlamı kullanarak amaca dayalı bir işlem gerçekleştirmek için yapay zeka modeliyle konuşan ve gerçekliğe dayalı bağımsız karar verme yeteneğine sahip olan bağımsız bir programdır.

Aracı Geliştirme Kiti (ADK)

Agent Development Kit (ADK), yapay zeka temsilcilerini geliştirmek ve dağıtmak için esnek ve modüler bir çerçevedir. ADK, birden fazla farklı aracı örneğini bir Çoklu Aracı Sistemi (MAS) içinde birleştirerek gelişmiş uygulamalar oluşturmayı destekler.

ADK'da çok agent'lı sistem, genellikle bir hiyerarşi oluşturan farklı agent'ların daha büyük bir hedefe ulaşmak için birlikte çalıştığı veya koordine olduğu bir uygulamadır. Uygulamanızı bu şekilde yapılandırmak, geliştirilmiş modülerlik, uzmanlaşma, yeniden kullanılabilirlik, sürdürülebilirlik ve özel iş akışı aracılarını kullanarak yapılandırılmış kontrol akışları tanımlama gibi önemli avantajlar sunar.

Ne oluşturacaksınız?

PROMPT prototipimizden temsilci oluşturmaya geçmeye hazır mısınız? Mutfak yenileme projesi için teklif belgesi oluşturmaya yardımcı olacak bir temsilci oluşturacağız. Bu laboratuvar kapsamında şunları yapacaksınız:

  1. ADK ile tadilat teklifi belgesi oluşturmak için basit bir temsilci oluşturma
  2. Oluşturulan Tadilat Teklifi Belgesi'ni bir Cloud Storage paketinde saklama
  3. Aracıyı Cloud Shell'de ve aracı web çıkışında test etme

Şartlar

  • Chrome veya Firefox gibi bir tarayıcı
  • Faturalandırmanın etkin olduğu bir Google Cloud projesi.

2. Başlamadan önce

Proje oluşturma

  1. Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
  2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin .
  3. Ayrıca, bu makaleyi okuyorsanız ve Google Cloud'u kullanmaya başlamanıza ve ADK'yı kullanmanıza yardımcı olacak bazı krediler almak istiyorsanız kredileri kullanmak için bu bağlantıyı kullanın.
  4. Bu teklifi kullanmak için buradakitalimatları uygulayabilirsiniz. Bu bağlantının yalnızca 15 Temmuz 2025'e kadar kullanılabileceğini lütfen unutmayın.
  5. Bu bağlantıyı tıklayarak Cloud Shell'i etkinleştirin. Cloud Shell'deki ilgili düğmeyi tıklayarak Cloud Shell Terminali (bulut komutlarını çalıştırmak için) ile Düzenleyici (projeleri oluşturmak için) arasında geçiş yapabilirsiniz.
  6. Cloud Shell'e bağlandıktan sonra aşağıdaki komutu kullanarak kimliğinizin doğrulanmış olduğunu ve projenin proje kimliğinize ayarlandığını kontrol edin:
gcloud auth list
  1. gcloud komutunun projeniz hakkında bilgi sahibi olduğunu doğrulamak için Cloud Shell'de aşağıdaki komutu çalıştırın.
gcloud config list project
  1. Projeniz ayarlanmamışsa ayarlamak için aşağıdaki komutu kullanın:
gcloud config set project <YOUR_PROJECT_ID>
  1. Python 3.9 veya sonraki sürümlerin yüklü olduğundan emin olun.

Diğer gcloud komutları ve kullanımı için belgelere bakın.

3. Prototip

Google AI Studio'ya gidin. İsteminizi yazmaya başlayın. İstemim:

I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.

En iyi yanıtı almak için sağ taraftaki parametreleri ayarlayın ve yapılandırın.

Gemini, bu basit açıklamaya dayanarak yenileme işlemine başlamam için inanılmaz derecede ayrıntılı bir istem oluşturdu. Bu sayede, AI Studio'dan ve modellerimizden daha iyi yanıtlar almak için Gemini'ı kullanıyoruz. Kullanım alanınıza bağlı olarak kullanmak üzere farklı modeller de seçebilirsiniz.

Gemini 2.5 Pro'yu seçtik. Bu bir Düşünme modeli olduğundan, uzun biçimli analizler ve ayrıntılı dokümanlar için daha fazla çıkış jetonu (bu durumda 65 bin jetona kadar) elde ederiz. Gemini 2.5 Pro'yu etkinleştirdiğinizde Gemini düşünce kutusu gösterilir. Bu model, doğal akıl yürütme özelliklerine sahiptir ve uzun bağlam isteklerini işleyebilir.

Yanıtın snippet'ini aşağıda görebilirsiniz:

4e4361663df80964.png

AI Studio, verilerimi analiz etti ve dolaplar, tezgahlar, arka panel, zemin, lavabo, uyum, renk paleti ve malzeme seçimi gibi tüm bu öğeleri üretti. Gemini kaynakları bile alıntılıyor.

Şimdi de farklı bir istemle fikrin nasıl hayata geçirildiğini görmeye çalışın.

  1. Bu istemi kopyalayıp istem düzenleyiciye yapıştırın:
Add flat and circular light accessories above the island area for my current kitchen in the attached image.
  1. Mevcut mutfağınızın bir resmini ekleyin (veya örnek mutfak resmimi kullanabilirsiniz).
  2. Resim oluşturma özelliğine erişebilmek için modeli "Gemini 2.0 Flash Preview Image Generation" olarak değiştirin.

Şu çıkışı aldım:

fb33e7b1f6560a0c.png

Gemini'ın gücü işte burada devreye girer.

Videoları anlamaktan doğal görüntü oluşturmaya, Google Arama ile gerçek bilgileri temellendirmeye kadar yalnızca Gemini ile yapılabilecek şeyler var.

AI Studio'da bu prototipi alabilir, API anahtarını kullanabilir ve Vertex AI ADK'nın gücünü kullanarak tam bir aracı uygulamaya dönüştürebilirsiniz.

4. ADK kurulumu

Şimdi de "Başlamadan önce" bölümünde etkinleştirdiğimiz Cloud Shell terminaline geçelim:

  1. Sanal ortam oluşturma ve etkinleştirme (önerilir)

Cloud Shell Terminal'inizden bir sanal ortam oluşturun:

python -m venv .venv

Sanal ortamı etkinleştirin:

source .venv/bin/activate
  1. ADK'yı yükleme
pip install google-adk

5. Proje Yapısı

  1. Cloud Shell Terminal'den, istediğiniz proje konumunda yapay zeka aracılı uygulamalarınız için bir kök dizin oluşturun:
mkdir agentic-apps
  1. Ana dizinde, mevcut projemize özel bir klasör oluşturun:
mkdir renovation-agent
  1. Cloud Shell düzenleyiciye gidin ve dosyaları oluşturarak (başlangıçta boş) aşağıdaki proje yapısını oluşturun:
renovation-agent/
        __init__.py
        agent.py
        requirements.txt
        .env

6. Kaynak Kod

  1. "init.py" dosyasına gidip aşağıdaki içerikle güncelleyin:
from . import agent
  1. agent.py dosyasına gidin ve dosyayı aşağıdaki yoldaki içerikle güncelleyin:

agent.py dosyasında gerekli bağımlılıkları içe aktarıyor, yapılandırma parametrelerini .env dosyasından alıyor ve bir teklif belgesi oluşturup Cloud Storage paketinde depolayan root_agent'ı tanımlıyoruz. Cloud Storage adımını gerçekleştirmek için store_pdf adlı bir araç kullanırız.

NOT: PDF şu anda FORMATSIZDIR. Topluluk geliştiricisinin PR'sine göre aşağıdaki snippet buraya eklenmiştir [test edilmemiştir]. Bu snippet'i store_pdf yöntemine ekleyebilirsiniz:

doc = SimpleDocTemplate(
        pdf_buffer,
        pagesize=letter,
        rightMargin=0.75 * inch,
        leftMargin=0.75 * inch,
        topMargin=0.75 * inch,
        bottomMargin=0.75 * inch
    )

    styles = getSampleStyleSheet()
    story = []

    # --- CUSTOM STYLES FOR HEADERS ---
    # Define a new style for section headers
    styles.add(ParagraphStyle(name='SectionHeader',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold', # Make it bolder
                              fontSize=14,               # Make it slightly larger
                              leading=16,                # Line spacing
                              spaceAfter=0.15 * inch,    # Space after the header
                              spaceBefore=0.25 * inch,   # Space before the header
                              textColor=black            # Ensure color is bright/black (default is usually black, but explicit is good)
                             ))

    # Define a style for the main document title
    styles.add(ParagraphStyle(name='DocumentTitle',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold',
                              fontSize=20,
                              leading=24,
                              spaceAfter=0.25 * inch,
                              alignment=TA_CENTER, # Center align the title
                              textColor=black
                             ))
    # ---------------------------------

    paragraphs_raw = pdf_text.split('\n\n')

    # Heuristic for the garbled line issue (as before, temporary)
    if paragraphs_raw and len(paragraphs_raw[-1]) < 50 and any(char in paragraphs_raw[-1] for char in ['io', 'og', 'al', 'op']):
         logger.warning("Detected potentially garbled last paragraph. Attempting to trim/omit.")
         paragraphs_raw[-1] = "11. Entire Agreement:\nThis proposal constitutes the entire agreement between the parties and supersedes all prior discussions and agreements."


    for i, para_text in enumerate(paragraphs_raw):
        para_text = para_text.strip()
        if not para_text:
            continue

        # Special handling for the main document title (PROPOSAL DOCUMENT)
        if i == 0 and "PROPOSAL DOCUMENT" in para_text.upper():
            p = Paragraph("PROPOSAL DOCUMENT", styles['DocumentTitle'])
            story.append(p)
            story.append(Spacer(1, 0.15 * inch)) # Add space after the title
            # Skip the rest of this initial block if it's just the title
            remaining_text_lines = para_text.splitlines()[1:]
            if remaining_text_lines:
                formatted_text = "<br/>".join(remaining_text_lines)
                p = Paragraph(formatted_text, styles['Normal'])
                story.append(p)
                story.append(Spacer(1, 0.1 * inch))
            continue # Move to the next paragraph

        # Check if the paragraph looks like a section header (e.g., starts with a number and dot or just bold text)
        # This is a heuristic and might need fine-tuning based on actual proposal content variability.
        is_section_header = False
        # Check for numbered sections (e.g., "1. Scope of Work:")
        if para_text.startswith(('1.', '2.', '3.', '4.', '5.', '6.', '7.', '8.', '9.', '10.', '11.')):
            is_section_header = True
        # Check for Exhibit headers (e.g., "Exhibit A: Cabinet Design") or Roman numeral headings
        elif para_text.startswith(('Exhibit ', 'I.', 'II.', 'III.', 'IV.', 'V.', 'VI.', 'VII.')):
            is_section_header = True
        # Check for specific known headers
        elif para_text.strip().upper() in ["IN WITNESS WHEREOF,", "EXHIBITS:"]:
            is_section_header = True


        if is_section_header:
            p = Paragraph(para_text, styles['SectionHeader'])
            story.append(p)
            # No additional Spacer here, as SectionHeader style has spaceAfter
        else:
            formatted_text = para_text.replace('\n', '<br/>')
            p = Paragraph(formatted_text, styles['Normal'])
            story.append(p)
            story.append(Spacer(1, 0.1 * inch)) # Standard space after body paragraphs

    doc.build(story)

    pdf_buffer.seek(0)

    # Upload the PDF to GCS
    storage_client = storage.Client()
    bucket = storage_client.bucket(STORAGE_BUCKET)
    blob = bucket.blob(PROPOSAL_DOCUMENT_FILE_NAME)

    blob.upload_from_file(pdf_buffer, content_type="application/pdf")

    logger.info(f"Successfully uploaded PDF to gs://{STORAGE_BUCKET}/{PROPOSAL_DOCUMENT_FILE_NAME}")

except Exception as e:
    logger.error(f"Error writing text to PDF and uploading: {e}")
    raise
finally:
    if 'pdf_buffer' in locals():
        pdf_buffer.close()
return "Successfully uploaded PDF to GCS!!"
  1. Cloud Storage paketinizin olduğundan emin olun

Bu, temsilcinin oluşturduğu teklif belgesini saklamak için kullanılır. Veri deposunu oluşturun ve Vertex AI ile oluşturduğumuz temsilci sistemin erişebilmesi için erişim sağlayın. Bunu şu şekilde yapabilirsiniz:

https://cloud.google.com/storage/docs/creating-buckets#console

Paketinizi "next-demo-store" olarak adlandırın. Farklı bir ad verirseniz .env dosyasındaki (ENV Değişkenleri Kurulumu adımında) STORAGE_BUCKET değerini güncellemeyi unutmayın.

  1. Pakete erişimi ayarlamak için Cloud Storage konsoluna ve Storage paketine gidin (örneğimizde paket adı "next-demo-storage" şeklindedir: https://console.cloud.google.com/storage/browser/next-demo-storage).

İzinler -> Ana Hesapları Görüntüle -> Erişim İzni Ver'e gidin. Asıl öğeleri "allUsers", rolü ise "Storage Nesne Kullanıcısı" olarak seçin.

Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.
  1. Bağımlılık listesi oluşturma

Tüm bağımlılıkları requirements.txt dosyasında listeleyin. Bunu repo'dan kopyalayabilirsiniz.

Tek temsilcili sistem kaynak kodu açıklaması

agent.py dosyası, Agent Development Kit'i (ADK) kullanarak mutfak yenileme çoklu aracı sistemimizin yapısını ve davranışını tanımlar. Temel bileşenleri inceleyelim:

Aracı Tanımı

Kök aracı (Orchestrator): proposal_agent

root_agent, bu tek aracı sisteminin düzenleyicisi olarak işlev görür. İlk yenileme isteğini alır ve isteğin ihtiyaçlarına göre hangi araçların kullanılacağını belirler.

Ardından root_agent, araçlardan gelen yanıtları toplayıp birleştirerek kullanıcıya kapsamlı bir yanıt verir. Bu örnekte yalnızca bir araç ("store_pdf") var.

7. Veri Akışı ve Temel Kavramlar

Kullanıcı, ADK arayüzü (terminal veya web kullanıcı arayüzü) üzerinden bir istek başlatır.

  1. İstek, root_agent tarafından alınır.
  2. root_agent, isteği analiz eder ve gerektiğinde araca yönlendirir.
  3. "store_pdf" aracı, yenilenen metin içeriğini bir PDF dosyasına yazmak ve ardından Google Cloud Storage'a yüklemek için tasarlanmıştır.
  4. Bu işlem, yanıtı root_agent'a döndürür.
  5. root_agent, yanıtları birleştirir ve kullanıcıya nihai bir çıktı sağlar.

LLM'ler (Büyük Dil Modelleri)

Aracıların metin oluşturma, soruları yanıtlama ve akıl yürütme görevlerini yerine getirme konusunda LLM'lere büyük ölçüde güvendiği görülmektedir. LLM'ler, aracıların kullanıcı isteklerini anlama ve yanıtlama becerisinin"beyinleridir". Bu uygulamada Gemini 2.5 kullanılmaktadır.

Google Cloud Storage

Oluşturulan yenileme teklifi belgelerini depolamak için kullanılır. Bir paket oluşturmanız ve temsilcilerin bu pakete erişmesi için gerekli izinleri vermeniz gerekir.

Cloud Run (isteğe bağlı)

OrderingAgent, AlloyDB ile arayüz oluşturmak için Cloud Run işlevini kullanır. Cloud Run, HTTP isteklerine yanıt olarak kod yürütmek için sunucusuz bir ortam sağlar.

AlloyDB

OrderingAgent'ı kullanıyorsanız sipariş bilgilerini depolamak için bir AlloyDB veritabanı oluşturmanız gerekir.

.env dosyası

.env dosyası, API anahtarları, veritabanı kimlik bilgileri ve paket adları gibi hassas bilgileri depolar. Bu dosyanın güvenliğini sağlamak ve deponuza işlememek çok önemlidir. Ayrıca aracıların ve Google Cloud projenizin yapılandırma ayarlarını da depolar. root_agent veya destekleyici işlevler genellikle bu dosyadan değerleri okur. Gerekli tüm değişkenlerin .env dosyasında doğru şekilde ayarlandığından emin olun. Cloud Storage paket adı da buna dahildir.

8. Model Kurulumu

Aracınızın kullanıcı isteklerini anlama ve yanıt oluşturma özelliği, Büyük Dil Modeli (LLM) tarafından desteklenir. Aracınızın bu harici LLM hizmetine güvenli aramalar yapması gerekir. Bu işlem için kimlik doğrulama kimlik bilgileri gerekir. Geçerli kimlik doğrulama olmadan LLM hizmeti, aracının isteklerini reddeder ve aracı çalışamaz.

  1. Google AI Studio'dan API anahtarı alın.
  2. .env dosyasını ayarladığınız sonraki adımda <<your API KEY>> kısmını gerçek API ANAHTARI değerinizle değiştirin.

9. ENV değişkenlerini ayarlama

  1. Bu repo'daki .env şablon dosyasında parametreler için değerlerinizi ayarlayın. Benim durumumda .env dosyasında şu değişkenler var:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION = us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT = <<your project id>>
PROJECT_ID = <<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>

Yer tutucuları kendi değerlerinizle değiştirin.

10. Temsilcinizi Çalıştırma

  1. Terminali kullanarak aracı projenizin üst dizinine gidin:
cd agentic-apps/renovation-agent
  1. Tüm bağımlıları yükleme
pip install -r requirements.txt
  1. Aracı yürütmek için Cloud Shell terminalinizde aşağıdaki komutu çalıştırabilirsiniz:
adk run .
  1. ADK ile sağlanan bir web kullanıcı arayüzünde çalıştırmak için aşağıdaki komutu çalıştırabilirsiniz:

Not: Bu komutu aracı projesi klasörünüzün DIŞINDA çalıştırıp bir adım dışarı çıkmanız ve ardından çalıştırmanız gerekir:

adk web
  1. Aşağıdaki istemlerle test edin:
user>> 

Hello. Generate Proposal Document for the kitchen remodel requirement in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.

11. Sonuç

adk run . komutu için sonuç aşağıdaki gibidir"

2703603a907329ae.png

ae56b38cc6da9afe.png

...

91452a4de933a75b.png

Yenileme Teklifi dokümanının Cloud Storage paketinde oluşturulup oluşturulmadığını doğrulayabilirsiniz.

12. Cloud Run'a dağıt

  1. Proje kök klasöründe Dockerfile adlı bir dosya oluşturun:
cd agentic-apps/renovation-agent
  1. GitHub deposundaki içeriği kopyalayın.
https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/Dockerfile

bu Dockerfile dosyasına kopyalayın.

  1. Aşağıdaki komutu kullanarak Cloud Run'a dağıtın:
adk deploy cloud_run --project=abis-345004 --region=us-central1 --service_name=renovation-agent --app_name=renovation-app --with_ui .

Bu kadar basit. Dağıtım tamamlandıktan sonra uç noktanızı terminalde görürsünüz ve kullanmaya başlayabilirsiniz.

13. Temizleme

Bu yayında kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini istemiyorsanız şu adımları uygulayın:

  1. Google Cloud Console'da Kaynakları yönetin sayfasına gidin.
  2. Proje listesinde silmek istediğiniz projeyi seçin ve Sil'i tıklayın.
  3. İletişim kutusunda proje kimliğini yazın ve projeyi silmek için Kapat'ı tıklayın.

14. Tebrikler

Tebrikler! ADK'yı kullanarak çoklu aracı uygulamanızı başarıyla oluşturup etkileşimde bulundunuz. Çoklu temsilci sistemi, teklif oluşturma, izin kontrolü ve sipariş durumu takibi gibi görevleri otomatikleştirerek mutfak yenileme sürecini kolaylaştırmak için tasarlanmıştır. Her aracının belirli bir rolü vardır ve root_agent, kapsamlı bir çözüm sunmak için etkinliklerini koordine eder. Sistem, işlevlerini sunmak için LLM'lerden, Google Cloud hizmetlerinden ve muhtemelen harici API'lerden yararlanır. Ürün belgelerinin bağlantısını burada bulabilirsiniz.