Channels no Microsoft Agent Framework: expondo agentes e workflows em múltiplos protocolos
Os channels no Agent Framework resolvem um problema prático: um agente de IA só gera valor quando as pessoas e os sistemas conseguem alcançá-lo. Esse alcance pode ser um cliente da API de Responses da OpenAI, uma conversa no Telegram, outro agente via A2A ou um cliente MCP.
O time do Microsoft Agent Framework anunciou os channels para agentes e workflows em Python em 26 de agosto de 2026. A proposta é expor o mesmo agente em vários protocolos sem reescrevê-lo, duplicá-lo ou movê-lo para um novo runtime.
Este artigo detalha o desenho dessa funcionalidade, os pacotes envolvidos e o modelo de estado compartilhado. Além disso, analisa as implicações de segurança e o estado atual do recurso no ecossistema .NET.
O problema que os channels no Agent Framework resolvem
O desenvolvimento de agentes tende a criar um acoplamento silencioso entre a definição do agente e o transporte que o expõe. Por exemplo, um agente escrito para um endpoint HTTP compatível com OpenAI raramente vira uma ferramenta MCP sem retrabalho.
O resultado prático é a duplicação. A mesma lógica de instruções, ferramentas e políticas acaba mantida em dois ou três lugares, com SDKs diferentes.
A alternativa comum, adotada por vários frameworks, é oferecer um servidor pronto que hospeda o agente. Essa abordagem funciona bem em demonstrações, mas costuma colidir com a infraestrutura real da empresa.
Afinal, a organização já possui roteamento, autenticação, armazenamento e pipeline de deploy definidos. Por isso, os channels no Agent Framework tomam o caminho oposto: entregam conversores de protocolo e um modelo mínimo de estado, e não um servidor.
Se você ainda está conhecendo o framework, vale começar pela visão geral do Microsoft Agent Framework. Ela apresenta os conceitos de agente e workflow usados ao longo do texto.
Os pacotes dos channels no Agent Framework
A funcionalidade chega dividida em um núcleo compartilhado de hosting e em integrações específicas por protocolo.
agent-framework-hosting: utilitários compartilhados de agente, workflow e estado de sessão.agent-framework-hosting-responses: conversão para a API de Responses da OpenAI.agent-framework-hosting-telegram: tradução de updates e operações do Telegram.agent-framework-hosting-a2a: conexão com os tipos nativos do SDK de A2A.agent-framework-hosting-mcp: exposição de agentes e workflows como ferramentas MCP.
Cada pacote se concentra apenas na fronteira do seu protocolo. Assim, a aplicação continua usando o framework web ou o SDK nativo de sua escolha.
Ela segue dona do roteamento, da autenticação, da autorização, do armazenamento e do deploy. Em outras palavras, os channels no Agent Framework se encaixam na arquitetura existente, em vez de substituí-la.
Todos esses pacotes estão em prerelease. Por isso, a instalação exige a flag explícita, e a documentação recomenda revisar as notas de versão antes de atualizar produção.
pip install --pre agent-framework-hosting
Um alvo compartilhado e um modelo de estado
O núcleo de hosting oferece duas abstrações centrais que todos os channels no Agent Framework consomem. A classe AgentState mantém um alvo do tipo agente junto do seu repositório de sessões.
Já a classe WorkflowState resolve um alvo do tipo workflow a partir de uma instância, de uma fábrica ou de um builder.
from agent_framework_hosting import AgentState, WorkflowState
agent_state = AgentState(agent)
workflow_state = WorkflowState(workflow_builder, cache_target=False)
Com esses dois tipos, handlers e adaptadores resolvem o alvo sempre da mesma forma. O alvo pode vir pronto ou de código de inicialização síncrono ou assíncrono.
Além disso, a aplicação pode manter o alvo em cache ou recriá-lo a cada requisição. O parâmetro cache_target=False merece atenção nesse ponto.
Instâncias de workflow preservam estado de execução. Portanto, aplicações que precisam de chamadas independentes devem fornecer uma fábrica e desabilitar o cache.
A sessão é uma decisão da aplicação
Para agentes, o AgentState mapeia identificadores de sessão escolhidos pela aplicação para valores do tipo AgentSession. No entanto, ele não decide como um usuário do Telegram ou um cliente MCP vira um identificador de sessão.
Esse mapeamento é código de aplicação, e não uma função do framework.
# Identidade e mapeamento de sessão definidos pela aplicação.
session_id = resolve_session_id(authenticated_user, channel_identity)
session = await agent_state.get_or_create_session(session_id)
É esse mapeamento que permite continuar uma conversa entre channels diferentes no Agent Framework. Se o mesmo usuário resolver para o mesmo identificador vindo de Responses e do Telegram, os dois canais compartilham a mesma AgentSession.
Se os identificadores forem distintos, os históricos ficam separados. Assim, a aplicação detém a vinculação de identidade, a autorização e os controles de concorrência das sessões compartilhadas.
Workflows seguem o mesmo modelo por meio do WorkflowState. Nesse caso, os checkpoints e o mapeamento entre continuação e checkpoint também ficam com a aplicação.
SessionStore e HistoryProvider
O SessionStore é uma classe assíncrona simples, com os métodos get, set e delete. Sua implementação padrão guarda as sessões na memória do processo, sem política de expiração.
A documentação recomenda herdar dessa classe para persistir sessões em Redis, banco de dados ou blob storage. Depois, basta passar a instância ao AgentState pelo parâmetro session_store.
Também existe uma distinção entre o repositório de sessões e o provedor de histórico. O primeiro grava um objeto por sessão, com metadados e estado de provedores.
Já um HistoryProvider dedicado armazena a conversa separadamente, em geral com um registro por mensagem. Essa separação ajuda hosts duráveis, porque anexar mensagens costuma custar menos do que reescrever uma sessão que cresce a cada turno.
O artigo sobre memória e provedores de contexto no Agent Framework aprofunda esse tema.
Channel de OpenAI Responses no Agent Framework
Entre os channels no Agent Framework, os helpers de Responses convertem a requisição de entrada em valores de execução. Em seguida, convertem o resultado, completo ou em streaming, de volta ao formato da API.
from agent_framework_hosting_responses import (
create_response_id,
responses_from_run,
responses_session_id,
responses_to_run,
)
run = responses_to_run(body)
session_id, is_conversation = responses_session_id(body)
response_id = create_response_id()
session = await agent_state.get_or_create_session(session_id or response_id)
result = await (await agent_state.get_target()).run(
run["messages"],
session=session,
options=run["options"],
)
await agent_state.set_session(session_id if is_conversation else response_id, session)
response = responses_from_run(
result,
response_id=response_id,
conversation_id=session_id if is_conversation else None,
)
A aplicação decide como identificadores de resposta e de conversa viram sessões. Ela também define quais opções o chamador controla, quando usar streaming e onde guardar o estado.
O exemplo oficial usa uma lista de permissão explícita de opções. Dessa forma, nega por padrão ferramentas, escolha de ferramentas e campos de persistência enviados pelo cliente.
Uso de tokens e workflows no Responses
Há um detalhe relevante na conversão de uso de tokens. Quando existe um objeto nativo de uso da OpenAI, o pacote o preserva sem misturá-lo aos campos do framework.
Quando não existe, o pacote reconstrói os valores a partir de campos equivalentes. Entre eles estão tokens de entrada, de saída, de cache e de raciocínio.
Se as informações forem incompletas ou inconsistentes com o esquema, o pacote simplesmente omite o bloco de uso. Ou seja, ele não adivinha valores nem derruba uma resposta válida.
Workflows também podem usar a interface de Responses. Em vez de uma AgentSession, a aplicação mapeia identificadores de resposta para checkpoints do workflow.
Channel do Telegram no Agent Framework
Os helpers do Telegram traduzem updates nativos para entrada do framework. Além disso, transformam uma execução em streaming em operações da Bot API.
O pacote não traz cliente de bot, polling, roteador de webhook nem registro de comandos. A aplicação executa as operações com chamadas HTTP diretas ou com SDKs como aiogram e python-telegram-bot.
Comandos, autenticação de webhook, mídia e política de entrega continuam sendo código comum da aplicação. Nesse sentido, o channel do Telegram no Agent Framework só cuida da tradução entre os dois mundos.
O exemplo oficial mostra cuidados raros em amostras introdutórias. Primeiro, serializa o processamento por chat com um lock assíncrono, para que um reinício não apague a sessão durante uma resposta.
Depois, aplica um intervalo mínimo entre edições de mensagem no streaming, por causa dos limites de taxa da plataforma. Por fim, persiste a sessão só depois que o stream termina e o histórico registra o turno.
A documentação também faz um alerta sobre autorização. Um segredo de webhook autentica a entrega do Telegram, mas não autoriza o usuário a acessar dados da aplicação.
Channels A2A e MCP no Agent Framework
Os dois últimos channels no Agent Framework atendem cenários diferentes. O A2A conecta agentes entre si, enquanto o MCP permite que um cliente use o agente como ferramenta.
O canal A2A
Para A2A, as classes AgentA2AAdapter e WorkflowA2AAdapter geram cartões de agente nativos. Elas também mantêm os modos de entrada e saída alinhados com os helpers de conversão.
A aplicação continua responsável pelo executor, pelo ciclo de vida das tarefas, pela fila de eventos e pelas rotas. Para revisar o protocolo, consulte o artigo sobre comunicação entre agentes com A2A.
Existem dois pacotes para A2A. O agent-framework-a2a traz um executor opinativo que converte requisições, executa o agente e publica eventos.
Já o agent-framework-hosting-a2a oferece blocos incrementais para um executor da própria aplicação. Ele serve quando é preciso controlar sessões, transições de tarefa ou hospedar vários protocolos no mesmo processo.
O canal MCP
Para MCP, as classes AgentMCPTool e WorkflowMCPTool derivam ferramentas nativas dos alvos do framework. A aplicação também pode usar funções de conversão de nível mais baixo com um servidor como FastMCP.
A AgentMCPTool deriva nome, descrição e esquema da ferramenta a partir do próprio agente. Com isso, listagem, execução e conversão de resultado não divergem com o tempo.
A continuidade de sessão em MCP também é possível, com um AgentState e um parâmetro de sessão. Contudo, autenticar esse identificador e serializar chamadas concorrentes continua sendo tarefa da aplicação.
Combinando channels no Agent Framework
Com os channels no Agent Framework, o mesmo agente ou workflow pode servir a mais de um protocolo. Cada canal mantém suas regras de autorização e instruções de apresentação, mas compartilha o alvo e a infraestrutura.
O desenvolvedor define o resolvedor que transforma uma identidade de canal em identificador de sessão. Com um resolvedor unificado, o usuário começa em um cliente de Responses e continua no Telegram.
Por outro lado, também é possível manter identidades de canal em namespaces separados. A decisão, mais uma vez, fica com quem constrói a aplicação.
A flexibilidade dos channels no Agent Framework se estende ao framework web. Os exemplos usam FastAPI, mas os helpers atuam apenas na conversão de protocolo e no estado de execução.
Por isso, eles funcionam com Django, Flask, Starlette, Azure Functions ou um serviço existente. Segundo a documentação, FastAPI e aiogram aparecem nas amostras apenas por concisão.
Segurança de sessão nos channels do Agent Framework
A documentação de self-hosting do Agent Framework traz uma orientação direta. Todo identificador fornecido por um protocolo é entrada não confiável.
Antes de usar um identificador para carregar sessão, checkpoint ou tarefa, a aplicação que usa channels no Agent Framework deve seguir quatro passos.
- Autenticar o chamador.
- Autorizar o acesso ao estado referenciado.
- Particionar o estado durável por tenant, usuário ou workspace.
- Persistir sessão e checkpoint só após o fim da execução.
Um identificador de continuação aponta a sessão a retomar, mas não prova que o chamador é o dono dela. Essa distinção explica uma classe inteira de vulnerabilidades em hosts de agentes.
Além disso, os repositórios padrão de tarefas do SDK de A2A ficam em memória e definem a posse pelo nome de usuário. Em serviços multi-tenant, a orientação é derivar a posse da identidade confiável e usar repositórios duráveis.
Channels no Agent Framework para .NET
Para quem trabalha com .NET, a leitura pede atenção. Neste momento, os channels no Agent Framework descritos no anúncio existem apenas na versão Python.
O lado .NET possui o pacote Microsoft.Agents.AI.Hosting, também em prerelease, que integra agentes ao host genérico. Ele oferece AddAIAgent, AddWorkflow e AgentSessionStore para registrar agentes, workflows e sessões.
Os protocolos disponíveis hoje em .NET são endpoints compatíveis com OpenAI, A2A e AG-UI. A documentação avisa que os helpers de Responses, Telegram e MCP para .NET ainda estão por vir.
O exemplo abaixo, baseado na documentação oficial, expõe um agente por meio de um endpoint de Responses no ASP.NET Core.
using Microsoft.Agents.AI.Hosting;
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
// Registra o agente nomeado na injeção de dependência
var hostedAgent = builder.AddAIAgent("weather-agent", (_, _) => agent);
WebApplication app = builder.Build();
// Expõe o agente por meio de um endpoint compatível com Responses
app.MapOpenAIResponses(hostedAgent);
app.Run();
Para mais detalhes, veja o artigo sobre como publicar agents no ASP.NET.
Isolamento de sessões no .NET
A plataforma .NET traz um cuidado adicional. O IsolationKeyScopedAgentSessionStore combina uma chave de isolamento com o identificador de continuação antes de acessar o repositório.
Assim, o mesmo identificador sob duas chaves diferentes resolve para duas sessões diferentes. Em aplicações com autenticação baseada em claims, o pacote Microsoft.Agents.AI.Hosting.AspNetCore fornece esse provedor.
// Isola as sessões pela claim NameIdentifier do usuário autenticado
builder.Services.AddHttpContextAccessor();
builder.Services.UseClaimsBasedAgentIsolation();
Também vale saber que o framework não inclui um repositório durável de sessões de uso geral. Portanto, a persistência fica com quem constrói a aplicação, em Python e em .NET.
Conclusão
A decisão mais significativa dos channels no Agent Framework não é técnica, e sim de escopo. O framework escolheu não ser o servidor.
Os pacotes de hosting entregam conversores de protocolo e um estado mínimo de execução. O resto, como identidade, autorização, armazenamento e implantação, fica nas mãos de quem já resolveu isso à sua maneira.
O custo dessa escolha nos channels do Agent Framework é evidente. É preciso escrever mais código, inclusive código de segurança que outros frameworks entregariam pronto.
O benefício também é evidente. A definição do agente fica independente dos canais, e um novo protocolo deixa de exigir uma segunda implementação.
Para equipes com infraestrutura madura, essa divisão de responsabilidades provavelmente é a correta. Já quem busca um caminho mais curto pode usar Foundry Hosted Agents ou a extensão durável em Azure Functions.
O time da Microsoft sinalizou que pretende ampliar os canais e helpers. Para isso, abriu uma issue pública para receber cenários ainda sem cobertura.
FAQ
Os channels estão disponíveis para .NET?
Não neste momento, porque o anúncio cobre a versão Python do Agent Framework. O .NET possui o pacote Microsoft.Agents.AI.Hosting com endpoints compatíveis com OpenAI, A2A e AG-UI, e os helpers de Responses, Telegram e MCP ainda estão por vir.
Preciso usar FastAPI para trabalhar com os pacotes de hosting?
Não. Os exemplos usam FastAPI por concisão, mas os helpers funcionam com Django, Flask, Starlette, Azure Functions ou qualquer outro framework.
Os pacotes já podem ser usados em produção?
Todos os pacotes de hosting citados estão em prerelease, tanto em Python quanto em .NET. A recomendação oficial é instalar com a flag de prerelease e revisar as notas de versão antes de qualquer atualização em produção.
Como faço para que a mesma conversa continue entre Telegram e um cliente de Responses?
É necessário implementar um resolvedor que mapeie a identidade de cada canal para um mesmo identificador canônico de sessão. O framework não faz esse mapeamento automaticamente, para que a aplicação controle a vinculação de identidade e a autorização.
O framework oferece armazenamento durável de sessões?
Não de uso geral. Em Python, o SessionStore padrão fica em memória e sem expiração, e o equivalente em .NET também é em memória, então a persistência durável cabe à aplicação.
Qual a diferença entre agent-framework-a2a e agent-framework-hosting-a2a?
O primeiro traz um executor opinativo que já implementa conversão, execução e publicação de eventos. O segundo oferece blocos incrementais para quando a aplicação precisa controlar sessões, tarefas, eventos ou hospedar vários protocolos.
Workflows podem ser expostos nos mesmos canais que agentes?
Sim, existem contrapartes como WorkflowState, WorkflowA2AAdapter e WorkflowMCPTool. A diferença principal é que checkpoints e continuação com intervenção humana permanecem responsabilidade da aplicação.