Pular para o conteúdo
niadra
Integração · OpenAI Agents SDK

Memória para agentes do OpenAI Agents SDK.

Em Python, NiadraAgentsMemory entrega run_config(), o filtro que injeta o contexto antes de cada chamada ao modelo, hooks, que registram os turnos, e tools. Em JavaScript, NiadraSession, niadraInstructions(), niadraTools() e niadraRunHooks(). A Session do SDK continua sua.

A Session do Agents SDK guarda os itens deste agente: o que ele viu e produziu em cada run. É a memória de trabalho de um agente, chaveada por uma sessão da sua aplicação. O que a mesma pessoa disse ao agente de voz de outro fornecedor, ou o que o agente de cobrança fez no ERP, não está em sessão nenhuma.

A Niadra guarda memória derivada da empresa sobre o cliente, não uma cópia de cada item. O call_model_input_filter põe o contexto depois das instruções do agente e o turn_block depois da entrada, a cada chamada ao modelo; os hooks registram o que o cliente disse e o que o agente respondeu, com o uso informado. Um handoff entre agentes do run leva a mesma memória.

O exemplo mínimo, como está na documentação
pip install 'niadra[openai-agents]'   # openai-agents 0.22.3 or newer, below 1
"""An OpenAI Agents SDK agent with the customer's memory."""

import asyncio

from agents import Agent, Runner

from niadra import AsyncNiadra, phone
from niadra.integrations.openai_agents import NiadraAgentsMemory

niadra = AsyncNiadra(channel="chat")


async def main() -> None:
    async with niadra.conversation("thread-81", subject=phone("+5511912345678")) as conversation:
        memory = NiadraAgentsMemory(conversation, agent_memory=True)
        agent = Agent(
            name="Support", instructions="You are Acme's agent.", model="gpt-4.1", tools=memory.tools
        )
        result = await Runner.run(
            agent, "Where is my replacement lid?", hooks=memory.hooks, run_config=memory.run_config()
        )
        print(result.final_output)
    await niadra.close()


asyncio.run(main())
  • Python
  • TypeScript

O mesmo código está em examples/openai_agents_run.py, examples/openai-agents.ts nos repositórios dos SDKs, onde roda na CI contra os tipos reais do framework e o emulador da Niadra. Para testar sem a nuvem da Niadra, niadra-mock e NIADRA_BASE_URL=http://127.0.0.1:8765.

Como o adaptador se liga

As cinco primitivas de toda integração da Niadra, nos pontos de extensão deste framework.

Contexto
Em Python, run_config() define call_model_input_filter, que roda logo antes de cada chamada ao modelo: o contexto vai depois das instruções do agente e o turn_block depois da entrada, como mensagem de sistema; um filtro que você já tinha roda primeiro. Em JavaScript, niadraInstructions(base, conversation) torna as instruções dinâmicas: o seu texto, depois as notas do agente e o contexto, depois o sufixo.
Turnos
Em Python, hooks (um RunHooks) registra as mensagens novas do cliente quando o modelo é chamado pela primeira vez para elas, e a resposta do agente com o uso informado; os turnos são chaveados pela posição, então o histórico que uma Session repete no próximo run nunca é registrado duas vezes. Em JavaScript, NiadraSession é uma Session para run(agent, input, { session }): guarda os itens na sessão que você passa e registra os dois lados.
Ferramentas
tools: as três do histórico como FunctionTool com os nomes, descrições e esquemas do kit, amarradas ao cliente. Em JavaScript, niadraTools(conversation).
Verificação
O que o seu app provou (um login, um OTP) vai a conversation.verify() antes do run.
Transbordo
Um handoff do SDK entre agentes registra handoff("agent"); dê a todo agente do run a mesma memória. Em JavaScript, niadraRunHooks(runner, conversation) registra os handoffs.

O que o agente recebe

O contexto é compilado quando a memória muda e servido pronto, sem modelo de IA na leitura. O que outro canal disse durante a conversa chega como delta, no fim do prompt.

  • Quem é o cliente, pelo que a conversa já provou: o nível de verificação decide o que entra
  • Fatos, pendências e promessas, com a data e o canal de origem
  • O que outros agentes fizeram por dentro, confirmado pelo sistema de registro
  • Padrões calculados por regra, com as evidências e o prazo
  • As três ferramentas do histórico: buscar, linha do tempo e abrir um item, amarradas ao cliente no seu código
  • Comprovante de cada leitura, encadeado por SHA-256

O que o adaptador não faz

  • O adaptador em Python não implementa a Session do SDK: uma Session guarda os itens do próprio agente, e a Niadra guarda memória derivada, não uma cópia de cada item. Use qualquer Session ao lado dele. Em JavaScript, NiadraSession embrulha a sessão que você escolher.
  • Nada aqui derruba um run: a Niadra lenta ou fora deixa as instruções só suas.
  • Em Python, o extra openai-agents fixa versões incompatíveis com livekit, crewai e litellm; instale um por ambiente.
  • Testado contra openai-agents 0.22.3 e @openai/agents 0.18.0 com o modelo substituído por um fake e a Niadra no emulador.

Perguntas frequentes

Isso substitui a Session do SDK?

Não. A Session é a memória de trabalho deste agente, e continua sua, em memória ou no SQLite. A Niadra é a memória da empresa sobre o cliente, derivada dos eventos de todos os canais e agentes. As duas convivem no mesmo run.

Com vários agentes e handoffs, quem lê a memória?

Todos os agentes do run recebem a mesma memória: o filtro roda a cada chamada ao modelo, de qualquer agente, e o handoff entre eles é registrado como transbordo para o agente seguinte, com a conversa aberta.

O contexto entra em cache no provedor?

O contexto vai depois das instruções, que continuam o prefixo do prompt, e vem fixado por conversa, então o começo do prompt se repete chamada após chamada e o provedor reaproveita. O que mudou entra como delta, no fim.

Preciso trocar de modelo, de prompt ou de fornecedor?

Não. O adaptador coloca o contexto depois das suas instruções e o delta no fim do prompt, nos pontos de extensão que o framework já tem. O seu modelo, o seu prompt e o seu fornecedor continuam os mesmos, e trocar qualquer um deles depois não apaga a memória.

Onde ficam os dados e quanto custa?

Os dados ficam numa região só, informada no contrato, cifrados com AES-256-GCM e chave exclusiva por empresa, protegida em HSM FIPS 140-3. O preço é por conversa ou tarefa em que um agente leu a memória: de US$ 2 a 3 a cada mil, conforme o volume, com leituras, buscas e eventos de sistema incluídos. A Niadra está abrindo para empresas por pedido, antes do lançamento.

Conte o que você está construindo.

E-mail corporativo e duas linhas sobre os seus agentes bastam. Quem responde é quem escreve o código, com uma proposta de acesso antecipado para o seu caso.

Prefere contar mais sobre a sua empresa? Use o formulário completo

Só aceitamos e-mail corporativo. Usamos estes dados apenas para responder ao seu pedido; para apagá-los, peça por este formulário.

O próximo agente já pode chegar sabendo.

A Niadra está abrindo para empresas por pedido, antes do lançamento. Conte o que você está construindo: quem responde é quem escreve o código.