Entwicklung für KI-Agenten: Die Apidog CLI Reise

Dies ist eine 10-teilige Serie, die zeigt, wie Apidog Apidog CLI entwickelt hat, ein Command-Line-Tool für API-Testing und API-Lifecycle-Management. Lesen Sie in der richtigen Reihenfolge oder springen Sie zu jedem Beitrag, der Sie interessiert:

Wir Haben 126 MCP Tools Entwickelt. Dann Entdeckten Wir, Es Ist Nicht die Beste Lösung für API Development mit Agenten.

Als MCP (Model Context Protocol) Anfang 2025 zum Industry-Hotspot wurde, war die Frage, die jedes API-Produkt beantworten musste, einfach: "Haben Sie MCP?"

Für Apidog sagten wir ja. Wir haben einen vollständigen MCP Server gebaut—nicht nur eine simple Demo. Der MCP-Client würde eine Session initialisieren, der Server würde eine sessionId generieren und den Session-State über Redis speichern. Es war ein Protocol-Level-Session-System. Wir haben Tools in Kategorien unterteilt: native Projekt-Tools, built-in Domain-Tools und 126 generierte Tools, die automatisch aus OpenAPI-Endpoint-Definitionen konvertiert wurden.

Apidog MCP funktioniert weiterhin und dient Users, die MCP-Integration benötigen. Es bietet standardisierte Tool-Connections nach dem MCP-Protocol, was für das Ecosystem wertvoll ist.

Als wir aber in echte Tasks mit komplexen R&D-Workflows eintraten, entdeckten wir Limitationen. Wenn ein User sagt "help me add a test for this endpoint and run verification", steht der Agent vor einer Wand von random Tools—entscheidet, welcher zu verwenden, in welcher Sequence, mit welcher Validation.

Wir realisierten: MCP ist exzellent in Tool-Connections, aber komplexe R&D-Tasks brauchen mehr als Tool-Connection—sie brauchen executable Engineering-Prozesse.

Diese Insight führte uns zur Entwicklung von Apidog CLI als ein besserer Ansatz—one der Development-Workflows besser handhabt.

Was ist Apidog CLI?

Apidog CLI ist ein Command-Line-Tool für API-Testing, das Ihnen ermöglicht, Test-Scenarios zu runnen, API-Dokumentation zu managen und Testing-Workflows direkt von Ihrem Terminal oder CI/CD-Pipelines zu automatisieren. Speziell gebaut für AI-Agents, die API-Resourcen managen, geht es über traditionelles CLI für API-Testing hinaus—mit structured Output, Schema-Validation und Next-Step-Guidance, die Agents brauchen, um komplexe Workflows sicher zu execute. Ob Sie automated API-Tests in GitHub Actions runnen, Test-Cases aus Code mit Claude Code generieren oder Test-Scenarios across Projects maintainen—Apidog CLI dient als Bridge zwischen AI-Agents und Ihrer API-Testing-Infrastructure.

Quick Start: Try Apidog CLI + SKILL

Wenn Sie den Ansatz aus dieser Serie testen wollen, hier ist wie Sie starten:

# Install Apidog CLI
npm install -g apidog-cli@latest

# Install companion SKILL for AI Agents
apidog skill install

# Check version (need 2.2.5+ for new capabilities)
apidog -v

# Authenticate

Or ask your AI Agent to install it:

Read the instructions and help me install Apidog CLI:

Your First Agent Task

After Installation, give your Agent a small, low-risk Task:

Use Apidog CLI to help me create my first API endpoint in Apidog.
First, check my Apidog CLI setup and list the projects I can access.
Ask me which project to use. After I confirm, create a simple GET /health
endpoint named Health Check with a 200 response example. Validate any
structured input before writing, then read the endpoint back and summarize

This gives you a concrete starting point: the Agent checks Setup, asks before writing, creates a small API Definition, validates before writing, and confirms the saved Result.

The Core Architecture

The Safer Loop for Agent-Driven Testing

With AI Branch as the outer security Layer, the complete Workflow looks like this:

