Canais HTTP para Deep Agents gerenciados

Autoria: LangChain · Assistir no YouTube

Vídeo de autoria do canal indicado, não da IANIA; todos os direitos pertencem ao criador. Transcrição, resumo e tradução gerados automaticamente; o conteúdo no idioma original é preservado na versão em idioma original.

Idioma original: inglês

Vídeo original: HTTP Channels for Managed Deep Agents · Canal: LangChain · 07:58 · Assistir no YouTube

Tópicos: Agentes de IA, Automação de tarefas e workflows, Ferramentas de desenvolvimento com IA

Resumo

O vídeo apresenta como criar canais HTTP personalizados para receber eventos de serviços externos e conectar esses eventos a um agent gerenciado. O exemplo constrói um agent de despesas chamado Reflex, que recebe recibos por iMessage usando Photon, verifica e interpreta as mensagens e mantém os dados em memória durável. O tutorial também mostra como gerenciar threads e enviar respostas de volta ao provedor do canal. Por fim, demonstra o deploy, o rastreamento das execuções no LangSmith e o armazenamento das despesas no Context Hub.

Pontos-chave

Canais HTTP são úteis para receber eventos de serviços externos ou de provedores sem um canal integrado.
O agent deve verificar a segurança das solicitações recebidas e interpretar o conteúdo dos eventos.
O exemplo usa Photon para conectar o agent a mensagens por iMessage.
Um parser extrai texto e imagens das mensagens para que o agent possa processá-los.
O ID da thread permite associar mensagens de um mesmo usuário ao contexto correto ao longo do tempo.
Um post hook envia as respostas do agent de volta ao provedor do canal.
O agent analisa recibos e armazena as informações extraídas em memória durável no Context Hub.
Em cenários com vários usuários, é necessário implementar autorização e separar adequadamente os dados.
Canais HTTP podem ser combinados com canais integrados, como Slack; para uma interface personalizada, o vídeo recomenda o LangGraph SDK.

Capítulos

Início	Capítulo	Resumo
00:00	Canais HTTP e estrutura do exemplo	Nathan apresenta os usos dos canais HTTP personalizados e descreve o agent de triagem de recibos que será construído.
02:07	Memória e integração com Photon	O tutorial configura memória durável e inicia a integração com Photon, incluindo as funções de verificação e parsing.
04:12	Parsing, threads e respostas	O agent extrai o conteúdo das mensagens, associa usuários a threads e envia respostas pelo provedor do canal.
06:25	Deploy e processamento de recibos	O agent recebe um recibo, extrai e armazena seus dados, que podem ser consultados depois no Context Hub.
07:25	Uso em produção e conclusão	O vídeo destaca a necessidade de autorização para vários usuários e resume como combinar canais HTTP com outras interfaces.

Citações

Você vai querer usar um canal HTTP personalizado sempre que precisar receber solicitações que não controla. — 00:00

O parser recebe um evento e interpreta o JSON que vem com esse evento. — 03:42

O ID da thread é crucial e importante para a experiência do usuário do seu agent. — 04:12

Você precisa interpretar o formato do evento e verificar se ele foi transmitido com segurança. — 07:58

Conceitos e entidades

HTTP channels (conceito): Canais personalizados que recebem eventos de serviços externos e os encaminham a um agent.
Managed Deep Agents (conceito): Agents gerenciados que podem ser conectados a canais personalizados por HTTP.
Photon (ferramenta): Serviço usado no exemplo para conectar o agent a mensagens por iMessage e enviar solicitações por webhooks.
LangChain (empresa): Empresa responsável pelo vídeo e pela plataforma apresentada.
LangSmith (ferramenta): Plataforma em que é possível inspecionar o agent e acompanhar traces das execuções.
Context Hub (ferramenta): Camada usada no exemplo para armazenar arquivos de memória durável, incluindo os registros de despesas.
LangGraph SDK (ferramenta): SDK recomendado no vídeo para criar uma interface personalizada para o agent.
durable memory (conceito): Memória persistente usada pelo agent para guardar dados e recuperá-los em interações futuras.
Reflex (conceito): Nome do agent de registro e triagem de despesas construído como exemplo.
Nathan (pessoa): Apresentador do vídeo e gerente de produto na LangChain.

