From 9eb6ef099f20b6b3fb5093d7ebb39a3c2d16a35f Mon Sep 17 00:00:00 2001 From: Lifei Zhou Date: Thu, 3 Sep 2026 03:56:32 +0000 Subject: [PATCH] doc (acp): move acp reference under GDK section (#11805) --- .gitignore | 2 +- CUSTOM_DISTROS.md | 2 +- .../index.md | 2 +- .../index.md | 4 +- .../index.md | 4 +- documentation/docs/experimental/index.md | 5 - .../docs/experimental/vs-code-extension.md | 2 +- documentation/docs/gdk/acp/_category_.json | 8 + documentation/docs/gdk/acp/index.md | 104 +++++++ documentation/docs/gdk/acp/zed.md | 130 +++++++++ documentation/docs/gdk/api-reference.mdx | 18 -- documentation/docs/gdk/index.md | 240 +---------------- documentation/docs/gdk/sdk/_category_.json | 8 + documentation/docs/gdk/sdk/api-reference.mdx | 18 ++ documentation/docs/gdk/sdk/index.md | 227 ++++++++++++++++ .../goose-architecture/goose-architecture.md | 3 +- documentation/docs/guides/acp-clients.md | 253 ------------------ .../docs/guides/goose-cli-commands.md | 2 +- .../docs/guides/remote-goose-server.md | 20 +- documentation/docs/guides/roaming-agents.md | 9 +- documentation/scripts/generate-acp-docs.js | 8 +- .../scripts/generate-released-acp-docs.sh | 2 +- .../src/components/GdkApiReference/index.tsx | 4 +- documentation/src/pages/index.tsx | 2 +- 24 files changed, 541 insertions(+), 536 deletions(-) create mode 100644 documentation/docs/gdk/acp/_category_.json create mode 100644 documentation/docs/gdk/acp/index.md create mode 100644 documentation/docs/gdk/acp/zed.md delete mode 100644 documentation/docs/gdk/api-reference.mdx create mode 100644 documentation/docs/gdk/sdk/_category_.json create mode 100644 documentation/docs/gdk/sdk/api-reference.mdx create mode 100644 documentation/docs/gdk/sdk/index.md delete mode 100644 documentation/docs/guides/acp-clients.md diff --git a/.gitignore b/.gitignore index 25a0a377f..d6338688f 100644 --- a/.gitignore +++ b/.gitignore @@ -49,7 +49,7 @@ debug_*.txt # Generated files .docusaurus .cache-loader -/documentation/docs/reference/goose-acp-reference.md +/documentation/docs/gdk/acp/reference.md # Benchmark paths benchmark-* diff --git a/CUSTOM_DISTROS.md b/CUSTOM_DISTROS.md index 74ace5fc5..be9373337 100644 --- a/CUSTOM_DISTROS.md +++ b/CUSTOM_DISTROS.md @@ -325,7 +325,7 @@ ws://localhost:3284/acp?token=a-long-random-secret For browser clients served from a non-loopback origin, pass the exact UI origin with `--allowed-origin`. When you pass `--allowed-origin`, it replaces the default loopback origin allowlist, so include every origin the client needs. -For the ACP protocol and client flow, see [Agent Client Protocol clients](documentation/docs/guides/acp-clients.md). +For the ACP protocol and client flow, see [Use goose as an ACP agent](documentation/docs/gdk/acp/index.md). ### Option 2: Agent Client Protocol (ACP) over stdio diff --git a/documentation/blog/2025-10-24-intro-to-agent-client-protocol-acp/index.md b/documentation/blog/2025-10-24-intro-to-agent-client-protocol-acp/index.md index 4ebd8b7c4..5a3ae87a2 100644 --- a/documentation/blog/2025-10-24-intro-to-agent-client-protocol-acp/index.md +++ b/documentation/blog/2025-10-24-intro-to-agent-client-protocol-acp/index.md @@ -65,7 +65,7 @@ If you're ready to see how fast and simple this setup really is, watch the full -*Ready to integrate goose directly into your editor? Get started with our [ACP setup guide](https://goose-docs.ai/docs/guides/acp-clients) and share your experience in our [Discord community](http://discord.gg/n8R5VaWDAn).* +*Ready to integrate goose directly into your editor? Get started with our [ACP setup guide](https://goose-docs.ai/docs/gdk/acp) and share your experience in our [Discord community](http://discord.gg/n8R5VaWDAn).* diff --git a/documentation/blog/2026-02-06-8-things-you-didnt-know-about-code-mode/index.md b/documentation/blog/2026-02-06-8-things-you-didnt-know-about-code-mode/index.md index 91b101d88..ffe243ce9 100644 --- a/documentation/blog/2026-02-06-8-things-you-didnt-know-about-code-mode/index.md +++ b/documentation/blog/2026-02-06-8-things-you-didnt-know-about-code-mode/index.md @@ -137,7 +137,7 @@ By explicitly importing developer, Code Mode ensured the tests ran in my actual ## 6. Code Mode Is Portable Across Editors -goose is more than an agent; it's also an [ACP (Agent Client Protocol)](/docs/guides/acp-clients) server. This means you can connect it to any editor that supports ACP, like Zed or Neovim. Plus, any MCP server you use in goose will work there, too. +goose is more than an agent; it's also an [ACP (Agent Client Protocol)](/docs/gdk/acp) server. This means you can connect it to any editor that supports ACP, like Zed or Neovim. Plus, any MCP server you use in goose will work there, too. I wanted to try this myself, so I set up Neovim to connect to goose **with Code Mode enabled**. Here's the configuration I used: @@ -210,7 +210,7 @@ Based on my experiments, here is when Code Mode makes sense: If you want to experiment with Code Mode, here are some resources: **Documentation:** -- [ACP client setup](/docs/guides/acp-clients) +- [ACP client setup](/docs/gdk/acp) - [Extensions guide](/docs/getting-started/using-extensions) **Previous posts:** diff --git a/documentation/blog/2026-04-08-how-to-break-up-with-your-agent/index.md b/documentation/blog/2026-04-08-how-to-break-up-with-your-agent/index.md index 13b42b327..c36b5480b 100644 --- a/documentation/blog/2026-04-08-how-to-break-up-with-your-agent/index.md +++ b/documentation/blog/2026-04-08-how-to-break-up-with-your-agent/index.md @@ -37,7 +37,7 @@ acp_providers = { What flows through ACP goes beyond prompts. Editors can delegate file reads (including files you haven't saved yet), run terminal commands, and present permission dialogs natively. Any MCP servers configured in your editor are automatically added as extensions for that goose session, so you don't have to configure them in two places. -See the [ACP clients guide](/docs/guides/acp-clients) for more. +See the [ACP clients guide](/docs/gdk/acp) for more. ## Use Any Agent with Goose @@ -79,7 +79,7 @@ I'm walking through this architecture at [AI Native DevCon](https://tessl.io/spe Pick the UI you like. Pick the agent you like. They don't have to be the same thing. -- [ACP clients guide](/docs/guides/acp-clients) +- [ACP clients guide](/docs/gdk/acp) - [ACP providers guide](/docs/guides/acp-providers) - [Goose on GitHub](https://github.com/aaif-goose/goose) - [Discord community](https://discord.gg/n8R5VaWDAn) diff --git a/documentation/docs/experimental/index.md b/documentation/docs/experimental/index.md index babb511ff..90c325c1f 100644 --- a/documentation/docs/experimental/index.md +++ b/documentation/docs/experimental/index.md @@ -34,11 +34,6 @@ The list of experimental features may change as goose development progresses. So description="Interact with goose directly from VS Code via ACP." link="/docs/experimental/vs-code-extension" /> - diff --git a/documentation/docs/experimental/vs-code-extension.md b/documentation/docs/experimental/vs-code-extension.md index 14e3265e7..80b10e6a7 100644 --- a/documentation/docs/experimental/vs-code-extension.md +++ b/documentation/docs/experimental/vs-code-extension.md @@ -12,7 +12,7 @@ The [goose for VS Code extension](https://marketplace.visualstudio.com/items?ite goose for VS Code is in active development. Behavior and configuration may change in future releases. ::: -The extension uses the [Agent Client Protocol (ACP)](/docs/guides/acp-clients) to communicate with goose. +The extension uses the [Agent Client Protocol (ACP)](/docs/gdk/acp) to communicate with goose. ## Install the Extension diff --git a/documentation/docs/gdk/acp/_category_.json b/documentation/docs/gdk/acp/_category_.json new file mode 100644 index 000000000..501d68ba9 --- /dev/null +++ b/documentation/docs/gdk/acp/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "ACP", + "position": 2, + "link": { + "type": "doc", + "id": "gdk/acp/index" + } +} diff --git a/documentation/docs/gdk/acp/index.md b/documentation/docs/gdk/acp/index.md new file mode 100644 index 000000000..f6bce8eaa --- /dev/null +++ b/documentation/docs/gdk/acp/index.md @@ -0,0 +1,104 @@ +--- +sidebar_position: 1 +title: Use goose as an ACP agent +sidebar_label: Overview +description: Build clients that connect to goose over stdio, HTTP, or WebSocket. +--- + +# Use goose as an ACP agent + +Use the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) to build +clients that connect to goose's agent runtime, tools, extensions, and configured +models. These clients can be code editors, desktop, web, or mobile apps, +automated services, or other custom integrations. + +For methods provided by goose in addition to the standard ACP methods, see the +[goose ACP Reference](/docs/gdk/acp/reference). + +## Install + +Choose one installation method based on how your ACP client runs goose. + +### Install the goose CLI + +Install the [goose CLI](/docs/getting-started/installation) to configure a client +to launch `goose acp` or to run `goose serve` yourself. + +### Install from the ACP Registry + +Supported ACP clients can install and manage goose for you through the +[goose entry in the ACP Registry](https://agentclientprotocol.com/get-started/registry#goose). +This does not require a separate goose CLI installation. + +## Run the agent + +### Connect over stdio + +Configure your ACP client to launch goose as a subprocess with this command: + +```bash +goose acp +``` + +The client communicates with goose through stdin and stdout and manages the +process for the lifetime of the connection. + +### Connect over HTTP or WebSocket + +Run `goose serve` when your ACP client connects over HTTP or WebSocket: + +```bash +GOOSE_SERVER__SECRET_KEY='a-long-random-secret' goose serve +``` + +`GOOSE_SERVER__SECRET_KEY` sets the secret your clients use to authenticate. +When you run `goose serve` directly, it listens on `127.0.0.1:3284` and exposes +the ACP endpoint at `/acp`. To use a different address, pass `--host` and +`--port`. + +#### Authentication + +HTTP clients authenticate with the `X-Secret-Key` header. WebSocket clients can +use the same header, but browser-based WebSocket clients must pass the secret in +the `?token=` query parameter. Requests without the correct secret receive a +`401 Unauthorized` response. + +:::warning Local development only +Passing `--dangerously-unauthenticated` starts `goose serve` without +authentication. Use it only when the server is isolated from untrusted traffic. +::: + +#### Browser origins + +Most clients do not need to configure origins. Browser-based clients served from +a non-loopback origin must allow that origin when starting goose. To allow both +a local development client and a deployed web client, specify both origins: + +```bash +GOOSE_SERVER__SECRET_KEY='a-long-random-secret' goose serve \ + --allowed-origin 'http://localhost:5173' \ + --allowed-origin 'https://app.example' +``` + +Specifying any `--allowed-origin` values replaces the default loopback origins, +so include every origin your clients need, including localhost origins used for +development. Origins must match exactly, including the scheme and port. + +For remote deployment, TLS, and certificate setup, see +[Running a Remote goose Server](/docs/guides/remote-goose-server). +Run `goose serve --help` for the complete list of options. + +## ACP client examples + +### Clients over stdio + +Browse the [official ACP clients directory](https://agentclientprotocol.com/get-started/clients) +for clients that can run local ACP agents. For a worked example of installing +and configuring goose as a stdio agent, see the +[Zed setup example](/docs/gdk/acp/zed). + +### goose Desktop over WebSocket + +[goose Desktop](https://github.com/aaif-goose/goose/tree/main/ui/desktop) is an +ACP client that uses WebSocket. It starts `goose serve` locally on an available +loopback port and connects to its `/acp` endpoint over WebSocket. diff --git a/documentation/docs/gdk/acp/zed.md b/documentation/docs/gdk/acp/zed.md new file mode 100644 index 000000000..6ccb314b5 --- /dev/null +++ b/documentation/docs/gdk/acp/zed.md @@ -0,0 +1,130 @@ +--- +title: Set up goose in Zed +sidebar_position: 3 +description: See how Zed installs and configures goose as an ACP agent. +--- + +# Set up goose in Zed + +Zed can run goose as an ACP agent. Install goose from the ACP Registry for the +simplest setup, or configure it manually to use your own goose binary and +environment overrides. + +## Install goose from the ACP Registry + +Zed has built-in ACP Registry support, so it can download and run goose for you +without manual configuration. + +1. Open Zed +2. Open Agent Settings +3. Click `Add Agent`, then choose `Install from Registry` +4. Select `goose` + +A registry-installed goose runs the same `goose acp` server and reads your +existing goose configuration, so your providers, models, and extensions carry +over. Zed keeps the installed version up to date for you. + +## Configure goose manually + +Use a custom agent if you want to run your own goose binary, such as a local +development build, or pass environment overrides. + +### Prerequisites + +Ensure you have both Zed and the goose CLI installed: + +- **Zed**: Download from [zed.dev](https://zed.dev/) +- **goose CLI**: Follow the [installation guide](/docs/getting-started/installation) + +Verify goose is installed: + +```bash +goose --version +``` + +### Add goose to your Zed settings + +1. Open Zed +2. Open Agent Settings, click `Add Agent`, then choose `Add Custom Agent`. Zed + scaffolds an `agent_servers` entry and opens your settings file +3. Edit the entry so it runs goose: + +```json +{ + "agent_servers": { + "goose": { + "type": "custom", + "command": "goose", + "args": ["acp"] + } + } +} +``` + +You can now interact with goose directly in Zed. ACP sessions use the extensions +enabled in your goose configuration, so their tools are also available in Zed. + +## Override the provider and model + +By default, goose uses the provider and model defined in your +[configuration file](/docs/guides/config-files). Override them for a specific +agent configuration with the `GOOSE_PROVIDER` and `GOOSE_MODEL` environment +variables. + +This example configures two goose agents with different model settings: + +```json +{ + "agent_servers": { + "goose": { + "type": "custom", + "command": "goose", + "args": ["acp"] + }, + "goose (GPT-4o)": { + "type": "custom", + "command": "goose", + "args": ["acp"], + "env": { + "GOOSE_PROVIDER": "openai", + "GOOSE_MODEL": "gpt-4o" + } + } + } +} +``` + +## Use Zed MCP servers with goose + +MCP servers in Zed's `context_servers` configuration are automatically +available to goose. This lets native Zed features and the goose agent use the +same MCP servers. + +```json +{ + "context_servers": { + "filesystem": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "/path/to/allowed/dir" + ] + } + }, + "agent_servers": { + "goose": { + "type": "custom", + "command": "goose", + "args": ["acp"] + } + } +} +``` + +All MCP servers in `context_servers` are available to goose when they use stdio +(command-based) or HTTP transports. goose does not support servers using the +deprecated SSE transport. + +If a server in `context_servers` has the same name as a goose extension, goose +uses its own [configuration](/docs/guides/config-files). diff --git a/documentation/docs/gdk/api-reference.mdx b/documentation/docs/gdk/api-reference.mdx deleted file mode 100644 index 9437ac341..000000000 --- a/documentation/docs/gdk/api-reference.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -sidebar_position: 2 -title: API Reference -sidebar_label: API Reference -description: Complete goose GDK API reference for Rust, Python, and Kotlin. ---- - -import GdkApiReference from '@site/src/components/GdkApiReference'; - -# API Reference - -The complete GDK surface. Use the toggles to switch language and GDK -version — names and types are shown using each language's own conventions. - -New to the GDK? Start with the [GDK overview](/docs/gdk) for installation and -runnable examples. - - diff --git a/documentation/docs/gdk/index.md b/documentation/docs/gdk/index.md index 4dc3583ec..8282f2de0 100644 --- a/documentation/docs/gdk/index.md +++ b/documentation/docs/gdk/index.md @@ -1,239 +1,17 @@ --- -sidebar_position: 1 title: GDK Overview sidebar_label: Overview -description: Build with goose providers in Rust, Python, and Kotlin. +description: Build on goose with the SDK and ACP. --- # GDK -The goose Development Kit (GDK) exposes goose's provider layer as a library so you -can call models, stream completions, and compact conversations from your own -application. +The goose Development Kit (GDK) provides the core components developers need to +build agentic applications, including agent orchestration, model access, context +management, tools, memory, remote execution, automations, and routing. There are +two ways to use it: -One Rust crate, `goose-sdk`, is the source of every language binding. Python and -Kotlin are generated from it with [UniFFI](https://github.com/mozilla/uniffi-rs), -so all three languages share the same types, behavior, and version number. - -See the [API Reference](/docs/gdk/api-reference) for the complete surface in your -language of choice. - -:::info Alpha -The GDK is in alpha. The surface may change between `0.x` releases. Pin an exact -version and check the API reference version selector when upgrading. -::: - -## What you can do - -- Construct providers for OpenAI, Anthropic, Groq, Databricks, or any - [declarative provider](#declarative-providers) defined in JSON -- Stream a completion chunk by chunk, including tool calls and reasoning output -- Request a single non-streaming completion -- Compact a long conversation into a summary so it can continue past the - model's context window -- Capture provider request logs as JSONL - -## Install - - - -### Rust - -```bash -cargo add goose-sdk -``` - -By default the crate re-exports the Agent Client Protocol (ACP) wire types for -talking to `goose acp` over stdio. Enable the `uniffi` feature for the -in-process provider API documented in the reference: - -```bash -cargo add goose-sdk --features uniffi -``` - -### Python - -```bash -pip install goose-sdk -``` - -The package installs as `goose-sdk` and imports as `goose`. Wheels bundle the -native library, so there is nothing else to build. Requires Python 3.9+. - -```python -import goose -``` - -### Kotlin / JVM - -```kotlin -dependencies { - implementation("io.github.aaif-goose:gdk:") - implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2") -} -``` - -The artifact version matches the Rust crate version. Classes live in the -`io.github.aaif_goose` package. The jar bundles native libraries for -macOS (arm64, x86-64), Linux (arm64, x86-64), and Windows (x86-64). - -On JDK 24+, add `--enable-native-access=ALL-UNNAMED` because the GDK loads its -native library through JNA. - - - -## Quickstart - -Each example builds a provider, sends one message, and prints the streamed -response. - -### Python - -```python -import asyncio -from goose import ( - MessageContent, - MessageRole, - ProviderMessage, - ProviderModelConfig, - StreamChunk, - openai_default_model, - openai_provider, -) - - -async def main() -> None: - provider = openai_provider(api_key="...") - model = ProviderModelConfig(model_name=openai_default_model()) - messages = [ - ProviderMessage( - role=MessageRole.USER, - content=[MessageContent.Text(text="What is the capital of France?")], - ) - ] - - stream = await provider.stream(model, "You are a geography expert.", messages, []) - while chunk := await stream.next_chunk(): - if isinstance(chunk, StreamChunk.TextChunk): - print(chunk.text, end="") - - -asyncio.run(main()) -``` - -### Kotlin - -```kotlin -import io.github.aaif_goose.MessageContent -import io.github.aaif_goose.MessageRole -import io.github.aaif_goose.ProviderMessage -import io.github.aaif_goose.ProviderModelConfig -import io.github.aaif_goose.StreamChunk -import io.github.aaif_goose.streamFlow -import io.github.aaif_goose.providers.openai.defaultModel -import io.github.aaif_goose.providers.openai.provider as openAiProvider -import kotlinx.coroutines.runBlocking - -fun main() = runBlocking { - val provider = openAiProvider(System.getenv("OPENAI_API_KEY")) - val model = ProviderModelConfig(modelName = defaultModel()) - val messages = listOf( - ProviderMessage( - role = MessageRole.USER, - content = listOf(MessageContent.Text(text = "What is the capital of France?")), - ), - ) - - provider.streamFlow(model, "You are a geography expert.", messages) - .collect { chunk -> - if (chunk is StreamChunk.TextChunk) print(chunk.text) - } -} -``` - -### Rust - -```rust -use goose_sdk::bindings::{ - openai_default_model, openai_provider, MessageContent, MessageRole, ProviderMessage, - ProviderModelConfig, StreamChunk, -}; - -#[tokio::main] -async fn main() -> Result<(), Box> { - let provider = openai_provider(std::env::var("OPENAI_API_KEY")?)?; - let model = ProviderModelConfig { - model_name: openai_default_model(), - ..Default::default() - }; - let messages = vec![ProviderMessage { - role: MessageRole::User, - content: vec![MessageContent::Text { - text: "What is the capital of France?".to_string(), - }], - }]; - - let stream = provider - .stream(model, "You are a geography expert.".to_string(), messages, vec![]) - .await?; - - while let Some(chunk) = stream.next_chunk().await? { - if let StreamChunk::TextChunk { text } = chunk { - print!("{text}"); - } - } - Ok(()) -} -``` - -## Kotlin idioms - -The Kotlin package adds a few conveniences on top of the generated bindings: - -| Kotlin API | Equivalent generated call | -| --- | --- | -| `provider.streamFlow(model, system, messages, tools)` | `stream(...)` plus a `nextChunk()` loop, as a `Flow` | -| `providers.openai.provider(apiKey)` | `openaiProvider(apiKey)` | -| `providers.openai.defaultModel()` | `openaiDefaultModel()` | -| `providers.anthropic.provider(apiKey, baseUrl, betaHeaders)` | `anthropicProvider(...)` | -| `providers.groq.provider(apiKey)` | `groqProvider(apiKey)` | -| `providers.databricks.provider(host, token)` | `databricksProvider(host, token)` | - -`tools` defaults to an empty list in the Kotlin helpers, and suspending -functions map to Kotlin coroutines. Errors surface as `GooseException` -subclasses. - -## Declarative providers - -Any provider that speaks an OpenAI- or Anthropic-compatible API can be defined -in JSON and loaded without new Rust code: - -```python -provider = goose.declarative_provider_from_json(open("deepseek.json").read()) -``` - -Environment variable placeholders such as `${DEEPSEEK_API_KEY}` in the JSON are -resolved when the provider is constructed. - -## Streaming model - -`stream()` returns a `ProviderStream`. Call `next_chunk()` until it returns -`None` to consume the response: - -| Chunk | Meaning | -| --- | --- | -| `TextChunk` | Assistant text | -| `ToolChunk` | A tool call request with JSON arguments and the provider's tool-call `index` | -| `ThinkingChunk` / `RedactedThinkingChunk` | Reasoning output | -| `EndChunk` | Stream finished, carries final token `Usage` | -| `ErrorChunk` | Mid-stream failure, carries a `GooseStreamError` | - -Errors raised before the stream starts are thrown as `GooseError` -(`GooseException` in Kotlin). Errors that occur mid-stream arrive as an -`ErrorChunk` instead. - -## Next steps - -- [API Reference](/docs/gdk/api-reference) — every function, type, and error -- [goose in ACP clients](/docs/guides/acp-clients) — drive the full goose agent - over the Agent Client Protocol +- [SDK](/docs/gdk/sdk) — use goose's provider layer as an in-process + library from Rust, Python, or Kotlin. +- [ACP](/docs/gdk/acp) — connect to goose as a separate agent process over + stdio, HTTP, or WebSocket. diff --git a/documentation/docs/gdk/sdk/_category_.json b/documentation/docs/gdk/sdk/_category_.json new file mode 100644 index 000000000..18edbd5d5 --- /dev/null +++ b/documentation/docs/gdk/sdk/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "SDK", + "position": 1, + "link": { + "type": "doc", + "id": "gdk/sdk/index" + } +} diff --git a/documentation/docs/gdk/sdk/api-reference.mdx b/documentation/docs/gdk/sdk/api-reference.mdx new file mode 100644 index 000000000..271130e73 --- /dev/null +++ b/documentation/docs/gdk/sdk/api-reference.mdx @@ -0,0 +1,18 @@ +--- +sidebar_position: 2 +title: SDK Reference +sidebar_label: API Reference +description: Complete SDK reference for Rust, Python, and Kotlin. +--- + +import GdkApiReference from '@site/src/components/GdkApiReference'; + +# SDK Reference + +The complete SDK surface. Use the toggles to switch language and SDK +version — names and types are shown using each language's own conventions. + +New to the SDK? Start with the [SDK overview](/docs/gdk/sdk) for +installation and runnable examples. + + diff --git a/documentation/docs/gdk/sdk/index.md b/documentation/docs/gdk/sdk/index.md new file mode 100644 index 000000000..0897e71df --- /dev/null +++ b/documentation/docs/gdk/sdk/index.md @@ -0,0 +1,227 @@ +--- +sidebar_position: 1 +title: SDK +sidebar_label: Overview +description: Build with goose providers in Rust, Python, and Kotlin. +--- + +# SDK + +The SDK exposes its provider layer as an in-process library so you can +call models, stream completions, and compact conversations from your own +application. + +One Rust crate, `goose-sdk`, is the source of every language binding. Python and +Kotlin are generated from it with [UniFFI](https://github.com/mozilla/uniffi-rs), +so all three languages share the same types, behavior, and version number. + +See the [API Reference](/docs/gdk/sdk/api-reference) for the complete +surface in your language of choice. + +:::info Alpha +The SDK is in alpha. The surface may change between `0.x` releases. Pin an +exact version and check the API reference version selector when upgrading. +::: + +## What you can do + +- Construct providers for OpenAI, Anthropic, Groq, Databricks, or any + [declarative provider](#declarative-providers) defined in JSON +- Stream a completion chunk by chunk, including tool calls and reasoning output +- Request a single non-streaming completion +- Compact a long conversation into a summary so it can continue past the + model's context window +- Capture provider request logs as JSONL + +## Install + + + +### Rust + +```bash +cargo add goose-sdk --features uniffi +``` + +The `uniffi` feature enables the in-process provider API documented here. + +### Python + +```bash +pip install goose-sdk +``` + +The package installs as `goose-sdk` and imports as `goose`. Wheels bundle the +native library, so there is nothing else to build. Requires Python 3.9+. + +```python +import goose +``` + +### Kotlin / JVM + +```kotlin +dependencies { + implementation("io.github.aaif-goose:gdk:") + implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2") +} +``` + +The artifact version matches the Rust crate version. Classes live in the +`io.github.aaif_goose` package. The jar bundles native libraries for +macOS (arm64, x86-64), Linux (arm64, x86-64), and Windows (x86-64). + +On JDK 24+, add `--enable-native-access=ALL-UNNAMED` because the GDK loads its +native library through JNA. + + + +## Quickstart + +Each example builds a provider, sends one message, and prints the streamed +response. + +### Python + +```python +import asyncio +from goose import ( + MessageContent, + MessageRole, + ProviderMessage, + ProviderModelConfig, + StreamChunk, + openai_default_model, + openai_provider, +) + + +async def main() -> None: + provider = openai_provider(api_key="...") + model = ProviderModelConfig(model_name=openai_default_model()) + messages = [ + ProviderMessage( + role=MessageRole.USER, + content=[MessageContent.Text(text="What is the capital of France?")], + ) + ] + + stream = await provider.stream(model, "You are a geography expert.", messages, []) + while chunk := await stream.next_chunk(): + if isinstance(chunk, StreamChunk.TextChunk): + print(chunk.text, end="") + + +asyncio.run(main()) +``` + +### Kotlin + +```kotlin +import io.github.aaif_goose.MessageContent +import io.github.aaif_goose.MessageRole +import io.github.aaif_goose.ProviderMessage +import io.github.aaif_goose.ProviderModelConfig +import io.github.aaif_goose.StreamChunk +import io.github.aaif_goose.streamFlow +import io.github.aaif_goose.providers.openai.defaultModel +import io.github.aaif_goose.providers.openai.provider as openAiProvider +import kotlinx.coroutines.runBlocking + +fun main() = runBlocking { + val provider = openAiProvider(System.getenv("OPENAI_API_KEY")) + val model = ProviderModelConfig(modelName = defaultModel()) + val messages = listOf( + ProviderMessage( + role = MessageRole.USER, + content = listOf(MessageContent.Text(text = "What is the capital of France?")), + ), + ) + + provider.streamFlow(model, "You are a geography expert.", messages) + .collect { chunk -> + if (chunk is StreamChunk.TextChunk) print(chunk.text) + } +} +``` + +### Rust + +```rust +use goose_sdk::bindings::{ + openai_default_model, openai_provider, MessageContent, MessageRole, ProviderMessage, + ProviderModelConfig, StreamChunk, +}; + +#[tokio::main] +async fn main() -> Result<(), Box> { + let provider = openai_provider(std::env::var("OPENAI_API_KEY")?)?; + let model = ProviderModelConfig { + model_name: openai_default_model(), + ..Default::default() + }; + let messages = vec![ProviderMessage { + role: MessageRole::User, + content: vec![MessageContent::Text { + text: "What is the capital of France?".to_string(), + }], + }]; + + let stream = provider + .stream(model, "You are a geography expert.".to_string(), messages, vec![]) + .await?; + + while let Some(chunk) = stream.next_chunk().await? { + if let StreamChunk::TextChunk { text } = chunk { + print!("{text}"); + } + } + Ok(()) +} +``` + +## Kotlin idioms + +The Kotlin package adds a few conveniences on top of the generated bindings: + +| Kotlin API | Equivalent generated call | +| --- | --- | +| `provider.streamFlow(model, system, messages, tools)` | `stream(...)` plus a `nextChunk()` loop, as a `Flow` | +| `providers.openai.provider(apiKey)` | `openaiProvider(apiKey)` | +| `providers.openai.defaultModel()` | `openaiDefaultModel()` | +| `providers.anthropic.provider(apiKey, baseUrl, betaHeaders)` | `anthropicProvider(...)` | +| `providers.groq.provider(apiKey)` | `groqProvider(apiKey)` | +| `providers.databricks.provider(host, token)` | `databricksProvider(host, token)` | + +`tools` defaults to an empty list in the Kotlin helpers, and suspending +functions map to Kotlin coroutines. Errors surface as `GooseException` +subclasses. + +## Declarative providers + +Any provider that speaks an OpenAI- or Anthropic-compatible API can be defined +in JSON and loaded without new Rust code: + +```python +provider = goose.declarative_provider_from_json(open("deepseek.json").read()) +``` + +Environment variable placeholders such as `${DEEPSEEK_API_KEY}` in the JSON are +resolved when the provider is constructed. + +## Streaming model + +`stream()` returns a `ProviderStream`. Call `next_chunk()` until it returns +`None` to consume the response: + +| Chunk | Meaning | +| --- | --- | +| `TextChunk` | Assistant text | +| `ToolChunk` | A tool call request with JSON arguments and the provider's tool-call `index` | +| `ThinkingChunk` / `RedactedThinkingChunk` | Reasoning output | +| `EndChunk` | Stream finished, carries final token `Usage` | +| `ErrorChunk` | Mid-stream failure, carries a `GooseStreamError` | + +Errors raised before the stream starts are thrown as `GooseError` +(`GooseException` in Kotlin). Errors that occur mid-stream arrive as an +`ErrorChunk` instead. diff --git a/documentation/docs/goose-architecture/goose-architecture.md b/documentation/docs/goose-architecture/goose-architecture.md index 7b601a2e9..4d5da395b 100644 --- a/documentation/docs/goose-architecture/goose-architecture.md +++ b/documentation/docs/goose-architecture/goose-architecture.md @@ -35,7 +35,7 @@ goose supports the [Agent Client Protocol (ACP)](https://agentclientprotocol.com ### goose as an ACP Server -`goose acp` starts goose as an ACP server over stdio, letting editors like JetBrains and Zed connect to it directly. See [Using goose in ACP Clients](/docs/guides/acp-clients). +`goose acp` starts goose as an ACP server over stdio, letting editors like JetBrains and Zed connect to it directly. See [Using goose in ACP Clients](/docs/gdk/acp). ### ACP Agents as Providers @@ -73,4 +73,3 @@ While goose is free and open source, there is typically a cost associated with L * goose uses algorithms to delete old or irrelevant content * goose will use find and replace instead of rewriting large files, use ripgrep to skip system files, and summarize verbose command outputs - diff --git a/documentation/docs/guides/acp-clients.md b/documentation/docs/guides/acp-clients.md deleted file mode 100644 index b1203a9e7..000000000 --- a/documentation/docs/guides/acp-clients.md +++ /dev/null @@ -1,253 +0,0 @@ ---- -sidebar_position: 105 -title: Using goose in ACP Clients -sidebar_label: goose in ACP Clients ---- - -Client applications that support the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) can connect natively to goose. This integration allows you to seamlessly interact with goose directly from the client. - -:::warning Experimental Feature -ACP is an emerging specification that enables clients to communicate with AI agents like goose. This feature has limited adoption and may evolve as the protocol develops. -::: - -## How It Works -After you configure goose as an agent in the ACP client, you gain access to goose's core agent functionality, including its extensions and tools. goose also automatically loads any [configured MCP servers](#using-mcp-servers-from-acp-clients) from your ACP client alongside its own extensions, making their tools available without additional configuration. - -The client manages the goose lifecycle automatically, including: - -- **Initialization**: The client runs the `goose acp` command to initialize the connection -- **Communication**: The client communicates with goose over stdio using JSON-RPC -- **Multiple Sessions**: The client manages multiple concurrent conversations, each with isolated state -- **Model and Mode Switching**: The client can switch models and modes mid-session without restarting -- **File Operations**: The client handles file reads and writes, so goose sees changes not yet saved to disk and edits show as native diffs -- **Terminal**: The client runs commands in its own terminal, so output appears alongside the conversation - -:::info Session Persistence -ACP sessions are saved to goose's session history where you can access and manage them using goose. Access to session history in ACP clients might vary. -::: - -:::tip Reference Implementation -The [goose for VS Code](/docs/experimental/vs-code-extension) extension uses ACP to communicate with goose. See the [vscode-goose](https://github.com/aaif-goose/vscode-goose) repository for implementation details. -::: - -## Setup in ACP Clients -Any editor or IDE that supports ACP can connect to goose as an agent server. Check the [official ACP clients list](https://agentclientprotocol.com/overview/clients) for available clients with links to their documentation. - -### Example: Zed Editor Setup - -ACP was originally developed by [Zed](https://zed.dev/). Zed offers two ways to add goose, and you can use either one. - -#### Option 1: Install from the ACP Registry (recommended) - -goose is published in the [ACP Registry](https://agentclientprotocol.com/registry), and Zed 1.5.0 and later has built-in registry support, so it can download and run goose for you, with no manual configuration and no pre-installed CLI required. - -1. Open Zed -2. Open Agent Settings -3. Click `Add Agent`, then choose `Install from Registry` -4. Select `goose` - -A registry-installed goose runs the same `goose acp` server and reads your existing goose configuration, so your providers, models, and extensions carry over. Zed keeps the installed version up to date for you. - -#### Option 2: Configure goose as a Custom Agent - -Use a custom agent if you want to run your own goose binary (for example, a local development build) or pass environment overrides. - -##### Prerequisites - -Ensure you have both Zed and goose CLI installed: - -- **Zed**: Download from [zed.dev](https://zed.dev/) -- **goose CLI**: Follow the [installation guide](/docs/getting-started/installation) - - - Verify goose is installed: `goose --version` - - - Temporarily run `goose acp` to test that ACP support is working: - - ```bash - goose acp - ``` - - Press `Ctrl+C` to exit the test. - -##### Add goose to Your Zed Settings - -1. Open Zed -2. Open Agent Settings, click `Add Agent`, then choose `Add Custom Agent`. Zed scaffolds an `agent_servers` entry and opens your settings file -3. Edit the entry so it runs goose: - -```json -{ - "agent_servers": { - "goose": { - "type": "custom", - "command": "goose", - "args": ["acp"] - } - }, -} -``` - -You should now be able to interact with goose directly in Zed. Your ACP sessions use the same extensions that are enabled in your goose configuration, and your tools (Developer, Computer Controller, etc.) work the same way as in regular goose sessions. - -#### Start Using goose in Zed - -After adding goose with either option above: - -1. **Open the Agent Panel**: Click the sparkles agent icon in Zed's status bar -2. **Create New Thread**: Click the `+` button to show thread options -3. **Select goose**: Choose `New goose` to start a new conversation with goose -4. **Start Chatting**: Interact with goose directly from the agent panel - -#### Advanced Configuration - -##### Overriding Provider and Model - -By default, goose will use the provider and model defined in your [configuration file](/docs/guides/config-files). You can override this for specific ACP configurations using the `GOOSE_PROVIDER` and `GOOSE_MODEL` environment variables. - -The following Zed settings example configures two goose agent instances. This is useful for: -- Comparing model performance on the same task -- Using cost-effective models for simple tasks and powerful models for complex ones - -```json -{ - "agent_servers": { - "goose": { - "type": "custom", - "command": "goose", - "args": ["acp"] - }, - "goose (GPT-4o)": { - "type": "custom", - "command": "goose", - "args": ["acp"], - "env": { - "GOOSE_PROVIDER": "openai", - "GOOSE_MODEL": "gpt-4o" - } - } - }, -} -``` - -## Using MCP Servers from ACP Clients - -MCP servers configured in the ACP client's `context_servers` are automatically available to goose. This allows you to use those MCP servers when using both native client features and the goose agent integration. - -**Example (Zed):** - -```json -{ - "context_servers": { - "filesystem": { - "command": "npx", - "args": [ - "-y", - "@modelcontextprotocol/server-filesystem", - "/path/to/allowed/dir" - ] - } - }, - "agent_servers": { - "goose": { - "type": "custom", - "command": "goose", - "args": ["acp"] - } - }, -} -``` - -To find out what tools are available, just ask goose while it's running in the client. - -:::info -All MCP servers in `context_servers` are automatically available to goose, provided that they use stdio (command-based) or HTTP transports. goose doesn't support servers that use the deprecated SSE transport. - -If a server in `context_servers` has the same name as a goose extension, goose uses its own [configuration](/docs/guides/config-files). -::: - -## TUI Client (Deprecated) - -:::warning Deprecated -The experimental terminal UI (TUI) client, formerly published to npm as `@aaif/goose`, is no longer maintained and has been removed. Use the [CLI](/docs/getting-started/installation) or the desktop app instead. -::: - -## Server Authentication - -Set the `GOOSE_SERVER__SECRET_KEY` environment variable to authenticate the ACP endpoint. `goose serve` refuses to start without this secret unless you explicitly pass `--dangerously-unauthenticated`: - -```bash -GOOSE_SERVER__SECRET_KEY='a-long-random-secret' goose serve -``` - -Clients authenticate by sending the token in the `X-Secret-Key` header, or as a `?token=` query parameter for WebSocket connections (the browser WebSocket API can't set custom headers). Requests without a matching token receive `401 Unauthorized`, including WebSocket handshakes. - -ACP WebSocket Origin validation allows loopback web origins by default. For `goose serve`, ACP CORS follows the same policy. If you pass any `--allowed-origin` values, that explicit list replaces the default loopback origins, so include every origin the client needs: - -```bash -GOOSE_SERVER__SECRET_KEY='a-long-random-secret' goose serve \ - --allowed-origin 'http://localhost:5173' \ - --allowed-origin 'app://localhost' \ - --allowed-origin 'https://app.example' -``` - -For local development only, `goose serve --dangerously-unauthenticated` starts without a secret and logs a warning. Do not use this mode with shell-capable builtins enabled unless the server is isolated from untrusted browser traffic. - -### Single Prompt Mode - -Send a single prompt and exit (useful for scripting): - -```bash -npm start -- --text "What files are in this directory?" -``` - -### Keyboard Shortcuts - -| Shortcut | Action | -|----------|--------| -| `Enter` | Send message | -| `↑` / `↓` | Scroll current response | -| `Shift+↑` / `Shift+↓` | Navigate conversation history | -| `Tab` | Expand/collapse tool call details | -| `Ctrl+C` or `Esc` | Exit (or cancel permission dialog) | - -### Permission Dialog - -When goose requests permission to use a tool, a dialog appears with these options: - -| Key | Action | -|-----|--------| -| `y` | Allow once | -| `a` | Always allow | -| `n` | Reject once | -| `N` | Always reject | -| `↑` / `↓` | Navigate options | -| `Enter` | Confirm selection | -| `Esc` | Cancel | - -## Additional Resources - -import ContentCardCarousel from '@site/src/components/ContentCardCarousel'; -import chooseYourIde from '@site/blog/2025-10-24-intro-to-agent-client-protocol-acp/choose-your-ide.png'; - - diff --git a/documentation/docs/guides/goose-cli-commands.md b/documentation/docs/guides/goose-cli-commands.md index c665eefd1..bbb92c374 100644 --- a/documentation/docs/guides/goose-cli-commands.md +++ b/documentation/docs/guides/goose-cli-commands.md @@ -695,7 +695,7 @@ goose acp ``` :::info -This command is automatically invoked by ACP-compatible clients and is not typically run directly by users. The client manages the lifecycle of the `goose acp` process. See [Using goose in ACP Clients](/docs/guides/acp-clients) for details. +This command is automatically invoked by ACP-compatible clients and is not typically run directly by users. The client manages the lifecycle of the `goose acp` process. See [Using goose in ACP Clients](/docs/gdk/acp) for details. ::: --- diff --git a/documentation/docs/guides/remote-goose-server.md b/documentation/docs/guides/remote-goose-server.md index 3ca87f805..bfb46bc30 100644 --- a/documentation/docs/guides/remote-goose-server.md +++ b/documentation/docs/guides/remote-goose-server.md @@ -112,6 +112,10 @@ After saving, goose Desktop will route all backend requests to the remote `goose Running `goose serve` in a terminal session is fine for testing, but for everyday use you probably want it managed as a background service so it starts at login and restarts on failure. On macOS, this is done with `launchd`. +The example below uses the CLI binary bundled with goose Desktop. If you installed the CLI separately, replace `/Applications/Goose.app/Contents/Resources/bin/goose` with the absolute path returned by `which goose`. + +Because the secret is stored in XML, use a hexadecimal value such as the output of `openssl rand -hex 32`, or escape XML special characters in the value. + Create a LaunchAgent plist at `~/Library/LaunchAgents/com.goose.serve.external.plist`: ```xml @@ -152,28 +156,32 @@ Create a LaunchAgent plist at `~/Library/LaunchAgents/com.goose.serve.external.p ``` -Replace `YOUR_SECRET` and `YOUR_USERNAME` with appropriate values, and make sure the log directory exists: +Replace `YOUR_SECRET` and `YOUR_USERNAME` with appropriate values. Then create the log directory and restrict access to the plist, which contains the secret key: ```bash mkdir -p ~/Library/Logs/GooseExternal +chmod 600 ~/Library/LaunchAgents/com.goose.serve.external.plist ``` -Then load and start the service: +Load and start the service: ```bash launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.goose.serve.external.plist +``` + +To restart the service later: + +```bash launchctl kickstart -k gui/$(id -u)/com.goose.serve.external ``` -To stop or remove it later: +To stop and unload the service: ```bash launchctl bootout gui/$(id -u)/com.goose.serve.external ``` -:::tip -Because the secret key is stored in plain text in the plist, the file should be readable only by your user. macOS LaunchAgents under `~/Library/LaunchAgents/` are already user-scoped, but you can tighten further with `chmod 600 ~/Library/LaunchAgents/com.goose.serve.external.plist`. -::: +To remove the service configuration, delete the plist after unloading it. ## Troubleshooting diff --git a/documentation/docs/guides/roaming-agents.md b/documentation/docs/guides/roaming-agents.md index 414ff6ac2..b124f6154 100644 --- a/documentation/docs/guides/roaming-agents.md +++ b/documentation/docs/guides/roaming-agents.md @@ -35,7 +35,7 @@ or wire p2p agent access into your own application. ## The core idea: roaming is an ACP transport Roaming does exactly one thing: it provides an **authenticated, peer-to-peer -[ACP](/docs/guides/acp-clients) transport**. The host runs goose's real ACP +[ACP](/docs/gdk/acp) transport**. The host runs goose's real ACP server; the connecting side is an ACP client. That's it. Everything that feels "session-shaped" is therefore just plain ACP that happens @@ -163,10 +163,9 @@ goose roam delegate 'goose+roam://…' --session "Now fix the first `connect` and `delegate` embed goose's own ACP client. `bridge` does the opposite: it exposes a remote agent as a **local ACP endpoint**, so any ACP -client — [Zed](/docs/guides/acp-clients) or another editor — can drive it as if -it were running locally. It runs no UI and no agent -of its own; it transparently proxies ACP bytes between the local client and the -remote agent. +client — Zed or another editor — can drive it as if it were running locally. It +runs no UI and no agent of its own; it transparently proxies ACP bytes between +the local client and the remote agent. Bridge over stdio (the default — for a client that launches goose as a subprocess): diff --git a/documentation/scripts/generate-acp-docs.js b/documentation/scripts/generate-acp-docs.js index 21912cc9a..009bd67a1 100644 --- a/documentation/scripts/generate-acp-docs.js +++ b/documentation/scripts/generate-acp-docs.js @@ -8,8 +8,9 @@ const OUTPUT_FILE = path.join( ROOT, 'documentation', 'docs', - 'reference', - 'goose-acp-reference.md' + 'gdk', + 'acp', + 'reference.md' ); const UNSUPPORTED_KEYWORDS = [ 'contains', @@ -239,7 +240,8 @@ function renderDocumentation(schemas, meta, gooseVersion = 'Preview') { const output = [ '---', 'title: goose ACP Reference', - 'sidebar_label: goose ACP Reference', + 'sidebar_label: Reference', + 'sidebar_position: 2', '---', '', '# goose ACP Reference', diff --git a/documentation/scripts/generate-released-acp-docs.sh b/documentation/scripts/generate-released-acp-docs.sh index 1f64ef043..915d9dc81 100755 --- a/documentation/scripts/generate-released-acp-docs.sh +++ b/documentation/scripts/generate-released-acp-docs.sh @@ -20,4 +20,4 @@ meta="$temp_dir/acp-meta.json" git show "$acp_ref:crates/goose/acp-schema.json" > "$schema" git show "$acp_ref:crates/goose/acp-meta.json" > "$meta" node documentation/scripts/generate-acp-docs.js "$schema" "$meta" \ - documentation/docs/reference/goose-acp-reference.md "$acp_ref" + documentation/docs/gdk/acp/reference.md "$acp_ref" diff --git a/documentation/src/components/GdkApiReference/index.tsx b/documentation/src/components/GdkApiReference/index.tsx index 81f321e9e..46942beb7 100644 --- a/documentation/src/components/GdkApiReference/index.tsx +++ b/documentation/src/components/GdkApiReference/index.tsx @@ -413,7 +413,7 @@ export default function GdkApiReference() {
-
+
{LANGUAGES.map((entry) => (

Agentic AI Foundation