AI Agents · Lektion

Teilbare Agent-Tools entwerfen

Standards für Tool-Schemas, Dokumentationsanforderungen und Paketierung zur Wiederverwendung.

Lektion 1 von 413 Schritte

Teilbare Agent-Tools entwerfen ist eine kostenlose AI Agents-Lektion auf CoddyKit. Dies ist Lektion 1 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des AI Agents-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der AI Agents-Kurs umfasst insgesamt 4 Lektionen.

Was macht ein Tool gemeinsam nutzbar

Ein gemeinsam nutzbares Agent-Tool ist eines, das andere Entwickler in ihre Agentensysteme integrieren können, ohne den Quellcode lesen zu müssen. Es verfügt über ein klares, maschinenlesbares Schema, eine für Menschen verständliche README, eindeutig definierte Fehlercodes und ein vorhersehbares Verhalten. Betrachten Sie es als Bibliothek, nicht als Skript.

Standards für Tool-Schemas

Jedes gemeinsam nutzbare Tool benötigt ein Schema, das seine Eingaben, Ausgaben und Metadaten beschreibt. Das Schema ist der Vertrag zwischen dem Tool-Autor und dem Agenten, der es verwendet. Orientieren Sie es an JSON Schema, um maximale Kompatibilität mit allen gängigen Agent-Frameworks zu erreichen.

TOOL_SCHEMA_TEMPLATE = {
    'name': 'get_weather',
    'description': 'Returns current weather conditions for a city. '
                   'Use when the user asks about weather or temperature.',
    'version': '1.2.0',
    'parameters': {
        'type': 'object',
        'properties': {
            'city': {
                'type': 'string',
                'description': 'City name (e.g., London, Tokyo)',
                'minLength': 1,
                'maxLength': 100
            },
            'units': {
                'type': 'string',
                'enum': ['celsius', 'fahrenheit'],
                'default': 'celsius',
                'description': 'Temperature unit'
            }
        },
        'required': ['city']
    },
    'returns': {
        'type': 'object',
        'properties': {
            'temperature': {'type': 'number'},
            'condition': {'type': 'string'},
            'humidity_pct': {'type': 'number'}
        }
    },
    'rate_limit': {'calls_per_minute': 60}
}

if __name__ == '__main__':
    print(f"Tool: {TOOL_SCHEMA_TEMPLATE['name']} (v{TOOL_SCHEMA_TEMPLATE['version']})")
    print('Description:', TOOL_SCHEMA_TEMPLATE['description'])
    print('Required params:', TOOL_SCHEMA_TEMPLATE['parameters']['required'])

Fehlercodes

Definieren Sie ein standardisiertes Format für Fehlerantworten. Jedes Tool sollte dieselbe Fehlerstruktur zurückgeben: code, message und optionale details. So kann der Agent Fehler programmgesteuert behandeln, ohne die Interna des Tools zu kennen.

from enum import Enum

class ToolErrorCode(Enum):
    INVALID_PARAMS = 'INVALID_PARAMS'
    NOT_FOUND = 'NOT_FOUND'
    RATE_LIMITED = 'RATE_LIMITED'
    UPSTREAM_ERROR = 'UPSTREAM_ERROR'
    TIMEOUT = 'TIMEOUT'
    UNAUTHORISED = 'UNAUTHORISED'
    INTERNAL_ERROR = 'INTERNAL_ERROR'

class ToolError(Exception):
    def __init__(self, code: ToolErrorCode, message: str, details: dict = None):
        self.code = code
        self.message = message
        self.details = details or {}

    def to_dict(self) -> dict:
        return {
            'error': True,
            'code': self.code.value,
            'message': self.message,
            'details': self.details
        }

try:
    raise ToolError(
        ToolErrorCode.NOT_FOUND,
        'City not found in database',
        {'city': 'Atlantis', 'suggestion': 'Did you mean Athens?'}
    )
except ToolError as e:
    print(e.to_dict())

Eingabevalidierung

Validieren Sie Eingaben vor der Ausführung anhand des Schemas. Verwenden Sie jsonschema für die automatische Validierung. Brechen Sie frühzeitig mit einem aussagekräftigen Fehler ab, statt zuzulassen, dass ungültige Eingaben tief in der Tool-Logik schwer verständliche Fehler verursachen.