Tradução completa (pt-BR)

00:00 Olá, sou Nathan. Sou gerente de produto aqui na LangChain, e hoje vamos falar sobre canais personalizados para agentes profundos gerenciados por HTTP. Você vai querer usar um canal HTTP personalizado sempre que quiser receber solicitações direcionadas ao seu agent que não controla, ou para serviços para os quais ainda não temos canais integrados. Hoje, isso inclui o Slack. Pense, por exemplo, em solicitações de um serviço externo como HubSpot ou Salesforce, ou em serviços personalizados para gerenciar conexões por RCS, WhatsApp ou iMessage, como Photon ou Twilio. Hoje vamos criar um exemplo de um agent que pode fazer a triagem de recibos: quando eu enviar despesas, o agent poderá armazená-las

00:31 com segurança usando memória durável. Essencialmente, a estrutura do nosso projeto será como costuma ser: definimos nosso agent e adicionamos um canal personalizado. Você declara o canal com uma configuração básica e precisa fornecer suas próprias funções para verificar e analisar qualquer mensagem recebida. Assim, quando o serviço externo enviar uma mensagem, isso criará uma execução para o seu agent, mas o agent precisa cuidar da verificação para garantir que a mensagem foi enviada com segurança e da análise para extrair os dados relevantes necessários para que o agent possa processá-la e criar uma resposta adequada.

01:04 Então, vamos montar a estrutura do nosso agent. Criei um agent, neste caso usando TypeScript, mas, se você estiver acompanhando em Python, os conceitos básicos são praticamente os mesmos. A primeira coisa que queremos fazer é adicionar nosso próprio conjunto de instruções. Este agent vai se chamar Reflex. É um agent de prestação de contas de despesas. Temos algumas políticas codificadas em nosso arquivo instructions.md. Também estamos dizendo que nosso livro-razão será armazenado na memória. Hoje vamos usar memória durável para armazenar o livro-razão, mas, em um caso de uso de produção, você talvez use um serviço externo para armazenar o livro-razão entre

01:36 muitos usuários que interagem com ele. Vamos testar nosso agent apenas com estas instruções e ver como funciona. Podemos conversar com ele por esta interface de terminal. Vamos perguntar o que ele pode fazer. Certo, ótimo. As instruções surtiram efeito. E o agent consegue responder a perguntas básicas sobre as políticas. Para distribuir isso, queremos que seja um agent de mensagens de texto; não queremos que as pessoas interajam com ele pelo terminal. Mas, para começar, isso nos dá uma ideia de como estamos gerenciando a personalidade e os controles básicos dentro deste agent. Agora que configuramos nosso arquivo de instruções, vamos adicionar a memória

02:07 Certo, criei o arquivo de memória e vamos adicionar a definição da memória. Neste caso, é uma configuração de memória durável bem simples, na qual o agent tem acesso à camada de memória e poderá armazenar arquivos no Context Hub usando isso. Certo, vamos começar a adicionar nosso canal. Vamos começar adicionando nosso verificador e nosso analisador. Hoje, vamos usar o Photon como canal. O Photon é um sistema simples que nos permite conectar por SMS, iMessage, WhatsApp ou outros sistemas. No meu painel do Photon, configurei um projeto chamado Reflex para

02:39 o agent que vou criar. Ele será distribuído pelo iMessage. Neste caso, é privado e só eu posso acessá-lo, e vamos enviar solicitações de volta ao Photon usando webhooks. Assim, quando o agent responder, vamos acionar um webhook, permitindo que o usuário receba uma mensagem de texto do nosso agent. Aqui estamos configurando, como vimos na documentação, nossas funções de verificação e análise, que vamos criar. É isso que o agente profundo gerenciado vai usar para se comunicar com este canal ou receber eventos dele

03:10 Então, a primeira coisa de que precisamos para esta implementação é um cliente. Vamos adicionar nosso cliente Photon, que nos permitirá interagir com o Photon. Cada conexão que você criar pode ter uma configuração um pouco diferente, dependendo do que o provedor recomenda e de como esperamos que ela funcione. Vamos adicionar nosso verificador e nosso analisador. Primeiro, vamos adicionar o verificador. Vamos colocá-lo neste arquivo Photon, que estamos referenciando aqui. No verificador, recebemos bytes brutos e garantimos que esta seja uma solicitação válida.

