Практычныя прытамулкі: стварэнне системы выкрычання шахрайства з агентамі, гатовай да эксплуатацыі

У гэтым карыце практычным напамінанні перакладзенаецца шлях ад сыр'ёў да рабочай системы для стварэння системы выкрычання шахрайства, гатовай да вывароту — Частка 1: Паўная кантэкст. Акцэнт ставіцца на практычныя крокі, чысткія пераконтрацыі і код, які можна проста дадаць у репазітарый без неабясненняя меты. У стадії агульнага відзірвання пярэд тым, як зменшыць код, неабходна визначыць вхідныя даны, адпаведальнага за крок і критэрыя завершэння. Аперацыйныя працавікі должны магчымае перадзваніць крок з вядомай точкі контролю, не падозрюючы пра схованы стан. Спрыяйце гэтай стадіі як даговору межа вхіднымі данымі і падтвердзенымі выходнымі рэзультатамі. Дайце назвы артыфактам, визначыце пераконтрацыі успеху і адмовіцеся ад тыхнаго частковага завершэння без паведамлення.

Форма проблемы

Калі працюеце над проектам «Форма сцэны», спачатку запісайце умовы кантракту: неабяжлівыя даны, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список контроля дапамагае заліцвачыць змяны ў кодзе.

Аптака системы

Калі працуеце над стадзіяй адгляду системы, спачатку запісайце умовы контракту: неабяжлівыя даны, сігнал успеху і тое, што выходзіць пад частыя неудачы. Такі список контроля дапамагае заліцвачыць змяны ў кодзе па правдзе. Зберагайце настройкі за межамі коду прыемліка. Файлы сераўнавання, хранілішчы секрэтных дадзеных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаюць адбавіць аудыт без неабяжлівага чытання всей структуры. Ставьце контрольныя пункты пасля дорогіх крокаў. Програма для продажу не должна занова ставіць плату за той самы вызов LLM, калі аператар перапрыяўляе роботу да наступнага элемента.

Агентная оркестрацыя — адлік мошчанства ў рэальны час

Калі працуеце над стадзіяй «Агентная оркестрацыя у рэальны час», спачатку запісайце контракт: неабяжлівыя даннэ, сігнал успеху і тое, што выканаецца у разы частковага нявыполнення. Такі список пераканаецца ў тым, што пазнейшыя змены коду будуць чыстымі. Документавайце як шлях успеху, так і шлях вярнення. Перапрыбуткі, людзкі контроль і обработка некоректных паведамленняў ёсць частью продукту, а не пазнейшым дапрацоўкам. Стварайце контрольныя пункты пасля дорогіх крокаў. Продовжэнне роботы не должна зноў выклікаць той самы каллендж да LLM, калі аператар перапрыбуе пазнейшы вузел.

Агент А — расчэты прыхілу (трэнаваны модель)

Калі працюеце над стадзіяю расчытку прапенсіі агента А, спачатку запішыце кантракт: неабяжлівыя даны, сигнал успеху і тое, што выходзіць у разе частковага неудачы. Такі список пераканальвае правядзіць пазнейшыя змены ў кодзе. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшае, неудача должна вказваць на адну адпаведальнасць, а не на заплутаны ланцужок задач. Зберагаеце у кэшы стабільныя інструкцыі системы і схемы інструментаў. Перадзял у тое ж самае прамаргінале — частая прычына витрачання ресурсаў.

Агент Б — расчытак прапенсіі на аднойчынных дзеяннях (без жадного модэлю)

Калі працюеце над стадзіяю атрыбутавання парадаксу поведзення Агента B, спачатку запішыце кантракт: неабяжлівыя даннэ, сігнал успеху і тое, што выходзіць у случае частковага нявыпання. Такі чэк-ліст дапамагае захаваць чыстасць пазнейшых змян у кодзе. Спрытывайце гэту стадзію як кантракт межа даннэмі і перакананымі выходамі. Дайце назвы элементам, задаце критэрыі успеху і не прымайце часткова завершэння без паведамлення. Зберагачвайце стабільныя інструкцыі системы і схемы інструментаў. Перадача тых самых прамэры ёсць частым выклікам зношвання ресурсаў.

Агент C — адзысканне правіл працы через pgvector

