البناء لوكلاء الذكاء الاصطناعي: رحلة Apidog CLI

هذه سلسلة من 10 أجزاء تشارك كيف طور Apidog Apidog CLI، أداة سطر الأوامر لاختبار API وإدارة دورة حياة API. اقرأ بالترتيب أو انتقل إلى أي مقال يهمك:

بنينا 126 MCP Tool. ثم اكتشفنا أنها ليست الحل الأفضل للعمل على تطوير API مع Agents.

عندما أصبح MCP (Model Context Protocol) نقطة اهتمام صناعية في بداية 2025، كان السؤال الذي واجهه كل منتج API بسيطاً: "هل لديك MCP؟"

بالنسبة لـ Apidog، أجبنا بنعم. بنينا MCP Server كامل—not مجرد demo بسيط. MCP client كان سيهيئ session، وserver كان سيولد sessionId، ويحفظ state session عبر Redis. كان نظام session على مستوى protocol. قسمنا الأدوات إلى categories: أدوات native project، أدوات domain built-in، و126 أداة generated تلقائياً محولة من تعريفات OpenAPI endpoint.

Apidog MCP يواصل العمل وخدمة users الذين يحتاجون MCP integration. يوفر tool connections موحدة تتبع MCP protocol، وهو valuable للـ ecosystem.

لكن عندما دخلنا في tasks حقيقية تتضمن workflows R&D معقدة، اكتشفنا limitations. عندما يقول user "ساعدني أضف test لهذا endpoint وrun verification"، Agent يواجه جدار من tools عشوائية—يقرر أي واحد use، في أي sequence، مع أي validation.

أدركنا: MCP يتقن في connecting tools، لكن tasks R&D معقدة تحتاج أكثر من tool connection—they need engineering processes قابلة للتنفيذ.

أدى ذلك insight إلى تطوير Apidog CLI كـ approach أفضل—one handles development workflows بشكل أفضل.

ما هو Apidog CLI؟

Apidog CLI هو أداة سطر الأوامر لاختبار API تتيح لك run test scenarios، manage API documentation، وautomate testing workflows مباشرة من terminal أو CI/CD pipelines. Built خصيصاً لـ AI agents manage API resources، يتجاوز CLI التقليدي لاختبار API—يوفر structured output، schema validation، وnext-step guidance الذي agents need لـ execute workflows معقدة بشكل آمن. سواء كنت running automated API tests في GitHub Actions، generating test cases من code مع Claude Code، أو maintaining test scenarios عبر projects، Apidog CLI serves كـ bridge بين AI agents وinfrastructure اختبار API.

Quick Start: جرب Apidog CLI + SKILL

إذا كنت تريد تجربة approach الموصوف في هذه السلسلة، إليك كيفية البدء:

# 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 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 concrete starting point: Agent check setup، asks before writing، creates small API definition، validates before writing، وconfirms saved result.

The Core Architecture

The Safer Loop for Agent-Driven Testing

With AI Branch كـ outer security layer، 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 لأن الكثير من Apidog resources structured. Test cases وtest scenarios تتضمن request data، assertions، variable extraction، pre/post processors، step order، وenvironment references. إذا Agent guess structure، small mistakes cause failed writes، incomplete display، أو tests لا behave as expected.

Let Agent generate، let CLI validate، وlet AI Branch isolate changes حتى human review.

The Apidog CLI Journey Overview

This series documents كيف طورنا Apidog CLI كـ strategy أفضل لـ API R&D workflows.

Apidog MCP continues لتوفير standardized tool connections—that's valuable ونحن maintain it. لكن لـ tasks تتضمن multi-step workflows، validation gates، وstructured execution، وجدنا CLI + SKILL offers experience أفضل.

We didn't just add commands to the old CLI، حيث users ran automatic API tests integrating مع CI/CD. Systematically introduced Apidog's core capabilities إلى CLI، making it workflow layer لـ developers، scripts، وAI Agents.

