Compartilhar via

Criar um agente de conhecimento no Azure AI Search

Observação

Esse recurso está atualmente em versão prévia pública. Essa visualização é fornecida sem um contrato de nível de serviço e não é recomendada para utilização em produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.

Na Pesquisa de IA do Azure, um agente de conhecimento é um recurso de nível superior que representa uma conexão com um modelo de conclusão de chat para uso em cargas de trabalho de recuperação agente. Um agente de conhecimento é usado pelo método de recuperação em um pipeline de recuperação de informações alimentado por LLM.

Um agente de conhecimento especifica:

  • Uma fonte de conhecimento (uma ou mais) que aponta para um conteúdo pesquisável
  • Um modelo de conclusão de chat que oferece funcionalidades de raciocínio para o planejamento de consultas e formulação de respostas
  • Propriedades para otimização de desempenho (limitar o tempo de processamento da consulta)

Depois de criar um agente de conhecimento, você pode atualizar suas propriedades a qualquer momento. Se o agente de conhecimento estiver em uso, as atualizações entrarão em vigor no próximo trabalho.

Importante

A versão prévia de 01/08/2025 introduz alterações interruptivas para agentes de conhecimento existentes. Esta versão de visualização requer uma ou mais definições de knowledgeSource. Recomendamos migrar o código existente para as novas APIs o quanto antes.

Pré-requisitos

Para seguir as etapas neste guia, recomendamos o Visual Studio Code com um cliente REST para enviar chamadas prévias da API REST para o Azure AI Search ou a extensão python e o pacote Jupyter.

Implantar um modelo para recuperação de agente

Verifique se você tem um modelo com suporte que o Azure AI Search pode acessar. As instruções a seguir presumem o Modelo da Fábrica de IA do Azure como provedor.

  1. Entre no portal do Azure AI Foundry.

  2. Implante um modelo com suporte usando estas instruções.

  3. Verifique se a identidade gerenciada do serviço de pesquisa tem permissões de usuário dos Serviços Cognitivos no recurso Azure OpenAI.

    Se você estiver testando localmente, também precisará de permissões de usuário dos Serviços Cognitivos .

Modelos com suporte

Use o Azure OpenAI ou um modelo de software livre equivalente:

  • gpt-4o
  • gpt-4o-mini
  • gpt-4.1
  • gpt-4.1-nano
  • gpt-4.1-mini
  • gpt-5
  • gpt-5-nano
  • gpt-5-mini

Configurar o acesso

O Azure AI Search precisa de acesso ao modelo de conclusão do chat. Você pode usar a autenticação baseada em chave ou de função (recomendado).

Se você estiver usando a autenticação baseada em função, em seu recurso do Azure OpenAI, atribua a função de Usuário dos Serviços Cognitivos a uma identidade gerenciada do serviço de pesquisa.

No Azure, você deve ter permissões de Proprietário ou Administrador de Acesso de Usuário no provedor de modelo para atribuir funções.

  1. Configurar a Pesquisa de IA do Azure para usar uma identidade gerenciada.

  2. Em seu provedor de modelo, como o Modelo da Fábrica, crie uma atribuição de função que forneça permissões de Usuário dos Serviços Cognitivos de identidade gerenciada do serviço de pesquisa. Se estiver testando localmente, atribua essa função a si mesmo.

  3. Para testes locais, siga as etapas no Início Rápido: conecte-se sem chaves para obter um token de acesso pessoal e garantir que você esteja conectado a uma assinatura e locatário específicos. Cole seu token de identidade pessoal na @accessToken variável. Uma solicitação que se conecta usando sua identidade pessoal deve ser semelhante ao exemplo a seguir:

    @search-url=<YOUR SEARCH SERVICE URL>
@accessToken=<YOUR PERSONAL ID>

# List Indexes
GET https://{{search-url}}/indexes?api-version=2025-08-01-preview
Authorization: Bearer {{accessToken}}

Importante

Se você usar a autenticação baseada em função, remova todas as referências à chave de API em suas solicitações. Em uma solicitação que especifica ambas as abordagens, a chave de API é usada em vez de funções.

Verificar se há agentes de conhecimento existentes

A solicitação a seguir lista os agentes de conhecimento por nome. Na coleção de agentes de conhecimento, todos os agentes de conhecimento devem ter nomes únicos. É útil saber mais sobre os agentes de conhecimento existentes para reutilização ou para nomear novos agentes.

# List existing knowledge agents on the search service
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint=search_endpoint, credential=credential)

try:
    agents = {agent.name: agent for agent in index_client.list_agents(api_version=search_api_version)}
    print(f"\nKnowledge agents on search service '{search_endpoint}':")
    
    if agents:
        print(f"Found {len(agents)} knowledge agent(s):")
        for i, (name, agent) in enumerate(sorted(agents.items()), 1):
            print(f"{i}. Name: {name}")
            if agent.knowledge_sources:
                ks_names = [ks.name for ks in agent.knowledge_sources]
                print(f"   Knowledge Sources: {', '.join(ks_names)}")
            print()
    else:
        print("No knowledge agents found.")
        
except Exception as e:
    print(f"Error listing knowledge agents: {str(e)}")

Você também pode retornar um único agente pelo nome para revisar sua definição de JSON.

# Get knowledge agent definition for earth-knowledge-agent-2
from azure.search.documents.indexes import SearchIndexClient
import json

index_client = SearchIndexClient(endpoint=search_endpoint, credential=credential)

