Adicionar uma Ferramenta de Função a um Agente usando o ADK

Este tutorial aborda as etapas para adicionar uma ferramenta de função a um agente existente nos Agentes do Generative AI.

As ferramentas de função permitem que o agente use funções personalizadas definidas localmente como ferramentas. Eles são muito flexíveis e particularmente úteis para casos corporativos devido ao processamento local, à fácil autenticação e à integração perfeita com a funcionalidade existente.

Neste exemplo, temos um agente meteorológico equipado com uma ferramenta de função personalizada. Isso também é conhecido como agente de chamada de função.

Observação

As ferramentas de função são executadas localmente ao seu lado.

O que é enviado a um agente remoto nos servidores do OCI é a definição da função (nome da função, parâmetros da função e suas descrições). Os servidores OCI não acessam a implementação da função.

Visão Geral

Quando uma consulta climática é feita, o agente remoto faz com que a classificação de intenção use a ferramenta get_weather. Por exemplo, com base na consulta de linguagem natural Is it cold in Seattle?, o agente remoto preenche o slot do argumento e faz a solicitação.

O agente envia uma solicitação que contém as ações necessárias para o aplicativo cliente. Nesse caso, a ação necessária para o cliente é chamar a ferramenta de função get_weather com um argumento location=Seattle.

O Agent Development Kit (ADK) faz o seguinte:

analisa a ação necessária
localiza a função local registrada
executa esta função com os argumentos específicos
captura a saída da chamada de função
envia a saída de volta para o agente remoto, de modo que o agente possa usar essa saída para gerar uma resposta ao prompt do usuário

Diagrama

Pré-requisitos

Antes de criar um aplicativo de agente, execute estas etapas:

Na máquina que executa seu código, configure um arquivo de configuração da API do OCI. Certifique-se de que a configuração se refira a uma região na qual os Generative AI Agents estão hospedados.

Criar um ambiente virtual:

python3 -m venv <myenv>

Ative o ambiente virtual.

source <myenv>/bin/activate

Instale o ADK. O Python ADK requer o Python 3.10 ou posterior.
```
pip install "oci[adk]
```

Configurar um Compartimento para Desenvolvimento

Para configurar o compartimento, siga estas etapas:

Peça a um administrador para adicionar a seguinte política do serviço IAM para você:
```
allow <a-group-your-user-name-belongs-to> to manage all-resources in compartment <your-compartment-name>
```
Importante

É conveniente para um tutorial fornecer acesso completo a um compartimento. No entanto, na produção, use políticas mais restritivas para limitar o acesso ao agente. Consulte Obtendo Acesso a Agentes de IA Generativa.
Acesse a Console do Oracle Cloud Infrastructure.
Abra o menu de navegação e selecione Identidade e Segurança. Em Identidade, selecione Compartimentos.
Selecione Criar Compartimento.
Preencha as seguintes informações:
- Nome: <your-compartment-name>
- Descrição: Compartment for <your-description>.
- Compartimento-pai: <your-tenancy>(root)
Selecione Criar compartimento.

Referência: Criar um compartimento

Criar um Agente

Na barra de navegação da Console, selecione a mesma região que você selecionou para o arquivo de configuração na seção anterior.
Na página de lista Agentes, selecione Criar agente. Se precisar de ajuda para localizar a página da lista, consulte Listando Agentes.
Digite as seguintes informações:
- Nome: <your-agent-name>
- Compartimento: Selecione um compartimento para o qual você tenha permissão para trabalhar.
- Descrição: Agente sem ferramentas iniciais. Adicionando ferramentas com o ADK.
- Mensagem de boas-vindas: Deixe em branco.
- Instruções de roteamento: Deixe em branco.
Selecione Próximo para navegar até a etapa Adicionar Ferramenta. Ignore esta página e não adicione ferramentas.
Selecione Próximo.
(Opcional) Selecione Criar automaticamente um ponto final para este agente para criar um ponto final quando o agente for criado e manter todas as outras opções padrão.
Selecione Próximo e, em seguida, Criar Agente.