import jsonschema  # pip install jsonschema

def validate_tool_input(params: dict, schema: dict) -> dict:
    """
    Validate params against schema.
    Returns validated (and default-filled) params.
    Raises ToolError on validation failure.
    """
    try:
        # Fill in defaults
        filled = dict(params)
        for prop, definition in schema['properties'].items():
            if prop not in filled and 'default' in definition:
                filled[prop] = definition['default']

        # Validate against schema
        jsonschema.validate(instance=filled, schema=schema)
        return filled

    except jsonschema.ValidationError as e:
        raise ToolError(
            ToolErrorCode.INVALID_PARAMS,
            f'Validation failed: {e.message}',
            {'path': list(e.path), 'schema_path': list(e.schema_path)}
        )

# Example usage:
try:
    params = validate_tool_input({'city': 'London'}, TOOL_SCHEMA_TEMPLATE['parameters'])
    print('Valid params:', params)
except ToolError as e:
    print('Error:', e.to_dict())

Nutzungsbeispiele im Schema

Fügen Sie Ihrem Tool-Schema konkrete Beispiele hinzu. Beispiele erfüllen zwei Zwecke: Sie helfen Menschen, das Tool schnell zu verstehen, und können als Few-Shot-Demonstrationen in den Kontext des Agenten eingefügt werden, um die Genauigkeit von Tool-Aufrufen zu verbessern.

TOOL_WITH_EXAMPLES = {
    'name': 'search_knowledge_base',
    'description': 'Search the company knowledge base for documentation.',
    'parameters': {
        'type': 'object',
        'properties': {
            'query': {'type': 'string'},
            'top_k': {'type': 'integer', 'default': 5, 'minimum': 1, 'maximum': 20}
        },
        'required': ['query']
    },
    'examples': [
        {
            'description': 'Search for onboarding docs',
            'input': {'query': 'how to onboard new users', 'top_k': 3},
            'output': {'results': [{'title': 'User Onboarding Guide', 'score': 0.95}]}
        },
        {
            'description': 'Search with default top_k',
            'input': {'query': 'API authentication'},
            'output': {'results': [{'title': 'API Auth Docs', 'score': 0.88}]}
        }
    ]
}

if __name__ == '__main__':
    print('Tool:', TOOL_WITH_EXAMPLES['name'])
    for ex in TOOL_WITH_EXAMPLES['examples']:
        print(f" - {ex['description']}: input={ex['input']} -> output={ex['output']}")

Ratenbegrenzung in Tools

Tools, die externe APIs aufrufen, müssen Ratenbegrenzungen einhalten. Implementieren Sie pro Tool einen Rate-Limiter mit einem Token-Bucket oder einem gleitenden Zeitfenster. Geben Sie bei Überschreitung des Limits einen standardisierten RATE_LIMITED-Fehler mit der Anzahl der Sekunden bis zum erneuten Versuch zurück.

import time
from collections import deque

class SlidingWindowRateLimiter:
    def __init__(self, max_calls: int, window_seconds: int):
        self.max_calls = max_calls
        self.window = window_seconds
        self._calls = deque()  # timestamps of recent calls

    def check(self) -> tuple:
        """
        Returns (allowed: bool, retry_after_seconds: float)
        """
        now = time.time()
        # Remove calls outside the window
        while self._calls and self._calls[0] < now - self.window:
            self._calls.popleft()

        if len(self._calls) >= self.max_calls:
            oldest = self._calls[0]
            retry_after = (oldest + self.window) - now
            return False, round(retry_after, 1)

        self._calls.append(now)
        return True, 0.0

weather_limiter = SlidingWindowRateLimiter(max_calls=10, window_seconds=60)
allowed, retry = weather_limiter.check()
if not allowed:
    raise ToolError(ToolErrorCode.RATE_LIMITED,
                    f'Rate limit exceeded. Retry in {retry}s',
                    {'retry_after': retry})

Verpackung als Python-Paket

Strukturieren Sie Ihr Tool als installierbares Python-Paket, damit andere Entwickler es mit einem einzigen pip install zu ihren Agenten hinzufügen können. Das Paket stellt die Funktionen get_tool_definition() und execute(params) als öffentliche API bereit.

