Skip to main content
The Agent is the main orchestrator in Goose that manages conversations, extensions, tools, and provider interactions.

​
Overview

The Agent is responsible for:
  • Managing conversation flow and message handling
  • Coordinating tool execution (both platform and extension tools)
  • Managing extensions (MCP servers, frontend tools)
  • Handling permission checks and confirmations
  • Processing retry logic and error recovery
  • Auto-compaction of conversation history

​
Struct Definition

pub struct Agent {
    pub provider: SharedProvider,
    pub config: AgentConfig,
    pub extension_manager: Arc<ExtensionManager>,
    // ... internal fields
}
Source: crates/goose/src/agents/agent.rs:136-153

​
Configuration

​
AgentConfig

Configuration for Agent initialization. 
pub struct AgentConfig {
    pub session_manager: Arc<SessionManager>,
    pub permission_manager: Arc<PermissionManager>,
    pub scheduler_service: Option<Arc<dyn SchedulerTrait>>,
    pub goose_mode: GooseMode,
    pub disable_session_naming: bool,
    pub goose_platform: GoosePlatform,
}
Source: crates/goose/src/agents/agent.rs:106-113
​
session_manager
Arc<SessionManager>
required
Manages session persistence and retrieval
​
permission_manager
Arc<PermissionManager>
required
Handles permission policies for tool execution
​
scheduler_service
Option<Arc<dyn SchedulerTrait>>
Optional scheduler for recurring tasks
​
goose_mode
GooseMode
required
Operating mode: Auto, Chat, or Agentic
​
disable_session_naming
bool
required
Whether to disable automatic session naming
​
goose_platform
GoosePlatform
required
Platform type: GooseCli or GooseDesktop

​
GoosePlatform

pub enum GoosePlatform {
    GooseDesktop,
    GooseCli,
}
Source: crates/goose/src/agents/agent.rs:91-94

​
Constructor Methods

​
new()

Create a new Agent with default configuration. 
impl Agent {
    pub fn new() -> Self
}
Returns: Agent instance with default settings Source: crates/goose/src/agents/agent.rs:205-216 Example: 
let agent = Agent::new();

​
with_config()

Create an Agent with custom configuration. 
pub fn with_config(config: AgentConfig) -> Self
​
config
AgentConfig
required
Custom agent configuration
Returns: Configured Agent instance Source: crates/goose/src/agents/agent.rs:218-252 Example: 
let config = AgentConfig::new(
    session_manager,
    permission_manager,
    None,
    GooseMode::Auto,
    false,
    GoosePlatform::GooseCli,
);
let agent = Agent::with_config(config);

​
Core Methods

​
reply()

Process a user message and generate a streaming response. 
pub async fn reply(
    &self,
    user_message: Message,
    session_config: SessionConfig,
    cancel_token: Option<CancellationToken>,
) -> Result<BoxStream<'_, Result<AgentEvent>>>
​
user_message
Message
required
The user’s input message
​
session_config
SessionConfig
required
Session configuration including ID and settings
​
cancel_token
Option<CancellationToken>
Token to cancel the operation
Returns: Stream of AgentEvent including messages, tool calls, and system notifications Source: crates/goose/src/agents/agent.rs:871-1078 Example: 
let message = Message::user().with_text("Run tests in the project");
let mut stream = agent.reply(message, session_config, None).await?;

while let Some(event) = stream.next().await {
    match event? {
        AgentEvent::Message(msg) => println!("Message: {:?}", msg),
        AgentEvent::ModelChange { model, mode } => {
            println!("Model changed to {} in {} mode", model, mode)
        }
        _ => {}
    }
}

​
provider()

Get the current LLM provider. 
pub async fn provider(&self) -> Result<Arc<dyn Provider>, anyhow::Error>
Returns: Arc reference to the active provider Source: crates/goose/src/agents/agent.rs:447-452

​
Extension Management

