goose Rust API: crate organization

[jamadeo]

Goal

To date, goose has been architected and shipped as a monolithic application. There are some crate boundaries internally, but they haven't been designed for independent use. We'd like to change that, and make the components of goose usable by other Rust binaries as a set of crates.

Non-goals

We won’t decide just yet on the exact semantics of the API. Code examples are intended to be illustrative, not authoritative.

Crates

goose-providers

Talk to OpenAI, Anthropic, Google etc. behind a common interface. All providers supported in goose today are available. Support for declarative (pre-packaged) and custom (user-defined) providers that adhere to the “shape” of the pseudo-standard APIs. goose-local-inference providers are also packaged here behind feature flags.

In the future, this crate can be the home for the model router.

Key dependencies: reqwest, provider-specific sdks as needed

use goose::messages::{Conversation, Message};
use goose::providers::Event;
use goose_providers::openai::OpenAIProvider;

let provider = OpenAIProvider::new("gpt-5.5");
let result_stream = provider.stream(
  Conversation::new(
    "You are a helpful assistant",
    [Message::user("what's the capital of France?")]
  )
);

while let Some(event) = result_stream.next() {
  match event {
    Event::TextChunk => ..,
    Event::ToolCall => ..,
    ..
  }
}

goose-local-inference

The implementation of the important parts of local inference. Feature flags for cuda/vulkan/etc. Isolated to its own crate to make flagging support in goose-providers straightforward. (Could maybe just be part of the goose-providers crate?)

goose-agent

see Unrolling the agent loop
The agent loop implementation. Use this crate to configure and run a goose agent. More detail is covered in other docs, but the key here is a pluggable, configurable, resumable agent loop.

This create doesn’t need to

use goose::messages::Conversation;
use goose_agent::agent;
use goose_providers::anthropic::AnthropicProvider;

let provider = AnthropicProvider::new(..);
let conversation = Conversation::new(..);
let result = agent::run(
  agent::Session {
    conversation: conversation,
    ..
  },
  agent::Operations {
    LLMOps(provider, ..),
    ..
  }
);

goose-extensions

Implementations of extensions and agent loop operations to build a functional agent. This might end up being a bit of a grab bag of bits that could be broken up:

• developer/shell extension
• analyze (feature flagged)
• skills/agents.md/openplugins

Key dependencies: tree-sitter, pctx (code mode), all feature flagged.

use goose_agent::Agent;
use goose_extensions::extensions::Developer;

let agent = Agent(.., extensions=[Developer::new()]);

goose-acp

Implementation of the goose ACP server.

use goose_acp::{Server, HttpTransport};
use goose_agent::Agent;

let agent = Agent(.., extensions=[Developer::new()]);
Server::new(agent, HttpTransport::new("localhost", 60053)).run();

goose

Core types/traits common to other crates. Traits that define the behavior of:

• Provider
• Operation (on the agent loop)
• Message
• Conversation

Next Steps

• Move provider implementations into goose-providers
• Formalize a minimally viable API for providers
• Create the unrolled agent loop API

[michaelneale]

should the goose crate be goose-core maybe?

it is possible that the extensions one could offer MCP servers that any harness could use? (can sort of do that today) - but maybe that is also a non goal.

I am guessing goose-agent would be where the compaction strategies are in (perhaps one can implement their own and plug it in) ? There is also the session management and storage - similarly in goose-agent? (as people might swap out sqlite for some other database implementation potentially? or would that more be left to using the agent in its unrolled form and you do that code outside of this?)

[jamadeo]

Calling it goose-core is good too, and would help us move things incrementally as well while goose remains the top-level application crate.

Re: extensions, yeah I think most of them could be independent MCP servers. Our "platform" extensions might take advantage of extra access into the agent loop, but that too should be something we package and make usable with the API.

Compaction, yes I think would be an "operation" on the unrolled agent loop. @DOsinga probably has some ideas there too.

[i386]

I’ve been experimenting with this from the embedding/runtime side, and the shape that has worked best for me is mostly compatible with the proposed breakdown here.

I’d frame this as a lower-level decomposition underneath goose-agent / goose-providers, rather than as a competing crate taxonomy.

I’d also encourage folks to manually examine, or point an agent at, my fork/branch here:

https://github.com/i386/goose/tree/decomposition

That branch already implements most of the crate decomposition I’m describing below, so it may be useful as a concrete reference point rather than only a design sketch.

Rough mapping:

• goose-agent
  • agent loop
  • runtime policy
  • session persistence
  • tool/workspace policy
• goose-providers
  • provider runtime contracts
  • provider implementations
• integration crates
  • goose-acp
  • protocol/runtime integrations outside the core agent crate

Why split below goose-agent?

For embedders, goose-agent is the right public concept, but it contains a few seams that hosts often need to own independently:

• where session state is stored
• how prompts/policies are layered
• which tools are available in a given session
• how approvals work
• how provider/model config is selected
• how agent-loop progress is streamed back to the host

In my downstream prototype, the host owns durable sessions, participants, task leases, artifacts, audit state, and live UI streaming. Goose is the runtime that executes a task. That works much better if the reusable Goose API has explicit contracts for those boundaries.

Suggested lower-level pieces

Provider runtime