The key difference هو حيث complexity lives:

• MCP route: Complexity في model context وtool selection stage—great لـ simple tool calls
• CLI + SKILL route: Complexity distributed إلى engineering system—better لـ workflows أكثر advanced

النتيجة: agent workflows أكثر أماناً لـ complex tasks، fewer tool calls، less token waste، وbetter error recovery—while MCP remains available لـ users الذين 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

بنينا 126 MCP Tool. ثم اكتشفنا Solution أفضل لـ API Development Workflows مع AI Agents.

MCP يوفر standardized tool connections—لكن لـ complex R&D workflows، اكتشفنا limitations. Agents faced جدار من random tools عندما tasks involved multi-step processes. This post explores four structural challenges ولما CLI + SKILL أفضل لـ workflow-heavy tasks.

Part 2: Architecture Development

2. لماذا طورنا Apidog CLI جديد تماماً

We didn't abandon MCP—we built CLI + SKILL لـ handle ما MCP doesn't optimize: complex workflows مع validation gates وstructured execution. This post compares execution chains ويشرح كيف CLI + SKILL distributes complexity إلى engineering system while MCP continues serving its purpose.

Part 3: Core Philosophy

3. القاعدة الذهبية: CLI ينتج Facts، Model يتصرف على Facts

Core principle: don't make model memorize all rules—let rules be executed at right places. This post introduces `cli-schema validate`، quality gate الذي catches field errors، wrong enums، وstructural problems قبل أن become failed writes.

Part 4-5: Technical Design

4. agentHints: تعليم CLIs التحدث مع Agents

Traditional CLI output لـ humans. Agents need structured results، failure reasons، وnext-step suggestions. `agentHints` turns product experience إلى machine-readable guidance—appearing exactly حيث Agents need لـ make decisions.

5. SKILL: شحن الخبرة التشغيلية كـ Code

SKILL ليس مجرد command reference. It's operating guide لـ AI Agents: when to use command، which comes first، what fields shouldn't be guessed، when to validate، when to read back. SKILL packages workflow knowledge إلى versionable، evolvable guides.

Part 6-7: Validation & Practice

6. الأرقام لا تكذب: 30% Tool Calls أقل، 25% Tokens أقل

قمنا بمقارنة MCP vs. CLI + SKILL عبر typical tasks. Tool call steps decreased ~30%. Token consumption من invalid descriptions وretries decreased ~25%. Structural error retries decreased ~40%. This post breaks down حيث savings come from.

7. من PRD إلى Loop Testing: Workflow Agent كامل مع Apidog CLI

Walk through real example: team has Order Refund PRD وcodebase. See how Agent uses CLI + SKILL لـ generate OpenAPI، create test cases، validate structures، build test scenarios، وrun verification—end to end.

Part 8-9: Foundation & Security

8. لماذا CI/CD Compatibility غير قابل للمساومة لأدوات Agent

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: تغييرات Project أكثر أماناً مع AI Agents

When Agents modify project resources، security matters. AI Branch provides isolated editing—changes stay في separate branch حتى human review. This prevents automated changes من directly affecting main branch. Create، review، ثم merge مع confidence.

Part 10: Vision & Future

10. Spec-First كان بالأمس. مرحباً Skill-First.

API development changing مع AI Agents joining workflow. Spec-First كان لـ human collaboration. Skill-First packages specs، tests، وscenarios إلى executable، verifiable skills—complementing existing approaches لـ Agent era. This post outlines future ويوفر concrete getting-started steps.

Key Takeaways (TL;DR)

ابدأ القراءة

Ready لـ dive in? Start مع Post 1: بنينا 126 MCP Tool. ثم اكتشفنا Solution أفضل لـ Workflows.

Download Apidog لـ design، mock، test، و document APIs في one workspace. Learn more عن Apidog CLI لـ command-line API testing، CI automation، وAI Agent workflows.