Lab 04: Wprowadzenie narzędzi

Opis

Narzędzia (tools) rozszerzają możliwości agentów - pozwalają na integrację z zewnętrznymi API, wyszukiwanie w internecie, wykonywanie kodu i wiele więcej. W tym labie poznamy podstawy tools i stworzymy agenta integrującego się z API Krajowego Rejestru Sądowego.

W warsztatach skupimy się na dwóch kluczowych tools:

• OpenAPI Spec Tool - integracja z REST API (bezpieczny setup przez Azure API Management)
• Bing Search Tool - wyszukiwanie aktualnych informacji w internecie

Dodatkowo wspomnimy o:

• Model Context Protocol (MCP) - obecnie w preview, ecosystem narzędzi community

Pełna dokumentacja: Wszystkie dostępne tools i szczegóły techniczne znajdziesz w oficjalnej dokumentacji Microsoft Learn

Jak działają tools?

Tools to opcjonalne możliwości dodawane do agenta. Model sam decyduje kiedy i które tool wywołać na podstawie user query i context.

Decision Flow

User query → Model analizuje intent → Wybiera tool(s) → Wykonuje → Zwraca results → Model generuje odpowiedź

Kluczowe zasady:

• Model może wywołać tool wielokrotnie w jednym run
• Może wywołać różne tools sekwencyjnie
• Tool outputs są widoczne tylko dla modelu (nie bezpośrednio dla użytkownika)
• Model kompiluje finalna odpowiedź na podstawie tool outputs

Tool Scope

Tools można dodawać na 3 poziomach:

Tip: Dodawaj tools tylko tam gdzie potrzebne. Mniej tools = szybsza decyzja modelu i niższe koszty.

Tool Choice Parameter

Możesz kontrolować deterministycznie które tool model użyje:

Przykład wymuszenia Bing Search:

run = project_client.agents.runs.create(
    thread_id=thread.id,
    agent_id=agent.id,
    tool_choice={"type": "bing_grounding"}  # MUSI użyć Bing
)

Katalog narzędzi

Azure AI Foundry oferuje szeroki katalog tools. Poniżej key facts o najważniejszych.

Knowledge Tools

Dostęp do danych i wiedzy.

Action Tools

Wykonywanie akcji i integracja z systemami.

Specialized Tools

Pełna lista tools: Microsoft Learn - Tools Overview

OpenAPI Spec Tool

Integruj istniejące REST APIs zero code changes. Model wywołuje endpointy bezpośrednio na podstawie OpenAPI specification.

Kiedy używać?

✅ Używaj gdy:

• Masz istniejący OpenAPI 3.0 spec
• API jest RESTful
• Potrzebujesz szybkiej integracji
• API nie wymaga złożonej logiki biznesowej

❌ Nie używaj gdy:

• Potrzebujesz stateful operations (użyj Azure Functions)
• API wymaga complex authentication flows

Przykład OpenAPI Spec

Minimalny przykład dla prostego Weather API (format JSON):

