Running a Python or LangGraph Agent as a Flisk Worker, With Dependencies Declared

A worker agent operates differently from HTTP-response agents. It utilizes a queue system, acquiring tasks, executing them via a model, and outputting results. The Flisk worker resource aligns with this architecture, necessitating Postgres and NATS services as dependencies. To set up the worker, initiate a scaffolded flisk resource named research-agent with a worker type, targeted at the shop stack, using the --yes flag for automation.

The service.json file must specify the worker's name, type, stack, and dependencies: Postgres and NATS. Connection strings for these services are referenced using @ref(...) within the environment block, preventing hard-coded URLs and ensuring flexibility.

The worker's boot sequence is contingent on the readiness of Postgres and NATS, as stipulated in the docs. This sequencing is crucial to prevent startup races, where a premature worker might fail during its initial poll due to an unready queue. Additionally, the worker demonstrates resilient behavior during hot reloads, seamlessly reconnecting. This characteristic should be validated within the operational setup, given that the reconnection logic resides within the agent's codebase.

For optimal functionality, the worker must be designed to be idempotent. This means that executing the same task twice should not result in duplicate actions, such as sending multiple emails or recording redundant database entries. Employing the task ID as a unique identifier helps prevent such duplications. Logging each task execution with its corresponding ID provides a clear audit trail.

In the event of a task failure, a defined retry limit should be enforced. Once exhausted, the task should transition to a failed state, preserving the error information for future reference.

It's important to differentiate a worker from a session server, as the latter does not support x-session-id routing due to the absence of conversational continuity in queue-based interactions. If a session continuity feature is required, the agent resource is the more suitable choice, as detailed in the preceding article of this series.

In essence, a background agent aligns with the worker resource model. The dependencies, namely Postgres and NATS, must be declared under dependsOn, with their URLs referenced via @ref(...) to maintain configuration agility. Ensuring the task handling is idempotent, imposing a cap on retry attempts, and confirming the start order through a dry run before deployment are essential steps to ensure the worker's reliability and efficiency.