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

Criar um Agente com a API Python

Aula 4 de 18 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. O Seu Primeiro Agente Mistral
  2. Pré-requisitos
  3. Criar um Agente Minimalista
  4. Definir o Comportamento com Instruções
  5. Controlar a Geração
  6. Equipar o Agente com Ferramentas
  7. Gerir o Ciclo de Vida do Agente
  8. Exemplo Completo
  9. Pontos-chave

O Seu Primeiro Agente Mistral

As três lições anteriores estabeleceram o vocabulário; esta coloca as suas mãos no teclado. Vai criar um agente através da API Python, enriquecendo-o progressivamente com instruções, parâmetros de geração e ferramentas, para depois iniciar uma conversa com ele. A progressão é intencionalmente incremental: cada adição modifica um comportamento observável, mostrando-lhe por que razão o mesmo método create() pode produzir quer um assistente genérico, quer um especialista com um estilo rigorosamente definido.

Pré-requisitos

A instalação consiste em dois passos. Primeiro, o SDK oficial.

pip install mistralai

De seguida, disponibilize a sua chave de API no ambiente, em vez de a codificar diretamente no seu código. Commitar acidentalmente uma chave num repositório é o primeiro incidente de segurança em qualquer projeto de LLM.

export MISTRAL_API_KEY="your-api-key"

Constrói depois o cliente numa única linha. Este objeto client serve como ponto de entrada para o restante da lição.

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Criar um Agente Minimalista

O método client.beta.agents.create() aceita três parâmetros obrigatórios e vários opcionais. Comecemos pelo estritamente necessário.

agent = client.beta.agents.create(
    model="mistral-medium-latest",
    name="Simple Assistant",
    description="A conversational agent with persistent state."
)

print(f"Agent created: {agent.id}")

Este agente é minimalista: sem instruções específicas, sem ferramentas, sem barreiras de segurança. Comporta-se como um endpoint de Chat Completions melhorado, mas com persistência. Note o identificador devolvido em agent.id: é isto que deve armazenar no lado da aplicação, pois é a única referência estável a esta configuração.

Definir o Comportamento com Instruções

As instruções atuam como o prompt do sistema e são a alavanca principal para controlar o comportamento. O exemplo abaixo transforma um assistente genérico num especialista jurídico cujo âmbito, formato e limites estão explicitamente delimitados.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Legal Expert",
    description="Agent specialized in French business law.",
    instructions="""You are an expert in French business law.

Rules:
- Always respond in French
- Cite relevant legal articles
- Specify when a question requires a lawyer's opinion
- Structure your responses with headings and lists
- Never give definitive legal advice"""
)

Observe a estrutura deste prompt: uma definição de papel no início, seguida de regras numeradas. Esta organização por secções ajuda o modelo a priorizar as restrições. Seja específico quanto ao papel, tom e limites, em vez de escrever apenas «seja prestativo». Acima de tudo, antecipe casos limite — o que deve o agente fazer se a pergunta sair do seu domínio? A linha sobre consultar a opinião de um advogado aborda exatamente isto. Por fim, trate as instruções como código: vai testá-las e revê-las várias vezes antes de produzirem o comportamento esperado.

Controlar a Geração

Os completion_args configuram o amostrador, ou seja, a forma como o modelo escolhe as suas palavras. Um agente encarregado de relatar factos não necessita da mesma liberdade que um agente de brainstorming.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Precise Agent",
    description="Agent with controlled generation parameters.",
    instructions="Respond factually and concisely.",
    completion_args={
        "temperature": 0.2,    # Less creativity, more precision
        "top_p": 0.9,          # Probability nucleus
        "max_tokens": 2048     # Response length limit
    }
)
  • temperature — Varia de 0,0 (determinístico) a 1,0 (criativo). Para tarefas factuais, prefira 0,1–0,3.
  • top_p — Filtragem de probabilidade cumulativa. 0,9 é um valor padrão adequado.
  • max_tokens — Limite estrito de tokens de saída.

Equipar o Agente com Ferramentas

Um agente torna-se verdadeiramente autónomo quando pode agir para além do texto. A configuração seguinte concede-lhe acesso à web e execução de código: perante uma pergunta que compara taxas atuais, ele irá buscar os valores e calcular o resultado sem a sua intervenção.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Research Agent",
    description="Agent with web search and code execution.",
    instructions="Use web search for current information and code for calculations.",
    tools=[
        {"type": "web_search"},
        {"type": "code_interpreter"}
    ],
    completion_args={"temperature": 0.3, "top_p": 0.95}
)

As ferramentas disponíveis incluem: web_search, web_search_premium, code_interpreter, image_generation, document_library.

Gerir o Ciclo de Vida do Agente

Os seus agentes são recursos persistentes no lado da Mistral e vai administrá-los como qualquer outro recurso: encontrá-los, modificá-los, eliminá-los. A listagem é particularmente útil durante o desenvolvimento, onde rapidamente acaba com dezenas de agentes de teste cujos IDs perdeu.

# List all your agents
agents = client.beta.agents.list()
for a in agents.data:
    print(f"{a.name} ({a.id})")

# Retrieve an agent by its ID
agent = client.beta.agents.get(agent_id="ag-xxxxxxxx")

As atualizações são parciais: apenas os campos fornecidos são modificados; os outros permanecem como estão. Isto permite-lhe refinar instruções em produção sem redeclarar toda a configuração.

agent = client.beta.agents.update(
    agent_id=agent.id,
    instructions="New updated instructions.",
    tools=[{"type": "web_search"}, {"type": "code_interpreter"}]
)

A eliminação, no entanto, é permanente.

client.beta.agents.delete(agent_id=agent.id)

Exemplo Completo

Vamos reunir tudo num agente totalmente funcional: criação, conversa e leitura da resposta. Pode utilizar este script tal como está; basta alterar o nome e as instruções, e terá o seu próprio analista operacional em minutos.

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Create the agent
agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Tech Analyst",
    description="Analyzes technology trends with web sources.",
    instructions="""You are a technology analyst.
- Use web search for recent data
- Always cite your sources
- Structure your analyses into key points""",
    tools=[{"type": "web_search"}],
    completion_args={"temperature": 0.3}
)

# Start a conversation
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="What are the latest advancements in agentic AI in 2026?"
)

# Display the response
for entry in response.outputs:
    if hasattr(entry, "content"):
        print(entry.content)

O ciclo final merece um momento de atenção: itera sobre response.outputs em vez de ler um único campo porque um agente equipado com ferramentas produz múltiplas entradas — a execução da pesquisa e, depois, o texto. Este é o ponto chave a observar na próxima lição.

Pontos-chave

  • client.beta.agents.create() cria um agente com modelo, nome e descrição (obrigatórios)
  • As instruções definem o comportamento — esta é a alavanca principal
  • completion_args controlam a geração (temperature, top_p, max_tokens)
  • Um agente pode ter múltiplas ferramentas ativadas simultaneamente
  • Os agentes são configurações reutilizáveis, não instâncias de conversa