Goa-AI フレームワーク

概要

Goa-AI は、Goa の design-first（設計を単一の真実の源にする）哲学を、エージェント型システムに拡張します。DSL でエージェント・ツールセット・サービス所有の completion・ポリシーを宣言し、型付けされたコントラクト、耐久性のあるワークフロー、ストリーミングイベントを備えたプロダクション品質の実装を生成します。

なぜ Goa-AI なのか？

Design-First Agents

壊れやすいエージェントコードを書くのをやめ、コントラクトから始めましょう。

多くのエージェントフレームワークでは、プロンプト、ツール、API 呼び出しを命令的につなぎ合わせます。壊れたとき (そして壊れます) には、明確な真実の情報源がない散在したコードをデバッグすることになります。

Goa-AI はこれを反転します。エージェントの能力を型付き DSL で定義し、実装を生成します。設計がそのままドキュメントになり、コントラクトがそのまま検証になります。変更は自動的に反映されます。

Agent("assistant", "A helpful coding assistant", func() {
    Use("code_tools", func() {
        Tool("analyze", "Analyze code for issues", func() {
            Args(func() {
                Attribute("code", String, "Source code to analyze", func() {
                    MinLength(1)           // Can't be empty
                    MaxLength(100000)      // Reasonable size limit
                })
                Attribute("language", String, "Programming language", func() {
                    Enum("go", "python", "javascript", "typescript", "rust", "java")
                })
                Required("code", "language")
            })
            Return(AnalysisResult)
        })
    })
})

プランナーがこのツールを不正な引数で呼び出した場合、たとえば code が空文字だったり language: "cobol" だったりすると、Goa-AI は型付き境界で呼び出しを拒否し、構造化された retry hint を返します。プランナーはその hint を使って、正確な追加質問をしたり、修正した引数で再試行したりできます。手作業の文字列パースや、手で保守する JSON schema は不要です。

メリット:

• 単一の真実の情報源 — DSL が振る舞い、型、ドキュメントを定義
• コンパイル時の安全性 — 実行前に payload の不整合を検出
• 自動生成クライアント — 手配線なしで型安全なツール呼び出し
• 一貫したパターン — すべてのエージェントが同じ構造に従う
• 修復可能なツール呼び出し — 検証エラーが feedback 付きの構造化 retry hint を生成

→ 詳細は DSL Reference と Quickstart を参照してください。

型付き直接 Completion

構造化されたやり取りのすべてがツール呼び出しである必要はありません。

適切なコントラクトが、型付きの最終アシスタント応答であることもあります。ツール呼び出しも、手書き JSON パースも、プロンプト文に隠した並行スキーマ定義も不要です。

Goa-AI はそれをサービス上の Completion(...) として明示的にモデル化します:

var TaskDraft = Type("TaskDraft", func() {
    Attribute("name", String, "Task name")
    Attribute("goal", String, "Outcome-style goal")
    Required("name", "goal")
})

var _ = Service("tasks", func() {
    Completion("draft_from_transcript", "Produce a task draft directly", func() {
        Return(TaskDraft)
    })
})

completion 名は structured-output contract の一部です。1-64 文字の ASCII で、英字、数字、_、- を使え、先頭は英字または数字でなければなりません。

codegen は gen/<service>/completions/ に JSON schema、型付き codec、provider-enforced structured output を要求して最終アシスタント応答を生成 codec で decode する helper を出力します。streaming helper は raw model.Streamer surface に留まります。completion_delta chunk は preview 専用で、正規なのは最後の 1 つの completion chunk だけです。生成 Decode<Name>Chunk(...) helper はその最終 payload だけを decode します。structured output を実装しない provider は model.ErrStructuredOutputUnsupported で明示的に失敗します。

メリット:

• 1 つの契約面 — 直接 assistant output にも Goa 型、validation、OneOf を再利用
• 手書き JSON パース不要 — 生成 codec が encode/decode/validation を所有
• provider-neutral structured output — helper が provider wiring を型付き API の背後に隠す

→ 詳細は DSL Reference と Runtime を参照してください。

Run Trees

単純で観測可能な部品から、複雑なシステムを組み立てます。

現実の AI アプリケーションは、単一エージェントで完結しません。エージェントが別のエージェントへ委譲し、ツールがサブタスクを生成し、全体を追跡できることが求められます。

