Agent

Core Agent implementation for the Goose AI framework

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

Related Types

• Session - Session management
• Conversation - Message history
• Config - Configuration system