A construção de sistemas de IA prontos para produção requer uma mudança de simples solicitações para orquestração estruturada. Com o Kit de desenvolvimento de agente do Google (ADK) E pítonVocê pode criar agentes robustos que lidam com raciocínio complexo e gerenciamento de estado.

Nesta postagem, Vou orientá-lo nos conceitos básicos do ADK: desde a definição do seu primeiro agente até a implantação dele como uma API pronta para produção usando FastAPI.

O que é um agente de IA?

Ao contrário de um LLM padrão que simplesmente gera texto com base em um prompt, um agente de IA inclui o seguinte Lógica de raciocínio e decisão. Ele pode interpretar solicitações do usuário, decidir quais ações tomar, e interagir com ferramentas ou outros componentes para concluir uma tarefa.
Na prática, um agente pode:

• Razão: Interprete a intenção do usuário e entenda as restrições da solicitação.
• Agir: Chame ferramentas externas, APIs, ou funções para recuperar informações ou realizar operações.
• Colaborar: Colabore com outros agentes especializados para resolver tarefas mais complexas.

Isto torna os agentes particularmente úteis para a construção estruturado, aplicativos de IA em vários estágios.

Nosso caso de uso

Neste exemplo vamos criar um Agente de planejamento de viagens que pode responder às perguntas dos usuários sobre viagens e destinos. O agente processa a solicitação do usuário, gera sugestões de viagens relevantes e estrutura a resposta de maneira útil.

Para tornar o sistema acessível a outros aplicativos, expomos o agente através de um API REST construída com FastAPIque permite a integração com aplicações web, interfaces de bate-papo e outros serviços.

Etapa 0: Configurando seu ambiente

Para participar, você precisará de Python 3.10+ e um gerenciador de pacotes como pipx ou uv (que é significativamente mais rápido que o Pip padrão).

Se você ainda não tem UV, você pode instalá-lo com um simples comando curl:

