Criar um Agente com a API Python
Nesta página
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_argscontrolam 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