Калі працюеце над стадзіяй выкарыстоўвання політыкы Agent C, спачатку запісайце умовы контракту: неабходныя даны, сігнал успеху і тое, што выходзіць па частковай нявыполненасці. Такі список дапамагае залічыцца з пазнейшымі змянамі ў кодзе.

Інжынерныя аспекты: тыя элементы, якія не паказваюцца ў карточцы модэлю

Калі працюеце над стадзіяй разрабаткі частак у Harness, спачатку запісайце контракт: неабяжлівыя даны, сігнал успеху і тое, што выканаецца пад частковым абяраннем. Такі список пераканаецца, што пазнейшыя змены коду будуць чыстымі. Зберагаеце канфігурацыю паза кодам прыемлена. Файлы серавэра, хранілішчы секретных дадзеных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаюць адбавіць аудыт без чытання всей структуры. Кэшаваеце стабільныя інструкцыі системы і схемы інструментаў. Перадзесланне ідэнтычных прамаравых дадзеных ёсць частым выклікам зношэння ресурсаў.

"""
SessionMemory — the public interface tying working memory (short-term) and
episodic memory (long-term, cross-session) together for context engineering.

    mem = SessionMemory()                      # new session, fresh UUID
    mem.remember("user", "...")                # auto-persists to pgvector
    mem.remember("assistant", "...")
    context = mem.build_context(next_question) # summary + recent turns + relevant past episodes
    mem.end_session()                          # finalize into episodic_memory
"""

"""
In-memory semantic cache in front of episodic recall.

Two layers:
  - exact-string embedding cache: a literal repeat query skips the OpenAI
    embeddings API call entirely.
  - semantic result cache: a near-duplicate query (different wording, same
    intent) still needs embedding to compare, but skips the Postgres/pgvector
    round-trip if it's cosine-similar enough to something already cached.

Process-local only (not shared across workers/processes) — fine for a
single running service, not a substitute for a distributed cache if this
ever runs behind multiple instances.

Must be invalidated when a new episode is saved: a cached "no good match" or
partial result set can go stale the moment the underlying corpus changes.
"""

"""
Fraud-detection event chain, built on the generic pub-sub bus in
common/pubsub.py:

    UserQueryEvent
        -> InputGuardrailService   -> InputGuardrailPassedEvent | InputGuardrailBlockedEvent
        -> OrchestrationService    -> OrchestrationCompletedEvent | OrchestrationPausedHITLEvent
        -> OutputGuardrailService  -> OutputGuardrailPassedEvent | OutputGuardrailBlockedEvent
        -> ResultPublisher         -> PipelineCompletedEvent

    HumanDecisionEvent (resumes a run paused at OrchestrationPausedHITLEvent)
        -> OrchestrationService    -> ... (same chain onward)

Each service subscribes to exactly one (or two, for resume) event type and
publishes the next event in the chain — a new listener (audit logger,
LangSmith exporter) can subscribe to any event without touching the
publishers. The guardrail/graph calls underneath are synchronous
(psycopg2, HF/OpenAI SDKs); handlers run them via asyncio.to_thread so a
slow call doesn't block the event loop for other in-flight events.
"""

@mcp.tool()
@guarded(action="score_transaction")
def score_propensity(features: dict[str, float], role: str) -> float:
    """Score one transaction's V1-V28 features for ML fraud probability (0-1). Agent A.
    Requires role: analyst or admin."""
    return score_customer_propensity(features)

@mcp.tool()
@guarded(action="score_transaction")
def score_behavior(customer_id: int, amount: float, category: str, merchant: str, role: str) -> dict:
    """Score one transaction's behavior anomaly vs its category's peer-cohort stats. Agent B.
    Requires role: analyst or admin."""
    return score_customer_behavior(customer_id, amount, category, merchant)

@mcp.tool()
@guarded(action="chat_query", free_text_arg="query")
def consult_fraud_policy(query: str, role: str, k: int = 3) -> list[dict]:
    """Semantic search over the indexed credit-card policy/handbook documents. Agent C.
    Requires role: viewer or higher. `query` is scanned for prompt injection/jailbreak and PII."""
    return consult_policy(query, k=k)


if __name__ == "__main__":
    mcp.run()

JWT_SECRET_KEY = os.environ["JWT_SECRET_KEY"]
JWT_ALGORITHM = os.environ.get("JWT_ALGORITHM", "HS256")
JWT_EXPIRE_MINUTES = int(os.environ.get("JWT_EXPIRE_MINUTES", "30"))
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