Goa-AI の ランツリー（run tree）モデルは、完全な可観測性を備えた階層実行を提供します。各ランは一意の ID を持ち、子ランは親にリンクされ、イベントはリアルタイムでストリーミングされます。失敗時はツリーを辿って原因に到達できます。

メリット:

• Agent-as-tool — 任意のエージェントを別エージェントからツールとして呼び出せる
• 階層トレーシング — エージェント境界を跨いだ実行を追跡できる
• 失敗の分離 — 子ランの失敗は独立し、親はリトライや回復を選べる
• ストリーミング・トポロジ — UI のためにツリーを遡ってイベントを流せる

→ 詳細は Agent Composition と Runtime を参照してください。

Structured Streaming

エージェントの意思決定をリアルタイムで可視化します。

ブラックボックスなエージェントはリスクです。ツール呼び出し、思考の開始、エラーの発生を 今すぐ 知る必要があります（タイムアウト後では遅い）。

Goa-AI は実行中に 型付けされたイベントを発行します。たとえば、ストリーミングテキストの assistant_reply、ツールのライフサイクルを表す tool_start/tool_end、推論の可視化のための planner_thought、トークン消費の usage などです。イベントはシンプルな Sink インターフェースを介して任意のトランスポートへ流せます。プロダクションでは UI は セッション所有ストリーム（session/<session_id>）を 1 本購読し、アクティブ run の run_stream_end を観測したら SSE/WebSocket を終了します。

// Wire a sink at startup — all events from all runs flow through it
rt := runtime.New(runtime.WithStream(mySink))

Stream profiles は消費者ごとにイベントをフィルタします。エンドユーザ UI 用の UserChatProfile()、開発者向けの AgentDebugProfile()、観測基盤向けの MetricsProfile() など。Pulse（Redis Streams）用の組み込み sink により、サービス間で分散ストリーミングできます。

メリット:

• トランスポート非依存 — WebSocket / SSE / Pulse / 独自バックエンドで同一イベントを利用
• 型付きコントラクト — 文字列パースなし。ドキュメント化された強い型
• 選択的配信 — プロファイルで消費者ごとに必要なイベントだけを配信
• マルチテナント対応 — RunID と SessionID によりルーティング・フィルタが可能

→ 実装詳細は Production Streaming を参照してください。

Temporal Durability

クラッシュ、再起動、ネットワーク障害に耐えるエージェント実行。

耐久性がないと、プロセスのクラッシュで進捗が消えます。レートリミットでラン全体が失敗します。ツール実行中のネットワーク瞬断で、高価な推論をやり直すことになります。

Goa-AI は Temporal による耐久実行を採用します。エージェントランはワークフローになり、ツール呼び出しはリトライ設定可能なアクティビティになります。すべての状態遷移が永続化され、ツールがクラッシュしても LLM 呼び出しを再実行することなく 自動的にリトライできます。

// Development: in-memory (no dependencies)
rt := runtime.New()

// Production: Temporal for durability
eng, _ := temporal.NewWorker(temporal.Options{
    ClientOptions: &client.Options{HostPort: "localhost:7233"},
    WorkerOptions: temporal.WorkerOptions{TaskQueue: "my-agents"},
})
rt := runtime.New(runtime.WithEngine(eng))

メリット:

• 推論の無駄を削減 — ツール失敗は LLM を再呼び出しせずにリトライ
• クラッシュリカバリ — ワーカーを再起動しても最後のチェックポイントから再開
• レート制限耐性 — 指数バックオフで API スロットリングを吸収
• 安全なデプロイ — ローリングデプロイでも進行中の作業を失わない

→ セットアップとリトライ設定は Production を参照してください。

Tool Registries

どこからでもツールを発見し、利用できます（クラスタ内でもパブリッククラウドでも）。

AI エコシステムが拡大すると、ツールはあらゆる場所に散らばります。社内サービス、サードパーティ API、公開 MCP レジストリ。ツール定義をハードコードする方法はスケールしません。動的ディスカバリが必要です。

Goa-AI は、自社ツールセット向けの クラスタ対応の内部レジストリと、Anthropic の MCP カタログのような外部レジストリと連携する フェデレーションを提供します。一度定義すれば、どこからでも発見できます。

// Connect to public registries
var AnthropicRegistry = Registry("anthropic", func() {
    Description("Anthropic MCP Registry")
    URL("https://registry.anthropic.com/v1")
    Security(AnthropicOAuth)
    Federation(func() {
        Include("web-search", "code-execution", "filesystem")
        Exclude("experimental/*")
    })
    SyncInterval("1h")
    CacheTTL("24h")
})