{
  "openapi": "3.0.0",
  "info": {
    "title": "Weather API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.weather.com"
    }
  ],
  "paths": {
    "/current": {
      "get": {
        "operationId": "getCurrentWeather",
        "summary": "Get current weather",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "temperature": {
                      "type": "number"
                    },
                    "condition": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Ważne: Każda operacja MUSI mieć unikalne operationId - to nazwa którą model używa do wywołania funkcji.

Dodanie do agenta w Portal

Krok 1: Przygotuj OpenAPI spec (tylko JSON format)

Krok 2: W Azure AI Foundry Portal:

• Agents → Wybrany agent → Actions
• Add tool → Function
• Upload OpenAPI spec JSON lub wklej URL

Krok 3: Konfiguracja authentication (jeśli wymagane):

• API Key: Header X-API-Key lub Authorization
• Managed Identity: Dla Azure services

Krok 4: Zapisz i przetestuj w Playground

Authentication

Najczęściej używany: API Key w header.

W Portal przy dodawaniu tool:

• Authentication type: API Key
• Header name: Ocp-Apim-Subscription-Key (dla APIM) lub Authorization
• API Key value: Twój klucz

Tip: Dla produkcji używaj Managed Identity zamiast API keys gdzie możliwe.

Bing Search Tool - teoria

Dodaj agentowi dostęp do real-time public web data.

Kiedy używać?

✅ Używaj dla:

• Aktualne wiadomości i wydarzenia
• Fakty które się zmieniają (pogoda, kursy walut)
• Queries z keywords: “latest”, “today”, “current”, “recent”

❌ NIE używaj dla:

• Podsumowywania całych stron web
• Scraping konkretnych domen (użyj Bing Custom Search)

Dodanie do agenta w Portal

Krok 1: W Azure AI Foundry Portal:

• Agents → Wybrany agent → Knowledge -> Add
• Add tool → Bing Grounding

Krok 2: Konfiguracja połączenia:

• W warsztatach: Dostaniesz gotowe credentials (Bing connection string)
• Wklej connection string
• Zapisz

Krok 3: Modyfikacja Instructions agenta:

Używaj Bing Grounding dla zapytań o aktualne informacje:
- "dzisiejsza pogoda"
- "najnowsze wiadomości"
- "obecny kurs EUR/PLN"

Krok 4: Test w Playground:

• “Jakie są dzisiejsze top tech news?”
• Obserwuj w thread logs kiedy agent wywołuje Bing
• Zobacz czy zmiana

Display Requirements (WYMAGANE PRAWNIE!)

Niebezpieczeństwo: Bing Search ma prawne Use and Display Requirements. MUSISZ:

1. Wyświetlać citations (źródła) z linkami
2. Wyświetlać Bing search query URL

Nieprzestrzeganie = naruszenie terms of use!

Jak wyświetlać citations:

• Agent automatycznie zwraca annotations w odpowiedzi
• W Portal Playground: citations są widoczne jako linki
• W kodzie: dostęp przez url_citation_annotations

Ograniczenia

Modele które NIE wspierają Bing:

• ❌ gpt-4o-mini-2024-07-18
• ❌ gpt-5 series

Compliance:

• ⚠️ Dane opuszczają Azure compliance boundary
• ⚠️ Nie działa z VPN/private endpoints (tylko public networking)

Model Context Protocol (MCP)

MCP = open standard dla integracji tools z LLMs. Pozwala na łatwe dodawanie tools z ecosystem community.

Czym jest MCP?

Model Context Protocol to:

• 🌐 Open standard - nie vendor lock-in
• 🔌 Plug-and-play - gotowe integracje (GitHub, Slack, Jira, etc.)
• 🛡️ Approval flow - kontrola nad wykonywanymi akcjami

Architektura:

Agent → MCP Tool (client) → Remote MCP Server → External service

Status: Preview

Ważne: MCP jest obecnie w preview. API może się zmieniać.

Approval Flow

MCP tools domyślnie wymagają approval dla bezpieczeństwa:

Niebezpieczeństwo: Zawsze sprawdzaj MCP tool calls przed approval. Niebezpieczne serwery mogą wykonywać niepożądane akcje.

Więcej informacji

• MCP Documentation
• Model Context Protocol Spec

🔬 Lab: Agent z OpenAPI Tool (KRS API)

Czas na praktykę! Stworzymy agenta który potrafi sprawdzać dane firm w Krajowym Rejestrze Sądowym używając OpenAPI tool i Azure API Management.

Cel laboratorium

Nauczyć agenta wywoływać REST API (KRS) przez Azure API Management używając OpenAPI specification.

Architektura

Agent → OpenAPI Tool → Azure APIM (subscription key) → KRS API (api-krs.ms.gov.pl)

Krok 1: Sprawdź Azure API Management

Azure API Management został już wdrożony w infrastrukturze Terraform. Sprawdź czy masz dostęp:

1. Zaloguj się do Azure Portal
2. Przejdź do swojej Resource Group
3. Znajdź zasób API Management (nazwa: apim-{company}-{suffix})
4. Sprawdź że masz rolę Reader (powinieneś widzieć zasób)

Krok 2: Sprawdź KRS API w APIM

API KRS zostało już zaimportowane do APIM przez prowadzącego.

Endpoint: GET /api/krs/OdpisAktualny/{krs}?rejestr={rejestr}&format=json

Sprawdź dostępność API:

1. W Azure Portal → Twój APIM → APIs
2. Znajdź KRS API na liście
3. Kliknij na API i zobacz dostępne operations:
   • getKrsOdpisAktualny - pobiera odpis aktualny

Tip: APIM automatycznie parsuje OpenAPI spec i tworzy operations z operationId.

Krok 3: Pobierz Subscription Key od prowadzącego

API Management wymaga subscription key dla bezpieczeństwa.

Ważne: Subscription key dostaniesz od prowadzącego warsztatu. Nie musisz go sam generować.

Skopiuj otrzymany klucz - użyjesz go w następnym kroku przy konfiguracji agenta.

Krok 4: Eksport OpenAPI spec z APIM (JSON)

Teraz wyeksportujjesz OpenAPI spec z APIM jako JSON, żeby agent miał poprawny URL i operation IDs.

1. W APIM → APIs → KRS API
2. Kliknij … (trzej kropki obok API name)
3. Export → OpenAPI v3 (JSON)
4. Pobierz plik (np. krs-api-from-apim.json)

Ten plik zawiera:

• ✅ Poprawny server URL: https://apim-xxx.azure-api.net/krs
• ✅ operationId: getKrsOdpisAktualny
• ✅ Full schema

Krok 5: Utwórz Connection (Custom keys)

Zanim utworzymy agenta, skonfigurujemy Custom keys connection w projekcie - lepsze zarządzanie credentials.

1. W Azure AI Foundry Portal, kliknij Management center (po lewo na dole)
2. Wejdź w Project (Twój projekt, nie Resource)
3. Connected resources → + New connection
4. Wybierz Custom keys*
5. Configuration:
   • Connection name: krs-apim-connection-<INICJAŁ>
   • Przewiń w dół do sekcji Connection key
   • Credentials (dodaj DWA klucze):
     • Pierwszy klucz:
       • Key: Ocp-Apim-Subscription-Key
       • Value: Wklej subscription key otrzymany od prowadzącego (z kroku 3)
       • Is secret: Zaznacz (checkbox)
     • Kliknij + Add key value pair i dodaj drugi:
       • Key: subscription-key
       • Value: Ten sam subscription key co powyżej
       • Is secret: Zaznacz (checkbox)
6. Create

Tip: Connection przechowuje credentials centralnie - możesz reużywać w wielu agents/tools.

Krok 6: Utworzenie agenta w Portal

1. W Azure AI Foundry Portal → Twój projekt
2. Agents → + New agent
3. Configuration:
   • Deployment: gpt-4.1-mini- (z Lab 04)
   • Name: KRS-Agent
   • Description: Agent do sprawdzania danych firm w KRS

Krok 7: Dodanie OpenAPI Action do agenta

1. W prawym panelu agenta → Actions
2. Add action → OpenAPI 3.0 specification tool
3. Tool details:
   • Name: krs_api (bez spacji, unikalna nazwa)
   • Description: Retrieves company data from Polish National Court Register (KRS) based on KRS number
4. OpenAPI spec:
   • Otwórz plik krs-api-from-apim.json (wyeksportowany z APIM w kroku 4) w edytorze tekstowym
   • Skopiuj całą jego zawartość
   • Wklej zawartość JSON do pola tekstowego w portalu
5. Authentication:
   • Type: Connection
   • Connection: Wybierz **krs-apim-connection-** (utworzony w kroku 5)
6. Add

Ważne: Name i Description są używane przez model do decyzji czy użyć tego action. Dobry opis = lepsze decyzje!

Tip: Używając Connection, nie musisz pamiętać o API key - jest zarządzany przez projekt.

Krok 8: Modyfikacja Instructions agenta

W polu Instructions dodaj:

Jesteś asystentem pomagającym sprawdzać dane firm w Krajowym Rejestrze Sądowym.

Twoje narzędzie:
- getKrsOdpisAktualny - pobiera aktualny odpis z KRS

Parametry:
- krs: numer KRS (10 cyfr, np. 0000123456)
- rejestr: ZAWSZE używaj "P" (rejestr przedsiębiorców)

Gdy użytkownik poda numer KRS:
1. Wywołaj getKrsOdpisAktualny z parametrem rejestr="P"
2. Przedstaw dane w czytelny sposób używając formatowania Markdown
3. Jeśli API zwróci 404 - powiedz że firma nie znaleziona

ZASADY:
- ZAWSZE używaj narzędzia - nie wymyślaj danych!
- Odpowiadaj TYLKO na pytania dotyczące danych z KRS
- Formatuj odpowiedzi używając Markdown (nagłówki, listy, pogrubienia)

Save konfigurację agenta.

Krok 9: Test agenta

W Playground zadaj pytanie:

Sprawdź dane firmy o numerze KRS 0000028860

Tip: KRS 0000028860 to Orlen S.A. Możesz użyć dowolnego innego numeru KRS.

Obserwuj:

1. Agent analizuje zapytanie
2. Identyfikuje numer KRS: 0000028860
3. Wywołuje tool getKrsOdpisAktualny z parametrami:
   • krs: “0000028860”
   • rejestr: “P”
4. Otrzymuje odpowiedź JSON z API
5. Formatuje i przedstawia dane użytkownikowi

Krok 10: Sprawdź Thread Logs

1. W Playground kliknij View logs lub zakładkę Logs
2. Znajdź sekcję Tool calls
3. Zobacz szczegóły:
   • Tool name: getKrsOdpisAktualny
   • Arguments: {"krs": "0000028860", "rejestr": "P"}
   • Response: Full JSON z KRS API
   • Status: success/failed

Co pokazują logi:

• Jak agent zdecydował wywołać tool
• Jakie parametry przekazał
• Jaka była odpowiedź API
• Jak agent skompilował finalną odpowiedź

Tip: Thread logs to najlepsze narzędzie do debugowania - widzisz dokładnie co się dzieje “pod maską”.

Krok 11: Test z błędnym numerem KRS

Zadaj pytanie z nieistniejącym numerem:

Sprawdź firmę KRS 0000000001

Agent powinien:

1. Wywołać API
2. Otrzymać 404 (not found)
3. Odpowiedzieć: “Firma o numerze KRS 0000000001 nie została znaleziona w rejestrze”

NIE powinien:

• Wymyślać danych
• Odpowiadać “nie wiem” bez wywołania API

Co osiągnęliśmy?

✅ Zintegrowaliśmy agenta z zewnętrznym REST API (KRS) ✅ Użyliśmy Azure API Management jako secure gateway ✅ Skonfigurowaliśmy OpenAPI Tool bez pisania kodu ✅ Nauczyliśmy agenta kiedy używać tool (przez instructions) ✅ Zweryfikowaliśmy wywołania w thread logs

Krok 12: Zmień format odpowiedzi na tabelę

Twoje zadanie:

Zmodyfikuj Instructions agenta KRS-Agent tak, aby:

• Odpowiadał w postaci tabeli Markdown
• Pokazywał tylko wybrane, najważniejsze dane firmy (sam zdecyduj które)
• Odmawiał odpowiedzi na pytania poza zakresem KRS

Test po modyfikacji:

1. Zadaj to samo pytanie: “Sprawdź dane firmy o numerze KRS 0000028860”
2. Sprawdź czy agent odpowiada w formie tabeli
3. Zapytaj: “Jaka jest pogoda w Warszawie?” - agent powinien odmówić

Pytania do przemyślenia:

• Jak napisać instructions żeby agent używał formatu tabeli?
• Które dane z API są najważniejsze do pokazania?
• Jak nauczyć agenta odmawiać pytań poza zakresem?

Krok 13: Testuj edge cases

Przetestuj jak agent radzi sobie z nietypowymi sytuacjami:

• Niepoprawny format numeru KRS (np. 123 zamiast 0000000123)
• Pytanie bez numeru KRS: “Sprawdź Microsoft”
• Jak agent reaguje?
• Czy agent umie wyszukiwać wiele firm na raz?

Podsumowanie

W tym labie poznaliśmy:

✅ Podstawy tools: Jak model decyduje o wywołaniach

✅ Tool scope: Agent/Thread/Run levels

✅ OpenAPI Spec Tool: Integracja z REST APIs zero code

✅ Bing Search Tool: Real-time web data (w warsztatach z gotowymi credentials)

✅ MCP (Preview): Ecosystem narzędzi community

✅ Praktyka: Agent z OpenAPI tool i Azure APIM (KRS API)

Kluczowe wnioski:

• OpenAPI Tool = najszybsza integracja z istniejącymi APIs
• APIM = secure gateway z subscription keys i rate limiting
• Instructions = kluczowe dla nauczenia agenta KIEDY używać tool
• Thread logs = essential debugging tool