Anatomia do SDK: Agente, Executor, Ferramenta, Salvaguarda
Nesta página
Anatomia do SDK: Agente, Executor, Ferramenta, Salvaguarda
O SDK de Agentes assenta em quatro conceitos fundamentais: Agente, Executor, Ferramenta e Salvaguarda. Cada um tem uma única responsabilidade. A interação entre eles — quem decide, quem executa, quem age, quem controla — é o que torna o SDK legível assim que o interiorizar.
Agente — O cérebro
Define instruções, modelo, ferramentas e salvaguardas. Esta é a configuração do seu agente.
Executor — O motor de execução
Orquestra o ciclo de raciocínio: envia pedidos, executa ferramentas e gere as transferências.
Ferramenta — Capacidades
Funções que o agente pode invocar: pesquisa na Web, execução de código, chamadas de API e muito mais.
Salvaguarda — Segurança
Valida as entradas e saídas do agente. Bloqueia pedidos perigosos ou fora do tema.
Agente: Configuração
A classe Agent é puramente declarativa: não executa nada, apenas descreve. Tudo o que define o comportamento do seu agente reside num único local.
from agents import Agent, function_tool, WebSearchTool
@function_tool
def get_price(product: str) -> str:
"""Retrieves the price of a product."""
prices = {"widget": "€29.99", "gadget": "€49.99"}
return prices.get(product, "Unknown product")
agent = Agent(
name="Sales Agent",
instructions="""You are a sales agent for an online store.
Help customers find products and learn their prices.
Always respond in French with a professional tone.""",
model="gpt-5.6-terra",
tools=[get_price, WebSearchTool()],
handoff_description="Agent specialized in selling products",
output_type=None, # or a Pydantic type to enforce an output format
)
Principais parâmetros do Agent:
name: Identificador legível por humanos para o agenteinstructions: O prompt do sistema que define o comportamentomodel: O modelo a utilizar (gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna)tools: A lista de ferramentas disponíveishandoff_description: Descrição utilizada para transferências entre agentesoutput_type: Tipo Pydantic para estruturar a saída
Executor: Execução
O Runner é o motor que executa o seu agente. Gere todo o ciclo e está disponível em três modos, dependendo do seu contexto de chamada.
from agents import Runner
# Modo síncrono (desenvolvimento)
result = Runner.run_sync(agent, "What is the price of the widget?")
# Modo assíncrono (produção)
result = await Runner.run(agent, "What is the price of the widget?")
# Modo de streaming (tempo real)
result = Runner.run_streamed(agent, "What is the price of the widget?")
Independentemente do modo, recebe um RunResult, que contém muito mais do que apenas a resposta visível. O histórico completo permite retomar uma conversa, e o last_agent torna-se essencial assim que vários agentes se transferem uns aos outros.
result = Runner.run_sync(agent, "What is the price of the widget?")
# A resposta final do agente
print(result.final_output)
# O histórico completo da conversa
print(result.to_input_list())
# O último agente ativo (útil com transferências)
print(result.last_agent.name)
Ferramenta: Capacidades
O SDK suporta três formas de declarar ferramentas, da mais comum à mais arquitetural.
1. Ferramentas de função (mais comum)
Uma função Python decorada torna-se uma ferramenta; o SDK infere o esquema a partir da assinatura e da docstring.
from agents import function_tool
@function_tool
def send_email(recipient: str, subject: str, body: str) -> str:
"""Sends an email to a recipient."""
# Your sending logic here
return f"Email sent to {recipient}"
2. Ferramentas alojadas pela OpenAI
Estas ferramentas são executadas no lado da OpenAI: não escreve a lógica de pesquisa nem o sandbox Python.
from agents import WebSearchTool, FileSearchTool, CodeInterpreterTool
tools = [
WebSearchTool(), # Web search
FileSearchTool(vector_store_ids=["vs_123"]), # File search
CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}), # Code execution
]
3. Agentes como ferramentas
Um agente pode utilizar outro como ferramenta. O coordenador abaixo delega a pesquisa sem jamais ceder o controlo da conversa, o que distingue isto de uma transferência.
search_agent = Agent(
name="Researcher",
instructions="You look up precise information.",
tools=[WebSearchTool()],
)
primary_agent = Agent(
name="Coordinator",
instructions="You coordinate research.",
tools=[search_agent.as_tool(
tool_name="search",
tool_description="Performs in-depth research"
)],
)
Salvaguarda: Segurança
Uma salvaguarda é um agente de controlo colocado à frente do seu agente de negócio. Aqui, um verificador determina se o pedido diz respeito a vendas antes de o agente de vendas responder.
from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner
guardrail_agent = Agent(
name="Verifier",
instructions="Determine whether the request concerns sales. Respond true or false.",
output_type=bool,
)
async def verify_topic(ctx, agent, input_data):
result = await Runner.run(guardrail_agent, input_data, context=ctx)
return GuardrailFunctionOutput(
output_info=result.final_output,
tripwire_triggered=not result.final_output,
)
protected_agent = Agent(
name="Protected Sales Agent",
instructions="You are a sales agent.",
input_guardrails=[
InputGuardrail(guardrail_function=verify_topic),
],
)
Se a salvaguarda for acionada (tripwire_triggered=True), a execução para e é lançada uma exceção InputGuardrailTripwireTriggered. Planeie capturar isto na sua aplicação; caso contrário, devolverá um erro 500 a um utilizador que simplesmente fez uma pergunta fora do tema.
Como estas peças interagem
O fluxo completo decorre da seguinte forma:
- Chama
Runner.run(agent, message) - O Executor verifica as salvaguardas de entrada
- O Executor envia a mensagem para o modelo do Agente
- Se o modelo solicitar uma ferramenta, o Executor executa-a
- O Executor devolve o resultado ao modelo (volta ao passo 3)
- Quando o modelo produz uma resposta final, o Executor verifica as salvaguardas de saída
- O
RunResulté devolvido
Pontos-chave
Agentdefine o comportamento (instruções, modelo, ferramentas)Runnerorquestra a execução do ciclo do agente- Declare ferramentas com
@function_tool, classes integradas ou.as_tool() - As salvaguardas validam entradas e saídas para segurança
RunResultcontém a resposta final e o histórico completo