--- author: AI Engineer date: '2026-10-09' guest: '' layout: post.njk source: https://www.youtube.com/watch?v=3wj6sgbi1YA speaker: AI Engineer tags: - agentic-interface - mcp - cli-design - context-management title: 面向 Agent 而非人类设计 CLI：Airbyte 在 MCP 与命令行界面的工程实践 summary: Airbyte 软件工程师 Pedro Lopez 深入探讨了如何为 AI Agent 构建高效的交互接口。文章系统对比了模型上下文协议（MCP）与命令行工具（CLI）在 Agent 场景下的适用边界，并总结了 Agent-First CLI 的三大核心设计原则：纯粹的 JSON 输入输出、强一致性的动名词命名结构，以及通过上下文分块与渐进式发现机制避免上下文溢出。 insight: '' draft: true series: '' category: software-development area: tech-engineering project: [] people: [] companies_orgs: - Airbyte products_models: [] media_books: [] status: evergreen --- ### 数据集成演进：从数据管道到 Agent 上下文引擎 **Airbyte** 作为开源数据集成标准，长期致力于将各类 SaaS 工具（如 Zendesk、Stripe、GitHub 等）连接至分析管道中。如今，随着大语言模型与自主智能体的兴起，团队正将深厚的数据管道经验转化为面向 **AI Agent** 的“数据与操作层”（Data & Action Level）。为了实现这一目标，Airbyte 推出了专门的 Agent 产品体系，其核心是位于数据源与 Agent 之间的 **上下文存储**（Context Store）。该存储充当了专用的检索引擎与索引层，将零散的客户档案、支持工单及交易数据高效融合，提供高吞吐的检索能力。 为了让各类系统和开发者能够便捷地访问这套上下文存储，Airbyte 提供了三种不同维度的接入方式：其一是面向自主编排与工具调用的 **软件开发工具包**（SDK: 供开发者构建自定义 Agent 的编程接口）；其二是面向终端用户的 Web **用户界面**（UI: 提供开箱即用图形交互的控制台）；其三则是专为大模型生态设计的 **模型上下文协议**（MCP: Model Context Protocol，Anthropic 提出的统一模型工具调用协议）与 **命令行界面**（CLI: Command Line Interface）。无论是基于 ChatGPT 还是 Claude 构建的 Agent，都可以通过后两者直接管理组织、工作空间及连接器等核心资产，完成安全的第三方 OAuth 授权，并对跨平台业务数据执行读写查询。
Original English Source こんにちは、みんな。自分 私の名前はペドロです。私 ソフトウェアエンジニア エアバイト。そして今日私たちは どのように 私たちはエージェントを作成しました MCPと当社のCLI。前に 掘り下げる 詳細を知りたいのですが 少し与える 文脈に関して 私たちがしていること Airbyteとは何か 我々の 製品。エアバイト すでに十分だ 長さ。私たちは オープンな標準 コード データ移動、 すべての接続 SaaSツール Zendesk、Stripe、GitHubなど あなたのコンベア データ分析。そして 今私たちは 私たちはそれを使っています 最も経験豊富で に変わった データとアクションレベル AIエージェント向けに。 私たちはこれを 私たちの助けを借りて エアバイトエージェント製品、 はいを含む ストレージと呼ばれる コンテキストストア、 に接続する すべて言及されている ツールと の間に配置される あなたのエージェント、 検索エンジンを提供する すべてのインデックス より多くのデータ 効果的なクエリ。 だから、 情報を収集する これらの記録すべてについて、 連絡先およびその他のデータ これらに含まれる ツールと簡単 彼らを団結させる 当社のストレージ コンテクスト。私たちの目標 — データを作成する アクセスしやすく 適しています どこでも使えます。 したがって、私たちはいくつか さまざまなインターフェース これにアクセスするには コンテキストの保存。 1つ目は当社SDKです。 どちらが便利か 自分で作成する エージェントと ツール。 2番 - これはインターフェースです ユーザーインターフェース（UI）、 手っ取り早い方法 使用 当社のウェブアプリケーション。そして 3つ目、私たちは何について話しているのか これに焦点を当てましょう 会話、私たちの MCPと CLIを簡単に 利用可能にする 既存の ChatGPTなどのエージェント そしてクロード。 では、具体的には何が これらを通じて提供する インターフェース？ 三つ 主な事柄。最初 - これはチャンスです 全員を管理する 主なリソース 当社の製品： 組織、 ワークスペース およびコネクタ。全て これらのインターフェース 許可します 彼らと交流する。 2番目は非常に 重要なこと — 可能性 認証する 先に述べた サードパーティサービス 安全な方法で、 あなたの AIの認証情報 エージェント。そして3番目は―― 問いかけ、行動する。 だから、私たちは 機会を提供する 検索 コンテキストストレージ、 読み書き データ、および すべてのアクションを実行する これらのシステムなので、 私たちはすべての インターフェース これら３つをカバーした 機会。 MCPとCLI 構造化 軽量ユニフォーム 弊社のインターフェース プラットフォーム、その方法ではない 再実装。 ほとんどの 表面レベル これらのインターフェースのうち、 プレゼンテーション： コマンドを入力してください ご連絡ください プラットフォームおよび特定の フォーマット方法 結果。これらすべ て 我々の基準に基づく 共通プラットフォーム そしてAPI。なぜなら私たちは 頻繁に配備される アップデート — 私たちの プラットフォームが変わりつつある 1日に10回以上、 私たちは常に これらをサポートするために インターフェース 現在の状況。 したがって、重要な役割 再生 OpenAPI仕様として 真実の源 弊社に接続しています API。そしてこれらの多くは インターフェース 主に構築 これらに基づいて 仕様。
### MCP 在终端用户与长会话鉴权中的优势与现实约束 在定位上，**模型上下文协议**（MCP）极其适合非技术用户或轻量级对话场景。用户无需繁琐的本地环境配置，只需将预托管的 MCP 服务器 URL 添加到 Claude Desktop 或 ChatGPT 应用中，即可让模型瞬间获得连接外部系统的能力。例如，当用户提问“展示 5 位在 Zendesk 中有待处理工单的付费客户”时，Agent 能够自主识别连接器、在上下文存储中进行关联检索，并将 Zendesk 工单与 Stripe 支付数据合并输出。 然而，在构建生产级 MCP 服务时，团队总结了两大核心工程挑战。首先是**工具数量收敛与渐进式暴露**：最初尝试为每个连接器构建独立的专用 MCP 工具，导致大模型上下文被海量 schema 塞满；最终方案收敛为两类核心通用工具——一类负责检索元数据与架构描述（Describe），另一类负责通用读写（Read/Write），并通过**渐进式发现**（Progressive Discovery）按需加载，从而大幅提升调用成功率。其次是**长效 OAuth 凭据管理**：Web 应用允许用户反复登录，但 MCP Agent 期望拥有长达数周的免登会话，必须将独立的离线刷新会话持久化存储。此外，不同 MCP 客户端对标准规范的实现差异巨大（例如规范中的动态输入抽屉模式 Drawer/URL query，Claude Desktop 等客户端并不支持），迫使服务端针对异构客户端做兼容妥协。
Original English Source 良い、 では次に進みましょう これらを考慮すると インターフェース。それでは始めましょう。 まずはMCPから始めましょう。 MCPは素晴らしい 適しています ユーザー できる 非技術的な 専門家。私たちの この場合は理想的です 欲しい人のために 接続が簡単 あなたのデータ ChatGPTに直接 またはクロード。それはクールだ それらはとても良い 詰め込んだ。彼らはとても 取り付けが簡単です。 例えば、これが私たちの リストエントリ 公式ストア ChatGPTアプリケーション。で アプリケーションもあります 人間活動に関する考察 それはまだ進行中です。もし Anthropicの誰かが私たちの声を聞いている そして私たちの 応用。しかし、もしあなたがこれらに載っていないなら マーケットプレイス、 ファイナル ユーザーへ 完全にインストールしてください 簡単です。あなたはただ URLを指定してください MCPを主催し、 すぐに 接続する。 わかりました、 見てみましょう 例えば。これが私たちのMCPです 実際に動いている。ここで私は尋ねます、 コネクタの種類 利用可能。システム 答えは この労働者 スペースが準備されました コネクタが4つ。 その後私は 質問をする お客様のデータに関して、 例えば：表示 5人が支払い済み チケットをお持ちのお客様 Zendeskでのサポート。 したがって 今彼は すべて表示 関係 私たちも探しています コンテキストストレージ その情報について 私が尋ねたことです。その後 彼はこれを組み合わせる Zendeskからの情報と ストライプを形成する 私にとっての答えはこれです。 はい、こちらです。 結果。だから彼は Zendeskのデータと Stripeと見つけた 五 ユーザーが チケットが空いています サポート。クラス。 次に 私たちが学んだ教訓 学習中 このMCPの作成、そして 価値のあるものへ 考慮に入れると、 同様のことをする。 だから、私たちが することに決めた 試行錯誤の末 制限する 番号 ツール。だから パフォーマンスの一部 コネクタで このデータを抽出すると、 私たちは 2つの主な ツール。初め - これはコネクタの説明です 計画を取得する データクエリ、および 2番目は、 読書を可能にする、 記録して レコードを削除します。 これとは反対 アプローチは 別のMCPを 作成する - ツール 数多くの コネクタは、 それぞれに異なる 本質と行動。 しかし、我々は以下のことを発見した。 狭い専門分野、 使用 プログレッシブ 検出 機会 コネクタと 容量制限 説明文中の文脈 ツールを大幅に 改善する MCPのパフォーマンス - サーバ。 ２：OAuthは 正しい方法で。それ どのように懸念するか 認証します MCPサーバー自体。ここ 人間原理の例。あなた ボタンを押す 繋がり、 私たちの OAuthフローでログインします Airbyteでは、 アクセス条件、その他すべて 一緒に働く準備ができています すべて繋がっている コネクタ。 技術的には可能です 他のものを使う メカニズム 認証 MCPですが、 例えば、 ベアラー認証、なぜなら 仕様 OAuth指向であり、 主な顧客 OAuthを優先する 最高のUXとして インストール コネクタ。これは一例です あなた自身の登録 コネクター人間的、 とんでもない 例えば、無記名トークン。すべては デフォルト 結局はOAuthに行き着く。したがって これは非常に重要です。 そして、 第二に、ユーザーは 実際に期待している 持つことになる 長時間のセッション これらのMCPサーバーを介して。 とは異なり ウェブアプリケーションで 同意できますか？ 再突入 何度か。 ユーザーは期待している それ 使用する モバイルとしてのMCP 彼らがそうしないアプリケーション 考える必要がある 認証。彼 簡単に手に入り、 たとえそうしなかったとしても 彼らが欲しかった 使用。前 ここにはいくつかのニュアンスがあります。 覚えておく価値のあるもの 実施中 OAuth: ストレージ 長期オフライン - セッション 別々に保管 ウェブアプリケーションから、 独自の ライフサイクル。急勾配です。 リクエストは 情報ではない 入り口。それでは説明します。 引き出しとは何か、 しかし重要なこと MCPサーバーの一部、 私が言及したように、 可能性 接続 ツール。あなた 提供する必要がある 資格 安全な方法で。そして これを実行したとき どうやって HubSpotに接続し、 私たちは生成します あなたがクリックしたリンク 渡って、 ウィジェットが開きます あなたが選ぶ場所 エンティティ 接続と リダイレクト先 HubSpotでフォローアップ OAuthフロー。技術的には、 MCPは仕様書に 機能 以下のURLを表示します。 住所とプロセス 入力されたデータ 「リクエスト」と呼ばれる（引き出し）。これがその方法だ 情報提供依頼 ユーザーから。 それは長い間存在していた クエリモードのみ フォームを通して、 適しています 機密データ 認証情報など API向け。しかし最近は クエリモードが表示されました 非常に 私たちが はい、そうです。しかし問題は さまざまなサポート MCPクライアント。それ 大きな話題は MCPでも動作します: 利用可能な場合 仕様、関数 サポートされている 異なるクライアント、 かなり強い それらは異なる。ここ クラウドデスクトップの例 彼らは私にこう言うだけです。「いや、私はそれを支持しない。 URLクエリモード 「私には無理です。」 したがって、私たちは しなければならない すべてはそれぞれのやり方で、いいえ 使用 仕様 そういったこと。
### Agent-First CLI 的三大设计支柱：格式、契机与上下文管理 针对更具工程深度、需处理海量数据或与本地环境深度绑定的复杂任务，**命令行界面**（CLI）展现出了远超 MCP 的吞吐能力与灵活性。人类使用 CLI 时偏好交互式提示符（Prompts）、富文本表格以及简写选项参数（Flags），但若直接将面向人类习惯的 CLI 交给 Agent 调用，往往会导致解析崩溃与流程死锁。Airbyte 在实践中确立了三大面向 Agent 的 CLI 架构设计原则： 1. **统一输入输出格式**：强制所有命令均通过 **JSON 格式** 接受参数并返回结构化输出。这不仅彻底规避了模型在拼接复杂 CLI Flags 时的语法臆测，还天生契合 Unix 管道哲学——Agent 能够无缝结合 `jq` 等工具在命令行内部完成数据流的初筛与转换，大幅降低主模型上下文负担。 2. **名动一致性契约**（Noun-Verb Hierarchy）：Agent 必须阅读文档才能知晓工具存在。为降低认知成本与猜错概率，CLI 命令全量遵循“名词 + 动词”结构（如 `airbyte connector list`、`airbyte workspace list`）。如果观察到 Agent 反复尝试某种错误的命令模式，应当反思并将其作为直觉契约吸收进 CLI 的规范体系中。 3. **伴生 Skill 与上下文分块**：Agent 无法凭空知晓 CLI 的参数与高级用法，必须配备配套的 **Skill 指南文档**。然而，将包含所有参数的巨型文档一次性注入模型会迅速导致上下文过载并稀释推理精度。团队采用**分层索引与按需引用**：主 Skill 仅提供简要触发入口与路由描述，具体命令细节拆分在子目录文件中，借助模型的渐进式文件检索能力按需加载。此外，必须彻底移除任何交互式等待（Non-blocking execution），环境密钥与鉴权必须预先通过环境变量或静态配置文件固化，绝不给 Agent 留出因“等待用户终端敲击回车”而永久挂起的机会。
Original English Source 良い、 話しましょう CLIについて少し説明します。 MCPの場合 シンプルに 非技術的な ユーザーの場合、CLIは 彼らのより多くの 技術的な類似例。 彼は ある意味でより強力で、 他にどんな話をするんですか？ 話し合いましょう。これがそれだ 私たちが 以前にも見たことがあるが、 今回はMCP、または 申し訳ありませんが、CLIから 私たちは、 コネクタ 利用可能。この時 読み込み中 情報を提供するスキル CLIについて、そして CLI自体を使用します 実行のために リクエスト。受け取りました コネクタの一覧。 そして私たちは尋ねました。「 5つを表示 有料顧客 チケットをお持ちの方 Zendeskでのサポート。はい。 前回と同じ 一度。今回は彼が CLIを使用できます リクエストのために作成します コンテキストストレージ、 このデータを収集し、 最終的には 結果を返します。 わかりました。ここにそれらがあります 彼ら5人 ユーザー。 の CLI設計は、 覚えておくべき重要なことは何ですか？ CLIの設計について エージェントを考慮に入れる。 いくつかの できる 役立つ ユーザーが CLIを作成すると、 障害物となる エージェント向け。私たちは 少し詳しく見てみましょう 詳細はこちら。 初め 設計ソリューション、 私たちが採用したのは JSONを入力として受け入れる そしてJSONを返す 出口。人々は快適です 山積みを示す 仕事用の旗 CLIでは、 より複雑な入力について クエリのデータ、 エージェントははるかに JSONの方がうまく動作する。 彼らは有能である もっと形を整える まっすぐで 少ない 仮定よりも 使用 旗。 の 出力、JSON形式も 作業が楽になります より詳しい回答 そして、 1つ使用する 鍵の CLI機能: Unix- コンベアを備えたシステム、 それによってあなたは リダイレクト出力 様々なプログラムにおいて。 例えば、 JQを使用する、 特定のものを選択する 出力からの要素と それらをフィルタリングして除外する。 つまりJSONは本当に 重要な これらの機能の一部 機会。 2番 ここでのシーケンスは 鍵。エージェント向け 完全に 明らかに、 アクションを実行する すべてのリソース あなたが提供するもの。もしあなたが CLIの構造 では、何が最初に来るのか？ 名詞、そして 動詞。このような 例: コネクタ一覧、 コネクタが作成されました。 必ず CLIコマンドの実装 ワークスペース向け 彼らもまた これに従う 形式。ワークスペースリスト — これも例です。 私たちはそれを持っています。したがって、 非常に重要なのは エージェントは すべてを正しく行うために、 そして彼らにとって簡単に それについて知るために 読む必要がある 大量のドキュメント。 そして もう一つ興味深い事実： もしあなたがそれを見たら エージェントは1つのことを行い、 またしても同じ間違いを犯してしまった そしてまた、呼びかける 間違ったコマンド、 考えてみてください それを一部にする あなたの契約。 こうする エージェントたちは できるだけシンプルに 適切なものを見つける 使用方法 ツール。なぜならこれは 通常は、 あなたの CLI契約はそうではない 明らかだが、どれほど少ないか エージェントの場合 常にいくつかは想定されている そして、同じ過ちを繰り返す。 第三に、スキル 一緒に供給されます CLIツールを使用します。 スキルは備わっている 必須 CLIを使って作業するのは、 そうでなければ、 CLIがインストールされました。 エージェントは 彼について知る 存在。これはとても 役立つ 利用可能なものを特定する あなたのツール。そして 彼らもまた ヘルプ 効果的に これらを使用してください ツール。だから、 私たちにはスキルがあります に登場 絶好のタイミング。 説明文には 毎回現れる あなたは何について尋ねています コネクタ; 彼女は知っている、 何をする必要があるのか このCLIを呼び出して その。 そしてあなたのやり方 スキルを構造化する これもまた 考えてみる価値はある。あなたも 追加したくない スキルが高すぎる 言うまでもなく、 過負荷になります コンテクスト。スキル 能力を持つ 分割する リンク先 メインにすることができます 示すスキル 他のファイルへ スキルディレクトリ、 何ができるのか 拡大する さまざまな情報 チーム。これは本当に 軽減するのに役立ちます 額 ダウンロード可能 文脈と 使用する エージェントの能力 プログレッシブ 検出。急勾配です。 まだ 興味深い点が1つあります 認証に関して： MCPにとって重要ですが、 また興味深いのは 私たちのCLIは、 私たちは想定できません、 そこに人がいるだろう、 交流する ヒント。 CLIの場合 と呼ばれる エージェントではない ただ待つことができる、 クエリを入力する際に コマンドラインで。あなた 提供しなければならない フラグによるデータ または、 アカウントの詳細、 変数を通じて 環境と 設定ファイル すべてが 設定済み 事前にではなく 待たなければならなかった CLI呼び出し中。私は...するだろう さらに 承認、これ 原則。 多くのCLIが作成されました 待っている人々のために コマンドを入力して ヒントではない エージェントを許可する 彼らと一緒で構わない 仕事。彼らは 簡単に言うと、 これに詰まってしまった。クラス。
### MCP 与 CLI 的工程选型权衡及场景落地 在技术架构选型中，MCP 与 CLI 并无绝对优劣之分，而是服务于不同的用户阶层与任务密度。MCP 的主要优势在于集中托管——团队更新后端服务时，所有 Agent 实时同步最新功能，且它在交互式问答、快速原型构建以及非技术人员日常使用中体验极佳。但 MCP 也伴随着不可忽视的局限：客户端实现碎片化严重，主流框架存在严苛的 Payload 上下文限制（如 Claude 针对服务器描述和工具调用的体积封顶），极易因通信超时导致复杂任务执行中断。 相比之下，CLI 虽有包版本分发与本地运行依赖的维护开销，却能赋予技术型 Agent 极强的系统级威力。对于耗时漫长的异步流水线、海量数据迁移或需要深度整合 Unix 标准流（如管道重定向、`tail`、`head` 截流分析）的场景，CLI 具备确定性的吞吐表现与容错能力。理解两者在交互范式、上下文开销及执行确定性上的底层差异，并据此构建双轨驱动的接入矩阵，是下一代 AI 系统工程架构演进的关键路径。
Original English Source では、どちらが良いのでしょうか？ CLIかMCPか？ まあ、誰もが 利点があり、 デメリット。あなたが知っている、 MCP仕様 全ての場所で実施されているわけではない 同様に。沢山あります 制限 開発者 加えて実装する 仕様そのもの。 例えば、クロードは 1キロバイトあたり2キロバイトの制限 サーバーの説明と 電話 ツール。がある 期限 実装 したがってツール 打ち上げがより困難 長いプロセスのため MCP。そして他にもいる 彼らが そこへ入った。 CLIに関して、 MCPの利点は、 持つことができる ホスティングサーバー、 いつも 更新中です。 CLIから 必ずしもそうではない。 もっと必要 考える バージョン管理。 より難しい サポート パッケージの関連性 新しいものすべてと共に 機能。そして、 MCPの制限は 不可欠であるために、 CLIで欠落している可能性がある エラーにつながる または周期的一 プロセスを通じて エージェントは「ハング」する。 前 どちらも オプションには権利がある 生涯にわたって。 MCPは素晴らしい 適しています ユーザーなし 技術的な知識、 速い プロトタイピング、 レポートの作成と 間の相互作用 異なるシステム。そして CLIの方が適している 技術的な 専門家。これらは長い タスク、大きな データ量、 できる 使用 Unix関数と コンベアなど リダイレクション ファイルに出力、末尾または 頭。ここでCLIが真価を発揮するのです。 現れ始める 最高の自分になれる。 わかりました。 それが私が実際に言いたかったこと。我々は持っています エアバイトスタンドなので ぜひお越しください 参加する 仕事。ありがとう。