try:
    agent_name = "earth-knowledge-agent-2"
    agent = index_client.get_agent(agent_name, api_version=search_api_version)
    
    print(f"Knowledge agent '{agent_name}':")
    print(f"Name: {agent.name}")
    
    if agent.description:
        print(f"Description: {agent.description}")
    
    if agent.models:
        print(f"\nModels ({len(agent.models)}):")
        for i, model in enumerate(agent.models, 1):
            print(f"  {i}. {type(model).__name__}")
            if hasattr(model, 'azure_open_ai_parameters'):
                params = model.azure_open_ai_parameters
                print(f"     Resource: {params.resource_url}")
                print(f"     Deployment: {params.deployment_name}")
                print(f"     Model: {params.model_name}")
    
    if agent.knowledge_sources:
        print(f"\nKnowledge Sources ({len(agent.knowledge_sources)}):")
        for i, ks in enumerate(agent.knowledge_sources, 1):
            print(f"  {i}. {ks.name} (threshold: {ks.reranker_threshold})")
    
    if agent.output_configuration:
        config = agent.output_configuration
        print(f"\nOutput: {config.modality} (activity: {config.include_activity})")
    
    # Full JSON definition
    print(f"\nJSON definition:")
    print(json.dumps(agent.as_dict(), indent=2))
    
except Exception as e:
    print(f"Error: {str(e)}")
    
    # Show available agents
    try:
        agents = {agent.name: agent for agent in index_client.list_agents(api_version=search_api_version)}
        print(f"\nAvailable agents: {list(agents.keys())}")
    except Exception:
        print("Could not list available agents.")

Criar um agente de conhecimento

Um agente de conhecimento conduz o pipeline de recuperação por meio de agentes. No código do aplicativo, ele é chamado por outros agentes ou bots de chat.

Sua composição consiste em conexões entre fontes de conhecimento (conteúdo pesquisável) e modelos de conclusão de chat implantados no Serviço OpenAI do Azure. As propriedades do modelo estabelecem a conexão. As propriedades da fonte de conhecimento definem padrões que orientam a execução da consulta e a resposta.

Para criar um agente, use a API REST do plano de dados da versão prévia 2025/08/01 ou um pacote de visualização do SDK do Azure que ofereça funcionalidade equivalente.

Lembre-se de que você deve ter uma fonte de conhecimento existente para dar ao agente.

from azure.search.documents.indexes.models import KnowledgeAgent, KnowledgeAgentAzureOpenAIModel, KnowledgeSourceReference, AzureOpenAIVectorizerParameters, KnowledgeAgentOutputConfiguration, KnowledgeAgentOutputConfigurationModality
from azure.search.documents.indexes import SearchIndexClient

aoai_params = AzureOpenAIVectorizerParameters(
    resource_url=aoai_endpoint,
    deployment_name=aoai_gpt_deployment,
    model_name=aoai_gpt_model,
)

output_cfg = KnowledgeAgentOutputConfiguration(
    modality=KnowledgeAgentOutputConfigurationModality.ANSWER_SYNTHESIS,
    include_activity=True,
)

agent = KnowledgeAgent(
    name=knowledge_agent_name,
    models=[KnowledgeAgentAzureOpenAIModel(azure_open_ai_parameters=aoai_params)],
    knowledge_sources=[
        KnowledgeSourceReference(
            name=knowledge_source_name,
            reranker_threshold=2.5,
        )
    ],
    output_configuration=output_cfg,
)

index_client = SearchIndexClient(endpoint=search_endpoint, credential=credential)
index_client.create_or_update_agent(agent, api_version=search_api_version)
print(f"Knowledge agent '{knowledge_agent_name}' created or updated successfully.")

Consultar o agente de conhecimento

Chame a ação de recuperação no objeto do agente de conhecimento para confirmar a conexão do modelo e retornar uma resposta. Usar a API REST do plano de dados da versão prévia 2025/08/01 ou um pacote de visualização do SDK do Azure que ofereça funcionalidade equivalente para esta tarefa. Para obter mais informações sobre a API de recuperação e a forma da resposta, consulte Recuperar dados usando um agente de conhecimento no Azure AI Search.

Substitua "onde o oceano parece verde?" por uma cadeia de consulta válida para seu índice de pesquisa.

Comece com instruções.

instructions = """
A Q&A agent that can answer questions about the Earth at night.
If you don't have the answer, respond with "I don't know".
"""

messages = [
    {
        "role": "system",
        "content": instructions
    }
]

Em seguida, envie a consulta.

from azure.search.documents.agent import KnowledgeAgentRetrievalClient
from azure.search.documents.agent.models import KnowledgeAgentRetrievalRequest, KnowledgeAgentMessage, KnowledgeAgentMessageTextContent, SearchIndexKnowledgeSourceParams

agent_client = KnowledgeAgentRetrievalClient(endpoint=search_endpoint, agent_name=knowledge_agent_name, credential=credential)
query_1 = """
    where does the ocean look green??
    """

messages.append({
    "role": "user",
    "content": query_1
})

req = KnowledgeAgentRetrievalRequest(
    messages=[
        KnowledgeAgentMessage(
            role=m["role"],
            content=[KnowledgeAgentMessageTextContent(text=m["content"])]
        ) for m in messages if m["role"] != "system"
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name=knowledge_source_name,
        )
    ]
)

result = agent_client.retrieve(retrieval_request=req, api_version=search_api_version)
print(f"Retrieved content from '{knowledge_source_name}' successfully.")

Excluir um agente

Se você não precisar mais do agente ou se precisar reconstruí-lo no serviço de pesquisa, use esta solicitação para excluir o objeto atual.

from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint=search_endpoint, credential=credential)
index_client.delete_agent(knowledge_agent_name)
print(f"Knowledge agent '{knowledge_agent_name}' deleted successfully.")

Conteúdo relacionado

  • Last updated on