Agent Commands

Bot orchestration: heartbeats, task claiming, coordination.

Commands

optimal agent heartbeat

Send agent heartbeat

Flag	Description	Default	Required
--agent <id>	Agent ID		yes
--status <s>	Status: idle, working, error	idle

optimal agent heartbeat --agent content-bot --status active
optimal agent heartbeat --agent finance-bot --status idle

optimal agent list

List active agents (heartbeat in last 5 min)

optimal agent list

optimal agent claim

Claim the next available task

Flag	Description	Default	Required
--agent <id>	Agent ID		yes
--skill <s>	Skill filter (comma-separated)

optimal agent claim --agent content-bot
optimal agent claim --agent finance-bot --skill financial-analysis

optimal agent report

Report progress on a task

Flag	Description	Default	Required
--task <id>	Task ID		yes
--agent <id>	Agent ID		yes
--message <msg>	Progress message		yes

optimal agent report --task 42 --agent content-bot --message "Generated 3 of 5 social posts"

optimal agent complete

Mark a task as done

Flag	Description	Default	Required
--task <id>	Task ID		yes
--agent <id>	Agent ID		yes
--summary <s>	Completion summary		yes

optimal agent complete --task 42 --agent content-bot --summary "Published 5 social posts for CRE-11TRUST"

optimal agent release

Release a claimed task back to ready

Flag	Description	Default	Required
--task <id>	Task ID		yes
--agent <id>	Agent ID		yes
--reason <r>	Release reason

optimal agent release --task 42 --agent content-bot --reason "Missing API credentials"

optimal agent blocked

Mark a task as blocked

Flag	Description	Default	Required
--task <id>	Task ID		yes
--agent <id>	Agent ID		yes
--reason <r>	Block reason		yes

optimal agent blocked --task 42 --agent finance-bot --reason "Waiting on income statement upload"

optimal agent coordinate

Run the coordinator loop

Flag	Description	Default	Required
--interval <ms>	Poll interval in milliseconds	30000
--max-agents <n>	Maximum agents to manage	10

optimal agent coordinate
optimal agent coordinate --interval 60000 --max-agents 5

optimal agent status

Show coordinator status

optimal agent status

optimal agent assign

Manually assign a task to an agent

Flag	Description	Default	Required
--task <id>	Task ID		yes
--agent <id>	Agent ID		yes

optimal agent assign --task 42 --agent finance-bot

optimal agent rebalance

Release stale tasks and rebalance

optimal agent rebalance