# Directory structure:
# agent_tool_weather/
#   __init__.py
#   tool.py
#   schema.py
#   pyproject.toml
#   README.md

# agent_tool_weather/tool.py
from .schema import SCHEMA
from .errors import ToolError, ToolErrorCode

def get_tool_definition() -> dict:
    return SCHEMA

def execute(params: dict) -> dict:
    validated = validate_tool_input(params, SCHEMA['parameters'])
    city = validated['city']
    units = validated['units']
    return _fetch_weather(city, units)

def _fetch_weather(city: str, units: str) -> dict:
    import requests
    url = f'https://api.weather.example.com/current?city={city}&units={units}'
    response = requests.get(url, headers={'X-API-Key': 'YOUR_KEY'}, timeout=5)
    if response.status_code == 404:
        raise ToolError(ToolErrorCode.NOT_FOUND, f'City not found: {city}')
    response.raise_for_status()
    return response.json()

Die README des Tools verfassen

Eine klare README ist entscheidend für die Verbreitung. Geben Sie an: die Funktion des Tools, den Installationsbefehl, erforderliche API-Schlüssel oder Zugangsdaten, alle Parameter mit Typen und Standardwerten, alle Fehlercodes und mindestens ein vollständiges Anwendungsbeispiel.

README_TEMPLATE = '''
# agent-tool-weather

Get real-time weather conditions for any city.

## Installation

pip install agent-tool-weather

## Setup

import os
os.environ["WEATHER_API_KEY"] = "your-key-here"

## Usage

from agent_tool_weather import get_tool_definition, execute

# In your agent
tool_def = get_tool_definition()

# Execute
result = execute({"city": "Tokyo", "units": "celsius"})
print(result)
# {"temperature": 22.5, "condition": "Partly cloudy", "humidity_pct": 65}

## Parameters

| Name  | Type   | Required | Default  | Description     |
|-------|--------|----------|----------|-----------------|
| city  | string | Yes      | -        | City name       |
| units | string | No       | celsius  | celsius or fahrenheit |

## Error Codes

- INVALID_PARAMS: Parameter validation failed
- NOT_FOUND: City not found
- RATE_LIMITED: 60 calls/minute limit exceeded
- UPSTREAM_ERROR: Weather API unavailable
'''

print(README_TEMPLATE[:300])

Ein gemeinsam nutzbares Tool testen

Ein gemeinsam nutzbares Tool muss automatisierte Tests enthalten, die den Erfolgsfall, jeden Fehlercode, Grenzfälle (leere Zeichenketten, Maximalwerte) und das Verhalten bei Ratenbegrenzung abdecken. Tests sind Dokumentation – sie zeigen genau, wie sich das Tool verhält.

import pytest

def test_valid_city_returns_weather(mock_weather_api):
    result = execute({'city': 'London'})
    assert 'temperature' in result
    assert 'condition' in result
    assert isinstance(result['temperature'], (int, float))

def test_missing_required_param_raises_error():
    with pytest.raises(ToolError) as exc_info:
        execute({})  # city is required
    assert exc_info.value.code == ToolErrorCode.INVALID_PARAMS

def test_unknown_city_raises_not_found(mock_weather_api_404):
    with pytest.raises(ToolError) as exc_info:
        execute({'city': 'Atlantis'})
    assert exc_info.value.code == ToolErrorCode.NOT_FOUND

def test_default_units_is_celsius():
    params = validate_tool_input({'city': 'Paris'}, TOOL_SCHEMA_TEMPLATE['parameters'])
    assert params['units'] == 'celsius'

def test_rate_limit_enforced():
    limiter = SlidingWindowRateLimiter(max_calls=2, window_seconds=60)
    limiter.check()  # call 1
    limiter.check()  # call 2
    allowed, _ = limiter.check()  # call 3 — should fail
    assert not allowed

OpenAI-kompatibles Format für Function Calling

Um mit den nativen APIs zur Tool-Nutzung von OpenAI und Claude kompatibel zu sein, stellen Sie sicher, dass Ihr Tool-Schema exakt dem von diesen APIs erwarteten Format entspricht. Die Methode get_openai_schema() konvertiert Ihr internes Schema in das OpenAI-kompatible Format.

