yao/agent/robot/api/README.md

Robot Agent Go API

Go API for managing autonomous robot agents.

Quick Start

import "github.com/yaoapp/yao/agent/robot/api"

// Start system
api.Start()
defer api.Stop()

// Trigger execution
result, _ := api.Trigger(ctx, "member_123", &api.TriggerRequest{
    Type:     types.TriggerHuman,
    Action:   types.ActionTaskAdd,
    Messages: []agentcontext.Message{{Role: "user", Content: "Analyze sales"}},
})

// Check status
exec, _ := api.GetExecution(ctx, result.ExecutionID)

Lifecycle

api.Start()                    // Start with defaults
api.StartWithConfig(config)    // Start with custom config
api.Stop()                     // Graceful shutdown
api.IsRunning()                // Check if running

Robot Query

// Get single robot
robot, err := api.GetRobot(ctx, "member_123")

// List robots with filters
result, err := api.ListRobots(ctx, &api.ListQuery{
    TeamID:    "team_1",
    Status:    types.RobotIdle,
    Keywords:  "sales",
    ClockMode: types.ClockInterval,
    Page:      1,
    PageSize:  20,
    Order:     "created_at desc",
})

// Get runtime status
state, err := api.GetRobotStatus(ctx, "member_123")
// state.Running, state.MaxRunning, state.RunningIDs, state.LastRun, state.NextRun

Triggers

Human Intervention

result, err := api.Trigger(ctx, "member_123", &api.TriggerRequest{
    Type:     types.TriggerHuman,
    Action:   types.ActionTaskAdd,
    Messages: []agentcontext.Message{
        {Role: "user", Content: "Generate weekly report"},
    },
})
// Or use shorthand:
result, err := api.Intervene(ctx, "member_123", req)

Event Trigger

result, err := api.Trigger(ctx, "member_123", &api.TriggerRequest{
    Type:      types.TriggerEvent,
    Source:    types.EventWebhook,
    EventType: "order.created",
    Data:      map[string]interface{}{"order_id": "12345"},
})
// Or use shorthand:
result, err := api.HandleEvent(ctx, "member_123", req)

Manual Trigger (Testing)

result, err := api.TriggerManual(ctx, "member_123", types.TriggerClock, nil)

Execution Management

// Get execution by ID
exec, err := api.GetExecution(ctx, "exec_abc123")

// List executions with filters
result, err := api.ListExecutions(ctx, "member_123", &api.ExecutionQuery{
    Status:   types.ExecRunning,
    Trigger:  types.TriggerClock,
    Page:     1,
    PageSize: 10,
})

// Get execution with runtime status
exec, err := api.GetExecutionStatus(ctx, "exec_abc123")

// Control execution
api.PauseExecution(ctx, "exec_abc123")
api.ResumeExecution(ctx, "exec_abc123")
api.StopExecution(ctx, "exec_abc123")

Types

ListQuery

type ListQuery struct {
    TeamID    string            // Filter by team
    Status    types.RobotStatus // Filter by status (idle|working|paused|error)
    Keywords  string            // Search in display_name
    ClockMode types.ClockMode   // Filter by clock mode (times|interval|daemon)
    Page      int               // Page number (default: 1)
    PageSize  int               // Page size (default: 20, max: 100)
    Order     string            // Order by column (default: "created_at desc")
}

TriggerRequest

type TriggerRequest struct {
    Type           types.TriggerType        // human | event | clock
    Action         types.InterventionAction // task.add, goal.adjust, etc.
    Messages       []agentcontext.Message   // User input
    PlanAt         *time.Time               // Schedule for later
    InsertPosition InsertPosition           // first | last | next | at
    AtIndex        int                      // When InsertPosition = "at"
    Source         types.EventSource        // webhook | database
    EventType      string                   // Event name
    Data           map[string]interface{}   // Event payload
    ExecutorMode   types.ExecutorMode       // standard | dryrun | sandbox
}

TriggerResult

type TriggerResult struct {
    Accepted    bool             // Whether trigger was accepted
    Queued      bool             // Whether queued (vs immediate)
    Execution   *types.Execution // Execution details
    ExecutionID string           // Execution ID for tracking
    Message     string           // Status message
}

ExecutionQuery

type ExecutionQuery struct {
    Status   types.ExecStatus  // Filter by status
    Trigger  types.TriggerType // Filter by trigger type
    Page     int               // Page number (default: 1)
    PageSize int               // Page size (default: 20, max: 100)
}

RobotState

type RobotState struct {
    MemberID    string            // Robot member ID
    TeamID      string            // Team ID
    DisplayName string            // Display name
    Status      types.RobotStatus // idle | working | paused | error
    Running     int               // Current running count
    MaxRunning  int               // Max concurrent limit
    LastRun     *time.Time        // Last execution time
    NextRun     *time.Time        // Next scheduled time
    RunningIDs  []string          // IDs of running executions
}

Files

File	Functions
lifecycle.go	Start, StartWithConfig, Stop, IsRunning
robot.go	GetRobot, ListRobots, GetRobotStatus
trigger.go	Trigger, TriggerManual, Intervene, HandleEvent
execution.go	GetExecution, ListExecutions, GetExecutionStatus, PauseExecution, ResumeExecution, StopExecution
types.go	Type definitions