Observação

Aceite os termos da licença, se solicitado.
Aguarde o agente se tornar ativo.

Reunir Informações Obrigatórias

Em seu ambiente, copie a região que você configurou para o arquivo de configuração em um bloco de notas. Por exemplo, us-chicago-1.
Na Console, na página de lista Agentes, selecione o agente que você criou neste tutorial. Se precisar de ajuda para localizar a página da lista, consulte Listando Agentes.
Copie o OCID do agente e cole-o em um bloco de notas para a próxima seção.

OCID do agente de exemplo: ocid1.genaiagent.oc1.us-chicago-1.<unique-id>
Selecione o Ponto Final para este agente.
Copie o OCID do ponto final e cole-o em um bloco de notas para a próxima seção.

Exemplo de OCID do ponto final: ocid1.genaiagentendpoint.oc1.us-chicago-1.<unique-id>
Navegue até Identity and Security e selecione Compartments. Selecione o compartimento com o agente. Copie o OCID do compartimento e cole-o em um bloco de notas.

OCID do compartimento de exemplo: ocid1.compartment.oc1..<unique-id>

Criar um Arquivo Local

No terminal, vá até o diretório home.
Crie um diretório chamado ADK.
Altere para o diretório ADK.
Crie um arquivo chamado weather_agent.py.

Cole o código a seguir em weather-agent.py.

Substitua <region-where-agent-is-created> e <your-agent-endpoint> pelos valores que você reuniu.

from typing import Dict
from adk import Agent, AgentClient, tool

@tool
def get_weather(location: str) -> Dict[str, str]:
    """Get the weather for a given location"""
    return {"location": location, "temperature": 72, "unit": "F"}


def main():
    # Create a client with your authentication details
    client = AgentClient(
        auth_type="api_key",
        profile="DEFAULT",
        region="<region-where-agent-is-created>"
    )

    # Instantiate the agent with your agent endpoint ID and the tool

    agent = Agent(
        client=client,
        agent_endpoint_id="<your-agent-endpoint>",
        instructions="Perform weather queries using the given tools.",
        tools=[get_weather]
    )

    # Set up the agent (configures instructions and tools in the remote agent resource)
    agent.setup()

    # Run the agent with an input
    input = "Is it cold in Seattle?"
    response = agent.run(input)

    # Print the response
    response.pretty_print()

if __name__ == "__main__":
    main()

Adicionar a ferramenta

Importante

Se você tiver escolhido um agente existente em vez de criar um novo para este tutorial, antes de executar este arquivo, certifique-se de que o agente remoto não tenha ferramentas. Este programa exclui todas as ferramentas do agente remoto, a menos que seja a ferramenta chamada ferramenta get_weather. Se encontrar uma ferramenta remota get_weather, ela atualizará a ferramenta remota para ser sincronizada com a ferramenta local.

Na Console, navegue até a página de detalhes do agente e anote os valores.
- Instruções de roteamento: Deve estar em branco.
- Selecione Ferramentas. A lista de ferramentas deve estar vazia.
Execute o arquivo Python, get_weather
```
python3 weather-agent.py
```

Na saída, revise os nomes de função local e remota e certifique-se de que a ferramenta get_weather esteja sendo adicionada ao agente remoto. Exemplo de saída:

Waiting for agent to be active...
╭─ Local and remote function tools found ─╮
│ Local function tools (1):               │
│ ['get_weather']                         │
│                                         │
│ Remote function tools (0):              │
│ []                                      │
╰─────────────────────────────────────────╯
Found local tool not in remote tools: get_weather. Adding it to the remote agent...
Waiting for tool to be active...
Checking synchronization of local and remote RAG tools...                                                             
No active remote RAG tools found. No local RAG tool to add.

Na Console, navegue até a página de detalhes do agente e assista às atualizações.
- Na página de detalhes do agente, as Instruções de roteamento são alteradas de branco para Perform weather queries using the given tools.
- Selecione Ferramentas. A ferramenta, get_weather, aparece na lista de ferramentas.
- Selecione get_weather e, em solicitações de serviço, verifique se a operação CREATE_TOOL foi bem-sucedida.

