goose/clients/python/README.md

Goose Python Client

A simple and powerful Python client for the Goose AI agent.

Features

• ✅ Simple chat interface
• ✅ Session management with context managers
• ✅ Streaming support (SSE)
• ✅ Tool confirmation handling for non-autonomous mode
• ✅ Type hints throughout
• ✅ Async support for streaming
• ✅ Optional extensions for retry and session management

Installation

pip install goose-client

Quick Start

from goose_client import GooseClient

# Initialize client
client = GooseClient(api_key="your-api-key")

# Simple chat
response = client.chat("What is 2+2?")
print(response)  # "4"

# One-shot Q&A
answer = client.ask("What's the weather like?")

# With session context
with client.session() as session:
    response1 = client.chat("Remember the number 42", session.id)
    response2 = client.chat("What number did I ask you to remember?", session.id)
    print(response2)  # "You asked me to remember 42"

# Streaming
for chunk in client.stream_chat("Tell me a story"):
    print(chunk, end="", flush=True)

Tool Confirmation (Non-Autonomous Mode)

When the Goose server is not in autonomous mode, it will request confirmation before executing tools:

# Auto-confirm all tools
for chunk in client.stream_chat_with_confirmations(
    "List files in current directory",
    auto_confirm="allow_once"  # or "always_allow" or "deny"
):
    if isinstance(chunk, str):
        print(chunk, end="")

# Manual confirmation
for chunk in client.stream_chat_with_confirmations(
    "Create a new file",
    auto_confirm=None  # Manual handling
):
    if isinstance(chunk, str):
        print(chunk, end="")
    else:
        # Handle tool confirmation request
        print(f"Tool {chunk['toolName']} needs confirmation")
        
        # Show security prompt if present
        if chunk.get('prompt'):
            print(f"Security: {chunk['prompt']}")
        
        # Confirm the tool
        client.confirm_permission(
            chunk['id'],
            "allow_once",  # or "always_allow" or "deny"
            session.id
        )

Session Management

# Manual session management
session = client.create_session("/home/project")
client.chat("Analyze this project", session_id=session.id)

# List sessions
sessions = client.list_sessions()
for s in sessions[:5]:
    print(f"{s.id}: {s.working_dir}")

# Delete session
client.delete_session(session.id)

Advanced Usage with Extensions

Retry Extension

Add automatic retry with exponential backoff:

from goose_client import GooseClient
from goose_client.extensions import with_retry

# Add retry capability
client = with_retry(
    GooseClient(api_key="your-key"),
    max_retries=5,
    backoff_factor=2.0
)

# Now all methods have automatic retry
response = client.chat("Hello")  # Will retry on failure

Session Manager Extension

Advanced session management features:

from goose_client.extensions import with_session_manager

# Add session management
client = with_session_manager(GooseClient(api_key="your-key"))

# Save and load sessions
session = client.create_session()
client.session_manager.save_session(session.id, "project_analysis")

# Later, load the session
saved_id = client.session_manager.load_session("project_analysis")
client.chat("Continue the analysis", session_id=saved_id)

# List saved sessions
saved = client.session_manager.list_saved()
print(saved)

Async Support

import asyncio
from goose_client import GooseClient

async def main():
    client = GooseClient(api_key="your-key")
    
    # Async streaming
    async for event in client.astream_reply(session_id, messages):
        print(event)

asyncio.run(main())

Direct Access to Generated Client

For advanced users who need full control:

from goose_client import GooseClient, StartAgentRequest

client = GooseClient(api_key="your-key")

# Access the generated API client directly
raw_response = client._agent_api.start_agent(
    StartAgentRequest(working_dir="/tmp", prompt="Custom prompt")
)

# Use generated models
from goose_client import Message, Content
custom_message = Message(
    role="user",
    content=[{"type": "text", "text": "Hello"}]
)

Configuration

Environment Variables

• GOOSE_API_KEY: Default API key
• GOOSE_BASE_URL: Default server URL (default: http://localhost:3000)

Custom Configuration

client = GooseClient(
    api_key="your-key",
    base_url="https://your-goose-server.com"
)

Error Handling

try:
    response = client.chat("Hello")
except Exception as e:
    print(f"Error: {e}")

# Check server health
if client.is_healthy:
    print("Server is running")
else:
    print("Server is down")

Examples

See the examples/ directory for more detailed examples:

• quickstart.py - Basic usage examples
• streaming.py - Streaming responses
• tool_confirmation.py - Handling tool confirmations in non-autonomous mode

API Reference

GooseClient

Main client class for interacting with Goose.

Methods

• chat(text, session_id=None) - Send a message and get response
• stream_chat(text, session_id=None) - Stream response chunks
• stream_chat_with_confirmations(text, session_id=None, auto_confirm=None) - Stream with tool confirmation support
• ask(question) - One-shot Q&A
• create_session(working_dir="/tmp") - Create a new session
• session(working_dir="/tmp") - Context manager for sessions
• list_sessions() - List all sessions
• get_session(session_id) - Get session details
• delete_session(session_id) - Delete a session
• list_tools(session_id=None) - List available tools
• list_extensions() - List available extensions
• confirm_permission(confirmation_id, action, session_id=None) - Confirm or deny tool execution
• health_check() - Check server health

Properties

• is_healthy - Boolean indicating server health
• active_session_id - Currently active session ID

License

Apache 2.0

Contributing

See CONTRIBUTING.md in the main Goose repository.