Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Boas Práticas e Próximos Passos

Aula 18 de 18 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. O que Aprendeu
  2. Conceção de Agentes Robustos
  3. Gestão de Erros
  4. Monitorização do Que Está a Ocorrer
  5. Teste de Roteamento
  6. Arquitetura de Referência
  7. Para Onde Ir a Seguir
  8. Pontos-chave
  9. Teste os Seus Conhecimentos

O que Aprendeu

Percorreu toda a API Mistral Agents. Vamos fazer um resumo antes de avançar para as práticas de produção, uma vez que cada parte deste curso se baseia na anterior.

As três primeiras lições lançaram as bases: um agente de IA é um sistema autónomo com um ciclo de perceção-ação; a API assenta em três objetos — Agent, Conversation e Entry; e o que separa um agente de um chatbot é a persistência, as ferramentas e as transferências de controlo (handoffs). As lições 4 a 7 tornaram estes objetos utilizáveis: criar e configurar agentes com client.beta.agents.create(), manter conversas persistentes com conversations.start() e conversations.append(), e utilizar o modo direto sem um agente quando está a criar protótipos e a persistência não agrega valor.

As lições 8 a 11 adicionaram capacidades. A ferramenta web_search dá-lhe acesso a informações atuais com citações automáticas; o code_interpreter executa Python num ambiente isolado (sandbox), fornecendo ao agente resultados exatos onde o modelo, por si só, apenas aproximaria; a image_generation produz elementos visuais a partir de prompts de texto; e a document_library traz RAG integrado para os seus próprios documentos. As lições 12 a 16 mostraram depois vários agentes a trabalhar em conjunto: as transferências de controlo passam a gestão de um agente para outro, a arquitetura de referência emparelha um router central com especialistas, o modo de servidor automatiza onde o modo de cliente o mantém no ciclo de decisão, e o encadeamento ilimitado divide-se em padrões lineares, em estrela e híbridos. Finalmente, a Lição 17 concluiu tudo com guardas (guardrails), o princípio do privilégio mínimo e moderação a montante.

Conceção de Agentes Robustos

Uma frase resume todo o curso: um agente, uma responsabilidade, uma descrição que indique quando deve ser chamado. O contraste abaixo torna a diferença tangível.

# BOM — agente especializado com descrição precisa
agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="invoice-processor",
    description="Processes invoices: extracts amounts, dates, vendors.",
    instructions="Extract invoice information into structured JSON.",
    tools=[{"type": "document_library", "library_ids": [invoices_lib.id]}]
)

# MAU — agente genérico e vago
agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="helper",
    description="A helpful agent.",
    tools=[{"type": "web_search"}, {"type": "code_interpreter"}, {"type": "image_generation"}]
)

O segundo agente falhará de duas formas simultaneamente. Nenhum router saberá quando lhe deve transferir um pedido, porque “um agente prestativo” não descreve nenhuma situação. E quando for chamado, as suas três ferramentas deixam-no livre para pesquisar na web algo que deveria ter calculado, ou para ilustrar algo que lhe foi pedido analisar.

Gestão de Erros

As chamadas de rede falham mais cedo ou mais tarde. Uma nova tentativa com retrocesso exponencial (exponential backoff) absorve incidentes transitórios sem transformar uma desaceleração momentânea numa indisponibilidade visível.

import time

def safe_conversation(agent_id, query, max_retries=3):
    """Conversation with error handling and retry."""
    for attempt in range(max_retries):
        try:
            response = client.beta.conversations.start(
                agent_id=agent_id,
                inputs=query
            )
            return response
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff
    return None

O retrocesso exponencial — um segundo, depois dois, depois quatro — distingue uma nova tentativa civilizada de bombardear um serviço que já está a ter dificuldades. Note também que a tentativa final volta a lançar a exceção em vez de devolver None: o seu chamador precisa de saber que a operação falhou.

Monitorização do Que Está a Ocorrer

Em produção, um fluxo de trabalho multi-agente que não pode ser observado torna-se impossível de depurar. O modo de cliente fornece exatamente os ganchos de que precisa.

import logging
import time

logger = logging.getLogger("agents")

def monitored_conversation(agent_id, query):
    """Conversation with monitoring."""
    start = time.time()

    response = client.beta.conversations.start(
        agent_id=agent_id,
        inputs=query,
        handoff_execution="client"
    )

    handoff_count = 0
    tool_count = 0

    for entry in response.outputs:
        if entry.type == "agent.handoff":
            handoff_count += 1
            logger.info(f"Handoff #{handoff_count}: → {entry.next_agent_id}")
        elif entry.type == "tool.execution":
            tool_count += 1
            logger.info(f"Tool #{tool_count}: {entry.tool_name}")

    duration = time.time() - start
    logger.info(f"Finished in {duration:.1f}s — {handoff_count} handoffs, {tool_count} tools")

    return response

Esses dois contadores valem mais do que a sua simplicidade sugere: um desvio na média de transferências de controlo sinaliza um router que está a hesitar; um pico nas chamadas de ferramentas aponta para consultas dispendiosas.

