A job agent in Python

The ecosystem arrives first here: provider SDKs, agent frameworks, browser drivers and data tooling all exist in Python, usually before anywhere else. For a job agent that also needs parsing and embedding work, that breadth matters.

The trade-off is runtime performance and packaging, neither of which is the bottleneck in an agent. Almost all the wall-clock time is spent waiting on model calls and network requests, so the language’s own speed barely registers.

The honest counterweight is duplication. If the product is already a TypeScript application, a Python agent means two domain models, two sets of validators and a synchronisation problem forever — and for a small team that cost frequently outweighs the ecosystem advantage.

The layout that survives has clear seams: tools, model interaction, state, and orchestration as separate modules with typed interfaces between them. Frameworks change; these boundaries do not.

Keep tool implementations free of model-specific detail, so switching provider touches one adapter rather than everything. Agent code that has provider types threaded through it is painful to change and people avoid changing it.

Be sceptical of frameworks that own the orchestration loop. They are excellent for getting something running in an afternoon and awkward once you need a specific budget, a particular stopping condition or a resume path they did not anticipate — and by then the logic is expressed in their vocabulary rather than yours.

• tools/ — plain functions with validated inputs and typed returns
• providers/ — one adapter per model provider, nothing else imports them
• state/ — persistence, resumption, idempotency keys
• agent/ — orchestration, budgets, stopping conditions

Model output is untrusted input. It will sometimes be malformed, sometimes contain the right shape with the wrong types, and occasionally contain something that should never reach a database.

Define the expected shapes as schemas and parse into them. The parse either succeeds and gives you typed data or fails in a way you can retry deliberately — which is far better than a stray key surfacing three layers later.

Put the domain rules in the same place. A salary that must be positive, a date that cannot be in the future, a seniority that must be one of five values — all of these are cheap to express as validators and expensive to discover in a ranking three weeks later.

Agents are IO-bound: model calls, page loads, database round-trips. Async concurrency fits this exactly, and scoring fifty postings concurrently rather than serially is the difference between one second and a minute.

Keep the CPU-bound work — document parsing, embedding maths — out of the event loop, in a process pool or a separate worker. Blocking the loop with a slow parse stalls every concurrent operation, and it is a bug that shows up only under load.

Bound the concurrency explicitly with a semaphore rather than gathering over a list. Unbounded fan-out over two hundred postings exhausts rate limits, spends a budget nobody approved and turns one bad prompt into two hundred simultaneous bad calls.

Watch for sync libraries hiding in async code. A database driver or HTTP client that is not async blocks the loop while appearing to participate in it, and the symptom is unexplained latency across unrelated work rather than an error anyone can trace.

A job agent runs for minutes or days, which does not fit in a web request. Put the work in a queue with durable workers, and let the API accept the request and return.

Workers restart, so the state must be external and every action idempotent. Design for a worker dying mid-application from the start: the alternative is discovering the requirement through duplicate applications in production.

Handle the termination signal deliberately. A worker that finishes or safely abandons its current step and refuses new work on shutdown turns a routine deploy into a non-event, where one that is killed mid-submission produces exactly the ambiguous state that is hardest to resolve.