Agenci AI do kodowania wibracyjnego: zarządzanie cyklem życia agenta za pomocą interfejsu wiersza poleceń Agents i pakietu ADK 2.0

1. Przegląd

Z tego ćwiczenia dowiesz się, jak używać interfejsu wiersza poleceń agentów do zarządzania całym lokalnym cyklem tworzenia agenta AI. Niezależnie od tego, czy tworzysz otoki istniejących modeli Gemini, czy też budujesz niestandardowych agentów od podstaw za pomocą pakietu Agent Development Kit (ADK 2.0), interfejs wiersza poleceń Agents zapewnia narzędzia do tworzenia szkieletów, budowania, sprawdzania i testowania agentów lokalnie.

Czego się nauczysz

  • Jak zainstalować i skonfigurować agents-cli oraz powiązane z nim umiejętności.
  • Jak utworzyć szkielet nowego projektu agenta.
  • Struktura i kluczowe pliki projektu agenta przepływu pracy w formie wykresu ADK 2.0.
  • Jak uruchamiać automatyczne sprawdzanie kodu i czyszczenie kodu.
  • Jak uruchomić i używać lokalnego środowiska testowego do interaktywnego testowania z automatycznym ponownym wczytywaniem.

Wymagania

  • Python 3.11 lub nowszy
  • system zarządzania pakietami uv,
  • Node.js 18 lub nowszy (jeśli używasz umiejętności agenta kodowania)
  • Antigravity IDE (instalacja i konfiguracja w Google Antigravity)

Wymagania wstępne

W tym ćwiczeniu z programowania zakładamy, że masz już doświadczenie w tych kwestiach:

  • za pomocą terminala i wiersza poleceń.

Nie jest wymagane wcześniejsze doświadczenie z agentami AI ani pakietem ADK 2.0.

2. Konfigurowanie uwierzytelniania i środowiska

Podaj dane uwierzytelniające, aby agent mógł wywoływać modele Gemini.

Opcja 1. Klucz interfejsu Gemini API (Google AI Studio)

Jeśli używasz standardowego klucza interfejsu Gemini API (który możesz uzyskać w Google AI Studio), wyeksportuj go w sesji terminala IDE:

export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE

Opcja 2. Domyślne uwierzytelnianie aplikacji Google Cloud

Jeśli korzystasz z Vertex AI w Google Cloud, uwierzytelnij się za pomocą domyślnych danych logowania aplikacji Google Cloud (ADC) i ustaw aktywny projekt Google Cloud:

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. Konfigurowanie interfejsu CLI i umiejętności agentów

Najpierw zainstaluj narzędzie agents-cli. To narzędzie wykonuje większość pracy związanej z zarządzaniem projektami agentów.

Po zainstalowaniu Antigravity uruchom polecenie konfiguracji bezpośrednio w terminalu.

👉 Otwórz terminal i uruchom:

uvx google-agents-cli setup

To polecenie automatycznie instaluje:

  1. Narzędzie Agents CLI globalnie w systemie.
  2. 7 umiejętności asystenta kodowania w określonych domenach, które Antigravity może wykorzystać, aby pomóc Ci w tworzeniu, budowaniu szkieletów, ocenianiu i wdrażaniu agentów. Te umiejętności są instalowane globalnie w ~/.agents/skills/ i automatycznie wykrywane przez Antigravity.

Uwaga: umiejętności są instalowane w ~/.agents/skills/ i automatycznie wykrywane przez Antigravity. Możesz to sprawdzić za pomocą polecenia /skills lub w ustawieniach Antigravity.

Oczekiwane dane wyjściowe (przycięte):

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

