Практычныя нататкі: агентная сістэма выяўлення махлярства для прадакшну

У гэтым карыце практычным напамінанні перакладзенаецца шлях ад сыр'ёў да рабочай сістэмы для стварэння сістэмы выкрычання шахрайства, гатовай да вывароту — Частка 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: вімеравайце час выканання, класію памылак і колькасць вікорыстоўваных токенав для гэтага прынцыпа, а пасля вырашайце, чы хацяце застаўіць змяну, спыраючыся на фіксаваны набор пытанняў, а не на індывідуальныя спостарожэння.