<p align="center"> <a href="https://goa.design/docs/2-goa-ai/#gh-light-mode-only"> <picture> <source media="(max-width: 600px)" srcset="docs/img/goa-ai-banner-mobile.png"> <img alt="Goa-AI: one Go design generates typed agent tools, MCP clients and servers, and HTTP and gRPC APIs." src="docs/img/goa-ai-banner.png" width="960"> </picture> </a> <a href="https://goa.design/docs/2-goa-ai/#gh-dark-mode-only"> <picture> <source media="(max-width: 600px)" srcset="docs/img/goa-ai-banner-mobile-dark.png"> <img alt="Goa-AI: one Go design generates typed agent tools, MCP clients and servers, and HTTP and gRPC APIs." src="docs/img/goa-ai-banner-dark.png" width="960"> </picture> </a> </p> <p align="center"> <a href="https://github.com/goadesign/goa-ai/releases/latest"><img alt="Release" src="https://img.shields.io/github/v/release/goadesign/goa-ai"></a> <a href="https://github.com/goadesign/goa-ai/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/goadesign/goa-ai/ci.yml?branch=main"></a> <a href="https://pkg.go.dev/goa.design/goa-ai"><img alt="Go reference" src="https://pkg.go.dev/badge/goa.design/goa-ai.svg"></a> <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-blue.svg"></a> </p>

Goa-AI: agents, MCP, and tool registries in Go

Design your capabilities once. Generate the contracts that connect your services, AI agents, and MCP clients.

Goa-AI extends Goa with AI agents, the Model Context Protocol (MCP), and distributed tool registries. Write a design in Go; generate typed clients, servers, model schemas, validation, and runtime wiring. Implement your application's behavior in ordinary Go.

For engineers, this means fewer contracts to maintain and compiler feedback when they change. For coding agents, it means explicit types, generated validation, and an application-specific guide to the code they need to implement.

Run the quickstart · Explore the guides · Upgrade to v0.89.0

Choose what you want to build

| Your goal | Start here | | --- | --- | | An AI agent that calls typed tools, returns structured answers, and can pause for human input | Agent quickstart | | An MCP server exposing Go service methods, resources, and prompts, or an MCP client consuming them | MCP integration guide | | A tool registry that publishes capabilities across services and lets agents discover independently implemented Agent operations without loading provider code, or binds generated native tools to selected registrations while retaining typed codecs and child routes | Registries and tool search |

Low-level runtime and custom Store integrations use a required generated run subject to identify the actual executor. Read its upgrade requirements before changing a deployment with saved runs.

These capabilities compose. You can also use MCP servers and clients independently of the agent runtime.

Paged agent tools declared with ContinueWith publish one operation for both the initial query and subsequent pages. Direct callers supply the declared page arguments; agents receive temporary no-argument actions tied to the exact query. See pagination ownership for the generated input and execution contracts.

One design, several ways to use it

A product lookup can be an HTTP endpoint, a gRPC method, an MCP tool, and a local agent tool. The input, output, descriptions, and validation come from the same design:

package design

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

var Lookup = Type("Lookup", func() {
    Field(1, "sku", String, "Product SKU", func() { MinLength(1) })
    Required("sku")
    Example(map[string]any{"sku": "SKU-123"})
})

var Product = Type("Product", func() {
    Field(1, "name", String, "Product name")
    Required("name")
})

var _ = Service("catalog", func() {
    Description("Look up products for applications and shopping assistants.")
    MCP("catalog", "1.0.0")
    JSONRPC(func() { POST("/mcp") })

    Method("lookup", func() {
        Description("Retrieve a product by its SKU.")
        Payload(Lookup)
        Result(Product)
        HTTP(func() { GET("/products/{sku}") })
        GRPC(func() {})
        Tool("lookup", "Look up a product by SKU")
    })

    Agent("shopper", "Help customers find products", func() {
        Use("products", func() {
            Tool("lookup", "Look up a product by SKU", func() {
                BindTo("lookup")
            })
        })
    })
})

Run generation using the Goa version selected by your application:

go run goa.design/goa/v3/cmd/goa gen <design-package-import-path>

| From this design | You get | | --- | --- | | Service contract | Typed Go interfaces, payloads, results, and validation | | Agent tool | Model-facing JSON Schema, examples, codecs, and a service executor | | MCP tool | A typed client and HTTP server with discovery and input/output schemas | | HTTP and gRPC methods | Clients, servers, OpenAPI, and protobuf definitions |

