Servidor API

O servidor ADK-Rust fornece um REST API para executar agentes, gerenciar sessões e acessar artefatos. Quando você implanta seu agente usando o Launcher no modo de servidor, ele expõe esses endpoints juntamente com uma interface web.

Visão geral

O servidor é desenvolvido com Axum e fornece:

• REST API: endpoints HTTP para execução de agentes e gerenciamento de sessões
• Server-Sent Events (SSE): transmissão em tempo real das respostas do agente
• Interface web: interface interativa baseada em navegador
• Suporte a CORS: solicitações de origem cruzada habilitadas
• Telemetria: observabilidade integrada com tracing

ServerConfig também expõe o passthrough no nível do runner para implantações de longa duração:

let config = ServerConfig::new(agent_loader, session_service)
    .with_compaction(compaction_config)
    .with_context_cache(context_cache_config, cache_capable_model);

Iniciando o servidor

Use o Launcher para iniciar o servidor:

use adk_rust::prelude::*;
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<()> {
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = Arc::new(GeminiModel::new(&api_key, "gemini-3.7-flash")?);
    
    let agent = LlmAgentBuilder::new("my_agent")
        .description("A helpful assistant")
        .instruction("You are a helpful assistant.")
        .model(model)
        .build()?;
    
    Launcher::new(Arc::new(agent)).run().await
}

Comece pelo scaffold API validado:

cargo adk new my-api --template api
cd my-api
cargo run

Endpoints REST API

Verificação de integridade

Verifique se o servidor está em execução:

GET /api/health

Resposta:

OK

Executar agente com transmissão

Execute um agente e transmita as respostas usando Server-Sent Events:

POST /api/run_sse

Corpo da solicitação:

{
  "appName": "my_agent",
  "userId": "user123",
  "sessionId": "session456",
  "newMessage": {
    "role": "user",
    "parts": [
      {
        "text": "What is the capital of France?"
      }
    ]
  },
  "streaming": true
}

Resposta:

• Content-Type: text/event-stream
• Transmite eventos como objetos JSON

Formato do evento:

{
  "id": "evt_123",
  "timestamp": 1234567890,
  "author": "my_agent",
  "content": {
    "role": "model",
    "parts": [
      {
        "text": "The capital of France is Paris."
      }
    ]
  },
  "actions": {},
  "llm_response": {
    "content": {
      "role": "model",
      "parts": [
        {
          "text": "The capital of France is Paris."
        }
      ]
    }
  }
}

Executar agente (sem transmissão)

Execute um agente até a conclusão e receba todos os eventos em uma única resposta JSON:

POST /api/run

Corpo da solicitação: mesma estrutura de POST /api/run_sse (o campo streaming é ignorado):

{
  "appName": "my_agent",
  "userId": "user123",
  "sessionId": "session456",
  "newMessage": {
    "role": "user",
    "parts": [
      {
        "text": "What is the capital of France?"
      }
    ]
  }
}

Resposta:

• Content-Type: application/json
• Um array JSON contendo todos os eventos produzidos pela execução, na ordem, usando o mesmo formato de evento que /api/run_sse

Esse endpoint replica a rota /run sem transmissão de ADK api_server do Google.

Gerenciamento de sessões

Criar sessão

Criar uma nova sessão:

POST /api/sessions

Corpo da solicitação:

{
  "appName": "my_agent",
  "userId": "user123",
  "sessionId": "session456"
}

Resposta:

{
  "id": "session456",
  "appName": "my_agent",
  "userId": "user123",
  "lastUpdateTime": 1234567890,
  "events": [],
  "state": {}
}

Obter sessão

Recuperar os detalhes da sessão:

GET /api/sessions/:app_name/:user_id/:session_id

Resposta:

{
  "id": "session456",
  "appName": "my_agent",
  "userId": "user123",
  "lastUpdateTime": 1234567890,
  "events": [],
  "state": {}
}

Excluir sessão

Excluir uma sessão:

DELETE /api/sessions/:app_name/:user_id/:session_id

Resposta:

• Status: 204 No Content

Listar sessões

Listar todas as sessões de um usuário:

GET /api/apps/:app_name/users/:user_id/sessions

Resposta:

[
  {
    "id": "session456",
    "appName": "my_agent",
    "userId": "user123",
    "lastUpdateTime": 1234567890,
    "events": [],
    "state": {}
  }
]

