← Back to Agent
Agent Workforce
Manage agent schedules, work hours, clock in/out, task queues, task pipelines, and clock history.
Overview
For Everyone
Think of the Workforce tab as your agent's HR department. It controls when the agent works (schedules), what the agent is working on (tasks), and tracks its time (clock history). You can set 9-to-5 hours, define shift patterns, clock agents in and out, and assign work — just like managing a human employee.
For Developers
The Workforce section integrates five subsystems:
- Agent Status — Real-time via SSE (
EventSource on /api/engine/agent-status-stream?agentId=…) plus initial fetch from GET /agent-status/:id.
- Schedules — CRUD via
GET/POST/PUT/DELETE /workforce/schedules/:agentId. Supports standard hours, shift patterns, and custom types.
- Workforce Status —
GET /workforce/status/:agentId for clock state and hours worked.
- Tasks —
GET/POST /workforce/tasks/:agentId with complete/cancel actions.
- Clock Records —
GET /workforce/clock-records/:agentId with client-side filtering and pagination (15/page).
The AgentTaskPipeline component is embedded from task-pipeline.js and provides real-time task tracking via SSE.
How It Works
- Status Monitoring — On mount, the current status is fetched and an SSE connection is opened. Status updates (online, idle, error) stream in real time.
- Schedule Configuration — Create or edit a schedule defining work hours, days, timezone, and enforcement rules.
- Clock In/Out — Manually clock the agent in or out. When clocked out, the agent's behavior depends on the off-hours action setting.
- Task Assignment — Create tasks with title, description, priority, and type. The agent processes tasks in priority order.
- Pipeline Tracking — The Task Pipeline shows automatically-recorded tasks from agent spawns with real-time status updates.
Key Concepts
Real-Time Agent Status
The status card at the top shows live agent state:
- Status Badge — Online (green), Idle (blue), Error (red), or Unknown (gray).
- Clock State — Whether the agent is currently clocked in or out, with the time since last clock-in.
- Hours Today — Total worked hours for the current day.
- Current Activity — If the agent is actively doing something, a banner shows what it's working on and which tool it's using.
Schedules
Three schedule types are supported:
| Type | Description | Configuration |
|---|
| Standard | Fixed daily hours | Start time, end time, days of week (clickable day buttons) |
| Shift | Named shift patterns | Multiple shifts, each with name, start, and end time |
| Custom | Flexible scheduling | Custom configuration |
Schedule options include:
- Timezone — Full timezone selector. All times are interpreted in this timezone.
- Enforce Clock-In — Agent must be clocked in to work.
- Enforce Clock-Out — Agent is automatically clocked out at schedule end.
- Auto-Wake — Automatically starts the agent when the schedule begins.
- Off-Hours Action — What happens outside schedule: Pause (suspend), Stop (terminate), or Queue (buffer work for later).
- Grace Period — Minutes of flexibility before/after schedule boundaries.
Task Queue
Manually assign work to the agent. Each task has:
- Title — Required. A brief description of the work.
- Description — Optional detailed instructions.
- Priority — Urgent, High, Normal, or Low. Color-coded badges.
- Type — General, Email, Research, or Communication. Helps categorize work.
- Status — Pending, In Progress, Completed, or Cancelled.
- Actions — Complete or Cancel buttons for active tasks.
Task Pipeline
Unlike the manual Task Queue, the Task Pipeline tracks tasks automatically created when the agent is spawned for work. It shows:
- Task status with real-time SSE updates
- Duration and model used
- Full task details on click
Tip: The Task Pipeline is separate from the manual Task Queue. Pipeline tasks are system-generated; queue tasks are manually created by administrators.
Clock History
A complete audit trail of all clock-in/out events. Features include:
- Search — Filter by timestamp, type, or notes.
- Type Filter — Show all records, clock-ins only, or clock-outs only.
- Pagination — 15 records per page with next/previous navigation.
- Detail Modal — Click any record to see full details including IP address, session ID, source, duration, and metadata.
Best Practices
- Set schedules to match your team's hours — If your team works 9-5 EST, set the agent to the same. This ensures it's available when needed and not burning tokens overnight.
- Use "Queue" for off-hours action — This buffers incoming work instead of dropping it. The agent processes the queue when it clocks back in.
- Enable Auto-Wake for critical agents — Ensures the agent starts on time without manual intervention.
- Use priority levels consistently — Reserve "Urgent" for genuinely time-sensitive tasks. Overusing high priority defeats its purpose.
- Review clock history for anomalies — Unexpected clock-ins/outs may indicate guardrail interventions or system issues.
- Set a grace period of 5-10 minutes — Prevents the agent from being cut off mid-task when the schedule ends.
Troubleshooting
Agent won't clock in
Check if the schedule is enabled and the current time falls within the configured hours (accounting for timezone). If "Enforce Clock-In" is active, the agent can only clock in during scheduled hours.
Tasks stuck in "Pending"
The agent must be clocked in and active to process tasks. Verify the agent status shows "Online" and "Clocked In". Also check if the agent is paused by guardrails.
Real-time status not updating
The SSE connection may have dropped. Refresh the page to re-establish it. If the issue persists, check network connectivity and that the engine API is running.
Schedule changes not taking effect
Schedule changes take effect at the next schedule boundary. If the agent is currently clocked in, it will continue until the current period ends. For immediate effect, manually clock the agent out and back in.
Organization Context
When an agent belongs to a client organization, workforce management respects organization-level settings:
- Business Hours — The agent's work schedule follows the organization's defined business hours and timezone. An info banner displays the organization name and configured hours.
- Schedule Inheritance — If the organization defines standard working hours, new schedules default to those hours. You can still override per-agent.
- Clock Records — Clock-in/out records are tagged with the organization context for auditing and compliance.
How do I know if an agent follows org hours?
A blue info banner appears at the top of the Workforce tab showing "Work schedule follows [Org Name] business hours" along with the configured hours and timezone when applicable.