03:42 Em seguida, vamos adicionar nosso analisador. O analisador terá uma aparência diferente dependendo do canal. Ele recebe um evento e analisa o JSON que vem desse evento. Em praticamente todos os casos, o JSON terá uma aparência um pouco diferente. O que você vai querer fazer é extrair as partes relevantes da resposta JSON e passá-las ao seu agent. Aqui temos um tratamento de erros gerenciado neste trecho. Vamos extrair nosso conteúdo, que poderá ser texto recebido pelas mensagens de texto ou imagens recebidas pelas mensagens de texto, e

04:12 depois vamos passá-lo ao nosso agent e retorná-lo como uma mensagem do tipo message, para que o agent possa responder. Certo, agora que configuramos o básico para as mensagens recebidas, vamos garantir que o gerenciamento das conversas esteja configurado. Ao analisar a solicitação, o ID da conversa é crucial e será importante para a experiência do usuário com seu agent. É assim que você controla quando uma nova conversa é criada ou quando uma conversa é encerrada. Aqui, vamos identificar os usuários pela mensagem de texto recebida. Então, podemos transformar o número de telefone da mensagem de texto em hash para gerar um UUID que possamos usar para associá-lo a uma conversa e acompanhar as interações por um período mais longo.

04:46 Assim, se um usuário enviar mensagens de texto ao nosso agent por um período mais longo, todas essas solicitações serão gerenciadas na mesma conversa, e o agent poderá manter o contexto das mensagens que já foram enviadas. Por exemplo, se eu enviar o mesmo recibo duas vezes. Vamos adicionar esse manipulador para transformar nossos números de telefone em hashes e gerar UUIDs. Ao fazer isso, a implementação pode variar um pouco dependendo da sua função de hash. Talvez você queira reiniciar a conversa todos os dias, ou permitir que o usuário reinicie a conversa com determinados comandos.

05:20 Você pode controlar isso dependendo de como configura o ID da conversa e de como o reinicia enquanto o usuário interage com o agent ao longo do tempo. Em nosso agent, também queremos enviar respostas. Quando um usuário envia um recibo ou faz uma pergunta sobre as políticas, queremos garantir que consigamos responder a esse usuário. Então, vamos incluir também um post hook. Com o post, podemos enviar a resposta de volta ao provedor do canal, neste caso o Photon, e então o Photon pode cuidar do restante — neste caso, enviar a mensagem de texto propriamente dita

05:52 Certo, vamos adicionar nossa lógica de post ao arquivo Photon. Ela foi adicionada e, mais uma vez, a lógica de post pode variar dependendo do seu provedor. Agora queremos adicioná-la à definição do canal. Certo, tudo parece bem. Agora nosso agent poderá receber mensagens do Photon e enviar mensagens de volta ao Photon depois de processá-las com a lógica fornecida. Quando recebermos uma mensagem, vamos extrair a imagem e o texto. O agent vai inspecionar a imagem e, com base nas instruções,

06:25 vai extrair informações específicas e, depois, armazená-las na memória durável. Assim, teremos um agent capaz de receber recibos, fazer a triagem deles e armazená-los de uma forma que poderá ser reutilizada mais tarde. Certo, vamos fazer o deploy. Depois, veremos como o agent funciona. Vamos enviar uma mensagem ao agent dizendo que temos um recibo para lançar como despesa. O Photon vai receber a solicitação, encaminhá-la para o deploy do LangSmith, e nosso servidor do agent poderá responder. Ele vai dizer que quer receber o recibo. Podemos encaminhá-lo.

06:55 Vamos enviar a foto. O agent vai iniciar automaticamente um sandbox, extrair os dados de que precisa, nos dar a resposta necessária e armazená-la na memória. Se acessarmos o LangSmith, veremos o agent e o conjunto de execuções que ocorreram. Elas são rastreadas aqui, então posso dar uma olhada mais detalhada nas interações por mensagem de texto dentro do portal do LangSmith. Mas também podemos ver no nosso Context Hub, na memória específica deste agent, que ele escreveu no arquivo de despesas aqui. Então, ele criou uma tabela em Markdown com todas as despesas que enviei,