def get_openai_schema(tool_schema: dict) -> dict:
    """Convert internal tool schema to OpenAI function-calling format."""
    return {
        'type': 'function',
        'function': {
            'name': tool_schema['name'],
            'description': tool_schema['description'],
            'parameters': tool_schema['parameters']
        }
    }

def get_anthropic_schema(tool_schema: dict) -> dict:
    """Convert to Anthropic tool format."""
    return {
        'name': tool_schema['name'],
        'description': tool_schema['description'],
        'input_schema': tool_schema['parameters']
    }

# Usage in an agent:
openai_tools = [get_openai_schema(t) for t in [TOOL_SCHEMA_TEMPLATE]]
anthropic_tools = [get_anthropic_schema(t) for t in [TOOL_SCHEMA_TEMPLATE]]
print('OpenAI format:', openai_tools[0]['function']['name'])
print('Anthropic format:', anthropic_tools[0]['name'])

Versionierung Ihres Tools

Verwenden Sie semantische Versionierung: MAJOR.MINOR.PATCH. Erhöhen Sie MAJOR bei nicht abwärtskompatiblen Schemaänderungen, MINOR beim Hinzufügen optionaler Parameter und PATCH bei Fehlerkorrekturen. Speichern Sie die Version im Schema und stellen Sie sie über get_tool_definition() bereit.

VERSION = '1.2.0'

def bump_version(current: str, change_type: str) -> str:
    parts = list(map(int, current.split('.')))
    if change_type == 'major':
        return f'{parts[0]+1}.0.0'
    if change_type == 'minor':
        return f'{parts[0]}.{parts[1]+1}.0'
    if change_type == 'patch':
        return f'{parts[0]}.{parts[1]}.{parts[2]+1}'
    raise ValueError(f'Unknown change_type: {change_type}')

# Breaking change (removed required param) -> major
print(bump_version('1.2.0', 'major'))  # 2.0.0
# Added optional param -> minor
print(bump_version('1.2.0', 'minor'))  # 1.3.0
# Bug fix -> patch
print(bump_version('1.2.0', 'patch'))  # 1.2.1

Wissenscheck

Welcher Teil des Schemas eines gemeinsam nutzbaren Tools ermöglicht es dem Agent-Framework, Eingaben vor dem Aufruf der Ausführungsfunktion des Tools automatisch zu validieren?

Beantworte es in der interaktiven Lektion

Zusammenfassung: Entwurf gemeinsam nutzbarer Agent-Tools

Wichtige Erkenntnisse aus dieser Lektion:

Schema: Name, Beschreibung, Version, Parameter (JSON Schema), Rückgabewerte, rate_limit
Fehlercodes: standardisierter ToolError mit code, message, details
Eingabevalidierung: jsonschema validiert anhand des Parameterschemas vor der Ausführung
Beispiele: als Few-Shot-Kontext im Schema enthalten
Ratenbegrenzung: gleitendes Zeitfenster mit RATE_LIMITED-Fehler und retry_after
Verpackung: per pip install installierbares Paket mit README, Tests und Versionierung

Nächstes Thema: Plugin-Erkennung und dynamisches Laden von Tools.

Kostenlos starten

Lerne AI Agents mit einem KI-Tutor — kostenlos

Schreibe und führe echten Code in deinem Browser aus, bekomme sofortige Hilfe von einem 24/7 KI-Tutor und setze dein Lernen im Web oder in der App fort.

Kurse: 60
Lektionen: 239

Kostenlos lernen Den vollständigen Kurs ansehen

Häufig gestellte Fragen

Ist die Lektion „Teilbare Agent-Tools entwerfen“ kostenlos?

Ja — der vollständige Text von „Teilbare Agent-Tools entwerfen“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des AI Agents-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der AI Agents-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Teilbare Agent-Tools entwerfen“?

Standards für Tool-Schemas, Dokumentationsanforderungen und Paketierung zur Wiederverwendung. Du übst AI Agents mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um AI Agents zu starten?

Keine Vorkenntnisse erforderlich. AI Agents auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 1 von 4.

Wie lange dauert die Lektion „Teilbare Agent-Tools entwerfen“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser AI Agents-Lektion Code schreiben und ausführen?

Ja. Jede AI Agents-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

← Zurück zu AI Agents