Gerenciamento de artefatos

Listar artefatos

Listar todos os artefatos de uma sessão:

GET /api/sessions/:app_name/:user_id/:session_id/artifacts

Resposta:

[
  "image1.png",
  "document.pdf",
  "data.json"
]

Obter artefato

Baixar um artefato:

GET /api/sessions/:app_name/:user_id/:session_id/artifacts/:artifact_name

Resposta:

• Tipo de conteúdo: determinado pela extensão do arquivo
• Corpo: conteúdo binário ou de texto

Gerenciamento de aplicativos

Listar aplicativos

Listar todos os agentes disponíveis:

GET /api/apps
GET /api/list-apps  (legacy compatibility)

Resposta:

{
  "apps": [
    {
      "name": "my_agent",
      "description": "A helpful assistant"
    }
  ]
}

Interface web

O servidor inclui uma interface web integrada acessível em:

http://localhost:8080/ui/

O início rápido de cinco minutos configura um servidor baseado em OpenAI e abre essa interface com quatro comandos. A gravação usa uma equipe para tornar visível a aresta da topologia ativa; agentes folha, ferramentas, grafos, fluxos de trabalho, agentes em tempo real e agentes remotos usam a mesma interface.

Recursos

• Execuções interativas: Envie mensagens e anexos e inspecione com segurança Markdown renderizado, texto em streaming, chamadas de ferramentas, falhas e transferências
• Gerenciamento de sessões: Crie, visualize e alterne entre sessões
• Topologia portátil de equipe: Diferencie arestas exatas de delegação e retorno de transferências de controle, com animação no estilo do Studio Next para o membro ativo e a aresta de entrada
• Inspetor de runtime: Inspecione eventos ordenados, spans de telemetria dedicados, estado compartilhado/da sessão, serviços de runtime configurados, descoberta de A2A e suporte ao protocolo de Apps de UI/MCP
• Reprodução em tempo real: Reconheça agentes em tempo real, combine deltas de transcrição e reproduza a saída PCM concluída como áudio WAV
• Visualizador de artefatos: Visualize e baixe artefatos da sessão
• Temas responsivos: Layouts do sistema, claro e escuro acessíveis por teclado, sem recursos externos

Rotas da UI