// Or run your own clustered registry
var CorpRegistry = Registry("corp", func() {
    Description("Internal tool registry")
    URL("https://registry.corp.internal")
    Security(CorpAPIKey)
    SyncInterval("5m")
})

内部レジストリのクラスタリング:

同じ名前の複数ノードは、Redis を介して自動的にクラスタを形成します。共有状態、協調ヘルスチェック、水平スケール——すべて自動です。

メリット:

• 動的ディスカバリ — コンパイル時ではなく実行時にツールを発見
• マルチクラスタ・スケール — ノードが Redis 経由で自動協調
• 公開レジストリ連携 — Anthropic/OpenAI など、任意の MCP レジストリからインポート
• ヘルス監視 — しきい値を持つ ping/pong の自動チェック
• 選択的インポート — include/exclude パターンで粒度の細かい制御

→ 詳細は MCP Integration と Production を参照してください。

機能概要

ドキュメントガイド

Total Section: ~21,400 tokens

アーキテクチャ

Goa-AI は、宣言的な設計をプロダクション品質のエージェントシステムへ変換する define → generate → execute パイプラインに従います。

レイヤ概要:

主要な統合ポイント:

• Model Clients — LLM プロバイダを統一インターフェースの裏に抽象化し、OpenAI/Anthropic/Bedrock を設計変更なしに差し替え
• Registry — プロセス境界を跨いでツールセットを発見・呼び出し。Redis でクラスタ化し水平スケール
• Pulse Streaming — UI 更新、観測パイプライン、サービス間通信のためのリアルタイムイベントバス
• Temporal Engine — 自動リトライ、リプレイ、クラッシュリカバリを備えた耐久ワークフロー実行

モデルプロバイダと拡張性

Goa-AI は 3 つの LLM プロバイダ向けにファーストクラスのアダプタを提供します。

• OpenAI (features/model/openai)
• Anthropic Claude (features/model/anthropic)
• AWS Bedrock (features/model/bedrock)

3 つはいずれも、プランナーが利用する同一の model.Client インターフェースを実装します。アプリケーションは rt.RegisterModel("provider-id", client) でモデルクライアントを登録し、プランナーや生成されたエージェント設定から ID で参照します。プロバイダ差し替えは設計変更ではなく設定変更になります。

新しいプロバイダを追加する手順も同様です。

1. プロバイダ SDK の型を model.Request / model.Response / ストリーミング model.Chunk にマッピングして model.Client を実装する。
2. 必要に応じて共有ミドルウェア（例: features/model/middleware.NewAdaptiveRateLimiter）でレート制限とメトリクスを付与する。
3. エージェント登録前に rt.RegisterModel("my-provider", client) を呼び出し、プランナーやエージェント設定から "my-provider" を参照する。

プランナーとランタイムは model.Client のみに依存するため、新しいプロバイダは Goa の設計や生成コードの変更なしに追加できます。

クイック例

package design

import (
    . "goa.design/goa/v3/dsl"
    . "goa.design/goa-ai/dsl"
)

var _ = Service("calculator", func() {
    Description("Calculator service with an AI assistant")

    // Define a service method that the tool will bind to
    Method("add", func() {
        Description("Add two numbers")
        Payload(func() {
            Attribute("a", Int, "First number")
            Attribute("b", Int, "Second number")
            Required("a", "b")
        })
        Result(Int)
    })

    // Define the agent within the service
    Agent("assistant", "A helpful assistant agent", func() {
        // Use a toolset with tools bound to service methods
        Use("calculator", func() {
            Tool("add", "Add two numbers", func() {
                Args(func() {
                    Attribute("a", Int, "First number")
                    Attribute("b", Int, "Second number")
                    Required("a", "b")
                })
                Return(Int)
                BindTo("add")  // Bind to the service method
            })
        })

        // Configure the agent's run policy
        RunPolicy(func() {
            DefaultCaps(MaxToolCalls(10))
            TimeBudget("5m")
        })
    })
})

はじめに

まずは Quickstart を参照し、Goa-AI をインストールして最初のエージェントを構築してください。

DSL の全体像は DSL Reference を参照してください。

ランタイムアーキテクチャは Runtime を参照してください。