def verify_password(plain_password: str, hashed_password: str) -> bool:
    return pwd_context.verify(plain_password, hashed_password)

def get_password_hash(password: str) -> str:
    return pwd_context.hash(password)

def get_user(username: str) -> dict | None:
    conn = get_connection()
    try:
        with conn.cursor() as cur:
            cur.execute("SELECT * FROM users WHERE username = %s", (username,))
            return cur.fetchone()
    finally:
        conn.close()

def authenticate_user(username: str, password: str) -> dict | None:
    user = get_user(username)
    if not user or user["disabled"]:
        return None
    if not verify_password(password, user["hashed_password"]):
        return None
    return user

Візуабельнасць

Калі працуеце над стадзіяй абсарвабельнасці, спачатку запісайце контракт: неабяжлівыя данні, сігнал успеху і тое, што выканаецца пад частковай нявыходзе. Такі список пераканаецца, што пазнейшыя змены коду буду чыстымі. Документавайце як шлях успеху, так і шлях вяснавання. Перапрыбуткі, людзкія контралісты і обработка некоректных паведамленняў ёсць часткай продукту, а не пазнейшым дапрацоўкам. Зрабіце контрольную пазнаку пасля дорогіх крокаў. Система вярнення не павінна зноў вырахоўваць кашты за той самы вызов LLM, калі аператар перапрыбуе пазнейшы вузел. Калі працуеце над стадзіяй абсарвабельнасці, спачатку запісайце контракт: неабяжлівыя данні, сігнал успеху і тое, што выканаецца пад частковай нявыходзе. Такі список пераканаецца, што пазнейшыя змены коду буду чыстымі. Спрацоўвайце з гэтай стадзіяй як з контрактом межа даннімі і перакананымі выходамі. Дайце назву артыфактам, задаце перакананні на успех і адмовіцеся ад тыхоўкага частковага завершэння.

Развяртанне ў AWS і фронтэнд

AWS Deployment і стадія працююць наўсёрэдзе, калі іх спрыяваць як мерыемую паверхню. Запісаце адна ідеальная версія, адзін прыклад неудачы і прыметкі па абратанню рэшыцтва прычымоў перад расширэнням масштаба. Запісвайце часы выканання і вартасць токенаў або запытак праза функцыйнае рэзультат. Відчутнасць вартасцей з самага пачатку запобегае неспакою з біламі, калі праця пераходзіць з дэмавайшнага режыма ў спяльныя среды. Храніце стан графаў у простам і типаваным формате. Вкладзеныя блокі маскуюць, який вузел запісаў канкрэтны поле, і спакшваюць продажчыку роботу пасля перарываў.

Што далей

Этап «Што далей» працюе найэфектывней, калі яго розглядаць як вимерную плошчу. Зберагачыце адны ідеальны прыклад роботы, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць сферу дзеяння.

Чэртак аператыўных задач

Этап чэртка аператыўных задач працюе найэфектывней, калі яго розглядаць як вимерную плошчу. Зберагачыце адны ідеальны прыклад роботы, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць сферу дзеяння.

Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшае, прычына неудачы павінна вказываць на адную адповядальнасць, а не на заплутаны ланцюг задач.

Зберагаюце стан графа ў простам і типаваным формате. Вкладаныя блобы маскуюць інфармацію пра тое, який вузел запісаў якое поле, і спакоююць працэз виконання пасля перерываў.

Калі дозволяе бюджет, дадзіце тэст на перакананне, які працюе з критычным шляхам у системе CI за дапамогою фіксатываў, а не з рэальнымі платнымі API.

Спрыяйце цэй стадзіі як даговору межа вхіднымі даннымі і перакананымі выходнымі рэзультатамі. Даўце назвы артыфактам, задзержыце критэрыя успеху і адмовіцеся ад беззвучнага частковага завершэння.

Зберагаюце стан графа ў простам і типаваным формате. Вкладаныя блобы маскуюць інфармацію пра тое, який вузел запісаў якое поле, і спакоююць працэз виконання пасля перерываў.

Перш чым апранаваць стэк, заморозьце версіі, зафіксуйце ідеальны транскрыпт для критычнага шляху і паказвайце крокі для адворачэння. У спакульнаваных средах неабходны ліміты частоты запытоў, перакананні ў прыналежнасці і чыстае вялоўніцтва для змены секрэтаў. Валіце надзейнасць працы над красавім разовым дэманстрацыйным прыкладам.

