doc (acp): move acp reference under GDK section (#11805)

This commit is contained in:
Lifei Zhou
2026-09-03 03:56:32 +00:00
committed by GitHub
parent 27d08b691b
commit 9eb6ef099f
24 changed files with 541 additions and 536 deletions
+1 -1
View File
@@ -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-*
+1 -1
View File
@@ -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
@@ -65,7 +65,7 @@ If you're ready to see how fast and simple this setup really is, watch the full
<iframe class="aspect-ratio" src="https://www.youtube.com/embed/Hvu5KDTb6JE" title="Vibe Code with goose: Intro to ACP" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
*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).*
<head>
@@ -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:**
@@ -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)
-5
View File
@@ -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"
/>
<Card
title="Using goose in ACP Clients"
description="Interact with goose natively in ACP-compatible clients like Zed."
link="/docs/guides/acp-clients"
/>
</div>
</div>
@@ -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
@@ -0,0 +1,8 @@
{
"label": "ACP",
"position": 2,
"link": {
"type": "doc",
"id": "gdk/acp/index"
}
}
+104
View File
@@ -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.
+130
View File
@@ -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).
-18
View File
@@ -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.
<GdkApiReference />
+9 -231
View File
@@ -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
<!-- prettier-ignore-start -->
### 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:<version>")
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.
<!-- prettier-ignore-end -->
## 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<dyn std::error::Error>> {
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<StreamChunk>` |
| `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.
@@ -0,0 +1,8 @@
{
"label": "SDK",
"position": 1,
"link": {
"type": "doc",
"id": "gdk/sdk/index"
}
}
@@ -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.
<GdkApiReference />
+227
View File
@@ -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
<!-- prettier-ignore-start -->
### 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:<version>")
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.
<!-- prettier-ignore-end -->
## 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<dyn std::error::Error>> {
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<StreamChunk>` |
| `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.
@@ -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
-253
View File
@@ -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';
<ContentCardCarousel
items={[
{
type: 'video',
title: 'Intro to Agent Client Protocol (ACP) | Vibe Code with goose',
description: 'Watch how ACP lets you seamlessly integrate goose into your code editor to streamline fragmented workflows.',
thumbnailUrl: 'https://img.youtube.com/vi/Hvu5KDTb6JE/maxresdefault.jpg',
linkUrl: 'https://www.youtube.com/watch?v=Hvu5KDTb6JE',
date: '2025-10-16',
duration: '50:23'
},
{
type: 'blog',
title: 'Intro to Agent Client Protocol (ACP): The Standard for AI Agent-Editor Integration',
description: 'Learn how to integrate AI agents like goose directly into your code editor via ACP, eliminating window-switching and vendor lock-in.',
thumbnailUrl: chooseYourIde,
linkUrl: '/blog/2025/10/24/intro-to-agent-client-protocol-acp',
date: '2025-10-24',
duration: '7 min read'
}
]}
/>
@@ -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.
:::
---
@@ -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
</plist>
```
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
+4 -5
View File
@@ -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 <SESSION_ID> "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):
+5 -3
View File
@@ -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',
@@ -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"
@@ -413,7 +413,7 @@ export default function GdkApiReference() {
<SelectionSearchContext.Provider value={selectionSearch(selection, location.search)}>
<div>
<div className={styles.toolbar}>
<div className={styles.tabs} role="tablist" aria-label="GDK language">
<div className={styles.tabs} role="tablist" aria-label="SDK language">
{LANGUAGES.map((entry) => (
<button
key={entry.id}
@@ -433,7 +433,7 @@ export default function GdkApiReference() {
<select
value={docVersion}
onChange={(event) => select({ docVersion: event.target.value })}
aria-label="GDK version"
aria-label="SDK version"
>
{VERSIONS.map((entry) => (
<option key={entry.docVersion} value={entry.docVersion}>
+1 -1
View File
@@ -222,7 +222,7 @@ function StandardsSection() {
an ACP server — connect from Zed, JetBrains, or VS Code — and can
use ACP agents like Claude Code and Codex as providers.
</p>
<Link to="/docs/guides/acp-clients">goose as ACP server →</Link>
<Link to="/docs/gdk/acp">goose as ACP server →</Link>
</div>
<div className={styles.standardCard}>
<h3>Agentic AI Foundation</h3>