create-agent-python

create-agent-python

Agent = orchestration only. No I/O, no business logic, no domain computation, no local domain data.

Allowed imports: shared/* — taxonomy VOs, constants, aggregate ABCs, protocol ABCs, utility functions. Forbidden imports: capabilities_*, agent_*, surface_*.

Allowed ops: for/while/async for, if/else/match, try/except/raise, asyncio.wait_for, collecting results into shared VOs. Forbidden ops: open(), Path(), os.*, requests.*, httpx.*, sqlite3.*, asyncpg.*, stdout/stderr write, env mutation, global state mutation.

3-Block Structure

# Block 1: Class Definition & Constructor
# Block 2: Aggregate Method Implementation
# Block 3: Dunder Methods, Factories, Helpers

Method placement:

Module-level def?                    → EXTRACT to *_utility.py
@abstractmethod in aggregate ABC?    → Block 2
Dunder / factory @classmethod?       → Block 3
@staticmethod pure + no class dep?   → EXTRACT to *_utility.py
Private helper (uses self)?          → Block 3

Helper vs Utility

Keep in Block 3 if ANY: uses self, coupled to this class, factory, agent-specific logic, single-use. Extract to utility only if ALL: no self/cls, pure, no side effects, domain-agnostic, reusable. I/O: stateless + I/O + domain-agnostic = taxonomy utility. Stateless + I/O + domain-specific = capabilities.

Computation, Errors, VOs

Computation forbidden: arithmetic, totals, averages, .reduce/.fold, parsing, normalization. Allowed: iteration to call deps, routing results, propagating errors.

Error rules:

• Rule 1: Never silently discard — no checker.check() or "".
• Rule 2: Analysis orchestration → return list[<ResultVO>], catch per-item into VO.
• Rule 3: Execution orchestration → return Result[...].
• Rule 4: Delegate I/O errors to capabilities — agent only wraps into VO.

VO rules: str/int/float forbidden for domain fields/contracts. bool for semantic toggles only.