​
add_extension()

Add a new extension to the agent. 
pub async fn add_extension(
    &self,
    extension: ExtensionConfig,
    session_id: &str,
) -> ExtensionResult<()>
​
extension
ExtensionConfig
required
Configuration for the extension (MCP, STDIO, or Frontend)
​
session_id
&str
required
Session ID to associate the extension with
Source: crates/goose/src/agents/agent.rs:715-734 Example: 
let extension = ExtensionConfig::Mcp {
    name: "filesystem".to_string(),
    url: "http://localhost:3000".to_string(),
    env: None,
};
agent.add_extension(extension, "session_123").await?;

​
remove_extension()

Remove an extension from the agent. 
pub async fn remove_extension(&self, name: &str, session_id: &str) -> Result<()>
​
name
&str
required
Name of the extension to remove
​
session_id
&str
required
Associated session ID
Source: crates/goose/src/agents/agent.rs:818-830

​
list_extensions()

Get all active extensions. 
pub async fn list_extensions(&self) -> Vec<String>
Returns: Vector of extension names Source: crates/goose/src/agents/agent.rs:832-837

​
list_tools()

Get all available tools for a session. 
pub async fn list_tools(&self, session_id: &str, extension_name: Option<String>) -> Vec<Tool>
​
session_id
&str
required
Session ID
​
extension_name
Option<String>
Optional filter for specific extension
Returns: Vector of available MCP tools Source: crates/goose/src/agents/agent.rs:796-816

​
Tool Execution

​
dispatch_tool_call()

Execute a single tool call. 
pub async fn dispatch_tool_call(
    &self,
    tool_call: CallToolRequestParams,
    request_id: String,
    cancellation_token: Option<CancellationToken>,
    session: &Session,
) -> (String, Result<ToolCallResult, ErrorData>)
​
tool_call
CallToolRequestParams
required
Tool call parameters (name, arguments)
​
request_id
String
required
Unique request identifier
​
cancellation_token
Option<CancellationToken>
Token to cancel the operation
​
session
&Session
required
Current session context
Returns: Tuple of (request_id, result) Source: crates/goose/src/agents/agent.rs:495-587

​
Permission Handling

​
handle_confirmation()

Handle user confirmation for a tool execution. 
pub async fn handle_confirmation(
    &self,
    request_id: String,
    confirmation: PermissionConfirmation,
)
​
request_id
String
required
The tool request ID awaiting confirmation
​
confirmation
PermissionConfirmation
required
User’s permission decision
Source: crates/goose/src/agents/agent.rs:843-862

​
Events

​
AgentEvent

Events emitted during agent execution. 
pub enum AgentEvent {
    Message(Message),
    McpNotification((String, ServerNotification)),
    ModelChange { model: String, mode: String },
    HistoryReplaced(Conversation),
}
Source: crates/goose/src/agents/agent.rs:156-161
​
Message
Message
A conversation message (user, assistant, tool results)
​
McpNotification
(String, ServerNotification)
Notification from an MCP server
​
ModelChange
{ model: String, mode: String }
The active model changed (for lead-worker providers)
​
HistoryReplaced
Conversation
Conversation history was replaced (e.g., after compaction)

​
Session State Management

​
save_extension_state()

Persist extension state to session metadata. 
pub async fn save_extension_state(&self, session: &SessionConfig) -> Result<()>
​
session
&SessionConfig
required
Session configuration
Source: crates/goose/src/agents/agent.rs:591-611

​
load_extensions_from_session()

Restore extensions from session metadata. 
pub async fn load_extensions_from_session(
    self: &Arc<Self>,
    session: &Session,
) -> Vec<ExtensionLoadResult>
​
session
&Session
required
Session containing extension metadata
Returns: Vector of load results indicating success/failure per extension Source: crates/goose/src/agents/agent.rs:638-713

Build docs developers (and LLMs) love

Get started for freeTalk to us