Tutoriais do framework de agentes

Começar a usar um notebook

Comece a usar o Agent Framework com um agente "Hello World" em um notebook.

Exemplos de agentes

Para conferir o código de exemplo de agentes de amostra, faça o download do arquivo .zip desta pasta do Google Drive para seu ambiente de desenvolvimento local.

No diretório de amostras, há agentes de demonstração. Instale as dependências no arquivo requirements.txt para um agente de demonstração específico:

pip install  -r samples/anthropic_demo/requirements.txt

Execute os comandos a seguir:

af web samples

af run samples/hello_world

Tutoriais

Esta página oferece tutoriais passo a passo para tarefas comuns ao trabalhar com o Agent Framework. Escolha um tutorial para começar.

Tutorial: integrar seus próprios dados a um agente

Este tutorial aborda diferentes métodos para fornecer seus próprios dados, conhecimentos ou documentos ao agente. A melhor abordagem depende do tamanho e do tipo de dados e do equilíbrio desejado entre latência e precisão.

Fornecer seus próprios dados

Há algumas maneiras de fornecer seus próprios dados / conhecimentos / documentos ao agente com base no tamanho, tipo e compensação de latência / precisão.

Tipo Pequena quantidade Valor grande
Texto simples Incorporar em instruções ou RAG RAG
Documentos Incorporar em instruções ou RAG RAG
Outras mídias
(imagens, áudios, vídeos etc.)		 WIP WIP

Os tutoriais a seguir têm mais informações sobre cada abordagem.

Incorporar dados em instruções

Uma maneira simples de fornecer uma pequena quantidade de documentos ao agente é incorporá-los nas instruções.

PDFs ou outros arquivos de texto podem ser convertidos em texto simples e incorporados às instruções.

Considerações

  • O conteúdo dos arquivos será enviado ao modelo. Portanto, quanto maior o arquivo, maior a latência e o custo.

  • O conteúdo será enviado ao modelo para todas as solicitações, mesmo que a consulta do usuário não tenha nada a ver com o conteúdo.

  • Você pode usar texto simples ou qualquer formato de texto legível, como Markdown, para seu arquivo.

Riscos de segurança

  • A incorporação de conteúdo dessa maneira tem alguns riscos de segurança, já que o servidor pode tratar o conteúdo dos documentos incorporados como instruções próprias.

  • Esse risco de segurança pode ser mitigado até certo ponto marcando claramente o início e o fim do conteúdo incorporado, conforme mostrado no exemplo abaixo.

  • Por causa desse risco, não incorpore conteúdo em que você não confia, como qualquer conteúdo gerado pelo usuário.

Exemplo

Para tornar as instruções legíveis, uma abordagem comum é carregar o arquivo e inseri-lo nas instruções usando a sintaxe de string f do Python.

Ele usa tags XML para separar o conteúdo do arquivo do restante das instruções. Você também pode usar outras formas de separação, desde que o modelo entenda. Por exemplo, tags como BEGIN_USER_GUIDE / END_USER_GUIDE.

def read_file(filename):
  file_path = os.path.join(os.path.dirname(__file__), filename)
  with open(file_path, 'r') as f:
    return f.read()

agent_framework_bot = Agent(
    # ...
    instruction=f"""You are an agent that answers user's questions about the Agent Framework.

You answer users' questions based on the user guide below:
<user_guide>
{read_file('user_guide.md')}
</user_guide>
"""
)

Usar a RAG

A geração aumentada de recuperação é um padrão comum para aumentar as respostas do modelo com seus próprios dados. Ela é particularmente útil para grandes quantidades de dados, porque indexa os dados e recupera apenas uma pequena parte deles que é relevante para a consulta.

O framework do agente oferece algumas maneiras de integração com vários sistemas diferentes de RAG.

Cenários Recomendações
Demonstrações / protótipos FilesRetrieval
Pequena quantidade de dados
(alguns documentos)		 FilesRetrieval
Solução RAG totalmente gerenciada VertexRagRetrieval
Soluções de RAG ou faça você mesmo LlamaIndexRetrieval

FilesRetrieval

O FilesRetrieval vai criar um repositório de vetores na memória quando o agente for iniciado. Ele adiciona latência e é limitado à memória e ao desempenho do ambiente de hospedagem da API. Portanto, essa opção é adequada apenas para demonstrações / protótipos ou produção com uma quantidade muito pequena de documentos.

O FilesRetrieval é criado com base no LlamaIndex. É necessário configurá-lo seguindo a documentação do LlamaIndex.

Depois de configurar, você pode colocar seus documentos em uma pasta e criar uma ferramenta de recuperação como esta:

company_policies_retrieval = FilesRetrieval(
    name='company_policies',
    description='Company policies about flight cancelation and rebooking.',
    input_dir=os.path.join(os.path.dirname(__file__), 'company_policies'),
)

root_agent = Agent(
  # ...
  tools=[company_policies_retrieval],
)

VertexRagRetrieval

O Vertex RAG Engine é um serviço totalmente gerenciado que processa a ingestão, transformação, embedding, indexação e recuperação de dados.

Para usá-lo, siga o Guia de início rápido para configurar seu corpus e transferir documentos. Em seguida, adicione a ferramenta ao seu agente.

