Quickstart: Agent Recrutador LinkedIn

Este guia mostra o caminho mais curto para criar seu primeiro Agent no Tech4AI usando um caso simples e prático: um agent de recrutamento que recebe critérios (cargo, habilidades e senioridade) e retorna uma shortlist simulada de candidatos.

O que você vai construir

Ao final deste quickstart, você terá:

• Um Agent Conversacional chamado Recrutador LinkedIn
• Uma Skill chamada Busca de Candidatos
• Uma Action chamada buscar_candidatos
• Um fluxo testável de ponta a ponta no Agent Builder

Escopo deste quickstart

Este exemplo usa dados simulados de candidatos para focar na construção do fluxo no Agent Builder.
Não há integração real com LinkedIn neste primeiro guia.

Passo 1: Criar o Agent

1. Acesse /agents/builder.
2. Clique em + Novo Agente.
3. Selecione o tipo Conversacional.
4. Preencha:
   • Nome: Recrutador LinkedIn
   • Descrição: Agent para apoiar triagem inicial de candidatos com base em perfil técnico
   • Instruções gerais: use o exemplo abaixo

Você é um assistente de recrutamento especializado em triagem inicial de candidatos.
Seu objetivo é ajudar recrutadores a encontrar bons perfis com base em cargo, habilidades e senioridade.

Regras:
- Faça perguntas objetivas para coletar critérios faltantes.
- Resuma os resultados de forma clara e profissional.
- Não invente dados fora do retorno das actions.

Criação de um novo Agent no Builder

Passo 2: Criar a Skill Busca de Candidatos

Na tela de edição do agent:

1. Na barra lateral, clique em + Nova Habilidade.
2. Nomeie como Busca de Candidatos.
3. Na aba Código, adicione um YAML inicial:

instructions: |
  Você é uma skill de apoio ao recrutamento técnico.
  Colete cargo, habilidades e senioridade antes de executar a busca.

topics:
  - description: Coletar critérios de vaga e executar busca de candidatos
    steps:
      - Solicite cargo, habilidades principais e nível de senioridade quando faltar contexto.
      - Quando os critérios estiverem completos, execute a action buscar_candidatos.
      - Apresente a shortlist de forma objetiva e pergunte se deseja refinar a busca.

Dica

Mantenha a skill curta neste primeiro momento. Depois, evolua com validações e múltiplos tópicos.

Passo 3: Criar a Action buscar_candidatos

Ainda na edição do agent:

1. Vá para a seção Ações.
2. Crie uma nova action com o nome buscar_candidatos.
3. Na aba Config. Gerais, cadastre os parâmetros de entrada da action.
4. Na aba Código, cole o exemplo abaixo:

Parâmetros de entrada da action

Na seção Parâmetros da action, configure:

Nome	Tipo	Obrigatório	Descrição
cargo	Texto	Sim	Cargo desejado para a vaga (ex: Engenheiro de Software)
habilidades	Texto	Sim	Principais skills técnicas do perfil (ex: Python, AWS, Microsserviços)
senioridade	Texto	Sim	Nível esperado do candidato (ex: Júnior, Pleno, Sênior)

Exemplo de valores recebidos pela action:

{
  "cargo": "Engenheiro de Software",
  "habilidades": "Python, AWS, Microsserviços",
  "senioridade": "Sênior"
}

def buscar_candidatos(cargo: str, habilidades: str, senioridade: str):
    candidatos = [
        {
            "nome": "Ana Silva",
            "cargo": cargo,
            "skills": habilidades,
            "nivel": senioridade,
            "linkedin": "linkedin.com/in/ana-silva",
        },
        {
            "nome": "Carlos Mendes",
            "cargo": cargo,
            "skills": habilidades,
            "nivel": senioridade,
            "linkedin": "linkedin.com/in/carlos-mendes",
        },
        {
            "nome": "Beatriz Costa",
            "cargo": cargo,
            "skills": habilidades,
            "nivel": senioridade,
            "linkedin": "linkedin.com/in/beatriz-costa",
        },
    ]

    lista = "\n".join(
        [f"- **{c['nome']}** — {c['linkedin']} ({c['nivel']})" for c in candidatos]
    )

    return actions_sdk.ResponseToUser(
        instruction=(
            f"Busca concluída: {len(candidatos)} candidatos para "
            f"'{cargo}' ({senioridade}) com skills '{habilidades}'."
        ),
        message=(
            f"Encontrei **{len(candidatos)} candidatos** para o perfil solicitado:\n\n"
            f"{lista}\n\n"
            "Deseja refinar os critérios ou seguir com contato inicial?"
        ),
    )