O controlo de custos resume-se então a decisões concretas. Monitore os tokens por conversa, pois essa é a unidade real de faturação. Utilize mistral-medium-latest sempre que mistral-large-latest não acrescente nada — o primeiro nível de suporte é um exemplo clássico. Limite o max_tokens em completion_args para evitar respostas intermináveis a perguntas simples e desative o armazenamento com store=False quando a persistência não for necessária.

Teste de Roteamento

Teste um sistema multi-agente como qualquer central telefónica: forneça-lhe casos cujo destino esperado conheça e verifique onde aterram.

def test_agent_routing():
    """Verifies that the router distributes correctly."""
    test_cases = [
        ("What is the price of Bitcoin?", "web-search-agent"),
        ("Calculate 25 * 48", "calculator-agent"),
        ("Summarize this document", "doc-agent"),
    ]

    for query, expected_agent_name in test_cases:
        response = client.beta.conversations.start(
            agent_id=router.id,
            inputs=query,
            handoff_execution="client"
        )

        for entry in response.outputs:
            if entry.type == "agent.handoff":
                target = client.beta.agents.get(agent_id=entry.next_agent_id)
                assert target.name == expected_agent_name, \
                    f"Incorrect routing for '{ query}': {target.name} instead of {expected_agent_name}"

Construa este conjunto de testes ao longo do tempo: cada pedido mal direcionado que detetar em produção torna-se noutra linha em test_cases, e saberá que reescrever uma descrição corrige o caso visado sem quebrar outro.

Arquitetura de Referência

Para um projeto de produção, eis uma arquitetura recomendada:

Application
    │
    ▼
Moderator Agent (filters requests)
    │
    ▼
Router Agent (distributes to specialists)
    ├── Search Agent (web_search)
    ├── Analysis Agent (code_interpreter)
    ├── Documents Agent (document_library)
    └── Creation Agent (image_generation)
    │
    ▼
Logging + Monitoring + Alerting

Esta arquitetura reúne tudo o que viu neste curso: o moderador filtra antes de qualquer execução, o router direciona sem nunca responder ele próprio, cada especialista carrega uma ferramenta e uma responsabilidade, e a observação envolve todo o sistema.

Para Onde Ir a Seguir

Quatro direções expandem o que pode fazer agora. A chamada de funções (function calling) permite-lhe construir as suas próprias ferramentas personalizadas para além das integradas: chamar uma API de negócio, consultar uma base de dados, acionar um serviço interno. Os Servidores MCP integram o Model Context Protocol, que padroniza a forma como as ferramentas são expostas. As saídas estruturadas forçam as respostas a um esquema JSON, o que muda tudo quando a saída de um agente alimenta outro sistema em vez de um leitor humano. Finalmente, a transmissão (streaming) devolve respostas em tempo real em vez de num único bloco — decisivo em cadeias longas, onde a espera silenciosa se torna desconfortável.

Três recursos acompanham este próximo passo: a documentação oficial em docs.mistral.ai/agents, os livros de receitas (cookbooks) da Mistral que fornecem exemplos completos de implementação, e a Referência da API que documenta cada endpoint em detalhe.

Pontos-chave

  • Especialize os seus agentes — um agente = uma responsabilidade
  • Monitore — registe cada transferência de controlo e execução de ferramenta
  • Teste — valide o roteamento e as respostas de cada agente
  • Proteja — guardas, privilégio mínimo, moderação a montante
  • Otimize custos — modelo dimensionado corretamente, max_tokens, store=False quando possível
  • Os Mistral Agents estão em beta — mantenha-se atualizado com as alterações da API

Teste os Seus Conhecimentos

Agentes, ferramentas integradas, transferências de controlo: a API Agents ainda tem pontos cegos?

1. Quando é necessário um agente e quando é suficiente um chatbot?

Resposta: Um agente justifica-se quando precisa de ferramentas, persistência e decisões em várias etapas; para perguntas e respostas simples, uma conversa padrão é suficiente — a arquitetura segue a necessidade.

2. O que gerem as conversas persistentes na API Agents?

Resposta: O histórico no lado da Mistral: continua uma conversa pelo seu ID sem reenviar todo o contexto — o estado torna-se um serviço.

3. Liste as ferramentas integradas disponíveis e a sua utilização.

Resposta: web_search (informação em tempo real), code_interpreter (executar Python), image_generation (criar imagens), document_library (perguntas e respostas sobre os seus ficheiros) — capacidades prontas a usar, sem implementação necessária.

4. Como funciona um sistema multi-agente com transferências de controlo?

Resposta: Um router qualifica o pedido e passa-o ao agente especialista competente; cada agente mantém-se simples, a orquestração garante a cobertura — e as transferências encadeiam-se em profundidade.

5. Como protege os agentes em produção?

Resposta: Com guardas nas entradas/saídas, ferramentas de âmbito restrito, rastreabilidade das ações e validação humana em decisões de alto risco — a autonomia conquista-se através do controlo.

Agentes especializados, ferramentas integradas, roteamento, guardas: a arquitetura completa cabe em quatro palavras — e este curso levou-o a construir cada uma delas.