Agent Lifecycle Hook

A PostStart hook executes immediately after an agent container is created. It is used for initialization tasks that must run before the agent is considered ready to accept work.

• Common Use Cases:

  • Loading large models or datasets into memory.
  • Warming up caches or establishing connections to external services (e.g., databases, vector stores).
  • Registering the agent with a service discovery system.
  • Performing initial health checks or seeding initial state.

• Execution Guarantee: The hook runs asynchronously and does not block the container start. However, if the hook fails (exits with a non-zero status), the container is terminated and restarted according to the pod's restart policy.

A PreStop hook executes immediately before a container is terminated. It provides a graceful shutdown mechanism, allowing the agent to complete in-flight work and persist state.

• Critical for Stateful Agents: Essential for agents handling transactions, managing sessions, or writing to persistent storage to prevent data corruption or loss.

• Common Use Cases:

  • Draining connections and finishing active requests.
  • Flushing in-memory buffers or logs to disk.
  • Deregistering from load balancers or service meshes.
  • Releasing acquired locks or resources in a distributed system.

• Execution Guarantee: The hook is called synchronously and must complete before the termination signal (SIGTERM) is sent. The agent is given a finite grace period to complete; if the hook hangs, a SIGKILL will force termination.

A readiness probe is a periodic check that determines if an agent is ready to serve traffic. It is a specialized form of lifecycle check, not a one-time hook.

• Function: Signals to the orchestration platform (e.g., Kubernetes) when the agent's main process has fully initialized. Traffic is only routed to the agent after its readiness probe succeeds.

• Probe Types:

  • HTTP GET: Checks a specific endpoint (e.g., /health/ready).
  • TCP Socket: Attempts to open a TCP connection on a specified port.
  • Exec: Executes a command inside the container.

• Key Difference from Liveness Probes: A failed readiness probe stops traffic to the pod but does not restart it. This allows the agent time to recover from transient issues (e.g., loading a large context window) without being killed.

A liveness probe is a periodic diagnostic that determines if an agent is still functioning correctly. If it fails, the container is restarted.

• Function: Detects and recovers from "deadlock" or "hung" states where the agent process is running but unable to make progress (e.g., a stalled inference loop, a deadlocked thread).

• Probe Types: Same as readiness probes (HTTP GET, TCP Socket, Exec).

• Critical Configuration:

  • initialDelaySeconds: Time to wait before starting probes after container start.
  • periodSeconds: How often to perform the probe.
  • failureThreshold: Consecutive failures required to restart the container.

• Design Consideration: The check must be lightweight and should not depend on external systems (like databases) whose failure would cause unnecessary agent restarts.

A startup probe is used for agents with long initialization periods. It disables liveness and readiness checks until the agent has successfully started, preventing premature restarts.

• Primary Use Case: Agents that require extended cold start times, such as those loading multi-billion parameter models or building large in-memory indices.

• How it Works:

  1. The startup probe runs with a high failureThreshold and periodSeconds.
  2. Once the startup probe succeeds once, it is disabled.
  3. Control is handed over to the liveness and readiness probes for the remainder of the agent's lifecycle.

• Example Configuration: failureThreshold: 30, periodSeconds: 10 gives the agent up to 5 minutes (30 * 10 seconds) to start before being considered failed.

Beyond core orchestration hooks, advanced agent frameworks define custom lifecycle events for domain-specific orchestration logic.

• Framework-Specific Hooks: Libraries like LangGraph or AutoGen provide hooks for integrating into their state machine execution.

• Common Custom Events:

  • on_agent_create: For setting up agent-specific context or tools.
  • on_task_assign: Logic executed when a new task is dequeued.
  • on_tool_call: Intercepting and logging/validating tool execution.
  • on_error: Custom error handling and retry logic.
  • on_state_snapshot: Triggered periodically to persist the agent's reasoning state for state persistence.

• Implementation: Typically implemented via decorators, event listeners, or middleware in the agent's SDK, allowing developers to inject monitoring, security, or business logic without modifying core agent code.