Under goose-providers, I’d keep a small provider runtime contract layer.

It would cover:

• typed provider/model config
• model hints and model config snapshots
• streaming policy
• retry policy
• normalized provider metadata
• provider creation traits

The provider implementations can still live in goose-providers; the important bit is that hosts can configure and instantiate providers without needing to adopt the whole Goose app surface.

Agent loop

Under goose-agent, I’d make the loop itself separately reusable.

It would expose a normalized event stream for things like:

• run started/completed
• text output
• tool calls
• tool results
• action required / approval required
• MCP notifications
• system notifications
• history replacement
• artifacts or task-like status updates

That gives embedders something stable to stream into their own task UI, logs, WebSockets, SSE, etc.

Runtime / prompt policy

I’d keep prompt/runtime policy separate from the loop.

It would cover:

• runtime mode: auto / approve / smart approve / chat
• runtime platform: CLI / desktop / server, etc.
• optional system prompt override
• additive system prompt extensions

The additive extension part is important: embedders should be able to add host-specific instructions without copying or forking Goose’s base prompt.

Session persistence

This is the one that most directly connects to Michael’s question.

I think session management should have an explicit swappable contract, even if goose-agent provides a default implementation.

That contract would cover:

• mapping host session IDs to Goose session IDs
• working directory / workspace binding
• append/list/replace runtime history
• persisted runtime session records

Then a CLI can keep using local filesystem/session-manager behavior, while a server or product host can store session state in SQLite, Postgres, object storage, etc.

Tool and workspace policy

Tool/runtime policy also seems worth separating.

It would cover:

• workspace bindings
• tool availability: all / only / none
• approval mode: auto / ask / deny
• tool visibility
• dispatch authorization
• working directory selection

This lets a host say “this agent in this session can use only these tools, against these mounted workspaces, with this approval policy” without relying on a single process-global permission setup.

Integration crates

goose-acp makes sense as an integration crate around the agent runtime. Other protocol surfaces could follow the same pattern without needing to live inside the core agent crate.

As one example, my branch is also experimenting with external agents discovered and invoked via A2A, plus a small Goose hosting loop for simple A2A agents. That work naturally falls into integration/runtime crates rather than the core agent crate. I’d treat that as branch-specific exploration for now, but it has been useful for pressure-testing the crate boundaries.

Possible mapping

• goose
  • shared core types, or maybe goose-core if the name is clearer
• goose-providers
  • provider implementations
  • provider runtime contracts
• goose-agent
  • public agent API
  • composes loop + policy + session + tools
• goose-agent-loop
  • lower-level loop/event stream contract
• goose-runtime-policy
  • prompt and runtime mode policy
• goose-session-runtime
  • swappable session/history persistence contracts
• goose-tool-runtime
  • workspace/tool availability/approval contracts
• goose-extensions
  • extension implementations
• goose-acp
  • ACP integration
• other protocol/runtime integration crates as needed

I don’t feel strongly about the exact crate names. The main point is that the embedding seams should be real API boundaries, not just internal modules of one large goose-agent crate.

That would make Goose usable in several modes:

• normal CLI app
• desktop app
• server-hosted worker
• cloud-resumable session runtime
• external-agent integrations
• product-specific agent platform with its own sessions, permissions, artifacts, and audit log

The big design principle I’d advocate for is:

Goose should own the reusable agent runtime pieces; the host should be able to own product/session/task state.

That keeps Goose portable without forcing every embedding environment to inherit the same storage, permission, and process assumptions.

[jamadeo]

Lots of good ideas and alignment here @i386 ! Thanks for sharing this. I'll have to look closer at your proposed layout, but a few quick thoughts:

• Session storage, permissions, etc absolutely should be pluggable as you point out.
• I'm hoping we can keep the idea of a "runtime" as small as possible, or even non-existent. It bridges well with how goose reads config now, but makes the API thicker and a bit harder to reason about I think. Where possible, I think we can lift that config to the API surface.
• In addition to the crate organizing, we're thinking about a redesigned agent loop. One primary goal is to make it resumable: an "unrolled" agent loop. Goose the SDK - and some future directions (not a roadmap!) #9811 alludes to this a bit but we'll hopefully have some more ideas shared there soon.

Goose should own the reusable agent runtime pieces; the host should be able to own product/session/task state.

Agreed.

[thepetk]

Thanks for the discussion folks! Still new to the project and it helped me get more context.

+1 @i386 I really liked your points :) and especially around pluggable session storage and runtime policy, both are real needs for anyone embedding Goose in a constrained environment.

I would like to focus also a bit on the Runtime / prompt policy and maybe put another aspect to it. I could see the need for session lifecycle hooks on the output path. Meaning, as far as I understand from the proposal additive system prompt extensions will cover what the model sees. But we could also think about things like notices or disclaimers need to be shown to the user, and not necessarily injected into the prompt.

[DOsinga]

@i386 also have a look at #9944 -- it unrolls the agent loop in a way that I think is similar to what you suggest on how we would expose this to the outside world

[i386]

@DOsinga i love that direction. Any way for me to contribute? I have a few ideas of where I'd like to apply it!

[michaelneale]

I think @jamadeo was busy helping flesh out a rust api, not sure how far that got in recent works