agent-module-architecture

Agent module architecture

Applicable scenarios

• Modify Agent startup, daemon, and process management
• Handle heartbeat, Ask polling, task pulling, or task completion flow
• Modify Agent upgrade, component upgrade, and build machine environment management
• Troubleshoot interaction issues between Agent and Dispatch, Worker

Inapplicable scenarios

• Only modifying task execution inside Worker
• Only modifying plugin definitions,task.json or plugin publishing
• Only modifying Dispatch scheduling quotas and queue policies
• Only modifying pipeline business logic

Quick guidance

1. This skill focuses on "how the build machine host side stays online, receives tasks, and pulls up executors".
2. Agent mainly handles daemon, heartbeat, upgrade, and task orchestration, and is not responsible for plugin body definitions.
3. First enter the corresponding reference document by problem type:
   • Runtime form and upgrade:reference/1-runtime-upgrade.md
   • Ask, heartbeat, and task pulling:reference/2-ask-heartbeat-build.md
   • Platform support, operations, and troubleshooting:reference/3-platform-ops.md
4. If the problem has entered task execution details, switch to worker-module-architecture。
5. If the problem is in build machine selection, queuing, or resource quotas, switch to dispatch-module-architecture。

High-signal rules

• Agent is the build machine-side orchestrator, Worker is the executor
• Daemon, heartbeat, Ask, and upgrade are the four core facets for understanding Agent
• Agent changes usually affect stability, online rate, and task claiming capability
• When process management and upgrades are involved, prioritize cross-platform differences

Key pitfalls

• Misjudging Worker detail issues as Agent issues
• Looking only at a single request, not the full daemon and polling chain
• Upgrade logic does not consider rollback, concurrency, and running tasks
• Ignoring behavioral differences across Linux / Windows / macOS

Further reading

• Runtime form and upgrade:reference/1-runtime-upgrade.md
• Ask, heartbeat, and task pulling:reference/2-ask-heartbeat-build.md
• Platform support, operations, and troubleshooting:reference/3-platform-ops.md
• If you are modifying Worker execution: also see worker-module-architecture
• If you are modifying scheduling and build machine selection: also see dispatch-module-architecture