Ler as Saídas

Na saída, leia a mensagem do usuário. Exemplo de saída:


                                                      
╭──────────────────────────────────── Chat request to remote agent ─────────────────────────────────────╮
│ (Local --> Remote)                                                                                    │
│                                                                                                       │
│ user message:                                                                                         │
│ Is it cold in Seattle?                                                                                │
│                                                                                                       │
│ performed actions by client:                                                                          │
│ []                                                                                                    │
│                                                                                                       │
│ session id:                                                                                           │
│ ocid1.genaiagentsession.<unique-id>                                                          │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯

Leia a resposta do chat. Exemplo de saída:


╭────────────────── Chat response from remote agent ──────────────────╮
│ (Local <-- Remote)                                                  │
│                                                                     │
│ agent message:                                                      │
│ null                                                                │
│                                                                     │
│ required actions for client to take:                                │
│ [                                                                   │
│     {                                                               │
│         "action_id": "<unique-id>",        │
│         "required_action_type": "FUNCTION_CALLING_REQUIRED_ACTION", │
│         "function_call": {                                          │
│             "name": "get_weather",                                  │
│             "arguments": "{\"location\": \"Seattle\"}"              │
│         }                                                           │
│     }                                                               │
│ ]                                                                   │
╰─────────────────────────────────────────────────────────────────────╯

Leia a chamada de função solicitada pelo agente. Exemplo de saída:


╭─ Function call requested by agent and mapped local handler function ─╮
│ Agent function tool name:                                            │
│ get_weather                                                          │
│                                                                      │
│ Agent function tool call arguments:                                  │
│ {'location': 'Seattle'}                                              │
│                                                                      │
│ Mapped local handler function name:                                  │
│ get_weather                                                          │
╰──────────────────────────────────────────────────────────────────────╯

Leia o resultado da execução da função. Exemplo de saída:


╭─────── Obtained local function execution result ────────╮
│ {'location': 'Seattle', 'temperature': 72, 'unit': 'F'} │
╰─────────────────────────────────────────────────────────╯

Leia a solicitação de chat para a saída de exemplo do agente remoto:


╭──────────────────────────────────── Chat request to remote agent ─────────────────────────────────────╮
│ (Local --> Remote)                                                                                    │
│                                                                                                       │
│ user message:                                                                                         │
│ null                                                                                                  │
│                                                                                                       │
│ performed actions by client:                                                                          │
│ [                                                                                                     │
│     {                                                                                                 │
│         "action_id": "<unique-id>",                                          │
│         "performed_action_type": "FUNCTION_CALLING_PERFORMED_ACTION",                                 │
│         "function_call_output": "{\"location\": \"Seattle\", \"temperature\": 72, \"unit\": \"F\"}"   │
│     }                                                                                                 │
│ ]                                                                                                     │
│                                                                                                       │
│ session id:                                                                                           │
│ ocid1.genaiagentsession.oc1.us-chicago-1.xxx                                                          │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯

Leia a resposta de chat da saída de exemplo do agente remoto:


╭─────────────────────────────── Chat response from remote agent ────────────────────────────────╮
│ (Local <-- Remote)                                                                             │
│                                                                                                │
│ agent message:                                                                                 │
│ {                                                                                              │
│     "role": "AGENT",                                                                           │
│     "content": {                                                                               │
│         "text": "It's not cold in Seattle. The current temperature is 72 degrees Fahrenheit.", │
│         "citations": null,                                                                     │
│         "paragraph_citations": null                                                            │
│     },                                                                                         │
│     "time_created": "2025-04-10T18:47:33.617000+00:00"                                         │
│ }                                                                                              │
│                                                                                                │
│ required actions for client to take:                                                           │
│ null                                                                                           │
╰────────────────────────────────────────────────────────────────────────────────────────────────╯

Leia a resposta de execução do agente que está em linguagem natural. Exemplo de saída:


