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.
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())npm install @niadra/sdk @openai/agents # @openai/agents 0.18, as an optional peer dependencyimport { Agent, Runner } from "@openai/agents";
import { Niadra, handles } from "@niadra/sdk";
import { NiadraSession, niadraInstructions, niadraRunHooks, niadraTools } from "@niadra/sdk/openai-agents";
const niadra = new Niadra();
const runner = new Runner();
/** One customer message in; `userId` comes from your session, never from the model. */
export async function reply(userId: string, chatId: string, text: string): Promise<string> {
const convo = niadra.conversation({ subject: handles.appUserId(userId), channel: "web_chat", conversation_id: chatId });
const billing = new Agent({ name: "Billing", instructions: niadraInstructions("You handle invoices and credits.", convo), tools: niadraTools(convo) });
const support = new Agent({
name: "Support",
instructions: niadraInstructions("You are Acme's support agent. Hand billing questions to Billing.", convo),
tools: niadraTools(convo),
handoffs: [billing],
});
const stop = niadraRunHooks(runner, convo);
try {
const result = await runner.run(support, text, { session: new NiadraSession(convo) });
return String(result.finalOutput ?? "");
} finally {
stop();
}
}- 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