Uso Básico

Caso você tenha finalizado a configuração inicial do Eitri App, agora é hora de começar a usar o hook useAgent para se comunicar com seus agentes de IA.

Criando seu primeiro agente

Para criar um agente, siga os seguintes passos:

1. Crie uma pasta chamada agents na raiz do seu projeto.
2. Dentro da pasta agents, crie um arquivo Markdown chamado SimpleAgent.md.
3. Adicione o seguinte conteúdo ao arquivo SimpleAgent.md:

---
---

Você é um assistente útil que responde a perguntas gerais. Seja conciso e amigável em suas respostas.

4. O nome do arquivo deve ser o mesmo que o nome do agente, sem a extensão (por exemplo, "SimpleAgent" para SimpleAgent.md).

Comunicando-se com o agente

O hook useAgent fornece uma interface simples e poderosa para se comunicar com seus agentes de IA. Ele cuida de toda a complexidade de gerenciar o contexto da conversa, chamar APIs de agentes e processar execuções de ferramentas.

Aqui está um exemplo simples de como usar o hook useAgent:

Exemplo:

import { useAgent } from "eitri-agents";
import { useState } from "react";
import { Page, View, Text } from "eitri-luminus";

export default function ChatComponent() {
  const agent = useAgent("SimpleAgent");
  const [message, setMessage] = useState("");
  const [response, setResponse] = useState("");

  const handleSend = async () => {
    const result = await agent.call({
      content: message,
    });
    setResponse(result.message);
  };

  return (
    <Page>
      <View>
        <Text>Digite sua mensagem:</Text>
        <TextInput
          value={message}
          onChange={(e) => setMessage(e.target.value)}
          placeholder="Digite sua mensagem..."
        />
        <Button onClick={handleSend}>Enviar</Button>
        {response && <Text>Agente: {response}</Text>}
      </View>
    </Page>
  );
}

Parâmetros

• agent (string, obrigatório): O nome do agente que você deseja usar. Deve corresponder ao nome do arquivo do agente sem a extensão (por exemplo, "SellerAgent" para SellerAgent.md).

• options (objeto, opcional): Um objeto para configurar o comportamento do agente.

  • llm (string): Especifica o LLM a ser usado (por exemplo, "gemini").
  • model (string): Especifica o modelo a ser usado (por exemplo, "gemini-2.5-flash").
  • verbose (boolean): Defina como true para habilitar logs detalhados no console. O padrão é false.
  • cleanContext (boolean): Defina como true para limpar o histórico da conversa quando o hook for inicializado. O padrão é false.
  • contextName (string): Um nome único para o contexto da conversa. Se não for fornecido, um nome será gerado automaticamente.
  • timeout (number): O tempo limite em milissegundos para a requisição da API.

Valores de Retorno

O hook retorna um objeto com as seguintes propriedades:

• call: Uma função assíncrona para enviar uma mensagem ao agente.

  • message (objeto, obrigatório): O objeto da mensagem.

    • content (string): O conteúdo de texto da mensagem.
    • role (string, opcional): O papel do remetente da mensagem (por exemplo, "user"). O padrão é "user".
    • file (objeto, opcional): O arquivo a ser enviado com a mensagem.
      • mimeType (string): O tipo MIME do arquivo.
      • data (string): Os dados codificados em base64 do arquivo. Alguns LLMs podem seguir o base64 com um prefixo (por exemplo, "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==").

  • callOptions (objeto, opcional): Opções adicionais para a chamada.

    • currentContext (MessageType[], opcional): Permite passar um contexto personalizado para a chamada, ao invés de usar o contexto padrão do hook.
    • skipSentToolResultToAgent (boolean, opcional): Quando true, o resultado da execução da ferramenta não é enviado de volta ao agente. Útil quando você quer processar o resultado da ferramenta diretamente sem uma resposta adicional do agente.

  • Retorno: Um objeto com as seguintes propriedades:

    • message (string): A resposta do agente.
    • rawToolResult (unknown, opcional): O resultado bruto da execução da ferramenta, quando skipSentToolResultToAgent é true.

• context: Uma variável de estado contendo um array de mensagens representando o histórico da conversa atual.

• getContexts: Uma função assíncrona que retorna as chaves de todos os contextos salvos para o agente atual.

• helper: Um objeto contendo funções utilitárias.

  • json (JSONHelper): Um auxiliar para analisar com segurança JSON a partir de strings, o que é útil para lidar com resultados de ferramentas.