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

Anatomia do SDK: Agente, Executor, Ferramenta, Salvaguarda

Aula 5 de 25 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Anatomia do SDK: Agente, Executor, Ferramenta, Salvaguarda
  2. Agente: Configuração
  3. Executor: Execução
  4. Ferramenta: Capacidades
  5. Salvaguarda: Segurança
  6. Como estas peças interagem
  7. Pontos-chave

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.

1

Agente — O cérebro

Define instruções, modelo, ferramentas e salvaguardas. Esta é a configuração do seu agente.

2

Executor — O motor de execução

Orquestra o ciclo de raciocínio: envia pedidos, executa ferramentas e gere as transferências.

3

Ferramenta — Capacidades

Funções que o agente pode invocar: pesquisa na Web, execução de código, chamadas de API e muito mais.

4

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 agente
  • instructions: O prompt do sistema que define o comportamento
  • model: O modelo a utilizar (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
  • tools: A lista de ferramentas disponíveis
  • handoff_description: Descrição utilizada para transferências entre agentes
  • output_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:

  1. Chama Runner.run(agent, message)
  2. O Executor verifica as salvaguardas de entrada
  3. O Executor envia a mensagem para o modelo do Agente
  4. Se o modelo solicitar uma ferramenta, o Executor executa-a
  5. O Executor devolve o resultado ao modelo (volta ao passo 3)
  6. Quando o modelo produz uma resposta final, o Executor verifica as salvaguardas de saída
  7. O RunResult é devolvido

Pontos-chave

  • Agent define o comportamento (instruções, modelo, ferramentas)
  • Runner orquestra 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
  • RunResult contém a resposta final e o histórico completo