Steward Tools

Steward tools enable the agent to act as a personal steward (管家) - managing tasks, calendar, reminders, and proactive automation on the user’s behalf. These tools help users organize their work and automate routine activities.

Overview

Task Management Tools

Task tools help users manage TODO items, reminders, and track task completion.

Available Tools

Usage Examples

Create a Task

# Via agent conversation
"Create a todo task called 'Review PR #123' with high priority"
 
# The agent will call create_task with:
# - name: "Review PR #123"
# - task_type: "todo"
# - priority: "high"

List Due Tasks

# Via agent conversation
"What tasks are due today?"
"Show me overdue tasks"
"List my high priority todos"

Task Analytics

# Via agent conversation
"Show me my task completion stats for this month"
"How many tasks did I complete last week?"

Task Types

Task Priorities

• low - Low priority
• medium - Medium priority (default)
• high - High priority
• urgent - Urgent priority

Calendar Tools

Calendar tools manage events, scheduling, and external calendar synchronization.

Available Tools

Usage Examples

Create an Event

# Via agent conversation
"Schedule a meeting with John tomorrow at 2pm for 1 hour"
"Add a dentist appointment on Friday at 10am"
 
# The agent will call create_calendar_event with:
# - title: "Meeting with John"
# - start_time: "2026-01-30T14:00:00"
# - duration_minutes: 60

Check Schedule

# Via agent conversation
"What's on my calendar today?"
"Do I have any meetings tomorrow morning?"
"Show me my schedule for this week"

External Calendar Sync

# Via agent conversation
"Sync my Google Calendar"
"Import events from my Outlook calendar"

Event Triggers (Proactive Automation)

Event tools enable proactive agent activation based on conditions, schedules, or external events. See triggers.md for the SDK API.

Available Tools

Trigger Types

Usage Examples

Price Alert

# Via agent conversation
"Alert me when Bitcoin drops more than 5%"
"Notify me if AAPL stock goes above $200"
 
# The agent will call register_price_alert with:
# - product: "Bitcoin"
# - threshold_value: 5.0
# - direction: "down"

Scheduled Task

# Via agent conversation
"Send me a daily summary of my tasks at 9am"
"Remind me to check emails every 2 hours during work"
 
# The agent will call register_scheduled_task with:
# - cron_expression: "0 9 * * *"
# - action_prompt: "Summarize today's tasks"

Fixed (2026-07-16): “Remind me…” style requests now reliably route to register_scheduled_task. Previously these could be misclassified as a recall_pattern and answered directly without creating a task — a false success where the agent replied conversationally but no reminder was actually scheduled.

Relative dates in the same request (“tomorrow”, “in 2 hours”) resolve against the agent’s actual current date and time — every turn is grounded with the real current date, so a request made at midnight still resolves “tomorrow” correctly instead of drifting to a stale cached date.

List Triggers

# Via agent conversation
"What alerts do I have set up?"
"Show me my active triggers"

Architecture

Data Flow

User Request
    ↓
Agent (isA_Agent)
    ↓
SDK injects user_id into tool arguments
    ↓
MCP Server (isA_MCP)
    ↓
User Tools (task_tools, calendar_tools, event_tools)
    ↓
Microservices (task_service, calendar_service, trigger_service)
    ↓
Database (PostgreSQL)

User Context

All user tools automatically receive the user_id from the agent session:

1. User authenticates with the agent
2. Agent passes user_id in request
3. SDK injects user_id into tool arguments
4. Tools send X-User-Id header to microservices
5. Microservices isolate data by user

Service Ports

Configuration

Enabling User Tools

User tools are enabled by default in the agent. To customize:

from isa_agent_sdk import ISAAgentOptions
 
options = ISAAgentOptions(
    user_id="user-123",
    allowed_tools=[
        # Task tools
        "create_task", "get_task", "list_tasks", "update_task",
        "delete_task", "complete_task", "get_due_tasks",
        "get_reminders", "get_task_analytics",
        # Calendar tools
        "create_calendar_event", "list_calendar_events",
        "get_calendar_event", "get_upcoming_events",
        # Trigger tools
        "register_price_alert", "register_scheduled_task",
        "list_triggers", "delete_trigger",
    ]
)

Environment Variables

# Service URLs (optional, defaults shown)
TASK_SERVICE_URL=http://localhost:8211
CALENDAR_SERVICE_URL=http://localhost:8212
TRIGGER_SERVICE_URL=http://localhost:8213

Best Practices

Task Management

1. Use specific task types - Choose todo, reminder, or scheduled appropriately
2. Set priorities - Help users focus on important tasks
3. Add due dates - Enable deadline tracking and reminders
4. Use tags - Organize tasks into categories

Calendar

1. Include duration - Always specify event length
2. Add descriptions - Include meeting details, links, etc.
3. Set reminders - Help users prepare for events
4. Sync regularly - Keep external calendars in sync

Triggers

1. Be specific - Clear conditions prevent false triggers
2. Test first - Verify triggers work before relying on them
3. Clean up - Remove triggers that are no longer needed
4. Monitor usage - Check trigger execution history

Related Documentation

• Triggers API - SDK trigger registration API
• Tools - General tool documentation
• Options - Agent configuration options