07:25 incluindo aquela que acabamos de enviar por mensagem de texto. Aqui está. Então, se um usuário perguntar mais tarde sobre as despesas que enviou, o agent poderá buscar esses dados no Context Hub e retorná-los usando memória durável. Mais uma vez, se você estiver criando isso em produção com vários participantes e muitos usuários, precisará adicionar autorização para que recibos diferentes sejam armazenados em locais diferentes, dependendo do usuário que os enviou, ou para que os recibos sejam armazenados em um serviço externo. Essa foi uma introdução rápida aos canais HTTP. Você pode usá-los para lidar com eventos recebidos pelo seu agent de qualquer serviço externo, não apenas dos que já vêm prontos.

07:58 Você também pode combinar canais HTTP com alguns dos canais já prontos, como o Slack, para que os usuários tenham várias interfaces pelas quais possam interagir com seu agent. Se estiver criando uma interface personalizada para seu agent, provavelmente vai querer usar o LangGraph SDK. Em geral, canais HTTP são sempre para eventos sobre os quais você não tem controle, enviados por um serviço externo. Você precisa lidar com o formato do evento, analisá-lo e verificar o evento para garantir que ele seja transmitido com segurança. É isso por hoje. Até a próxima.

Transcrição original

[00:00] Hey, I’m Nathan. I’m a product manager here at LangChain, and today we’re talking about custom channels for managed deep agents over HTTP. You’re going to want to use a custom HTTP channel anytime you want inbound requests to your agent that you don’t control, or for services where we don’t yet have built-in channels. Today, this includes Slack. Think, for example, requests from an external service like HubSpot or Salesforce, or custom services to manage connections through RCS, WhatsApp, or iMessage, like Photon or Twilio. Today we’re gonna build an example of an agent that can handle receipt triage, where when I send in expenses, the agent can store them

[00:31] securely using durable memory. Essentially our project structure is gonna look as it usually does, where we define our agent, and we’re gonna add a custom channel in there. You declare the channel with a basic setup, and you need to provide your own functions to verify and parse any of the inbound messages. So when the external service sends a message, this will create a run for your agent, but your agent needs to handle the verification to ensure that the message is sent securely, and the parsing to pull out the relevant data that the agent needs to actually process in order to create a reasonable response.

[01:04] So let’s scaffold our agent out. I’ve created an agent, in this case, using TypeScript, but if you’re following along on Python, it’s overall the same basic concepts. the first thing we wanna do is add our own instruction set. So this agent is gonna be called Reflex. It’s an expense reporting agent. We have some policy that’s encoded in our instructions.md. And then we’re saying also our ledger is gonna be stored in memory. Today we’re gonna use durable memory to store the ledger, but in a production use case, you might use an external service in order to store the ledger across

[01:36] many users that are interacting with it. let’s try out our agent with just these instructions and see how it works. We can chat with it in the terminal interface here. Let’s ask what it can do All right, sweet. So the instructions took effect. And the agent can answer basic questions about the policy. To distribute this, we want this to be a text message agent, we don’t want people interacting with this from the terminal. But just to get started, this gives us a sense of how we’re managing the personality and basic levers inside of this agent. Now that we have our instructions file set up, let’s add in our memory

[02:07] All right, so I’ve created the memory file, and we’re gonna add in our memory definition. In this case, it’s a very simple durable memory setup where the agent has access to the memory layer, and it’s gonna be able to store files in Context Hub using this Okay, so let’s start adding our channel. We’ll start by adding our verifier and our parser. And today, we’re gonna be using Photon as the channel. Photon is a simple system to allow us to connect using SMS or iMessage or WhatsApp or other systems. So in my Photon dashboard, I’ve set up a project here called Reflex for

[02:39] the agent that I’ll be building. This is gonna be distributed in iMessage. In this case, it’s private to only me, and we’re going to send requests back to Photon using webhooks. So when the agent responds, we’ll invoke a webhook, and this will allow the user to receive a text from our agent So here we’re setting up, just like we saw in the docs, our verify and our parsing function, which we’re going to build. And this is what the managed deep agent is gonna use to communicate or receive events from this channel