Запіска параграфу 5d0d59733252: не трэба кантрацеўваць ключы прадаўцаў у репазітарыі, задаць максімальную кантэйнернасць токена на кожную сесію, а таксама зберагчы транскрыпціі празаўседле фікстурамі адлікавання, каб пазнейшыя замены модэляў заставаліся парабелнымі.

Калі працуеце над 0-й стадзіяю запіскі пра зміцнэнне, спачатку запісайце контракт: неабходныя вхідныя даны, сігнал успеху і тое, што выходзіць у разе частковага абякання. Такі чэк-ліст дапамагае заставаць пазнейшыя змены коду чыстымі. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісьць крок абякае, абяканне павінна вказваць на адну адпаведальнасць, а не на заплутаны лянцюг задач.

Дзеянне пра зміцнэнне 0/721: вымерыце час выканання, класію абякання і выкарыстаны токен для гэтай запіскі, а пасля вырашыце, чы робіць змену на адной фіксаванай сэтке пытанняў, а не на адной лягендзе.

Этап 1 прыцелення на зміцнэнне работае найкраща, калі яго расследжваць як вимерную паверхню. Запісаўце адна «золатая» транскрыпцыю, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць масштабы. Запісвайце часы выканання і косты токенаў або запытак праза функцыйнае рэзультаты. Відразлівае паказанне костаў з’являецца перашкоду неспакою, калі процес пераходзіць з дэмаверсіі ў спяльныя среды.

Дзеянне прыцелення на зміцнэнне 1/721: вимеравайце час выканання, класію памылак і витраты токенаў для гэтага запісу, а потым вырашайце, чы рашыцца застаўляць змяну, адпаведна фіксаванаму набору пытанняў, а не толькі на адной прыгадцы.

Для этапа 2 прыцелення на зміцнэнне паказвайце вхідныя даны, адпаведальнага за крок і критэрыя завершэння перш чым зменіць код. Аперацыйныя працавнікі павінны магчымае перазваляць крок з вядомай точкі контролю, не спадзяваючыся на схованы стан. Документавайце як «шчаслівы» так і «вярнучыся» шляхі разам. Перапрыбуткі, людзкія контрольныя пункты і обработка неканальных паведамленняў є часткай продукту, а не чымсь, што дадаецца пазней.

Дзеянне паўжасткі 2/721: звярніце увагу на час выканання, клас памылакі і колькасць викорыстоўваных токенаў для гэтага зьязначэння, а пасля, на аднойчынай базе фіксаванага набору пытанняў, а не на індывідуальных прыкладах, выявіце, чы хачаце застаўіць змяну.

Працюючы над 3-й стадзіяю паўжасткі, спачатку запісайце контракт: неабходныя вхідныя даны, сігнал успеху і тое, што выканаецца у разе частковай памылки. Такі чэрніцкі ліст абавяжае да правадзення чыстых змян у кодзе пазнейша. Спрыятлівае ставленне да гэтай стадзіі як да контракту межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Дайце назвы артыфактам, задаце крэтыры успеху і адмовіцеся ад мовчанкавага частковага завершэння.

Дзеянне паўжасткі 3/721: звярніце увагу на час выканання, клас памылакі і колькасць викорыстоўваных токенаў для гэтага зьязначэння, а пасля, на аднойчынай базе фіксаванага набору пытанняў, а не на індывідуальных прыкладах, выявіце, чы хачаце застаўіць змяну.

Этап 4 прынцыпа зміцнення работае наяўна, калі яго розглядаць як вимерную паверхню. Зафіксавайце адна «золатая» копія даных, адин прыклад неудачы і запіс пра вярненне да пачатковага стану перш чым расширваць сферу дзеяння. Зберагаюце настройкі пазырочна ад коду прыемліка. Файлы сераўнавання, хранільнікі секрэтных данных і пазнакі функцый крануцца на адным месцы, якое аператары можаць пераглядаць без неабяжнага чытання всіх дадзеных.

Дакладнасць прынцыпа зміцнення 4/721: вимеравайце час выканання, класію памылак і колькасць викорыстоўваных токенав для гэтага прынцыпа, а пасля вырашайце, чы хацяце застаўіць змяну, спыраючыся на фіксаваны набор пытанняў, а не на індывідуальныя спостарожэння.