╭──────────────────────────────────────────────── Agent run response ────────────────────────────────────────────────╮
│ agent text message:                                                                                                │
│ It's not cold in Seattle. The current temperature is 72 degrees Fahrenheit.                                        │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Remover a ferramenta

No seu ambiente local, crie um arquivo chamado list_agent_tools.py com o conteúdo a seguir. Atualize também todas as variáveis de ID com suas informações de OCID.

import json
from adk import AgentClient



def main():

    agent_id = "ocid1.genaiagent.<unique-id>"
    agent_compartment_id = "<your-compartment-ocid>"
    region_id = "<your-region-id>"
    # Enter an OCI region such as "us-chicago-1" or airport code such as "ORD"

    # Create a client with your authentication details
    client = AgentClient(
        auth_type="api_key",
        profile="DEFAULT",
        region=region_id
    )


    # Find the tools of the following agent in the following compartment
    tool_list = client.find_tools(agent_compartment_id, agent_id)

    json_str = json.dumps(tool_list, indent=4)

    

    print(json_str)

    for item in tool_list:
        print(f"Tool Name: {item.get('display_name')}  \nTool OCID: {item.get('id')}")


if __name__ == "__main__":
    main()

Esse script chama a operação find_tool do cliente e retorna todas as ferramentas de um agente especificado em um compartimento especificado.

Verifique a saída:

[
    {
    "id": "ocid1.genaiagenttool.<unique-id>",
        "lifecycle_state": "ACTIVE",
        "time_created": "2025-04-10T21:49:19.350000+00:00",
        "time_updated": "2025-04-10T21:49:42.132000+00:00",
        "display_name": "get_weather",
        "description": "Get the weather for a given location created by ADK",
        "compartment_id": "<your-compartment-ocid>",
                                "agent_id": "ocid1.genaiagent.<unique-id>",
        "tool_config": {
            "tool_config_type": "FUNCTION_CALLING_TOOL_CONFIG",
            "function": {
                "name": "get_weather",
                "description": "Get the weather for a given location",
                "parameters": {
                    "type": "object",
                    "properties": "{\"location\": {\"type\": \"string\"}}",
                    "required": "['location']"
                }
            }
        },
        "metadata": null,
        "freeform_tags": {
            "ModifiedBy": "ADK",
            "CreatedBy": "ADK"
        },
        "defined_tags": {
            "Oracle-Tags": {
                "CreatedBy": "john.doe@example.com",
                "CreatedOn": "2025-04-10T21:49:19.277Z"
            }
        },
        "system_tags": {}
    }
]
Tool Name: get_weather  
Tool OCID: ocid1.genaiagenttool.oc1.us-chicago-1.amaa<your-ocid>

Crie um arquivo chamado delete_tools.py e copie as informações a seguir para usar a operação delete_tool e excluir o weather_tool. Atualize também todas as variáveis de ID com suas informações de OCID.

import json
from adk import AgentClient



def main():

agent_id = "ocid1.genaiagent.<unique-id>"
    agent_compartment_id = "<your-compartment-ocid>"
    endpoint_id = "ocid1.genaiagentendpoint.<unique-id>"
    region_id = "<your-region-id>"

    # Create a client with your authentication details
    client = AgentClient(
        auth_type="api_key",
        profile="DEFAULT",
        region=region_id
    )


    # Find the tools of the following agent in the following compartment
    tool_list = client.find_tools(agent_compartment_id, agent_id)

    json_str = json.dumps(tool_list, indent=4)

    

    print(json_str)

    for item in tool_list:
        print(f"Tool Name: {item.get('display_name')}  \nTool OCID: {item.get('id')}")

    for item in tool_list:
        print(f"Deleting tool {item.get('display_name')} with tool OCID: {item.get('id')}")
        client.delete_tool(item.get('id'))

    print ("Tool deleted!")

if __name__ == "__main__":
    main()

Na Console, vá para a página de detalhes do agente e veja se a ferramenta foi excluída.
Desativar o ambiente virtual.
decativate

Documentação do Oracle Cloud Infrastructure