`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. Tworzenie projektu agenta

W tej sekcji utworzysz w pełni ustrukturyzowany katalog projektu przy użyciu szablonu prototypu.

👉 Prompt Antigravity:

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 automatycznie uruchamia polecenie szkieletowe (agents-cli scaffold create customer-support-agent --prototype --yes) i konfiguruje pliki projektu.

5. Poznaj kod agenta

👉 Poproś Antigravity o wyjaśnienie wygenerowanego kodu:

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.

W środowisku IDE Antigravity nowo utworzone pliki projektu i artefakty są wyświetlane bezpośrednio w panelu pomocniczym (po lewej stronie). Możesz go wyświetlić app/agent.py w tym miejscu lub otworzyć w eksploratorze plików IDE, aby przejrzeć wygenerowany kod.

# 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,
)

Kluczowe pojęcia

  • Przepływ pracy i krawędzie: w ADK 2.0 aplikacje agentów są koordynowane jako wykres za pomocą Workflow. Lista edges określa przepływ wykonania, łącząc węzły z START i umożliwiając rozgałęzianie warunkowe na podstawie ścieżek (np. kierowanie do faq_agent w przypadku "shipping" lub do handle_unrelated w przypadku "unrelated").
  • LlmAgent: deklaratywne węzły, które definiują zadania oparte na LLM z określonymi instrukcjami, modelami i danymi wyjściowymi w formacie strukturalnym (output_schema).
  • Węzły i kontekst: funkcje Pythona oznaczone dekoratorem @node (lub funkcje standardowe), które wykonują logikę, uzyskują dostęp do stanu wykonania za pomocą Context i zwracają obiekty Event, aby przekazywać dane i sygnały routingu wzdłuż wykresu.
  • Model: jako domyślny szybki model rozumowania używany jest model „gemini-3.1-flash-lite”.
  • App Wrapper: obiekt App najwyższego poziomu otacza główny przepływ pracy. Narzędzia zewnętrzne, takie jak lokalny plac zabaw, platformy oceny ADK i Agent Runtime, wykrywają i wykonują przepływ pracy za pomocą tego standardowego app interfejsu.

6. Automatyczne sprawdzanie kodu

Przed uruchomieniem lub przetestowaniem agenta warto sprawdzić, czy kod jest przejrzysty i prawidłowo sformatowany.

👉 Prompt Antigravity:

Run linting on my agent project to verify its health.

Antigravity wykona agents-cli lint za kulisami, aby uruchomić wstępnie skonfigurowane testy, sprawdzając importy, składnię i spójność formatowania w plikach.

7. Interaktywne testowanie w narzędziu Playground

Lokalny plac zabaw w internecie to najszybszy sposób na sprawdzenie działania agenta. Jest to interaktywny interfejs czatu, w którym możesz rozmawiać z agentem i sprawdzać realizację zadań w czasie rzeczywistym.

👉 Prompt Antigravity:

Launch the local development playground for my agent.

Antigravity uruchomi lokalny serwer deweloperski (agents-cli playground). Otwórz podany adres URL (zwykle http://127.0.0.1:8080/dev-ui/?app=app) w przeglądarce, wybierz z menu folder app i zacznij rozmawiać z agentem.

Rozpocznij czat z agentem w interfejsie internetowym. Spróbuj zadać pytanie dotyczące dostawy:

How much is standard shipping?

Zwróć uwagę, jak przepływ pracy skutecznie kategoryzuje i kieruje zapytanie do faq_agent, aby uzyskać odpowiedź. Spróbuj też zadać pytanie niezwiązane z tematem, aby sprawdzić, czy przepływ pracy kieruje do handle_unrelated i prawidłowo odmawia odpowiedzi:

What is the weather like?

Testowanie automatycznego doładowywania w czasie rzeczywistym

Możesz zobaczyć, jak zmiany wprowadzone w agencie w czasie rzeczywistym są odzwierciedlane w sekcji Playground.

  1. Zmodyfikuj instrukcję faq_agent w app/agent.py, zadając pytanie Antigravity: 
    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. Wyślij agentowi w playgroundzie nową wiadomość, aby przetestować automatyczne ponowne wczytywanie: 
    How much is standard shipping?
    Środowisko testowe automatycznie przeładuje i wykona zaktualizowany kod w czasie rzeczywistym bez konieczności ponownego uruchamiania serwera. W odpowiedzi powinny pojawić się emotikony.

8. Wykonywanie w wierszu poleceń

W przypadku szybkich testów, automatyzacji lub skryptów możesz poprosić Antigravity o uruchomienie agenta bezpośrednio z terminala.

👉 Prompt Antigravity:

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

Antigravity wykona polecenie zapytania (agents-cli run "How long does standard delivery take?"). Spowoduje to szybkie wnioskowanie jednorazowe i wyświetlenie ostatecznej odpowiedzi agenta wraz ze szczegółami wykonania narzędzia.

9. Czyszczenie

Aby uniknąć pozostawienia niechcianych zasobów w środowisku lokalnym, wykonaj te czynności czyszczenia:

  1. Zatrzymaj serwery lokalne: jeśli serwer agents-cli playground nadal działa, zatrzymaj go w terminalu, naciskając Ctrl + C.
  2. Usuń lokalne pliki projektu: usuń z komputera lokalnego katalog projektu agenta.
rm -rf customer-support-agent

10. Podsumowanie i dalsze kroki

Gratulacje! Udało Ci się zarządzać pełnym cyklem życia lokalnego programowania agenta AI za pomocą interfejsu wiersza poleceń Agents i ADK 2.0.

Czego się dowiedziałeś(-aś)

  • Skonfiguruj narzędzia: zainstaluj interfejs wiersza poleceń agentów i skonfiguruj umiejętności przepływu pracy w określonej domenie na potrzeby Antigravity.
  • Utworzono projekt: utworzono w pełni ustrukturyzowany customer-support-agent projekt przy użyciu standardowych szablonów.
  • Analiza struktury ADK 2.0: omówienie przepływów pracy w postaci wykresów, agentów LLM, węzłów, krawędzi i routingu warunkowego.
  • Zarządzane lokalne usługi zdrowotne: przeprowadzono automatyczne kontrole jakości kodu za pomocą agents-cli lint.
  • Sprawdzone działanie: agent został przetestowany interaktywnie z użyciem funkcji szybkiego przeładowywania w czasie rzeczywistym w środowisku testowym oraz przeprowadzono szybkie testy w wierszu poleceń.

Co dalej?

Teraz, gdy opanujesz już lokalny cykl programowania, możesz rozbudować i wdrożyć swojego agenta w środowisku produkcyjnym:

  • Ocena: oceń agenta na podstawie zbioru ewaluacyjnego za pomocą funkcji agents-cli eval run, aby zmierzyć dokładność i wykryć regresje.
  • Skala chmury klasy korporacyjnej: wdrażanie i obserwowanie: pakuj i wdrażaj agenta w środowiskach produkcyjnych, takich jak środowisko wykonawcze agentów lub Cloud Run, za pomocą agents-cli deploy. Skonfiguruj telemetrię produkcyjną, aby przesyłać strumieniowo logi i ślady wykonania do Cloud Trace i BigQuery.

Dodatkowe materiały