• / - Redireciona para /ui/
• /ui/ - Interface principal de chat
• /ui/assets/* - Recursos estáticos (CSS, JS, imagens)
• /ui/assets/config/runtime-config.json - Configuração do runtime
• /api/ui/agents/{name} - Recursos, hierarquia e metadados de topologia portátil do agente

A interface é mantida em adk-server/webui, e seu build de produção é incorporado ao crate do servidor, portanto projetos gerados e implantações usam a mesma UI de runtime sem um serviço de frontend separado.

A demonstração da interface do runtime executável inclui walkthroughs e capturas de tela separados baseados em OpenAI para um agente que chama ferramentas, um fluxo de trabalho de grafo determinístico e uma equipe portátil de transferência. A galeria avançada de agentes adiciona uma programação ambiente, reprodução de voz em tempo real do OpenAI, descoberta de A2A, descoberta de MCP 2026-07-28 com tarefas SEP-2663 e serviços configurados de telemetria, artefatos e memória em um único servidor. A marca Runtime ADK vincula-se a adk-rust.com em uma nova aba.

Exemplos de cliente

JavaScript/TypeScript

Usando o Fetch API com SSE:

async function runAgent(message) {
  const response = await fetch('http://localhost:8080/api/run_sse', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      appName: 'my_agent',
      userId: 'user123',
      sessionId: 'session456',
      newMessage: {
        role: 'user',
        parts: [{ text: message }]
      },
      streaming: true
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunk = decoder.decode(value);
    const lines = chunk.split('\n');
    
    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const event = JSON.parse(line.slice(6));
        console.log('Event:', event);
      }
    }
  }
}

Python

Usando a biblioteca requests:

import requests
import json

def run_agent(message):
    url = 'http://localhost:8080/api/run_sse'
    payload = {
        'appName': 'my_agent',
        'userId': 'user123',
        'sessionId': 'session456',
        'newMessage': {
            'role': 'user',
            'parts': [{'text': message}]
        },
        'streaming': True
    }
    
    response = requests.post(url, json=payload, stream=True)
    
    for line in response.iter_lines():
        if line:
            line_str = line.decode('utf-8')
            if line_str.startswith('data: '):
                event = json.loads(line_str[6:])
                print('Event:', event)

run_agent('What is the capital of France?')

cURL

# Create session
curl -X POST http://localhost:8080/api/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "my_agent",
    "userId": "user123",
    "sessionId": "session456"
  }'

# Run agent with streaming
curl -X POST http://localhost:8080/api/run_sse \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "my_agent",
    "userId": "user123",
    "sessionId": "session456",
    "newMessage": {
      "role": "user",
      "parts": [{"text": "What is the capital of France?"}]
    },
    "streaming": true
  }'

Configuração do servidor

Porta personalizada

Para usar uma porta personalizada, defina PORT antes de iniciar o servidor gerado:

PORT=3000 cargo run

Serviço de artefatos personalizado

Forneça seu próprio serviço de artefatos:

use adk_artifact::InMemoryArtifactService;

let artifact_service = Arc::new(InMemoryArtifactService::new());

Launcher::new(Arc::new(agent))
    .with_artifact_service(artifact_service)
    .run()
    .await

Serviço de sessão personalizado

Para implantações em produção, use um serviço de sessão persistente:

use adk_session::SqliteSessionService;

// Note: This requires implementing a custom server setup
// The Launcher uses InMemorySessionService by default

Tratamento de erros

O API usa respostas de erro estruturadas com códigos de status HTTP derivados da categoria do erro:

Formato de resposta de erro (Problema JSON):

{
  "error": {
    "code": "model.openai.rate_limited",
    "message": "OpenAI rate limit exceeded",
    "component": "model",
    "category": "rate_limited",
    "requestId": "req-abc123",
    "retryAfter": 5000,
    "upstreamStatusCode": 429
  }
}

Os campos requestId, retryAfter e upstreamStatusCode são incluídos quando disponíveis (caso contrário, nulo).

Configuração de CORS

O servidor habilita CORS permissivo por padrão, permitindo solicitações de qualquer origem. Isso é adequado para desenvolvimento, mas deve ser restringido em produção.

Telemetria

O servidor inicializa automaticamente a telemetria quando é iniciado. Os logs são enviados para a saída padrão com formatação estruturada.

Níveis de log:

• ERROR: Erros críticos
• WARN: Avisos
• INFO: Informações gerais (padrão)
• DEBUG: Depuração detalhada
• TRACE: Rastreamento muito detalhado

Defina o nível de log com a variável de ambiente RUST_LOG:

RUST_LOG=debug cargo run

Práticas recomendadas

1. Gerenciamento de sessão: sempre crie uma sessão antes de executar um agente
2. Tratamento de erros: verifique os códigos de status HTTP e trate os erros adequadamente
3. Streaming: use SSE para respostas em tempo real; analise os eventos linha por linha
4. Segurança: em produção, implemente autenticação e restrinja CORS
5. Persistência: use SqliteSessionService ou PostgresSessionService para implantações em produção
6. Monitoramento: habilite a telemetria e monitore os logs em busca de problemas

Exemplo de pilha completa

Para obter um scaffold de servidor completo e funcional, use o template API validado do cargo-adk. Isso demonstra:

• Frontend: cliente HTML/JavaScript com streaming em tempo real
• Backend: agente ADK com ferramentas personalizadas de pesquisa e geração de PDF
• Integração: uso completo de REST API com streaming de SSE
• Artefatos: geração e download de PDF
• Gerenciamento de sessão: criação e tratamento automáticos de sessões

O exemplo mostra um padrão pronto para produção para criar aplicações web com tecnologia de IA usando ADK-Rust.

Início rápido:

cargo adk new my-api --template api
cd my-api
cargo run

Arquivos:

• Backend: adk-rust-guide/examples/deployment/full_stack_research.rs
• Frontend: examples/research_paper/frontend.html
• Documentação: examples/research_paper/README.md
• Arquitetura: examples/research_paper/architecture.md

Relacionados

• Inicializador - Iniciando o servidor
• Sessões - Gerenciamento de sessões
• Artefatos - Armazenamento de artefatos
• Observabilidade - Telemetria e registro de logs

---

Anterior: ← Inicializador | Próximo: Protocolo A2A →