Servidor API

O servidor ADK-Rust fornece uma REST API para executar agents, gerenciar sessions e acessar artefatos. Quando você implanta seu agent usando o Launcher no modo de servidor, ele expõe esses endpoints juntamente com uma interface de usuário web.

Visão Geral

O servidor é construído sobre Axum e fornece:

REST API: endpoints HTTP para execução de agent e gerenciamento de session
Server-Sent Events (SSE): Streaming em tempo real de respostas do agent
Web UI: Interface interativa baseada em navegador
CORS Support: Requisições de origem cruzada habilitadas
Telemetry: Observabilidade integrada com tracing

ServerConfig também expõe passthrough de nível de 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-2.5-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 a partir do scaffold API validado:

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

REST API Pontos de Extremidade

Verificação de Integridade

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

GET /api/health

Resposta:

OK

Executar Agent com Streaming

Executa um agent e transmite as respostas usando Server-Sent Events:

POST /api/run_sse

Corpo da Requisição:

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

Resposta:

Tipo de Conteúdo: 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."
        }
      ]
    }
  }
}

Gerenciamento de Session

Criar Session

Cria uma nova session:

POST /api/sessions

Corpo da Requisição:

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

Resposta:

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

Obter Session

Recupera os detalhes da session:

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

Resposta:

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

Excluir Session

Exclui uma session:

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

Resposta:

Estado: 204 No Content

Listar Sessions

Lista todas as sessions para 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 Artifact

Listar Artifacts

Lista todos os artifacts para uma session:

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

Resposta:

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

Obter Artefato

Baixe um artefato:

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

Resposta:

Content-Type: Determinado pela extensão do arquivo
Body: Conteúdo binário ou de texto

Gerenciamento de Aplicações

Listar Aplicações

Liste todos os agents 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/

Funcionalidades

Chat Interativo: Envie mensagens e receba respostas em streaming
Gerenciamento de Sessões: Crie, visualize e alterne entre sessões
Suporte Multi-Agent: Visualize transferências e hierarquias de agents
Visualizador de Artefatos: Visualize e baixe artefatos de sessão
Atualizações em Tempo Real: Streaming baseado em SSE para respostas instantâneas

Rotas da Interface

/ - Redireciona para /ui/
/ui/ - Interface principal de chat
/ui/assets/* - Ativos estáticos (CSS, JS, imagens)
/ui/assets/config/runtime-config.json - Configuração de tempo de execução

Exemplos de Cliente

JavaScript/TypeScript

Usando a 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 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 de erro:

Código de Status	Categoria	Significado
200	—	Sucesso
204	—	Sucesso (Sem Conteúdo)
400	`invalid_input`	Requisição Inválida — parâmetros ou configuração inválidos
401	`unauthorized`	Credenciais ausentes ou inválidas
403	`forbidden`	Credenciais válidas, permissões insuficientes
404	`not_found`	Recurso não encontrado
408	`timeout`	Operação expirou
429	`rate_limited`	Limite de taxa upstream excedido
500	`internal`	Erro interno do servidor
501	`unsupported`	Funcionalidade não suportada
503	`unavailable`	Serviço upstream indisponível

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
  }
}

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

CORS Configuração

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

Telemetria

O servidor inicializa automaticamente a telemetria ao ser iniciado. Os logs são enviados para stdout 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

Melhores Práticas

Gerenciamento de Sessão: Sempre crie uma session antes de executar um agent
Tratamento de Erros: Verifique os HTTP status codes e trate os erros apropriadamente
Streaming: Use SSE para respostas em tempo real; analise os eventos linha por linha
Segurança: Em produção, implemente autenticação e restrinja CORS
Persistência: Use SqliteSessionService ou PostgresSessionService para implantações em produção
Monitoramento: Habilite a telemetria e monitore os logs em busca de problemas

Exemplo Full-Stack

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

Frontend: HTML/JavaScript cliente com streaming em tempo real
Backend: ADK agent com pesquisa personalizada e ferramentas de 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 manipulação automática de sessão

O exemplo mostra um padrão pronto para produção para construir aplicações web com 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

Launcher - Iniciando o servidor
Sessões - Gerenciamento de sessão
Artefatos - Armazenamento de artefatos
Observabilidade - Telemetria e registro

Anterior: ← Lançador | Próximo: A2A Protocolo →

Servidor API

Visão Geral

Iniciando o Servidor

REST API Pontos de Extremidade

Verificação de Integridade

Executar Agent com Streaming

Gerenciamento de Session

Criar Session

Obter Session

Excluir Session

Listar Sessions

Gerenciamento de Artifact

Listar Artifacts

Obter Artefato

Gerenciamento de Aplicações

Listar Aplicações

Interface Web

Funcionalidades

Rotas da Interface

Exemplos de Cliente

JavaScript/TypeScript

Python

cURL

Configuração do Servidor

Porta Personalizada

Serviço de Artefatos Personalizado

Serviço de Sessão Personalizado

Tratamento de Erros

CORS Configuração

Telemetria

Melhores Práticas

Exemplo Full-Stack

Relacionado