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ń Agents do zarządzania całym lokalnym cyklem tworzenia agenta AI. Niezależnie od tego, czy tworzysz otokę dla istniejących modeli Gemini, czy budujesz niestandardowych agentów od podstaw za pomocą pakietu Agent Development Kit (ADK 2.0), interfejs wiersza poleceń Agents udostępnia narzędzia do tworzenia szkieletu, kompilowania, 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 grafu ADK 2.0.
  • Jak uruchamiać automatyczne sprawdzanie kodu i czyszczenie kodu.
  • Jak uruchamiać i używać lokalnego internetowego środowiska testowego do interaktywnego testowania z automatycznym przeładowywaniem.

Wymagania

  • Python 3.11 lub nowszy
  • uv
  • Node.js 18+ (jeśli używasz umiejętności agenta kodowania)
  • Antigravity IDE (zainstaluj i skonfiguruj w Google Antigravity)

Wymagania wstępne

W tym ćwiczeniu zakładamy, że masz doświadczenie w:

  • korzystaniu z terminala i wiersza poleceń.

Nie jest wymagane wcześniejsze doświadczenie z agentami AI ani 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 używasz Vertex AI w Google Cloud, uwierzytelnij się za pomocą domyślnego uwierzytelniania aplikacji Google Cloud (ADC) i ustaw aktywny projekt w chmurze 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 wiersza poleceń Agents i umiejętności

Pierwszym krokiem jest zainstalowanie narzędzia agents-cli. To narzędzie zajmuje się zarządzaniem projektem agenta.

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

👉 Otwórz terminal i uruchom:

uvx google-agents-cli setup

To polecenie automatycznie zainstaluje:

  1. Narzędzie Agents CLI globalnie w systemie.
  2. 7 umiejętności asystenta kodowania w określonych domenach, których Antigravity może używać do tworzenia, tworzenia szkieletu, oceniania i wdrażania 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 ustawień Antigravity.

Oczekiwane dane wyjściowe (skrócone):

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

`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 za pomocą szablonu prototypu.

👉 Poproś 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 uruchomi polecenie tworzenia szkieletu (agents-cli scaffold create customer-support-agent --prototype --yes) i skonfiguruje pliki projektu.

5. Przeglądanie kodu 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 Antigravity IDE nowo utworzone pliki projektu i artefakty są wyświetlane bezpośrednio w panelu pomocniczym (po lewej stronie). Możesz tam wyświetlić plik app/agent.py lub otworzyć go w eksploratorze plików IDE, aby przejrzeć kod szkieletu.

# 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 graf za pomocą Workflow. Lista edges określa przepływ wykonywania, łączy węzły od START i umożliwia rozgałęzianie warunkowe na podstawie tras (np. przekierowanie do faq_agent w przypadku "shipping" lub handle_unrelated w przypadku "unrelated").
  • LlmAgent: deklaratywne węzły, które określają zadania oparte na LLM z konkretnymi instrukcjami, modelami i ustrukturyzowanymi danymi wyjściowymi (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 generują obiekty Event, aby przekazywać dane i sygnały routingu wzdłuż grafu.
  • Model: `gemini-3.1-flash-lite` jest używany jako domyślny model rozumowania.
  • Otoka aplikacji: obiekt najwyższego poziomu App otacza główny przepływ pracy. Narzędzia zewnętrzne, takie jak lokalne środowisko testowe, narzędzia do oceny ADK i środowisko wykonawcze agentów, wykrywają i wykonują przepływ pracy za pomocą tego standardowego interfejsu app.

6. Automatyczne sprawdzanie kodu

Przed uruchomieniem lub przetestowaniem agenta warto upewnić się, że kod jest czysty i prawidłowo sformatowany.

👉 Poproś Antigravity:

Run linting on my agent project to verify its health.

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

7. Interaktywne testowanie w środowisku testowym

Lokalne internetowe środowisko testowe to najszybszy sposób na sprawdzenie działania agenta. Udostępnia interaktywny interfejs czatu, w którym możesz rozmawiać z agentem i sprawdzać wykonywanie narzędzi w czasie rzeczywistym.

👉 Poproś 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 folder app z menu, aby rozpocząć rozmowę z agentem.

Rozpocznij rozmowę z agentem w interfejsie internetowym. Spróbuj zadać pytanie dotyczące wysyłki:

How much is standard shipping?

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

What is the weather like?

Testowanie automatycznego przeładowywania w czasie rzeczywistym

Możesz zobaczyć, jak zmiany wprowadzane w agencie w czasie rzeczywistym są odzwierciedlane w środowisku testowym.

  1. Zmodyfikuj instrukcję faq_agent w app/agent.py, prosząc 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 nową wiadomość do agenta w środowisku testowym, aby przetestować automatyczne przeładowywanie: 
    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 się teraz pojawić emotikony.

8. Wykonywanie z wiersza poleceń

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

👉 Poproś 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 w jednym kroku i wyświetli ostateczną odpowiedź 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ć całym lokalnym cyklem tworzenia agenta AI za pomocą interfejsu wiersza poleceń agentów i pakietu ADK 2.0.

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

  • Konfigurowanie narzędzi: zainstalowano interfejs wiersza poleceń Agents i skonfigurowano umiejętności przepływu pracy w określonych domenach dla Antigravity.
  • Tworzenie szkieletu projektu: utworzono w pełni ustrukturyzowany projekt customer-support-agent za pomocą standardowych szablonów.
  • Analizowanie struktury ADK 2.0: przeanalizowano przepływy pracy grafu, agentów LLM, węzły, krawędzie i routing warunkowy.
  • Zarządzanie stanem lokalnym: przeprowadzono automatyczne sprawdzanie jakości kodu za pomocą agents-cli lint.
  • Sprawdzanie działania: przetestowano agenta interaktywnie za pomocą przeładowywania na gorąco w czasie rzeczywistym w środowisku testowym i przeprowadzono szybkie testy w wierszu poleceń.

Co dalej?

Teraz, gdy opanowałeś(-aś) lokalny cykl tworzenia, możesz rozszerzyć i wdrożyć agenta:

  • Ocena: oceń agenta na podstawie zbioru danych do oceny za pomocą agents-cli eval run, aby zmierzyć dokładność i znaleźć regresje.
  • Skala chmury dla przedsiębiorstw: wdrożenie i obserwacja: spakuj i wdróż 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