company_policies_retrieval = VertexRagRetrieval(
    name='company_policies',
    description='Company policies about flight cancelation and rebooking.',
    rag_corpus_name='projects/.../locations/.../ragCorpora/...',
)
root_agent = Agent(
  # ...
  tools=[company_policies_retrieval],
)

Ao usar a Pesquisa Google, seu agente poderá acessar informações reais em tempo real e usar a Pesquisa Google para pesquisar perguntas.

Observações

  • O uso do Embasamento com a Pesquisa Google pode gerar cobranças adicionais.
  • Para o Gemini 1.5:
    • Quando você adiciona a ferramenta de pesquisa do Google a um agente, não é possível ter outras ferramentas para esse agente.
    • A ferramenta de pesquisa do Google é sempre executada, independentemente de a consulta precisar da Pesquisa Google ou não.
  • Para o Gemini 2.0 e versões mais recentes:
    • Você pode usar outras ferramentas enquanto usa a ferramenta de pesquisa do Google.
    • A ferramenta de pesquisa do Google é executada apenas quando o modelo considera que isso é necessário.
  • Os modelos de terceiros não são compatíveis com as ferramentas de pesquisa do Google.
  • Para usar a ferramenta da Pesquisa Google, é necessário seguir as diretrizes em Usar as Sugestões da Pesquisa Google, incluindo a exibição de um banner para mostrar consultas relacionadas. Nossa interface para desenvolvedores também segue essas regras.

Exemplo

Ativar a ferramenta de pesquisa do Google é muito simples. Basta adicionar google_search à sua lista de ferramentas.

from agents.tools import google_search

root_agent = Agent(
    # ...
    tools=[google_search],
)

Tutorial: avaliar a performance do seu agente

Avaliar o agente é crucial para garantir que ele funcione conforme o esperado e atenda aos seus padrões de qualidade. O Agent Framework oferece várias maneiras de avaliar o desempenho do agente usando arquivos de teste e critérios de avaliação.

Como a avaliação funciona

Cada arquivo de teste contém uma lista de consultas, trajetórias de ferramentas esperadas e respostas de referência. Os arquivos de teste podem ser organizados em pastas. Opcionalmente, uma pasta pode incluir um arquivo test_config.json que especifica os critérios de avaliação.

Exemplo de arquivo de teste

Um arquivo de teste contém uma sessão com consultas, uso esperado da ferramenta e respostas de referência. Veja um exemplo:

[
  {
    "query": "hi",
    "expected_tool_use": [],
    "reference": "Hello! What can I do for you?\n"
  },
  {
    "query": "roll a die for me",
    "expected_tool_use": [
      {
        "tool_name": "roll_die",
        "tool_input": {
          "sides": 6
        }
      }
    ]
  },
  {
    "query": "what's the time now?",
    "expected_tool_use": [],
    "reference": "I'm sorry, I cannot access real-time information, including the current time. My capabilities are limited to rolling dice and checking prime numbers.\n"
  }
]

Critérios de avaliação

Os critérios de avaliação em test_config.json definem como a performance do agente será medida:

  • tool_trajectory_avg_score: avaliar as trajetórias da ferramenta.
  • response_match_score: avalie as respostas.

Se nenhum critério de avaliação for fornecido, uma configuração padrão será aplicada.

Exemplo de critérios de avaliação (test_config.json)

Confira um exemplo de arquivo test_config.json que especifica critérios de avaliação personalizados:

{
  "criteria": {
    "tool_trajectory_avg_score": 1.0,
    "response_match_score": 0.8
  }
}
  • tool_trajectory_avg_score: definido como 1,0, o que significa que o uso da trajetória de ferramenta perfeita é esperado.
  • response_match_score: definido como 0,8, permitindo uma pequena margem de erro nas respostas do agente.

Formas de executar a avaliação

1. af web: executar avaliações pela interface da Web

É possível avaliar os agentes de forma interativa usando nossa interface baseada na Web.

Etapas:
  1. Inicie o servidor da Web executando: bash af web
  2. Na interface da Web:
    • Selecione um agente.
    • Clique em "Salvar sessão como arquivo de teste" para salvar uma sessão como um arquivo de teste.
    • Clique em "Run test file" para mostrar um pop-up com arquivos de teste na pasta do agente.
Arquivos de teste:

Os arquivos de teste são armazenados na mesma pasta que o agente. É possível atualizar manualmente ou adicionar arquivos de teste conforme necessário.

2. af test: executar testes na linha de comando.

É possível executar todos os arquivos de teste em uma pasta específica usando o comando af test. A pasta precisa conter a definição do agente e os arquivos de teste.

Exemplo:
af test samples/agent_folder

Esse comando localiza e executa todos os arquivos de teste (*.test.json) na pasta especificada.

3. pytest: executar testes de maneira programática.

Também é possível usar pytest para executar arquivos de teste como parte dos testes de integração.

Exemplo de comando:
pytest tests/integrations/
Exemplo de código de teste:

Confira um exemplo de caso de teste do pytest que executa um único arquivo de teste:

def test_with_single_test_file():
    """Test the agent's basic ability via a session file."""
    AgentEvaluator.evaluate(
        "tests.integration.fixture.home_automation_agent",
        "tests/integration/fixture/home_automation_agent/simple_test.test.json",
    )

Essa abordagem permite integrar as avaliações de agentes aos pipelines de CI/CD ou pacotes de teste maiores.