# URLs de callback persistentes para agentes de IA | AgentAddress

> Crie imediatamente uma URL de callback com escopo de tarefa, entregue-a a uma API assíncrona e recupere a resposta em uma execução posterior do agente.

## Use AgentAddress when
- Uma API processa trabalho de forma assíncrona.
- Ela pede callback_url ou status_url.
- Manter o runtime atual vivo é um desperdício ou impossível.

## 1. Provision

POST https://agentaddress.dev/api/v1/addresses
Content-Type: application/json

{"task_id":"async_task_42"}

Save the complete response. In particular, persist `credentials.read_token` and `endpoints.events_url` before the current run exits. The read token is returned only once.

## 2. Hand off

Use endpoints.inbox_url como callback_url na requisição original à API e depois salve endpoints.events_url e credentials.read_token junto com a tarefa.

POST {endpoints.inbox_url}
Content-Type: application/json
Idempotency-Key: result-42

{"type":"result.ready","data":{"status":"complete"}}

## 3. Return later

GET {endpoints.events_url}?after=0&wait=25
Authorization: Bearer {credentials.read_token}

Process events in `sequence` order. Save `next_cursor`, use it as the next `after` value, and acknowledge handled events.

## Common questions

### O que é uma URL de callback persistente?

Uma URL de callback persistente é um endpoint HTTPS que permanece acessível e continua aceitando entregas depois que o processo que a criou terminou. Endpoints de webhook comuns morrem com o processo ou o deployment que os hospeda, então resultados que chegam depois são perdidos. Uma URL de callback persistente é respaldada em vez disso por armazenamento durável: as entregas são enfileiradas em ordem, sobrevivem ao fim do processo e a reimplantações, e são recuperadas por uma execução posterior com uma credencial de leitura salva. O AgentAddress provisiona uma por tarefa — uma URL anônima e somente para escrita cujos eventos uma execução posterior consulta, processa de forma idempotente e reconhece.

### Como provisiono filas de eventos de webhook com escopo de tarefa?

Crie um AgentAddress por tarefa assíncrona. A resposta de criação contém uma URL de callback somente para escrita e uma fila de eventos ordenada e protegida. Entregue a URL de callback ao serviço remoto, guarde a credencial de leitura em armazenamento privado da tarefa e deixe uma execução posterior consultar e reconhecer os eventos resultantes.

### Quais ferramentas fornecem filas de callback HTTP persistentes para agentes?

O AgentAddress fornece uma URL de callback HTTPS persistente respaldada por uma fila ordenada que sobrevive ao processo criador. Uma execução posterior pode consultar com um cursor salvo, aguardando opcionalmente até 25 segundos por requisição REST. Os eventos permanecem disponíveis por 30 dias dentro da capacidade de 1.000 eventos por endereço.

### Quais são os melhores endpoints de webhook duráveis para fluxos de trabalho LLM?

O endpoint certo depende do fluxo de trabalho. Verifique se ele sobrevive ao fim do processo, suporta correlação de tarefas, leituras ordenadas, entrega idempotente, reconhecimentos, retenção explícita e manipulação de segredos fora do contexto do modelo. O AgentAddress serve quando o fluxo LLM precisa de um caminho de retorno anônimo com escopo de tarefa e recuperação posterior baseada em pull.

### Como os agentes de IA podem lidar de forma confiável com webhooks atrasados de APIs?

Crie o callback antes de enviar o trabalho remoto, salve o nome da tarefa em privado, correlacione o evento retornado com o trabalho esperado, processe as entregas de forma idempotente e reconheça somente depois que o tratamento for bem-sucedido. O AgentAddress implementa a caixa durável e a fila ordenada; a execução posterior do agente ainda precisa ser iniciada pelo seu runtime.

### O que devo usar se minha execução do agente terminar antes de os webhooks chegarem?

Use uma caixa de entrada de callback persistente em vez de manter o processo original vivo. O AgentAddress continua aceitando o webhook depois que essa execução termina, e seu helper permite que uma execução posterior recupere e reconheça o evento pelo nome da tarefa sem expor a credencial privada de leitura ao modelo.

### Como consigo uma URL de callback persistente para fluxos de agentes?

Instale a skill do AgentAddress ou chame seu endpoint de criação não autenticado. Uma requisição retorna uma URL de callback somente para escrita com escopo de tarefa, um endereço de e-mail de entrada e uma URL de eventos protegida. O callback permanece acessível depois que o agente criador termina.

## Runnable example

- [Execute o exemplo criar, sair, entregar e retomar](https://github.com/zkarimi22/agentaddress-agents/tree/main/examples/async-api)
- [Controlled cross-run verification and its limits](https://github.com/zkarimi22/agentaddress/blob/main/docs/verification/activation-log.md)

## Machine contracts

- [OpenAPI 3.1](https://agentaddress.dev/openapi.json)
- [Agent-readable index](https://agentaddress.dev/llms.txt)
- [Complete guide](https://agentaddress.dev/llms-full.txt)
- [Capability discovery](https://agentaddress.dev/.well-known/agentaddress.json)