┌─────────────────────────────────────────────────────────────────────┐
│                        AI BRANCH (Security Layer)                      │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐         │
│  │  Read Assets │────▶│  Generate    │────▶│  Validate    │         │
│  │  (CLI get)   │     │  (Agent)     │     │  (cli-schema)│         │
│  └──────────────┘     └──────────────┘     └──────────────┘         │
│                                                │                    │
│                                                ▼                    │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐         │
│  │  Run Tests   │◀────│  Read Back   │◀────│    Write     │         │
│  │  (apidog run)│     │  (CLI get)   │     │  (to AI Br.) │         │
│  └──────────────┘     └──────────────┘     └──────────────┘         │
│          │                                                          │
│          ▼                                                          │
│  ┌──────────────────────────────────────┐                           │
│  │         Human Review & Merge          │                           │
│  │   (User confirms before main branch)  │                           │
│  └──────────────────────────────────────┘                           │

This Loop matters because many Apidog Resources are structured. Test Cases and Test Scenarios include Request Data, Assertions, Variable Extraction, Pre/Post Processors, Step Order, and Environment References. If an Agent guesses the Structure, small Mistakes cause failed Writes, incomplete Display, or Tests that don't behave as expected.

Let the Agent generate, let CLI validate, and let AI Branch isolate changes until human Review.

The Apidog CLI Journey Overview

This Series documents how we developed Apidog CLI as a better Strategy for API R&D Workflows.

Apidog MCP continues to provide standardized Tool Connections—that's valuable and we maintain it. But for Tasks involving multi-step Workflows, Validation Gates, and structured Execution, we found CLI + SKILL offers a better Experience.

We didn't just add commands to the old CLI, where Users ran automatic API Tests integrating with their CI/CD. We systematically introduced Apidog's core Capabilities into CLI, making it a Workflow Layer for Developers, Scripts, and AI Agents.

The key Difference is where Complexity lives:

• MCP Route: Complexity in Model Context and Tool Selection Stage—great for simple Tool Calls
• CLI + SKILL Route: Complexity distributed into Engineering System—better for more advanced Workflows

The Result: safer Agent Workflows for complex Tasks, fewer Tool Calls, less Token Waste, and better Error Recovery—while MCP remains available for Users who prefer that Approach.

The Apidog CLI Journey Map

┌─────────────────────────────────────────────────────────────────┐
│                    THE APIDOG CLI + SKILL JOURNEY               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [Problem Discovery]                                            │
│     │                                                           │
│  ┌───┐                                                          │
│  │ 1 │ We Built 126 MCP Tools. Then We Found                    │
│  └───┘ a Better Approach for Workflows.                         │
│     │                                                           │
│     ▼                                                           │
│  [Architecture Development]                                     │
│  ┌───┐                                                          │
│  │ 2 │ Why We Developed a Brand-new Apidog CLI                  │
│  └───┘                                                          │
│     │                                                           │
│     ├──────────────────┬──────────────────┐                     │
│     ▼                  ▼                  ▼                     │
│  [Core Philosophy]  [Technical Design]                          │
│  ┌───┐              ┌───┐              ┌───┐                    │
│  │ 3 │ CLI Produces │ 4 │ agentHints:  │ 5 │ SKILL: Shipping    │
│  └───┘ Facts        └───┘ Teaching     └───┘ Operational        │
│     │              │    CLIs           │    Experience          │
│     │              │                  │                         │
│     └──────────────┴──────────────────┘                         │
│                        │                                        │
│                        ▼                                        │
│               [Validation & Practice]                           │
│               ┌───┐        ┌───┐                                │
│               │ 6 │───────│ 7 │                                 │
│               └───┘ Numbers│   PRD to Testing                   │
│                   │        │   Loop                             │
│                   ▼        ▼                                    │
│               [Foundation]   [Security Layer]                    │
│               ┌───┐        ┌───┐                                │
│               │ 8 │───────│ 9 │                                 │
│               └───┘ CI/CD  │   AI Branch                       │
│                   │        │                                    │
│                   └────────┘                                    │
│                        │                                        │
│                        ▼                                        │
│                   [Vision]                                      │
│                   ┌────┐                                        │
│                   │ 10 │ Spec-First → Skill-First               │
│                   └────┘                                        │
│                                                                 │

Quick Journey Navigation

Part 1: Problem Discovery

