Definições de agentes

O agente é a unidade básica de um fluxo de trabalho criado com o SDK. Ele reúne um modelo, instruções e recursos opcionais que definem seu comportamento durante a execução, como ferramentas, mecanismos de proteção, servidores MCP, transferências entre agentes e saídas estruturadas.

O que configurar no agente

Use a configuração do agente para definir o que é específico daquele especialista.

Comece com um agente dedicado a uma tarefa

Defina o agente mais simples capaz de assumir uma tarefa bem delimitada. Adicione outros agentes apenas quando precisar dividir responsabilidades ou usar instruções, conjuntos de ferramentas ou políticas de aprovação diferentes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import { Agent, tool } from "@openai/agents";
import { z } from "zod";

const getWeather = tool({
  name: "get_weather",
  description: "Return the weather for a given city.",
  parameters: z.object({ city: z.string() }),
  async execute({ city }) {
    return `The weather in ${city} is sunny.`;
  },
});

const agent = new Agent({
  name: "Weather bot",
  instructions: "You are a helpful weather bot.",
  model: "gpt-6-astra",
  tools: [getWeather],
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15from agents import Agent, function_tool


@function_tool
def get_weather(city: str) -> str:
    """Return the weather for a given city."""
    return f"The weather in {city} is sunny."


agent = Agent(
    name="Weather bot",
    instructions="You are a helpful weather bot.",
    model="gpt-6-astra",
    tools=[get_weather],
)

Configure instruções, transferências e saídas

Três decisões de configuração merecem atenção especial.

• Comece com instruções estáticas em instructions. Se as orientações dependerem do usuário, do tenant ou do contexto de execução atual, use uma função de callback para gerar as instruções dinamicamente em vez de concatenar strings no ponto de chamada.
• Escreva uma descrição breve e específica em handoffDescription para que os agentes responsáveis pelo roteamento saibam quando escolher esse especialista.
• Use outputType quando o código que consome a saída precisar de dados tipados em vez de texto livre.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import { Agent, run } from "@openai/agents";
import { z } from "zod";

const calendarEvent = z.object({
  name: z.string(),
  date: z.string(),
  participants: z.array(z.string()),
});

const agent = new Agent({
  name: "Calendar extractor",
  instructions: "Extract calendar events from text.",
  outputType: calendarEvent,
});

const result = await run(agent, "Dinner with Priya and Sam on Friday.");

console.log(result.finalOutput);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30import asyncio

from pydantic import BaseModel

from agents import Agent, Runner


class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]


agent = Agent(
    name="Calendar extractor",
    instructions="Extract calendar events from text.",
    output_type=CalendarEvent,
)


async def main() -> None:
    result = await Runner.run(
        agent,
        "Dinner with Priya and Sam on Friday.",
    )
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

Use prompt para fazer referência a uma configuração de prompt armazenada na API Responses em vez de incluir o prompt de sistema inteiro no código.

Separe o contexto local do contexto do modelo

O SDK permite passar o estado do aplicativo e suas dependências para uma execução sem enviá-los ao modelo. Use esse recurso para disponibilizar informações sobre o usuário autenticado, clientes de banco de dados, objetos de log e funções auxiliares.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";

const fetchUserAge = tool({
  name: "fetch_user_age",
  description: "Return the age of the current user.",
  parameters: z.object({}),
  // TypeScript users can type this as RunContext<{ name: string; uid: number }>.
  async execute(_args, runContext) {
    return `User ${runContext?.context.name} is 47 years old`;
  },
});

const agent = new Agent({
  name: "Assistant",
  tools: [fetchUserAge],
});

const result = await run(agent, "What is the age of the user?", {
  context: { name: "John", uid: 123 },
});

console.log(result.finalOutput);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35import asyncio
from dataclasses import dataclass

from agents import Agent, RunContextWrapper, Runner, function_tool


@dataclass
class UserInfo:
    name: str
    uid: int


@function_tool
async def fetch_user_age(wrapper: RunContextWrapper[UserInfo]) -> str:
    """Fetch the age of the current user."""
    return f"The user {wrapper.context.name} is 47 years old."


agent = Agent[UserInfo](
    name="Assistant",
    tools=[fetch_user_age],
)


async def main() -> None:
    result = await Runner.run(
        agent,
        "What is the age of the user?",
        context=UserInfo(name="John", uid=123),
    )
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

A distinção está em quem tem acesso às informações.

• O modelo tem acesso ao histórico da conversa.
• Seu código tem acesso ao contexto da execução.

Se o modelo precisar de uma informação, inclua-a nas instruções ou na entrada, ou disponibilize-a por meio de recuperação de informações ou de uma ferramenta. Se apenas o ambiente de execução precisar dela, mantenha-a no contexto local.

Quando dividir um agente em vários

Divida um agente quando um único especialista não deva assumir a responsabilidade pela resposta inteira ou quando houver diferenças significativas entre os recursos necessários. Considere a divisão nas situações a seguir.

• Um especialista precisa de um conjunto diferente de ferramentas ou de recursos MCP.
• Um especialista precisa de outra política de aprovação ou de outro mecanismo de proteção.
• Uma ramificação do fluxo de trabalho exige outro modelo ou estilo de saída.
• Você quer que o roteamento apareça explicitamente nos rastreamentos em vez de concentrá-lo em um único prompt extenso.

Próximos passos

Depois de definir o primeiro especialista, escolha o guia que aborda a próxima decisão sobre o fluxo de trabalho.