π References
This section provides comprehensive documentation for the SDK, covering the core Client, configuration options, API services, and all associated data models.
π Client: The Heart of the SDK
The Client class is the primary entry point for all interactions with the WyseOS API. It handles authentication, request dispatching, and response parsing to streamline your integration.
Initialization
To start, initialize the Client with an optional ClientOptions object. If no options are provided, the SDK will use default values.
from wyseos.mate import Client, ClientOptions
from wyseos.mate.config import load_config
# Option 1: Load configuration from mate.yaml (Recommended)
try:
config = load_config()
client = Client(config)
print("β
Client initialized from mate.yaml.")
except FileNotFoundError:
print("β οΈ mate.yaml not found. Manually configuring client.")
# Option 2: Manual configuration
client = Client(ClientOptions(api_key="YOUR_API_KEY"))
print("Client instance is ready to use.")Accessible API Services
The Client object provides direct access to various API services as attributes:
client.user: π€ Manages user-specific operations like API keys.client.team: π₯ Facilitates team management.client.agent: π€ Handles operations related to agents.client.session: π¬ Manages session creation, information, and messages.client.browser: π Provides functionalities for interacting with browser instances.
π§ ClientOptions: Configuring Your Client
The ClientOptions class allows you to fine-tune the behavior of your Client instance.
| Attribute | Type | Description | Default Value |
|---|---|---|---|
api_key | Optional[str] | Your WyseOS API key. Required for API calls. | None |
base_url | str | The base URL for the WyseOS API. | https://api.wyseos.com |
timeout | int | Request timeout in seconds (1-300). | 30 |
π οΈ API Services
Here you'll find detailed references for each service available through the Client.
π€ User Service
Access via client.user. Manages user-related resources, primarily API keys.
Methods
list_api_keys
Retrieves a paginated list of API keys for the current user.
list_api_keys(options: Optional[ListOptions] = None) -> PaginatedResponse[APIKey]
| Parameter | Type | Description |
|---|---|---|
options | Optional[ListOptions] | Pagination options. |
Example:
# List the first 5 API keys
api_keys = client.user.list_api_keys(ListOptions(page_size=5))
for key in api_keys.data:
print(f"- {key.name} (Last Used: {key.last_used_at})")Data Models
APIKey: Represents an API key.Attribute Type Description namestrThe name of the API key. api_keystrThe actual API key string. created_atdatetimeTimestamp of creation. last_used_atdatetimeTimestamp of last use.
π₯ Team Service
Access via client.team. Manages teams.
Methods
get_list
Retrieves a paginated list of teams, optionally filtered by type.
get_list(team_type: str = "", options: Optional[ListOptions] = None) -> PaginatedResponse[TeamInfo]
| Parameter | Type | Description |
|---|---|---|
team_type | str | Filter by team type (e.g., "personal"). |
options | Optional[ListOptions] | Pagination options. |
get_info
Retrieves detailed information for a specific team.
get_info(team_id: str) -> TeamInfo
| Parameter | Type | Description |
|---|---|---|
team_id | str | The ID of the team. |
Data Models
TeamInfo: Represents a team.Attribute Type Description team_idstrUnique ID of the team. user_idstrID of the owner user. avatarstrURL to the team's avatar. namestrName of the team. descriptionstrDescription of the team. team_typestrType of team (e.g., "personal"). agentsList[AgentInfo]List of agents in the team. modelModelInfoThe AI model associated with the team. parametersTeamParametersConfiguration parameters for the team. created_atdatetimeTimestamp of creation. updated_atdatetimeTimestamp of last update.
π€ Agent Service
Access via client.agent. Manages agents.
Methods
get_list
Retrieves a paginated list of agents, optionally filtered by type.
get_list(agent_type: str = "", options: Optional[ListOptions] = None) -> PaginatedResponse[AgentInfo]
| Parameter | Type | Description |
|---|---|---|
agent_type | str | Filter by agent type (e.g., "coder"). |
options | Optional[ListOptions] | Pagination options. |
get_info
Retrieves detailed information for a specific agent.
get_info(agent_id: str) -> AgentInfo
| Parameter | Type | Description |
|---|---|---|
agent_id | str | The ID of the agent. |
Data Models
-
AgentInfo: Represents an agent.Attribute Type Description agent_idstrUnique ID of the agent. namestrName of the agent. descriptionstrDescription of the agent. system_messagestrThe system prompt for the agent. modelModelInfoThe AI model associated with the agent. agent_typestrType of agent (e.g., "coder"). parametersAgentParametersConfiguration parameters for the agent. created_atdatetimeTimestamp of creation. updated_atdatetimeTimestamp of last update. -
ModelInfo: Represents an AI model.Attribute Type Description providerstrThe model provider (e.g., "openai"). model_typestrThe model name (e.g., "gpt-4"). -
AgentParameters: Agent configuration.Attribute Type Description temperaturefloatControls the randomness of the output.
π¬ Session Service
Access via client.session. Manages sessions and messages.
Methods
create
Creates a new session.
create(request: CreateSessionRequest) -> CreateSessionResponse
get_info
Retrieves detailed information for a specific session.
get_info(session_id: str) -> SessionInfo
get_messages
Retrieves a paginated list of messages from a session.
get_messages(session_id: str, page_num: int = 1, page_size: int = 20, filter: Optional[MessageFilter] = None) -> GetMessagesResponse
update_session_name
Updates the name of a session.
update_session_name(request: UpdateSessionNameRequest) -> None
Data Models
-
CreateSessionRequest: Request to create a session.Attribute Type Description team_idstrThe ID of the team to use for the session. taskstrThe initial task for the session. -
SessionInfo: Represents a session.Attribute Type Description session_idstrUnique ID of the session. statusstrCurrent status (e.g., "running"). namestrThe name of the session. intent_idOptional[str]ID related to the session's goal. taskList[UserTaskMessage]The task(s) for the session. messagesList[MessageResponse]A list of messages within the session. -
MessageResponse: Represents a single message.Attribute Type Description message_idstrUnique ID of the message. sourcestrThe source of the message (e.g., "agent"). contentstrThe content of the message. typestrThe type of message (e.g., "text", "plan").
π Browser Service
Access via client.browser. Manages browser instances.
Methods
get_info
Retrieves detailed information for a specific browser instance.
get_info(browser_id: str) -> BrowserInfo
list_browsers
Retrieves a list of browser instances for a session.
list_browsers(session_id: str, options: Optional[ListOptions] = None) -> ListBrowsersResponse
release_browser
Releases a browser instance.
release_browser(browser_id: str) -> None
list_browser_pages
Retrieves a list of open pages in a browser.
list_browser_pages(browser_id: str, options: Optional[ListOptions] = None) -> ListBrowserPagesResponse
Data Models
-
BrowserInfo: Represents a browser instance.Attribute Type Description browser_idstrUnique ID of the browser. session_idstrID of the associated session. statusstrCurrent status (e.g., "open"). widthintBrowser width in pixels. heightintBrowser height in pixels. pagesList[BrowserPageInfo]A list of open pages in the browser. -
BrowserPageInfo: Represents a single browser page.Attribute Type Description page_idstrUnique ID of the page. urlstrThe current URL of the page. statusstrLoading status (e.g., "completed").
π€ TaskRunner: Simplified Task Execution
New in v0.2.1 - The TaskRunner interface revolutionizes WebSocket operations by reducing complex implementation from 400+ lines to just 10-20 lines of code.
Accessing TaskRunner
TaskRunner is accessed through the WebSocketClient:
from wyseos.mate.websocket import WebSocketClient
ws_client = WebSocketClient(
base_url=client.base_url,
api_key=client.api_key,
session_id=session.session_id
)
task_runner = ws_client.create_task_runner(client, session)π― TaskExecutionOptions
Configuration class for fine-tuning task execution behavior.
| Attribute | Type | Default | Description |
|---|---|---|---|
auto_accept_plan | bool | True | Automatically accept execution plans without user confirmation |
capture_screenshots | bool | False | Capture browser screenshots during execution (impacts performance) |
enable_browser_logging | bool | True | Enable detailed browser operation logging |
enable_event_logging | bool | True | Control detailed execution event logging |
completion_timeout | int | 300 | Task completion timeout in seconds (5 minutes default) |
max_user_input_timeout | int | 0 | User input timeout in seconds (0 = infinite wait) |
Example Usage:
from wyseos.mate.websocket import TaskExecutionOptions
# Performance-optimized configuration
fast_options = TaskExecutionOptions(
auto_accept_plan=True,
capture_screenshots=False, # Faster execution
completion_timeout=180 # 3-minute timeout
)
# Debug-friendly configuration
debug_options = TaskExecutionOptions(
auto_accept_plan=False, # Manual plan approval
capture_screenshots=True, # Visual debugging
enable_event_logging=True, # Detailed logs
completion_timeout=600 # Extended timeout
)π TaskResult
Comprehensive result object returned by TaskRunner operations.
| Attribute | Type | Description |
|---|---|---|
success | bool | Whether the task completed successfully |
final_answer | str | The final answer or result from the task |
error | Optional[str] | Error message if the task failed |
screenshots | List[Dict[str, Any]] | Captured screenshots (when capture_screenshots=True) |
execution_logs | List[Dict[str, Any]] | Detailed execution event logs |
plan_history | List[Dict[str, Any]] | History of plan changes during execution |
session_duration | float | Total execution time in seconds |
message_count | int | Total number of messages processed |
Example Usage:
result = task_runner.run_task("Analyze market trends", "wyse_mate")
if result.success:
print(f"β
Task completed in {result.session_duration:.1f}s")
print(f"π Answer: {result.final_answer}")
print(f"π Messages processed: {result.message_count}")
# Access screenshots if captured
if result.screenshots:
print(f"πΈ {len(result.screenshots)} screenshots captured")
else:
print(f"β Task failed: {result.error}")π TaskRunner Methods
run_task()
Execute a task with full automation and return comprehensive results.
Signature:
def run_task(
task: str,
team_id: str,
options: Optional[TaskExecutionOptions] = None
) -> TaskResultParameters:
| Parameter | Type | Description |
|---|---|---|
task | str | The task description to execute |
team_id | str | ID of the team to use for execution |
options | Optional[TaskExecutionOptions] | Execution configuration options |
Example:
# Simple automated execution
result = task_runner.run_task(
"Research renewable energy trends",
"wyse_mate"
)
# Advanced configuration
result = task_runner.run_task(
"Analyze competitor pricing strategies",
"analysis_team",
TaskExecutionOptions(
auto_accept_plan=True,
capture_screenshots=True,
completion_timeout=600
)
)run_interactive_session()
Start an interactive session that allows real-time user input and guidance.
Signature:
def run_interactive_session(
initial_task: str,
team_id: str,
options: Optional[TaskExecutionOptions] = None
) -> NoneParameters:
| Parameter | Type | Description |
|---|---|---|
initial_task | str | The initial task to start the session |
team_id | str | ID of the team to use for the session |
options | Optional[TaskExecutionOptions] | Execution configuration options |
Example:
# Start interactive session
task_runner.run_interactive_session(
"Help me research market opportunities",
"research_team",
TaskExecutionOptions(
auto_accept_plan=False, # Manual approval for interactive use
capture_screenshots=True,
max_user_input_timeout=300 # 5-minute user input timeout
)
)π WebSocketClient Enhancements
New in v0.2.1 - Additional methods for TaskRunner integration.
create_task_runner()
Factory method to create a TaskRunner instance with proper initialization.
Signature:
def create_task_runner(client: Client, session: SessionInfo) -> TaskRunnerParameters:
| Parameter | Type | Description |
|---|---|---|
client | Client | The WyseOS client instance |
session | SessionInfo | Session information for the task execution |
Example:
from wyseos.mate.websocket import WebSocketClient
ws_client = WebSocketClient(
base_url=client.base_url,
api_key=client.api_key,
session_id=session.session_id,
heartbeat_interval=30
)
# Create TaskRunner - replaces 400+ lines of manual WebSocket setup
task_runner = ws_client.create_task_runner(client, session)π― Migration from Legacy WebSocket Code
Before (v0.2.0 and earlier):
# 400+ lines of complex WebSocket message handling
def websocket_operations(client, session, task):
msg_list = []
plan_state = None
def on_message(message):
# Complex message handling logic...
msg_type = WebSocketClient.get_message_type(message)
if msg_type == MessageType.TEXT:
# Handle text messages...
elif msg_type == MessageType.PLAN:
# Handle plan messages...
# ... 350+ more lines
ws_client = WebSocketClient(...)
ws_client.set_message_handler(on_message)
# ... more complex setupAfter (v0.2.1+):
# Simple 3-line solution
task_runner = ws_client.create_task_runner(client, session)
result = task_runner.run_task(task, team_id)
print(f"Result: {result.final_answer}")π Pagination
These models are used across multiple services.
-
ListOptions: Defines pagination parameters.Attribute Type Description Default page_numintThe page number to retrieve (1-indexed). 1page_sizeintThe number of items per page (1-100). 20 -
PaginatedResponse[T]: A generic container for paginated API responses.Attribute Type Description page_numintThe current page number. page_sizeintThe number of items per page. totalintThe total number of items across all pages. total_pageintThe total number of pages. dataList[T]A list of items for the current page.