LangChain e LangGraph

stalwart_agents.langchain coloca o roteamento, a verificação de ferramentas e as sagas da Stalwart dentro de agentes LangChain e LangGraph. Nenhum seletor, vocabulário ou verificação está neste módulo. Toda decisão sobre a qual ele age é tomada pelo runtime que o wheel traz, na mesma máquina, sob a sua licença, ou pelo qls-router enterprise que você executa no seu próprio ambiente, onde o cliente o nomeia (router_url). A API hospedada da Stalwart não toma nenhuma delas. Um turno que precisa de um cálculo que nenhuma ferramenta responde é executado pelo nó de cálculo na imagem de contêiner qls-sandbox no seu próprio host, onde há um mecanismo de contêineres e a imagem; nos demais casos, ele é recusado, com um motivo que começa com compute off:.

$ pip install stalwart-agents                # the middlewares, the graph parts, Guard
$ pip install "stalwart-agents[otel]"        # OpenTelemetry spans
$ pip install "stalwart-agents[postgres]"    # resume confirmations from Postgres (or [sqlite])
$ pip install "stalwart-agents[nemo]"        # the NeMo Guardrails actions and rails

LangChain: dois middlewares, um importador, um callback

from langchain.agents import create_agent
from stalwart_agents.langchain import (StalwartRouterMiddleware, StalwartToolGuardMiddleware,
                                StalwartFeedbackCallback, register_catalogue)

register_catalogue(tools, agent="desk", client=client)            # POST /v1/catalogues
agent = create_agent(model, tools, middleware=[
    StalwartRouterMiddleware(client, agent="desk", on_unread="refuse"),
    StalwartToolGuardMiddleware(client, agent="desk"),
])

• O roteador lê cada turno do usuário em um plano antes de o modelo ser chamado. Um turno que se resolve em uma ferramenta, uma pergunta ou uma recusa custa nenhuma chamada de modelo. Um cálculo é escrito pelo seu próprio modelo. Pede-se que um turno que nada lê seja reformulado uma vez; depois disso, ele segue a sua configuração: refuse, model ou ask, que o entrega ao modelo só quando o usuário diz que sim (uma interrupção delegate: approve ou decline).
• A guarda de ferramentas verifica toda chamada de ferramenta, quem quer que a tenha escolhido. Uma chamada recusada não executa nada e recebe um resultado que diz por quê. Uma escrita pausa na interrupção do LangGraph e só é executada quando os argumentos exatos mostrados são aprovados. As chamadas de uma mensagem rodam lado a lado e se revezam no único histórico da sessão, de modo que nenhuma se perde.
• A composição: o middleware do NeMo Guardrails por fora, depois o roteador, depois o modelo; a guarda de ferramentas em volta da execução das ferramentas. O nosso nunca remove o hook de outro middleware.
• StalwartFeedbackCallback lembra o turno e a ferramenta de cada execução. thumbs(run_id, up=False) envia um registro de feedback. Onde o roteador leu o turno, o registro é a leitura do próprio roteador, a partir do estado da execução: o seu veredito, a regra que decidiu e as ferramentas visíveis do agente; um turno que ele entregou ao modelo registra unread e a ferramenta do modelo. Um turno com várias instruções é avaliado passo a passo (step=); uma resposta que a conversa decidiu, ou a resposta depois de uma confirmação, é recusada com ThumbRefused.

LangGraph: as partes, ou o grafo inteiro

from stalwart_agents.langchain.graph import create_stalwart_agent

agent = create_stalwart_agent(model, tools, catalogue=catalogue, agent="desk", client=client,
                              checkpointer=checkpointer)            # verified once per graph digest

Python puro: Guard

from stalwart_agents.langchain.guard import Guard

guard = Guard(client, agent="desk", catalogue=catalogue, tools=[charge_card, refund_card])
with guard.run(guard.session()) as run:
    run.call(charge_card, order_id=o, amount=a)    # checked, keyed, its undo pushed
    run.call(provision_account, order_id=o)        # raises -> the charge refunded

stalwart_agents.langchain.guard não carrega nem LangChain nem LangGraph.

Em volta do agente

• stalwart_agents.langchain.server.ResumeServer: um app ASGI sobre o seu checkpointer. Ele lista as interrupções em aberto (as aninhadas e as paralelas, cada uma pelo seu próprio id), retoma uma delas em qualquer worker, recusa uma retomada desatualizada com 409 interrupt_stale, transmite os passos de uma conversa (retomáveis por Last-Event-ID) e permite que um operador reverta uma conversa: ResumeServer(operator_token=...), enviado como Authorization: Bearer em POST /threads/{id}/rollback; sem nenhum definido, a rota responde
  403. Duas respostas a uma mesma interrupção são diferenciadas por uma reivindicação (SqlClaims sobre o seu banco de dados, para vários workers). Cada resposta leva o refusal e o rollback do turno como dados. Webhook(url, secret) envia cada interrupção com uma assinatura HMAC, um carimbo de tempo e uma janela de repetição de cinco minutos; um envio que falha nunca faz o turno falhar.
• Recibos: uma chamada leva current_receipt() -- o histórico da sessão terminando na verificação que a permitiu --, de modo que um ponto de controle na frente das suas ferramentas (a rota da receita do Kong) a admite pela verificação do próprio agente, em vez de decidi-la de novo.
• stalwart_agents.langchain.otel: OtelTracer e NodeSpans dão um span para cada nó, plano, verificação, chamada, reversão, interrupção e retomada, com a decisão como evento do span. O conteúdo fica desligado por padrão.
• python -m stalwart_agents.langchain.trace show|html|diff renderiza uma execução a partir do seu arquivo de spans, ou só a partir do checkpointer.
• stalwart_agents.langchain.nemo: as ações stalwart_route e stalwart_check_tool, e um rail de entrada e uma guarda de execução em Colang 1.0 e Colang 2. Os dois trechos são verificados no nosso solver.
• stalwart_agents.langchain.redteam.RedTeam: um planejador, um explorador e um crítico apontados para os achados do caçador, ou em aberto, contra o seu grafo e o seu modelo, com toda ferramenta substituída por um stub. Not realised in budget não diz nada sobre segurança. graph_from_export constrói o alvo a partir de uma exportação, onde o seu próprio código não está à mão.