17 Criação de Agente
Esta seção aborda a criação de agentes de IA por meio do criador de fluxo visual ou por meio de código.
Padrões de Sistemas e Supervisor de Vários Agentes
Um sistema multiagente é um design de aplicativo de IA no qual uma solicitação de usuário é tratada por vários agentes cooperantes, em vez de um agente grande e multifuncional.
Cada agente tem sua própria função, instruções, configuração do modelo, política de memória e ferramentas permitidas. O fluxo define como a solicitação se move entre esses agentes e como a resposta final é produzida.
Esse design é útil quando um fluxo de trabalho se separa naturalmente em responsabilidades especializadas. Por exemplo, um agente pode recuperar dados, outro pode chamar uma API, outro pode resumir descobertas e um supervisor pode decidir qual especialista usar e combinar os resultados em uma única resposta.
Observação:
Como princípio de design, é melhor começar com o menor design de agente que atenda aos requisitos. Adicione vários agentes quando a separação de preocupações melhorar a confiabilidade, a segurança, a capacidade de manutenção ou a observabilidade mais do que aumenta o custo e a complexidade.Benefícios dos sistemas multiagentes
- Especialização: dê a cada agente um trabalho focado, um prompt e um conjunto de ferramentas em vez de um bloco de instruções lotado.
- Roteamento e decomposição: permita que um supervisor interprete a solicitação, a divida em subtarefas e escolha o especialista certo para cada subtarefa.
- isolamento de ferramentas e dados: exponha ferramentas confidenciais ou de alto impacto apenas aos agentes responsáveis por usá-las.
- Governança e solução de problemas: facilitam a inspeção de transferências, propriedade da ferramenta, configurações de memória e pontos de falha.
Quando Escolher Designs de Vários Agentes ou Agentes Únicos
Um único agente com mais ferramentas geralmente é o primeiro projeto certo. É mais simples de testar, mais barato de executar e mais fácil de raciocinar quando a tarefa tem um objetivo claro e um modelo de permissão. Use um design de vários agentes quando o fluxo de trabalho se beneficiar de funções explícitas, acesso limitado a ferramentas ou um supervisor que possa coordenar várias saídas de especialistas.
| Pergunta de Design | Usar agentes únicos quando... | Usar vários agentes quando... |
|---|---|---|
| Forma da tarefa | O pedido tem um objetivo principal e um stile de resposta. | A solicitação deve ser decomposta, encaminhada, verificada ou sintetizada entre as especialidades. |
| Ferramentas e dados | O mesmo conjunto de instruções e modelo de permissão podem governar com segurança todas as ferramentas | Agentes diferentes precisam de ferramentas, origens de dados ou limites de acesso diferentes. |
| Instruções | O prompt permanece claro mesmo com todas as regras de negócios e orientação de ferramentas em um só lugar. | As instruções são mais fáceis de manter como prompts menores e específicos da função. |
| Custo e latência | Você deseja o caminho mais curto da mensagem do usuário para a resposta. | Os benefícios de confiabilidade, governança ou capacidade de manutenção justificam uma orquestração extra. |
| Diagnosticando e Solucionando Problemas | Falhas são simples de depurar em um único rastreamento. | Você precisa de transferências explícitas, isolamento de estado e propriedade mais clara para cada etapa. |
Padrão Suportado: Orchestrator/Supervisor
A experiência atual da tela suporta o padrão do orquestrador/supervisor. Nesse padrão, o Trigger de Chat recebe a mensagem do usuário, os Guardrails opcionais avaliam a entrada e um Agente Supervisor age como o orquestrador para o restante do fluxo.
O supervisor deve se concentrar no planejamento, na rota, na delegação e na síntese da resposta final. Ele decide qual agente executor deve lidar com uma tarefa, envia a esse executor uma instrução com escopo, revisa o resultado e, em seguida, delega outra etapa ou retorna a resposta final. Os agentes executores devem ser especialistas mais restritos: eles fazem o trabalho atribuído, usam suas ferramentas anexadas e retornam resultados úteis ao supervisor.
Sobre o Visual Flow Canvas
Um agente é montado arrastando nós e modelos de ferramenta da paleta esquerda para a tela e, em seguida, conectando os nós na ordem em que a solicitação deve se deslocar.
A seleção de um nó abre um painel de configuração na parte inferior da tela.
| Elemento da Tela | Objetivo |
|---|---|
| Trigger de Bate-papo | Ponto de entrada para uma mensagem do usuário. Na captura de tela, esse nó é rotulado como Mensagem e normalmente fica na parte superior do fluxo.
Um nó de trigger de chat pode ser conectado a um agente, um agente supervisor ou um nó de guardrails. Apenas um trigger de chat é permitido por tela. |
| Guardrails de proteção | Camada opcional de política e segurança colocada antes ou depois do trabalho do modelo. As políticas de guardrails incluem PII, moderação de conteúdo e detecção de injeção imediata.
Um nó de guardrails pode filtrar o tráfego entre um acionador de chat e um nó de agente, entre um supervisor e agentes executores ou entre nós de agente e ferramenta. Recomendamos um único nó de guardrails entre o trigger de chat e o nó do agente. |
| Agente Supervisor | O orquestrador. Ele recebe a solicitação do usuário, decide qual agente executor ou ferramenta deve lidar com cada tarefa e coordena a resposta final.
Apenas um agente supervisor é permitido em uma tela. |
| Agente | Um agente executor. Cada executor deve ter uma especialidade clara, como recuperação de dados, pesquisa de API, resumo ou resposta a perguntas de documentos.
Use um agente/executor para um único sistema de agente. |
| Modelos de ferramentas | Recursos reutilizáveis que podem ser anexados a um executor individual ou agente supervisor. Os modelos de ferramentas incluem SQL, RAG, Prompt, HTTP, servidor MCP remoto e Ferramenta personalizada. |
| Desenvolvimento / Playground | Seletor de modo acima da tela. O desenvolvimento é usado durante a edição do sistema agentic; o Playground é usado para iniciar sessões de teste e inspecionar o comportamento do agente.
O playground requer que uma computação de IA seja anexada ao seu agente. |
| Controle de zoom | Seletor de zoom da tela. As capturas de tela mostram níveis de zoom de 60% e 90%. |
Criar um Agente
Você pode criar um agente em um espaço de trabalho em que tenha a permissão Gerenciar.
- Clique em
Criar Agente ou clique em Criar no canto superior direito.
- Para Modo de criação de fluxo do agente, selecione Visual builder.
Adicionar Trigger de Chat e Agente à Tela do Visual Builder
Sua primeira etapa após a criação de um agente com o Visual Builder deve ser adicionar um acionador de chat e um agente supervisor.
- Clique e arraste um Agente do Supervisor para a tela.
Configurar um Agente Supervisor
Você precisa configurar um agente de supervisor adicionado à tela do Visual Builder com instruções que descrevem a função de supervisor.
| Campo | Configuração |
|---|---|
| Nome do Agente | Forneça um nome descritivo para o agente do supervisor. Um nome bom e descritivo será benéfico ao depurar o comportamento do sistema por meio de rastreamentos e logs. |
| Descrição do Agente | Forneça uma descrição da finalidade, da função e do comportamento geral do agente. Útil para fins de documentação. |
| Região | Escolha a região na qual o modelo do OCI Generative AI usado pelo Supervisor Agent está hospedado. Consulte Modelos de IA Generativa por Região. |
| Modelo | Escolha o modelo de serviço OCI Generative AI usado pelo supervisor. A lista drop-down lista os modelos disponíveis na região selecionada. |
| Instruções do agente | Descreva a função de supervisor, as regras de roteamento, a política de delegação, as expectativas de uso da ferramenta e o formato de resposta final. |
- Navegue até o agente em seu espaço de trabalho.
- Clique no nó Agente do Supervisor na sua tela.
- Forneça um nome e uma descrição minuciosos para o seu agente supervisor.
- Digite a região e o modelo do modelo de serviço do OCI Generative AI usado pelo supervisor.
- Forneça as instruções do agente para seu Agente Supervisor.
Instruções de Supervisor Sugeridas
Você deve usar o campo Instruções para um Agente Supervisor para tornar o supervisor responsável pela orquestração, não por executar cada tarefa em si.
Mantenha as instruções concretas para que as decisões de roteamento sejam previsíveis. Consulte o seguinte para obter um exemplo de um conjunto de instruções do Supervisor:
You are the supervisor for a multi-agent system.
Responsibilities:
- Understand the user's request and break it into subtasks.
- Select the most appropriate executor agent or tool for each subtask.
- Do not perform specialist work yourself when an executor agent is available.
- Ask for clarification only when required information is missing.
- Combine executor outputs into a concise final answer.
- Mention important assumptions, limits, or failed tool calls in the final answer.
Routing rules:
- Use the SQL agent for structured data questions.
- Use the HTTP agent/tool for external API lookups.
- Use the RAG agent/tool for document or knowledge-base questions.
- Use the prompt tool for reusable prompt-only transformations.Configurar Memória do Agente Supervisor e Isolamento de Estado
A guia Memória de um Agente Supervisor controla a quantidade de histórico de conversação e saída de ferramentas disponível para o supervisor e quanto contexto é compartilhado com agentes executores.
| Campo | Configuração |
|---|---|
| Ativar Memória do Agente | Ative quando os usuários precisarem de continuidade de várias voltas. Desativar para tarefas isoladas de uso único.
Este campo não pode ser desativado para Agentes do Supervisor. |
| Limitar histórico de conversas | Ative para truncar a janela de contexto do LLM após o limite especificado ser atingido. Desativar para mostrar o histórico completo. |
| Configuração de truncamento | Se a opção Limitar histórico de conversas estiver ativada, use esse campo para definir as condições para truncar a janela de contexto.
As opções são:
|
| Limites Máximos de Mensagens e Orçamento de Token | Uma ou ambas as opções são exibidas, dependendo da sua escolha para Configuração de Execução.
Os valores padrão são 20 mensagens e 5000 tokens. Recomendamos começar com valores moderados e ajustar conforme necessário. |
| Isolamento de Estado para Agentes Executores | Selecione Sem Monitoramento de Estado, Privado ou Compartilhado.
|
- Navegue até o agente em seu espaço de trabalho.
- Clique no nó Agente do Supervisor na sua tela.
- Clique na guia Memória.
- Escolha se deseja ativar Limitar histórico de conversas. Selecione uma Configuração de Execução e defina limites, se ativado.
- Escolha uma opção para Isolamento de Estado para Agentes do Executor.
Guia Parâmetro de Modelos
A guia Parâmetros do modelo permite configurar parâmetros específicos do modelo que estão disponíveis para o modelo selecionado.
Os parâmetros do modelo podem ser configurados separadamente para agentes de supervisor e executor. Os parâmetros que você pode usar incluem temperatura, K superior, P superior e penalidade de frequência.
Observação:
Somente um subconjunto de modelos expõe parâmetros configuráveis. Além disso, os parâmetros variam entre as famílias de modelos.
Adicionar Guardrails a um Agente
Você pode adicionar camadas adicionais de proteção aos seus agentes adicionando um ou mais nós de corrimão à sua tela.
| Corrimão | Options | Quando usar |
|---|---|---|
| Informações Pessoais Identificáveis (PII) |
|
Use quando o fluxo deve bloquear ou mascarar dados pessoais confidenciais antes ou depois do processamento do modelo. |
| Prevenção de moderação de conteúdo | Linhas de entrada e saída com as opções Bloquear, Informar e Permitir. | Use para definir como o fluxo lida com conteúdo de ódio, sexual, violento, tóxico, depreciativo ou assediante. |
| Detecção de Injeção de Prompt | Linha de entrada com as opções Bloquear e Permitir. | Use para reduzir a chance de que instruções maliciosas substituam as instruções do sistema ou do agente. |
- Exclua a conexão entre o Trigger de Chat e o Agente Supervisor passando o mouse sobre a conexão e clicando no X vermelho.
Adicionar Agentes e Ferramentas do Executor a um Agente
Você pode adicionar agentes executores a ferramentas para executar trabalhos especializados para o agente supervisor.
- Navegue até o agente em seu espaço de trabalho.
- Arraste um nó do Agente da paleta para a tela. Os nós do agente devem ser colocados abaixo de um Agente Supervior.
- Arraste Ferramentas da paleta para a tela.
- Clique e arraste a alça do conector no Agente do Supervisor para estabelecer conexão com os nós do Agente.
- Clique e arraste a alça do conector em seus Agentes para se conectar aos nós da Ferramenta.
Configuração do Agente do Executor
Os nós do agente podem ser configurados modificando as definições nas guias Configuração, Memória e Modelo para ajudá-lo a definir a finalidade de cada agente.
Os agentes devem ser configurados de forma restrita, dada uma função e uma meta específicas, para que o agente supervisor possa rotear o trabalho de forma confiável.
Tabela 17-1 Guia Configuração do Agente
| Campo | Configuração |
|---|---|
| Nome do Agente | A melhor prática é nomear cada agente executor de acordo com sua especialidade, como SQL_AGENT, DOCUMENT_AGENT, API_AGENT ou SUMMARY_AGENT.
Como o nome de cada agente executor fica visível para o agente supervisor, use nomes descritivos. |
| Descrição do Agente | Forneça uma descrição detalhada de cada agente executor. A descrição de cada agente executor fica visível para o agente supervisor. |
| Região | Escolha a região na qual o modelo do OCI Generative AI usado pelo Agente está hospedado. Consulte Modelos de IA Generativa por Região. |
| Modelo | Escolha o modelo de serviço do OCI Generative AI usado pelo agente. O menu drop-down lista os modelos disponíveis na região selecionada.
Selecione um modelo que se ajuste à tarefa do executor. Os agentes executores não precisam usar o mesmo modelo que o agente supervisor. |
| Instruções do agente | Descreva exatamente o que o executor deve fazer, quais ferramentas ele pode usar e qual estrutura de saída ele deve retornar. |
Guia Memória do Agente Executor
No caso de agentes executores conectados a um agente supervisor, a memória para executores é configurada no nó supervisor e aplicada a todos os agentes executores.
| Campo | Configuração |
|---|---|
| Ativar Memória do Agente | Ative quando os usuários precisarem de continuidade de várias voltas. Desativar para tarefas isoladas de uso único. |
| Limitar histórico de conversas | Ative para truncar a janela de contexto do LLM após o limite especificado ser atingido. Desativar para mostrar o histórico completo. |
| Configuração de truncamento | Se a opção Limitar histórico de conversas estiver ativada, use esse campo para definir as condições para truncar a janela de contexto.
As opções são:
|
| Limites Máximos de Mensagens e Orçamento de Token | Uma ou ambas as opções são exibidas, dependendo da sua escolha para Configuração de Execução.
Os valores padrão são 20 mensagens e 5000 tokens. Recomendamos começar com valores moderados e ajustar conforme necessário. |
| Isolamento de Estado para Agentes Executores | Selecione Sem Monitoramento de Estado, Privado ou Compartilhado.
|
Guia Parâmetros do Modelo do Agente Executor
A guia Parâmetros do modelo permite configurar parâmetros específicos do modelo que estão disponíveis para o modelo selecionado.
Observação:
Somente um subconjunto de modelos expõe parâmetros configuráveis. Os parâmetros também variam entre as famílias de modelos.Exemplos de parâmetros incluem temperatura, K superior, P superior e penalidade de frequência. Os parâmetros do modelo podem ser configurados separadamente para agentes de supervisor e executor.
Instruções do Executor Sugeridas
You are the SQL executor agent.
Responsibilities:
- Translate the supervisor's task into safe SQL tool usage.
- Use only the SQL tools attached to this agent.
- Return a concise answer plus any important query assumptions.
- Do not invent data. If the tool cannot answer, say what is missing.
- Return structured output with: answer, evidence, assumptions, and follow_up_needed.
Lista de Verificação para Agentes por meio do Visual Builder
Use essa lista como guia para garantir que você tenha incluído e configurado todos os componentes necessários para um agente criado usando o Visual Builder.
Criar Lista de Verificação
- O agente tem exatamente um ponto de entrada esperado: Disparador de Chat / Mensagem.
- Os corrimãos são conectados na posição pretendida e ativados quando necessário. Recomendamos a inserção de guardrails entre a mensagem do trigger e o agente.
- O Agente do Supervisor tem uma região selecionada, um modelo selecionado e instruções de orquestração. O mesmo para os agentes executores.
- Configure a memória do sistema de vários agentes na guia Memória do agente Supervisor. Selecione o isolamento do estado do executor que corresponda aos requisitos de privacidade e continuidade.
- Cada Agente executor tem uma especialidade clara e instruções restritas.
- Cada ferramenta é anexada somente ao agente que deve usá-la.
- Nenhum nó está desconectado.
- Uma computação de IA é anexada ao sistema agentic para testar ferramentas individuais e para executar a experiência do Playground.
Tabela 17-2 Problemas Comuns
| Problema | Provável Causa | Ação Sugerida |
|---|---|---|
| O supervisor não chama um executor | As instruções do supervisor são muito vagas ou nenhum executor está conectado. | Adicione regras de roteamento explícitas e confirme se o nó do executor está conectado ao supervisor. |
| Executor retorna respostas amplas ou fora do tópico | As instruções do executor são muito gerais. | Torne a função de executor mais restrita e defina a estrutura de saída necessária. |
| A ferramenta não foi usada | A ferramenta está desconectada ou anexada ao agente errado. | Verifique a conexão da ferramenta e o crachá de contagem de ferramentas do agente. |
| Guardrail não atira | A seção Guardrail está configurada, mas não ativada. | Abra o nó guadrails e confirme se a alternância da seção está ativada. |
| Vazamentos de contexto entre agentes | O isolamento do estado é definido como Compartilhado ou a memória é mais ampla do que o pretendido. | Use isolamento Stateless ou Privado para uma separação mais rigorosa. |
| Perguntas de acompanhamento perdem contexto | A memória está desativada ou o truncamento é muito agressivo. | Ative a memória e ajuste o limite máximo de mensagens. |
Agentes por Código
Você pode trazer sua própria base de código LangGraph para agentes de IA no Oracle AI Data Platform Workbench ou criar um novo agente LangGraph diretamente na plataforma por meio da experiência de codificação do agente.
Você pode usar a biblioteca Python do utilitário AI Data Platform Workbench aidputils para configurar seu modelo básico e importar ferramentas do sistema para seu agente. Para obter referência da API aidputils, consulte API do Aidp-utils para o Oracle AI Data Platform Workbench.
Você cria um agente por meio do código fazendo upload de um arquivo de código existente ou criando arquivos de código diretamente no seu agente por meio do editor em linha.
- Python (.py)
- JSON
- TXT
- CSV
- PSV
- SH
- Pasta
Você pode ver e navegar pelos arquivos de código disponíveis clicando na lista drop-down do seletor de arquivos.
Arquivos de Entrada e Dependência
Arquivos de entrada são arquivos de código que têm a classe com métodos de configuração e chamada esperados para um agente definido como código. O Oracle AI Data Platform Workbench requer que você defina um arquivo de entrada para agentes por meio de código.
Arquivos de dependência são arquivos que incluem bibliotecas de terceiros exigidas pelo seu agente definidas como código. Os arquivos de dependência geralmente são arquivos requirements.txt que contêm uma lista das bibliotecas de terceiros necessárias.
Observação:
As bibliotecas de terceiros são instaladas quando você testa seu código no editor clicando no botão Reproduzir ou quando você testa o agente na guia Testar. Recomendamos a instalação de bibliotecas de terceiros testando o código primeiro. Erros durante a instalação das bibliotecas são exibidos na célula de saída.Classe do Agente
AgentBasic é uma classe de modelo para configurar e chamar um agente de conversação simples usando um workflow LangGraph com monitoramento de estado. Ele demonstra a estrutura necessária para o desenvolvimento mínimo de agentes com dois métodos principais:
setup(): Inicializa o workflow do agente e define o gráfico.invoke(user_query, **kwargs): Executa o agente em uma mensagem do usuário e retorna a resposta.
Ele pode ser executado e testado diretamente usando uma função main() antes da integração em um sistema maior.
Definição
class AgentBasic:
def __init__(self) -> None:
self.graph = None
def setup(self) -> None:
self.graph = StateGraph(MessagesState)
self.graph.add_node(mock_llm)
self.graph.add_edge(START, "mock_llm")
self.graph.add_edge("mock_llm", END)
self.graph = self.graph.compile()
system_prompt = "Be a helpful assistant."
async def invoke(self, user_query: str, **kwargs):
user_message = HumanMessage(content=user_query)
messages = {"messages": [dict(user_message)]}
try:
return self.graph.invoke(messages)
except Exception as e:
import traceback
logger.error(f"Exception while calling invoke {e}", exc_info=True)
print("Stack trace:\n", traceback.format_exc())
Testar chamada
Esta chamada de teste é ideal para testes funcionais iniciais.
Observação:
Inclua um ponto de entrada principal para testes independentes.import asyncio
async def main():
test_agent = AgentBasic()
test_agent.setup()
result = await test_agent.invoke("Hi there")
print("Agent response:", result)
if __name__ == "__main__":
asyncio.run(main())
- O script cria um agente, o configura e envia uma mensagem de usuário de amostra.
- O agente responde ({"messages": [{"role": "ai", "content": "hello world"}]} neste exemplo.
Guia de Uso
Crie uma classe Agente com os métodos de configuração e chamada.
| configuração() | Inicializa o workflow do agente | agent.setup() |
| chamar() | Executa o agente com uma mensagem do usuário | await agent.invoke("Sua pergunta") |
- Assíncrono:
invoke()é um método assíncrono; use-o comawaitou execute em um loop assíncrono. - Testando: O guarda
main()incluído (if __name__ == "__main__":) facilita o teste do agente antes da implantação.
Criar um Agente Através do Código por Upload
Você pode criar seu aplicativo de agente de ponta a ponta com código existente fazendo upload da sua base de código LangGraph.
Observação:
Você pode fazer upload de arquivos e pastas individuais até um máximo de 500 arquivos, cada arquivo pode ter um tamanho máximo de 500 MB. O upload é limitado a um tamanho total de 5 GB.- Clique em Fazer Upload.
Criar um Agente Através do Código Criando um Novo Código
Você pode criar seu aplicativo de agente de ponta a ponta com o código existente criando o código diretamente no seu agente por meio do editor de código.
- Python (.py)
- JSON
- TXT
- CSV
- PSV
- SH
- Pastas
- Clique em Adicionar novo arquivo.
Definir um Arquivo de Entrada para Agentes por meio de Código
Seu agente de IA por meio do código requer um arquivo de entrada que tenha a classe necessária, a configuração e os métodos de chamada esperados para seu agente.
- Clique com o botão direito do mouse no arquivo de entrada e clique em Definir arquivo de entrada. Você também pode selecionar o arquivo e clicar no botão Definir arquivo de entrada no canto superior direito do editor de código.
Definir um Arquivo de Dependência para Agentes por meio de Código
É necessário definir um arquivo de dependência para que os agentes fluam pelo código que contém qualquer biblioteca de terceiros da qual seu código depende.
- Clique com o botão direito do mouse no arquivo de dependência e clique em Definir dependência. Você também pode selecionar o arquivo e clicar no botão Definir arquivo de dependências no canto superior direito do editor de código.
Código do Agente de Teste
Você pode testar o código usado para seu agente na guia Testar para validar e depurar o código.
- Clique na guia Playground.
- Clique em Reproduzir para testar o arquivo de código selecionado.
Habilidades do agente na experiência de codificação
As Habilidades do Agente permitem que um agente descubra e use instruções específicas da tarefa, arquivos de referência, modelos, ativos e scripts executáveis opcionais sem codificar esse conhecimento de domínio nas instruções do agente.
Uma habilidade é armazenada como uma pasta na sua base de código do agente. Cada habilidade tem um arquivo SKILL.md necessário que descreve o que a habilidade faz e como o agente deve usá-lo. Uma habilidade também pode incluir arquivos de suporte, como esquemas, exemplos, prompts, modelos, ativos ou scripts.
Para obter mais informações, consulte Visão Geral das Habilidades do Agente.
- O agente descobre que existe uma habilidade.
- O agente só ativa a habilidade quando ela é relevante.
- O agente carrega arquivos adicionais da pasta de habilidades somente quando necessário.
- O agente poderá executar um ponto de entrada de habilidade explicitamente declarado, se a habilidade permitir.
Quando usar Habilidades do Agente
- Instruções específicas do domínio
- Fluxos de trabalho de codificação ou análise de dados
- Orientação para geração de SQL
- Manuais do processo de negócios
- Modelos de arquivo
- Referências do esquema
- Scripts reutilizáveis para cálculos, transformações ou pesquisas seguras
Como as habilidades funcionam em tempo de execução
No runtime, o aplicativo host determina quais diretórios de habilidades estão disponíveis, como pastas de habilidades no nível do projeto e no nível do usuário. A plataforma carrega os metadados de cada habilidade de SKILL.md e cria um catálogo com chave por nome de habilidade.
Em seguida, o agente pode usar ferramentas relacionadas a habilidades:
| Ferramenta | Objetivo |
|---|---|
activate_skill(name) |
Carrega as instruções de habilidade de SKILL.md. |
list_skill_files(name, path) |
Lista os arquivos disponíveis em uma pasta de habilidades. |
load_skill_file(name, path) |
Carrega um arquivo de suporte da pasta de habilidades. |
run_skill_entrypoint(name, entrypoint, args_json, timeout_seconds) |
Executa um ponto de entrada Python declarado explicitamente, se permitido pela habilidade. |
Alguns ambientes também podem incorporar um resumo das habilidades disponíveis diretamente no prompt do sistema. Nessa configuração, o agente pode descobrir as habilidades disponíveis no prompt e usar activate_skill quando precisar de instruções completas.
Estrutura da Pasta de Habilidades
Uma habilidade usa um layout de pasta no estilo Habilidades do Agente:
<skills_dir>/
some-skill/
SKILL.md
references/
...
scripts/
...
assets/
...Somente SKILL.md é obrigatório. As outras pastas são opcionais.
| Pasta ou Arquivo | Obrigatório | Objetivo |
|---|---|---|
SKILL.md |
Sim | Metadados e instruções principais da habilidade. |
references/ |
No | Suporte a documentação, esquemas, exemplos ou modelos. |
scripts/ |
No | Scripts Python que podem ser executados apenas quando explicitamente declarados como pontos de entrada. |
assets/ |
No | Ativos estáticos usados pela habilidade. |
Escrevendo SKILL.md
Cada habilidade deve incluir frontmatter YAML no topo de SKILL.md, seguido por instruções de Markdown.
Exemplo Básico
---
name: sql-helper
description: Helps the agent write safe SQL queries using project schemas.
license: internal
compatibility: "agent-platform"
metadata:
owner: data-platform
domain: analytics
allowed-tools: "analyzeQuery inspectSchema"
---
# SQL Helper
Use this skill when the user asks for SQL generation, query review, or schema-aware analysis.
Before writing SQL:
1. Inspect the relevant schema files in `references/`.
2. Prefer explicit column names.
3. Avoid destructive statements unless the user explicitly asks for them and the environment allows them.
Tabela 17-3 Campos de Material Frontal Suportados
| Campo | Obrigatório | Descrição |
|---|---|---|
| name | Sim | Nome de habilidade exclusivo usado pelo catálogo e pelas ferramentas. |
| descrição | Sim | Descrição curta usada para descoberta e roteamento. |
| licença | No | Licença ou política de uso da habilidade. |
| compatibilidade | No | Nota de compatibilidade para runtimes ou plataformas suportados. |
| metadados | No | Mapa de metadados de string para string. |
| ferramentas permitidas | No | Lista de ferramentas separadas por espaço que essa habilidade permite. |
| pontos de entrada | No | Lista de pontos de entrada executáveis declarados pela habilidade. |
Adicionando Arquivos de Suporte
Os arquivos de suporte permitem que uma habilidade mantenha conteúdo detalhado fora das instruções principais. Isso mantém o SKILL.md focado enquanto ainda dá ao agente acesso a um contexto mais rico. Por exemplo:
skills/
sql-helper/
SKILL.md
references/
warehouse_schema.md
query_style_guide.md
examples.md
O agente pode inspecionar esses arquivos com:
list_skill_files("sql-helper", "references")
load_skill_file("sql-helper", "references/warehouse_schema.md")
- Esquemas do banco de dados
- Exemplos de API
- Modelos de prompt
- Guias de estilo
- Glossários de domínio
- Guias passo a passo
- Casos de teste ou exemplos
Criando uma Habilidade Executável
Uma habilidade pode, opcionalmente, expor o comportamento executável reutilizável por meio de run_skill_entrypoint. Destina-se a operações controladas, como cálculos, transformações, validação ou extração de dados estruturados.
- A habilidade deve incluir
run_skill_entrypointnas ferramentas permitidas. - O script deve ser declarado explicitamente na seção de pontos de entrada do
SKILL.md.
Exemplo de Habilidade Executável
skills/
statistics-helper/
SKILL.md
scripts/
summarize_numbers.py
HABILIDADE.md
---
name: statistics-helper
description: Computes basic summary statistics for numeric data.
allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"
entrypoints:
- name: summarize_numbers
script: scripts/summarize_numbers.py
func: run
description: Returns count, min, max, mean, and median for a list of numbers.
---
# Statistics Helper
Use this skill when the user asks for basic descriptive statistics.
scripts/summarize_numbers.py:
from statistics import mean, median
def run(*, values: list[float]) -> dict:
if not values:
raise ValueError("values must not be empty")
return {
"count": len(values),
"min": min(values),
"max": max(values),
"mean": mean(values),
"median": median(values),
}
Example invocation:
run_skill_entrypoint(
name="statistics-helper",
entrypoint="summarize_numbers",
args_json="{\"values\": [10, 20, 30, 40]}",
timeout_seconds=10
)
The runner returns structured output that includes exit_code, stdout, stderr, and a best-effort parsed result when the script prints or returns JSON.
Regras para Pontos de Entrada Executáveis
- Localizado sob o diretório/scripts da habilidade
- Declarado no frontmatter dos pontos de entrada da habilidade
- Permitido pela definição
allowed-toolsda habilidade
A plataforma não fornece execução de script arbitrário de uso geral. Scripts que não são declarados em SKILL.md não são executáveis.
O executor de script usa um timeout, assume como padrão 10 segundos, executa o Python com comportamento de modo isolado e aplica restrições de caminho. No entanto, a execução baseada em subprocesso não é uma sandbox completa do sistema operacional. Para uso em produção, deve-se considerar um isolamento maior, como contêineres, sistemas de arquivos restritos ou controles de rede.
Permissões de Ferramenta com allowed-tools
allowed-tools atua como um gate de permissão no nível da habilidade. Para uma habilidade somente para documentação, você só pode permitir ferramentas de leitura de arquivos:
allowed-tools: "load_skill_file list_skill_files"Para uma habilidade que pode executar scripts declarados, inclua run_skill_entrypoint:
allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint" Não adicione run_skill_entrypoint a menos que a habilidade realmente precise de comportamento executável.
Como deixar seus agentes descobrirem e usarem habilidades
Para complementar seu agente com habilidades, você deve instanciar um catálogo de habilidades, um middleware de habilidades e converter habilidades em ferramentas usando os seguintes objetos da biblioteca aidpUtils:
| Ferramenta | Objetivo |
|---|---|
discover_skill_catalog |
Determinar locais de pesquisa de habilidades padrão (projeto + usuário) Criar um Catálogo de Habilidades com base em diretórios descobertos |
SkillMiddleware |
Anexe o resumo de habilidades disponíveis e as regras de roteamento ao prompt do sistema.
Forneça ajudantes de fábrica para construção de middleware orientada a espaços de trabalho. |
make_skill_tools |
Este método retorna as ferramentas de descoberta de habilidades – activate_skill, list_skill_files, load_skill_file e run_skill_entrypoint. Essas ferramentas podem ser usadas pelo agente para ativar e executar diferentes habilidades. |
Veja a seguir um exemplo do que seu arquivo de entrada incluiria:
from aidputils.agents.skills.discovery import discover_skill_catalog
from aidputils.agents.skills.middleware import SkillMiddleware
from aidputils.agents.skills.tools.factories import make_skill_tools
...
class SchoolGradeAgentWithEmbededSkills:
...
def init(self) -> None:
...
self.catalog = discover_skill_catalog(skill_folder_whitelist=None)
self.skill_middleware = SkillMiddleware(self.catalog)
self.tools = make_skill_tools(self.catalog)
Você pode depurar seu catálogo de habilidades adicionando esta instrução do logger ao seu código. Isso imprimirá todas as habilidades descobertas no catálogo de habilidades:
for info in self.catalog.list():
logger.info("skill_id=%s name=%s desc=%s root=%s skill_file=%s", info.skill_id, info.name, info.description, info.root_dir, info.skill_file)
Precedência de Habilidade
A plataforma pode carregar habilidades de vários locais, como diretórios de nível de projeto e de usuário. O catálogo agrega esses locais em uma única lista de habilidades com chave de nome.
Quando vários armazenamentos contêm uma habilidade com o mesmo nome, a precedência determina qual deles é usado. Os armazenamentos posteriores substituem os anteriores, o que permite que um aplicativo host controle se as habilidades no nível do usuário, as habilidades no nível do projeto ou as habilidades no nível do espaço de trabalho têm prioridade.
Melhores Práticas de Criação de Habilidades
Mantenha o SKILL.md focado
Use SKILL.md para as instruções principais que o agente precisa imediatamente após a ativação. Coloque esquemas longos, exemplos e material de referência em referências/.
Escreva descrições claras
O campo de descrição é usado para descoberta. Torne-o específico o suficiente para que o agente saiba quando ativar a habilidade.
description: Helps generate BigQuery SQL using the finance warehouse schema.description: Helps with data.Usar nomes de ponto de entrada explícitos
entrypoints:
- name: validate_query
- name: summarize_numbers
- name: transform_csventrypoints:
- name: run
- name: do_it Retornar resultados estruturados
Scripts executáveis devem retornar resultados serializáveis JSON sempre que possível. Isso torna a saída mais fácil para o agente inspecionar e usar.
Evite execução desnecessária
Prefira instruções e arquivos de referência quando possível. Use pontos de entrada executáveis somente para operações que realmente exigem código.
Adicionar uma Nova Habilidade
Você pode adicionar novas habilidades do Agente criando uma nova pasta dentro do diretório de habilidades e adicionando os arquivos e pastas necessários.
Adicionar um Novo Recurso Executável a uma Habilidade Existente
Você pode adicionar uma nova operação executável a uma habilidade existente para expandir os recursos do SKILL.md.
Diagnóstico e Solução de Problemas de Habilidades do Agente
Se você encontrar problemas com a implementação de Habilidades do Agente, verifique esta lista para obter ajuda para resolver seu problema.
O agente não vê minha habilidade
- A pasta de habilidades está localizada em um diretório de habilidades configurado.
- A pasta contém SKILL.md.
- SKILL.md tem frontmatter YAML válido.
- O frontmatter inclui nome e descrição.
O agente ativa a habilidade errada
Verifique se há nomes de habilidades duplicados nos diretórios de habilidades. Se duas habilidades tiverem o mesmo nome, a precedência do catálogo determinará qual delas será usada.
Não é possível carregar um arquivo de suporte
- O arquivo está dentro da pasta de habilidades.
- O caminho não inclui travessias como ../.
- O arquivo não está oculto.
- O arquivo não foi excluído, como __pycache__ ou .pyc.
Um ponto de entrada não será executado
- run_skill_entrypoint está incluído nas ferramentas permitidas.
- O ponto de entrada é declarado em SKILL.md.
- O caminho do script está em scripts/.
- O script é um arquivo .py.
- O nome da função no func existe no script.
- Os argumentos são um objeto JSON válido.
Um ponto de entrada expira
Aumente timeout_seconds somente se a operação demorar mais. Para operações de longa execução ou com uso intenso de recursos, considere mover a operação para um serviço dedicado ou um ambiente de execução mais isolado.
Exemplo: Concluir Habilidade do Agente
Este exemplo demonstra como seria uma habilidade completa do agente após a implementação.
Estrutura da Pasta
skills/
customer-support-reply/
SKILL.md
references/
tone_guide.md
refund_policy.md
escalation_rules.md
HABILIDADE.md
---
name: customer-support-reply
description: Helps draft customer support replies using the company tone guide and policy references.
allowed-tools: "load_skill_file list_skill_files"
metadata:
owner: support-operations
domain: customer-support
---
# Customer Support Reply
Use this skill when the user asks for help drafting, reviewing, or improving a customer support response.
Workflow:
1. Identify the customer’s issue.
2. Load the relevant policy file from `references/` if needed.
3. Draft a clear, empathetic response.
4. Avoid making commitments that are not supported by policy.
5. Recommend escalation when the request matches the escalation rules.
This skill does not run code. It gives the agent structured instructions and optional policy files that can be loaded only when relevant.
Teste do Agente
Você pode testar seus agentes para visualizar e depurar a saída deles. Você também pode criar e gerenciar sessões de teste para explorar diferentes cenários de teste para seus agentes.
A primeira etapa para testar um agente é anexá-lo a uma computação de IA. A ação de anexar um agente envia uma cópia do seu agente para uma computação de IA. Desde que seu agente esteja anexado a uma computação AI, todas as alterações feitas no seu agente serão propagadas para a computação anexada toda vez que você clicar no botão Testar.
Depois de clicar no botão Test, você será levado ao playground de teste.
- Uma janela de chat na qual você pode iniciar uma sessão e começar a conversar com o agente ou retomar uma sessão existente
- Uma representação baseada em gráfico do agente
- Um painel mostrando uma árvore de rastreamentos e intervalos gerados durante a sessão
- Um painel do explorador de rastreamentos e intervalos que exibe atributos de rastreamentos e intervalos, entrada/saída. A guia Detalhes inclui IDs, horário inicial e final, tempo de execução e as guias Eventos destacam os erros durante a execução.
O Playground permite que você interaja e teste cada agente de forma independente, se desejar. Por padrão, o agente supervisor é selecionado, mas você pode optar por conversar e testar cada agente executor de forma independente. Isso permite simular o comportamento de um agente supervisor emitindo solicitações para agentes executores. Para fazer isso, selecione o agente que deseja testar no menu drop-down na janela de chat.
Rastreamentos e intervalos são exibidos no painel central assim que você cria sua primeira mensagem. Cada tarefa corresponde a uma mensagem de usuário diferente. Você pode clicar no cursor esquerdo para expandir o rastreamento e inspecionar os intervalos.
Teste seus Agentes no Playground
Você pode testar o visual builder e os agentes baseados em LangGraph no playground de Teste para validar e depurar seus agentes.
- Na parte superior da tela, clique em Playground. Pode levar alguns segundos para enviar o agente à sua computação anexada.
Criar uma Sessão de Teste do Agente
Você pode criar uma sessão de teste para iniciar uma nova conversa com seu agente.
- No seletor de sessão, clique em Criar uma sessão.
- Inicie uma caixa de diálogo com seu agente informando uma consulta na caixa de chat.