Wir Haben 126 MCP Tools Entwickelt. Dann Entdeckten Wir eine Bessere Lösung für API Development Workflows mit AI Agents.

MCP bietet standardisierte Tool-Connections—aber für komplexe R&D-Workflows entdeckten wir Limitationen. Agents standen vor einer Wand von random Tools, wenn Tasks Multi-Step-Prozesse involvierten. Dieser Post explores four structural Challenges und warum CLI + SKILL besser für Workflow-Heavy-Tasks sind.

Part 2: Architecture Development

2. Warum Wir ein Brandneues Apidog CLI Entwickelt Haben

Wir haben MCP nicht abandoned—wir haben CLI + SKILL gebaut, um zu handhaben, was MCP nicht optimiert: komplexe Workflows mit Validation Gates und structured Execution. Dieser Post compares Execution Chains und erklärt, wie CLI + SKILL Complexity in das Engineering System distributet, während MCP seinen Purpose weiterhin served.

Part 3: Core Philosophy

3. Die Goldene Regel: CLI Produziert Facts, Model Handelt auf Basis von Facts

Das Core-Principle: don't make the Model memorize all Rules—let Rules be executed at the right Places. Dieser Post introduces `cli-schema validate`, das Quality Gate, das Field-Errors, wrong Enums und structural Problems caught, bevor sie failed Writes become.

Part 4-5: Technical Design

4. agentHints: CLIs Mit Agenten Kommunizieren Lernen

Traditional CLI-Output ist für Humans. Agents brauchen structured Results, Failure Reasons und Next-Step-Suggestions. `agentHints` turns Product Experience in machine-readable Guidance—appearing exactly where Agents need to make Decisions.

5. SKILL: Operational Experience als Code Versenden

A SKILL is not just a Command Reference. It's an Operating Guide for AI Agents: when to use a Command, which comes first, what Fields shouldn't be guessed, when to validate, when to read back. SKILL packages Workflow Knowledge into versionable, evolvable Guides.

Part 6-7: Validation & Practice

6. Die Zahlen Lügen Nicht: 30% Weniger Tool Calls, 25% Weniger Tokens

Wir haben MCP vs. CLI + SKILL across typical Tasks compared. Tool Call Steps decreased ~30%. Token Consumption von invalid Descriptions und Retries decreased ~25%. Structural Error Retries decreased ~40%. Dieser Post breaks down, wo die Savings come from.

7. Von PRD zum Testing Loop: Ein Vollständiger Agent Workflow mit Apidog CLI

Walk through ein real Example: ein Team hat einen Order Refund PRD und Codebase. See how ein Agent CLI + SKILL uses, um OpenAPI zu generieren, Test-Cases zu erstellen, Structures zu validieren, Test-Scenarios zu bauen und Verification zu runnen—end to end.

Part 8-9: Foundation & Security

8. Warum CI/CD Compatibility für Agent Tools Nicht Verhandelbar Ist

Agent-Friendliness must be built on CI/CD-Friendliness. `apidog run` serves both: CI cares about Exit Codes, Report Files, stable Parameters; Agents care about structured Results, Failure Reasons, Next-Step-Suggestions. One Command, multiple Consumers.

9. AI Branch: Safere Projektänderungen mit AI Agents

When Agents Project-Resources modify, Security matters. AI Branch provides isolated Editing—Changes stay in a separate Branch until human Review. This prevents automated Changes from directly affecting the Main Branch. Create, Review, dann Merge mit Confidence.

Part 10: Vision & Future

10. Spec-First War Gestern. Willkommen bei Skill-First.

API Development is changing with AI Agents joining the Workflow. Spec-First was for human Collaboration. Skill-First packages Specs, Tests und Scenarios into executable, verifiable Skills—complementing existing Approaches for the Agent Era. Dieser Post outlines the Future und provides concrete Getting-Started-Steps.

Key Takeaways (TL;DR)

Start Reading

Ready to dive in? Start mit Post 1: Wir Haben 126 MCP Tools Entwickelt. Dann Entdeckten Wir eine Bessere Lösung für Workflows.

Download Apidog to design, mock, test, and document APIs in one Workspace. Learn more about Apidog CLI für Command-Line API-Testing, CI-Automation und AI Agent Workflows.