API do Servidor

O servidor adk-rust fornece uma API REST 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 oferece:

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

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
}

Inicie o servidor:

cargo run -- serve --port 8080

Endpoints da API REST

Verificação de Saúde

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

GET /api/health

Resposta:

OK

Executar Agente com Streaming

Executa um agente e transmite 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:

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."
        }
      ]
    }
  }
}

Gerenciamento de Sessões

Criar Sessão

Cria uma nova sessão:

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 Sessão

Recupera os detalhes de uma 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

Exclui uma sessão:

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

Resposta:

Status: 204 No Content

Listar Sessões

Lista todas as sessões 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 Artefatos

Listar Artefatos

Lista todos os artefatos para uma sessão:

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

Resposta:

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

Obter Artefato

Baixa um artefato:

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

Resposta:

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

Gerenciamento de Aplicações

Listar Aplicações

Lista todos os agentes disponíveis:

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

Resposta:

{
  "apps": [
    {
      "name": "my_agent",
      "description": "Um assistente útil"
    }
  ]
}

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 Multiagente: Visualize transferências e hierarquias de agentes
Visualizador de Artefatos: Visualize e baixe artefatos da sessão
Atualizações em Tempo Real: Streaming baseado em SSE para respostas instantâneas

Rotas da UI

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

Especifique uma porta personalizada:

cargo run -- serve --port 3000

Serviço de Artefato Personalizado

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

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::DatabaseSessionService;

// Nota: Isso requer a implementação de uma configuração de servidor personalizada
// O Launcher usa InMemorySessionService por padrão

Tratamento de Erros

A API usa códigos de status HTTP padrão:

Código de Status	Significado
200	Sucesso
204	Sucesso (Sem Conteúdo)
400	Requisição Inválida
404	Não Encontrado
500	Erro Interno do Servidor

Formato da Resposta de Erro:

{
  "error": "Error message description"
}

Configuração CORS

O servidor habilita o 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 quando iniciado. Os logs são enviados para a 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 -- serve

Melhores Práticas

Gerenciamento de Sessão: Sempre crie uma session antes de executar um agent
Tratamento de Erros: Verifique os códigos de status HTTP e trate os erros de forma apropriada
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 DatabaseSessionService para implantações em produção
Monitoramento: Habilite telemetry e monitore logs para problemas

Exemplo Full-Stack

Para um exemplo completo e funcional de uma aplicação frontend interagindo com um backend ADK, consulte o exemplo Research Paper Generator. Isso demonstra:

Frontend: Cliente HTML/JavaScript com streaming em tempo real
Backend: agent ADK com ferramentas personalizadas de pesquisa e geração de PDF
Integração: Uso completo da REST API com streaming SSE
Artifacts: Geração e download de PDF
Gerenciamento de Sessão: Criação e manipulação automática de session

O exemplo mostra um padrão pronto para produção para a construção de aplicações web com inteligência artificial usando ADK-Rust.

Início Rápido:

# Start the server
cargo run --example full_stack_research -p adk-rust-guide -- serve --port 8080

# Open the frontend
open examples/research_paper/frontend.html

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

Relacionado

Launcher - Iniciando o servidor
Sessions - Gerenciamento de session
Artifacts - Armazenamento de artifacts
Observability - Telemetry e logging

Anterior: ← Launcher | Próximo: A2A Protocol →