Início rápido

Siga este guia para colocar um agente em funcionamento com o SDK pelo caminho mais curto. Os exemplos em JavaScript e Python seguem os mesmos princípios. Primeiro, defina e execute um agente. Depois, adicione ferramentas e agentes especializados à medida que o fluxo de trabalho crescer.

Instale o SDK

Crie um projeto, instale o SDK e configure sua chave de API.

1234567# JavaScript
npm install @openai/agents zod

# Python
pip install openai-agents

export OPENAI_API_KEY=sk-...

Crie e execute seu primeiro agente

Comece com um agente dedicado a uma tarefa específica e um único turno de conversa. O SDK chama o modelo e retorna um objeto de resultado com a saída final e o histórico da execução.

1
2
3
4
5
6
7
8
9
10import { Agent, run } from "@openai/agents";

const agent = new Agent({
  name: "History tutor",
  instructions: "You answer history questions clearly and concisely.",
  model: "gpt-6-astra",
});

const result = await run(agent, "When did the Roman Empire fall?");
console.log(result.finalOutput);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import asyncio

from agents import Agent, Runner

agent = Agent(
    name="History tutor",
    instructions="You answer history questions clearly and concisely.",
    model="gpt-6-astra",
)


async def main() -> None:
    result = await Runner.run(agent, "When did the Roman Empire fall?")
    print(result.final_output)


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

Você deverá ver uma resposta breve no terminal. Quando esse ciclo funcionar, mantenha a estrutura e adicione recursos aos poucos. Assim, você evita começar com uma arquitetura complexa de múltiplos agentes.

Leve o estado para o próximo turno

O resultado da primeira execução também permite escolher qual estado usar no segundo turno.

Após uma transferência de controle, reutilize lastAgent se o mesmo especialista precisar continuar conduzindo a conversa no próximo turno.

Adicione uma ferramenta ao agente

Em geral, o primeiro recurso que você adiciona é uma ferramenta definida como função ou uma ferramenta hospedada pela OpenAI, como a pesquisa na Web ou a pesquisa em arquivos.

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

const historyFunFact = tool({
  name: "history_fun_fact",
  description: "Return a short history fact.",
  parameters: z.object({}),
  async execute() {
    return "Sharks are older than trees.";
  },
});

const agent = new Agent({
  name: "History tutor",
  instructions:
    "Answer history questions clearly. Use history_fun_fact when it helps.",
  tools: [historyFunFact],
});

const result = await run(
  agent,
  "Tell me something surprising about ancient life on Earth."
);

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
28import asyncio

from agents import Agent, Runner, function_tool


@function_tool
def history_fun_fact() -> str:
    """Return a short history fact."""
    return "Sharks are older than trees."


agent = Agent(
    name="History tutor",
    instructions="Answer history questions clearly. Use history_fun_fact when it helps.",
    tools=[history_fun_fact],
)


async def main() -> None:
    result = await Runner.run(
        agent,
        "Tell me something surprising about ancient life on Earth.",
    )
    print(result.final_output)


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

Consulte o guia Como usar ferramentas, que se aplica às duas linguagens de programação, quando precisar usar ferramentas hospedadas, pesquisar ferramentas ou usar agentes como ferramentas.

Adicione agentes especializados

Um próximo passo comum é dividir o fluxo de trabalho entre especialistas. Um agente roteador delega tarefas a eles por meio de transferências de controle.

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

const historyTutor = new Agent({
  name: "History tutor",
  instructions: "Answer history questions clearly and concisely.",
});

const mathTutor = new Agent({
  name: "Math tutor",
  instructions: "Explain math step by step and include worked examples.",
});

const triageAgent = Agent.create({
  name: "Homework triage",
  instructions: "Route each homework question to the right specialist.",
  handoffs: [historyTutor, mathTutor],
});

const result = await run(
  triageAgent,
  "Who was the first president of the United States?"
);

console.log(result.finalOutput);
console.log(result.lastAgent?.name);

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
34import asyncio

from agents import Agent, Runner

history_tutor = Agent(
    name="History tutor",
    handoff_description="Specialist for history questions.",
    instructions="Answer history questions clearly and concisely.",
)

math_tutor = Agent(
    name="Math tutor",
    handoff_description="Specialist for math questions.",
    instructions="Explain math step by step and include worked examples.",
)

triage_agent = Agent(
    name="Homework triage",
    instructions="Route each homework question to the right specialist.",
    handoffs=[history_tutor, math_tutor],
)


async def main() -> None:
    result = await Runner.run(
        triage_agent,
        "Who was the first president of the United States?",
    )
    print(result.final_output)
    print(result.last_agent.name)


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

Examine os rastreamentos desde o início

O fluxo padrão de execução do SDK no servidor inclui rastreamento. Assim que a primeira execução funcionar, abra o painel de rastreamentos para examinar as chamadas ao modelo e às ferramentas, as transferências de controle e os mecanismos de proteção antes de começar a ajustar os prompts.

Próximos passos

Depois que a primeira execução funcionar, escolha o guia correspondente ao próximo recurso que você quer adicionar.