[03:10] So the first thing that we need in the case of this implementation is a client. So we’re gonna add in our Photon client, which is going to allow us to interact with Photon. Every connection you create may have a slightly different configuration depending on what the provider recommends and how we expect it to work Let’s add our verifier and our parser So first we’ll add in the verifier. We’re gonna put it in this Photon file, which we’re referencing from over here. In the verifier we’re receiving raw bytes and we’re ensuring that this is a valid request.

[03:42] Next, we’ll add in our parser The parser is gonna look different depending on what your channel is. The parser takes in an event and parses the JSON that comes from this event. And in pretty much any case, the JSON is gonna look a little bit different. What you’re gonna wanna do is pull out the relevant parts of the JSON response and pass that through to your agent. So here we have some error handling that’s managed in here. We’re gonna pull out our content, which is either gonna be text that’s coming in from the text messages or images that’s coming in from the text messages, and

[04:12] then we’re going to pass that through to our agent, and we’ll return this as type message so that the agent can respond. Okay, so now that the basics are configured for inbound messages, we’re gonna make sure that our threading is managed So when you’re parsing the request, the thread ID is pretty crucial, and this is gonna be important for the user experience of your agent. This is how you control when a new thread is created, or when a thread is destroyed. And here we’re gonna identify users by the inbound text message. So what we can do is we can hash the text message phone number into

[04:46] a UUID that we can use to match that to a thread and keep track of things over a longer period of time. So if a user is texting our agent over a longer period of time, then all of those requests are managed in the same thread, and the agent will be able to keep track in context of messages that have already been sent. For example, if I send the same receipt twice. Let’s add that handler in order to hash our phone numbers into UUIDs When you’re doing this, it may look a little different depending on your hashing function. Maybe you want to reset the thread every day, or you wanna give the user the ability to reset their thread with certain commands.

[05:20] You can control that depending on how you set up the thread ID and how you reset the thread ID when a user is interacting with the agent over time In our agent, we also want to send replies. When a user sends in a receipt or asks a question about the policy, we wanna make sure that we’re able to actually respond successfully to that user. So we’re gonna include a post hook as well. With post, we can send the response back to the channel provider, in this case Photon, and then Photon can handle the rest, in this case, sending out the actual text message

[05:52] All right, so we’ll add our post logic into our Photon file here. This is added in, and again, the post logic might look different depending on your provider. Now we wanna add that to the channel definition. Okay, so things look good. Now our agent is going to be able to take in messages from Photon and send out messages back to Photon after handling them using the logic provided. When we receive a message, we’re going to pull out the image and the text. The agent is going to inspect the image, and based on its instructions,

[06:25] it will pull out specific information, and then it will store that information in durable memory. So we end up with an agent that’s going to be able to take in receipts, triage them, and store them in a way that will be reusable later. All right, so let’s get this deployed And then we’ll take a look at how the agent works Let’s text the agent that we have a receipt to expense. Photon will receive the request, pass that on to the LangSmith deployment, and our agent server can respond. It’ll say it wants the receipt. We can pass that on.

[06:55] We’ll send the photo. The agent will automatically spin up a sandbox, pull out the data it needs, and give us the response we need, and store it to memory. If we go into LangSmith, we can see the agent and the set of runs that happened, and these are traced here, so I could take a deeper look at the text message interactions from within the LangSmith portal. But we can also see in our Context Hub, in the specific memory of this agent, that it’s written to the expenses file here. So it’s created a table in Markdown that creates all of the expenses that I sent,

[07:25] including the one that we just texted. Here it is. So if a user asks later on about the expenses that they’ve sent, then the agent can pull that data from Context Hub and return that back to them using durable memory. Again, if you’re building this in production with multiplayer and many users, you’re gonna need to add in authorization so that different receipts are stored in different places depending on the user that sent them, or receipts are stored in an external service. That’s a quick intro to HTTP channels. You can use these to handle inbound events to your agent from any external service, rather than just the ones that are pre-built.

[07:58] You can also combine HTTP channels with some of the pre-built channels like Slack, so users have multiple interfaces with which they can interact with your agent. If you’re building a custom UI for your agent, you’re probably gonna wanna stick with the LangGraph SDK. In general, HTTP channels are always for events that you don’t have control over, where it’s sent by an external service. You need to handle the shape of the event, you need to handle parsing it out, and you need to handle verifying the event in order to ensure that it’s securely transmitted. That’s it for today. See you next time.