# Instalar UV
enrolar -LsSf [https://astral.sh/uv/install.sh](https://astral.sh/uv/install.sh) | eh

Estrutura do projeto

Para este projeto esperamos a seguinte estrutura de projeto:

Inicialize seu projeto

Depois que o UV estiver instalado, da raiz do seu repositório, instale as bibliotecas relevantes para as camadas de agente e API e habilite o ambiente virtual:

# Instale o Google ADK, API rápida, e Uvicórnio (o servidor ASGI)
uv adicionar google-adk fastapi uvicorn
# Sincronize dependências e ative seu ambiente
sincronização UV
fonte .venv/bin/activate

A próxima etapa é inicializar seu agente por meio da CLI do ADK, que cria a estrutura de diretórios necessária para a lógica do seu agente.

# Crie um novo projeto de agente
adk criar meu_planner_de_viagem

A configuração .env

O manuseio seguro de chaves de API é de extrema importância. Você deve criar um arquivo .env no diretório my_travel_planner (ou preencha o arquivo de modelo .env existente criado na etapa acima) para gerenciar credenciais.

É importante que você nunca coloque este arquivo sob controle de versão. Certifique-se de adicionar isso ao .arquivo gitignore (se ainda não existe).

• Opção 1 (Estúdio de IA do Google): Se você usar uma chave API Gemini padrão de Estúdio de IA do Googledefina GOOGLE_GENAI_USE_VERTEXAI=False e adicione sua chave.
• Opção 2 (Vértice AI): Se você estiver no Google Cloud, defina GOOGLE_GENAI_USE_VERTEXAI=True e faça referência às credenciais do seu aplicativo. Você pode acompanhar isso link para documentação precisa.

# .modelo de ambiente
GOOGLE_API_KEY=your_gemini_api_key_aqui
GOOGLE_GENAI_USE_VERTEXAI=Falso
# Opcional para Vertex AI:
# GOOGLE_APPLICATION_CREDENTIALS=caminho/para/suas/credenciais.json

Etapa 1: Defina o agente

O “cérebro” do seu sistema é definido em my_travel_planner/agent.py. Aqui damos um nome ao agente, um modelo específico (como gemini-2.5-flash) e instruções claras sobre sua personalidade.

do agente de importação google.adk.agents
def get_root_agent():
    # O agente raiz (The "Brain")
    travel_planner = Agente(
        name="travel_planner",
        model="gemini-2.5-flash",
        description="A comprehensive travel planning assistant.",
        instruction="""You are a world-class travel planner.
        Recommend places to visit based on the user's query.""",
    )
    retorno travel_planner
root_agent = get_root_agent()

Etapa 2: Gerencie o armazenamento com sessões e executores

LLMs sem estado esquecem o contexto assim que a solicitação termina. Agentes são necessários para sistemas de produção Memória. ADK gerencia isso através reuniões e o corredor.

• Sessões: Armazenar histórico de conversas do agente, informações do usuário, e status intermediários.
• Corredor: Orquestra toda a interação – recebendo informações, transmitindo isso para o cérebro, e mantendo o estado.

Veja como você pode executar esse pipeline de forma assíncrona. Na raiz do seu repositório, crie run.py assim:

de google.adk.sessions importar InMemorySessionService
de google.adk.agents.llm_agent agente de importação
de google.adk.runners importar Runner
dos tipos de importação google.genai  # Para criar conteúdo/partes de mensagens
importar assíncrono
do caminho de importação pathlib
de importação dotenv load_dotenv
carregar_dotenv(Caminho(__arquivo__).pai / "my_travel_planner" / ".env")  # Carregar variáveis ​​de ambiente do arquivo .env
de my_travel_planner.agent importar get_root_agent
APP_NAME = "travel-planner_app"
USER_ID = "user_1"
SESSION_ID = "session_001"
assíncrono def setup_session_and_runner(agente_raiz: Agente = Nenhum, ID_da_sessão: str = SESSION_ID):
    # Configurar Runner para execução
    session_service=InMemorySessionService()
    sessão = aguardar session_service.create_session(app_name=APP_NAME, user_id=USER_ID, session_id=session_id)
    corredor = Corredor(agente = agente_raiz, app_name=APP_NAME, session_service=session_service)
    sessão de retorno, corredor
assíncrono def call_agent_async(consulta: str, agente_raiz: Agente = Nenhum, ID_da_sessão: str = SESSION_ID) -> str:
    conteúdo = tipos.Conteúdo(role='user', partes =[tipos.Parte(texto=consulta)])
    sessão, corredor = aguarda setup_session_and_runner(root_agent=root_agent, session_id=session_id)
    eventos = runner.run_async(user_id=USER_ID, session_id=session_id, nova_mensagem=conteúdo)
    final_response_text = "No response received."
    assíncrono para evento em eventos:
        # Conceito-chave: is_final_response() marca a mensagem final da virada.
        se evento.is_final_response():
            se evento.content e evento.content.parts:
                final_response_text=evento.content.parts[0].texto
            elif event.actions e event.actions.escalate:
                final_response_text = f"Agent escalated: {event.error_message or 'No specific message.'}"
            quebrar
imprimir(f"<<< Resposta do agente: {texto_resposta_final}")
    retornar final_response_text
def assíncrono run_agent_pipeline(consulta: str) -> str:
    root_agent = get_root_agent()
    retornar aguardar call_agent_async(consulta=consulta, root_agent=root_agent, session_id=SESSION_ID)
if __name__ == "__main__":
    consulta_usuário = ("I'm planning a trip to Paris in the spring. Quais são algumas atrações imperdíveis e eventos locais "
                  "during that time?")
    assíncio.run(run_agent_pipeline(consulta = consulta_usuário))

Etapa 3: Transforme seu agente em uma API

Para tornar seu agente útil no mundo real, precisamos expô-lo como uma API. API rápida é o padrão moderno para isso porque é poderoso, usa dicas de tipo para validação, e gera documentação automática do Swagger.

Envolvendo nosso pipeline ADK em um endpoint POST, podemos conectar nosso agente a frontends, aplicativos móveis, ou outros microsserviços.

Na raiz do repositório, criamos api.py, onde definimos um endpoint /ask simples:

da importação fastapi FastAPI
da importação pydantic BaseModel
do caminho de importação pathlib
de importação dotenv load_dotenv
carregar_dotenv(Caminho(__arquivo__).pai / "my_travel_planner" / ".env")
de executar importação run_agent_pipeline
aplicativo = FastAPI(title="Travel Planner AI", description="Powered by Google ADK + Gemini")
classe ConsultaRequest(Eles são modelos):
    consulta: str
classe QueryResponse(Eles são modelos):
    consulta: str
    resposta: str
@app.post("/ask", response_model=QueryResposta)
assíncrono def ask_agent(solicitar: Solicitação de consulta):
    resposta = aguarda run_agent_pipeline(consulta = solicitação.consulta)
    retornar QueryResponse(consulta = solicitação.consulta, resposta=resposta)

Execute seu servidor com: uv executar API Uvicorn:aplicativo –recarregar
O servidor começa às http://host local:8000 e documentos interativos (IU arrogante): http://host local:8000/documentos

Considerações Finais: O caminho para a produção

Um roteiro local é um bom começo, mas pronto para produção requer mais algumas etapas:

1. Verificar: Escreva testes de unidade para verificar se a lógica do agente lida com casos extremos.
2. Contentorizar: Use o Docker para garantir que “funciona no meu computador” seja traduzido como “funciona no servidor”.
3. Inserir: Envie seu contêiner para um provedor de nuvem como o Google Cloud (Execução na nuvem) ou AWS.

Pronto para construir? Obtenha o código do Repositório GitHub e comece a criar seus próprios fluxos de trabalho de agentes especializados hoje mesmo!

✨ Nós agradecemos isso Programas para desenvolvedores de IA/ML do Google Equipe de suporte de créditos do Google Cloud.

✨ O código fonte pode ser acessado no GitHub Aqui.

✨ Se você gostou do artigo, por favor inscrever-se para o meu último.
Para entrar em contato, entre em contato comigo em LinkedIn ou sobre ashmibanerjee.com.

Divulgação de uso do GenAI: Modelos GenAI foram usados ​​para verificar inconsistências gramaticais no blog e refinar o texto para maior clareza. Os autores assumem total responsabilidade pelo conteúdo apresentado neste blog.

---

[Tutorial] De Agentes a APIs: Construindo sistemas de IA prontos para produção com o Google ADK & FastAPI foi publicado originalmente no Google Developer Experts on Medium, onde as pessoas continuam a discussão destacando e respondendo a esta história.