Sobre instruction e message

No ResponseToUser, o campo instruction mantém o contexto para o LLM e o campo message é o texto final para o usuário.

State e Memory

Neste ponto, seu fluxo já funciona. Agora vale dar um passo além para deixar o agent mais robusto.

Quando usar cada um

Aspecto	State	Memory
Propósito	Regras de negócio e controle interno da action	Contexto que ajuda o LLM a responder melhor
Visibilidade	Somente dentro das actions	Enviado ao LLM como contexto da conversa
Exemplos	Contadores, flags, status de execução	Preferências do usuário, fatos da conversa, progresso de atendimento

Regra prática:

• Se é controle interno da lógica, use state_manager.
• Se é contexto útil para o agent conversar melhor, use memory_manager.

Exemplo prático na mesma action

Use a versão abaixo para registrar tentativa de busca no State e fatos relevantes na Memory:

def buscar_candidatos(cargo: str, habilidades: str, senioridade: str):
    # 1) Controle interno (não vai para o LLM)
    tentativas = state_manager.get("recrutamento.buscas_realizadas") or 0
    state_manager.update("recrutamento.buscas_realizadas", tentativas + 1)
    state_manager.update("recrutamento.ultima_busca", {
        "cargo": cargo,
        "senioridade": senioridade,
    })

    # 2) Contexto de conversa (vai para o LLM)
    memory_manager.store_conversation_fact(
        f"Usuário buscou candidatos para {cargo} ({senioridade})",
        metadata={"habilidades": habilidades}
    )
    memory_manager.store_user_info("perfil_vaga_recente", {
        "cargo": cargo,
        "habilidades": habilidades,
        "senioridade": senioridade,
    })
    memory_manager.store_workflow_progress(
        "triagem_recrutamento",
        "busca_realizada",
        {"total_tentativas": tentativas + 1}
    )

    candidatos = [
        {
            "nome": "Ana Silva",
            "cargo": cargo,
            "skills": habilidades,
            "nivel": senioridade,
            "linkedin": "linkedin.com/in/ana-silva",
        },
        {
            "nome": "Carlos Mendes",
            "cargo": cargo,
            "skills": habilidades,
            "nivel": senioridade,
            "linkedin": "linkedin.com/in/carlos-mendes",
        },
        {
            "nome": "Beatriz Costa",
            "cargo": cargo,
            "skills": habilidades,
            "nivel": senioridade,
            "linkedin": "linkedin.com/in/beatriz-costa",
        },
    ]

    lista = "\n".join(
        [f"- **{c['nome']}** — {c['linkedin']} ({c['nivel']})" for c in candidatos]
    )

    return actions_sdk.ResponseToUser(
        instruction=(
            f"Busca concluída: {len(candidatos)} candidatos para "
            f"'{cargo}' ({senioridade}) com skills '{habilidades}'."
        ),
        message=(
            f"Encontrei **{len(candidatos)} candidatos** para o perfil solicitado:\n\n"
            f"{lista}\n\n"
            "Deseja refinar os critérios ou seguir com contato inicial?"
        ),
    )

Boas práticas rápidas

• Evite colocar dados de controle técnico (ex.: retries, flags internas) na memória.
• Evite colocar no state informações que o LLM precisa usar para decidir a próxima resposta.
• Prefira chaves de memória organizadas por domínio, como informacoes_usuario e progresso_workflow.

Para detalhes completos dos métodos:

• State Management (SDK Actions)
• Memory Management (SDK Actions)

Passo 4: Testar o fluxo

Teste com uma solicitação como:

Preciso de um engenheiro Python sênior com experiência em AWS e arquitetura de microsserviços.

Resultado esperado:

• O agent coleta algum critério faltante (se necessário)
• Executa buscar_candidatos
• Retorna a shortlist simulada com links e pergunta de refinamento

Próximos passos

Para aprofundar:

• Gestão de Agents Conversacional
• Response Objects (Actions SDK)
• API v2: visão geral