Change a field and regenerate these contracts together. Your implementation, planner, authorization, and business rules remain application code. Ordinary methods can coexist with MCP tools in the same service.

Tools can expose a focused subset of a method's inputs and results, inject server-owned values, or return a selected Goa result view. The generator handles the declared transforms. See service bindings and MCP composition.

Quick start

With Go 1.27.0 or newer, run the checked-in example:

git clone https://github.com/goadesign/goa-ai.git
cd goa-ai/quickstart
go run ./cmd/orchestrator

It runs the real agent loop and typed completions with a deterministic planner and an in-memory engine and store. No model API key, Temporal, Redis, or MongoDB is required. You'll see:

Assistant: Tool helpers.answer returned {"text":"Tokyo is the capital of Japan."}
Completion draft_task: Prepare launch checklist (Confirm the service is ready to launch.), 3 steps

Run its evaluation suite:

go run ./cmd/chat_quality-evals

The quickstart guide walks through the design, generation, service wiring, and connecting a model. For MCP, follow the MCP integration guide.

What you can build

Agents and typed outputs

• Typed tools and structured answers. Bind tools to Goa methods or custom executors; declare Completion(...) for typed direct responses. Generated codecs and schemas enforce the authored contract.
• Correction of invalid tool calls. Missing fields, wrong types, and invalid values receive specific feedback and authored examples. The runtime can ask the model for a replacement within your recovery budget, before execution.
• Specialist agents. Expose agents as tools and compose real child runs with linked progress and cancellation. Cancellation preserves completed results and waits for required cleanup before closing the run; cleanup failures remain errors. Child workflow IDs stay bounded for long names and repeated nesting; see the identifier and worker upgrade contract.
• Human input and approvals. Save a pending question or confirmation and continue from the host's answer. Direct and registered operations share durable continuation submission and completion. Hosts supply each successor workflow's Memo explicitly; recovery preserves it and rejects changed answers or metadata. Canceling a root question with no saved child or remote work closes its continuation while preserving the original suspended result. Text-only runs exclude interactive tools. Hosts can apply the same restriction to exact direct and registered operations with WithTextOnly(true).
• Large results and images. Bound model-visible results, continue paginated queries, retain native image evidence, and keep rich host data outside model requests. Saved history remains readable after tool changes; only compatible current tools can supply another page.

Agent DSL · Runtime and composition · Native images

MCP clients and servers

• MCP 2026-07-28 over HTTP. Generate stateless servers and typed clients with discovery, tools, structured results, and ordered text, image, audio, resource links, and embedded resources. Consumers also support stdio; generated stdio servers are deferred. Generated HTTP servers also accept basic 2025-11-25 clients on the same URL, using the same configured Goa endpoints. See the older-client contract.
• Runtime-defined tools. Declare DynamicTools() to implement tool listing and invocation through generated protocol types without authored static tools. Older clients receive dynamic structured results in a matching value object; modern clients receive the original JSON value. See runtime-defined tools.
• Resources and prompts. Serve fixed or parameterized text/binary resources, typed prompts, argument completion, and authenticated paginated catalogs.
• Progress and subscriptions. Report progress from ordinary service methods; observe catalog changes, resource updates, and full Task state. Silent HTTP responses use transport keepalive comments without requiring service progress. Regenerate MCP servers when upgrading: a dependency-only update leaves streaming before middleware. Follow the required upgrade.
• Additional input and durable Tasks. Collect form input or URL consent; preserve additional protocol members without changing declared fields; expose existing durable jobs with creation, observation, answers, and cancellation. The same native methods work as local and registry tools.
• Authorization. Compose browser OAuth, machine credentials, signed client authentication, and enterprise identity exchange. Servers verify configured signed tokens or use token introspection. Hosts own trusted registration, consent, and private credential storage.
• Apps and Skills. Associate tools with HTML app resources and caller visibility; publish Skill catalogs and files with manifest verification. Reference hosts demonstrate browser isolation and content-bound approval.

MCP declarations · Clients and authorization · Apps example · Skills guide

Context-limit responses are recovered by the workflow rather than accepted as completed answers or executable tool batches. The runtime uses its existing history policy to summarize older turns before a replacement request, preserves live text and usage, and stops if compaction cannot shorten the input. This uses the existing recovery-turn budget. See context-window recovery.

Initial-history writes reference the already bound preparation operation; seed reads return its original invocation without duplicating it in bounded commands. Custom stores must follow the preparation ownership upgrade.

Registries, search, and production execution

• Distributed tool registries. Publish typed toolsets, discover changing catalogs, and route calls to providers with e