ai-agents-for-beginners

Configuração do Curso

Introdução

Esta lição abordará como executar os exemplos de código deste curso.

Junte-se a Outros Estudantes e Obtenha Ajuda

Antes de começar a clonar o seu repositório, junte-se ao canal Discord AI Agents For Beginners para obter ajuda com a configuração, esclarecer dúvidas sobre o curso ou conectar-se com outros estudantes.

Clone ou Faça Fork deste Repositório

Para começar, por favor clone ou faça fork do repositório GitHub. Isso criará sua própria versão do material do curso para que você possa executar, testar e ajustar o código!

Isso pode ser feito clicando no link para fazer fork do repositório.

Agora você deve ter sua própria versão forkada deste curso no seguinte link:

Repositório Forkado

Clone Superficial (recomendado para workshop / Codespaces)

O repositório completo pode ser grande (~3 GB) ao baixar todo o histórico e todos os arquivos. Se você estiver apenas participando do workshop ou precisar de apenas algumas pastas de lições, um clone superficial (ou clone esparso) evita a maior parte desse download ao truncar o histórico e/ou ignorar blobs.

Clone superficial rápido — histórico mínimo, todos os arquivos

Substitua <your-username> nos comandos abaixo pelo URL do seu fork (ou o URL original se preferir).

Para clonar apenas o histórico do último commit (download pequeno):

git clone --depth 1 https://github.com/<your-username>/ai-agents-for-beginners.git

Para clonar um branch específico:

git clone --depth 1 --branch <branch-name> https://github.com/<your-username>/ai-agents-for-beginners.git

Clone parcial (esparso) — blobs mínimos + apenas pastas selecionadas

Isso utiliza clone parcial e sparse-checkout (requer Git 2.25+ e Git moderno recomendado com suporte a clone parcial):

git clone --depth 1 --filter=blob:none --sparse https://github.com/<your-username>/ai-agents-for-beginners.git

Entre na pasta do repositório:

cd ai-agents-for-beginners

Depois, especifique quais pastas deseja (exemplo abaixo mostra duas pastas):

git sparse-checkout set 00-course-setup 01-intro-to-ai-agents

Após clonar e verificar os arquivos, se você precisar apenas dos arquivos e quiser liberar espaço (sem histórico do Git), por favor exclua os metadados do repositório (💀irreversível — você perderá toda a funcionalidade do Git: sem commits, pulls, pushes ou acesso ao histórico).

# zsh/bash
rm -rf .git

# PowerShell
Remove-Item -Recurse -Force .git

Usando GitHub Codespaces (recomendado para evitar downloads locais grandes)

Dicas

Executando o Código

Este curso oferece uma série de Jupyter Notebooks que você pode executar para obter experiência prática na construção de Agentes de IA.

Os exemplos de código utilizam:

Requer Conta GitHub - Gratuito:

1) Framework Semantic Kernel Agent + GitHub Models Marketplace. Identificado como (semantic-kernel.ipynb) 2) Framework AutoGen + GitHub Models Marketplace. Identificado como (autogen.ipynb)

Requer Assinatura Azure: 3) Azure AI Foundry + Azure AI Agent Service. Identificado como (azureaiagent.ipynb)

Incentivamos você a experimentar todos os três tipos de exemplos para ver qual funciona melhor para você.

Qualquer que seja a opção escolhida, ela determinará quais etapas de configuração você precisará seguir abaixo:

Requisitos

Incluímos um arquivo requirements.txt na raiz deste repositório que contém todos os pacotes Python necessários para executar os exemplos de código.

Você pode instalá-los executando o seguinte comando no terminal na raiz do repositório:

pip install -r requirements.txt

Recomendamos criar um ambiente virtual Python para evitar conflitos e problemas.

Configuração do VSCode

Certifique-se de que está utilizando a versão correta do Python no VSCode.

image

Configuração para Exemplos usando Modelos do GitHub

Passo 1: Recupere Seu Token de Acesso Pessoal (PAT) do GitHub

Este curso utiliza o GitHub Models Marketplace, fornecendo acesso gratuito a Modelos de Linguagem Natural (LLMs) que você usará para construir Agentes de IA.

Para usar os Modelos do GitHub, você precisará criar um Token de Acesso Pessoal do GitHub.

Isso pode ser feito indo às configurações de Tokens de Acesso Pessoal na sua conta GitHub.

Por favor, siga o Princípio do Menor Privilégio ao criar seu token. Isso significa que você deve dar ao token apenas as permissões necessárias para executar os exemplos de código deste curso.

  1. Selecione a opção Fine-grained tokens no lado esquerdo da sua tela, acessando as configurações de desenvolvedor.

    Configurações de Desenvolvedor

    Em seguida, selecione Generate new token.

    Gerar Token

  2. Insira um nome descritivo para seu token que reflita seu propósito, facilitando sua identificação posteriormente.

    🔐 Recomendação de Duração do Token

    Duração recomendada: 30 dias
    Para uma postura mais segura, você pode optar por um período mais curto—como 7 dias 🛡️
    É uma ótima maneira de definir uma meta pessoal e concluir o curso enquanto sua motivação está alta 🚀.

    Nome e Expiração do Token

  3. Limite o escopo do token ao seu fork deste repositório.

    Limitar escopo ao repositório forkado

  4. Restrinja as permissões do token: Em Permissions, clique na aba Account e no botão “+ Add permissions”. Um menu suspenso aparecerá. Procure por Models e marque a caixa correspondente.

    Adicionar Permissão de Modelos

  5. Verifique as permissões necessárias antes de gerar o token. Verificar Permissões

  6. Antes de gerar o token, certifique-se de que está pronto para armazená-lo em um local seguro, como um cofre de gerenciador de senhas, pois ele não será exibido novamente após sua criação. Armazenar Token com Segurança

Copie seu novo token que acabou de criar. Agora você o adicionará ao arquivo .env incluído neste curso.

Passo 2: Crie Seu Arquivo .env

Para criar seu arquivo .env, execute o seguinte comando no terminal.

# zsh/bash
cp .env.example .env

# PowerShell
Copy-Item .env.example .env

Isso copiará o arquivo de exemplo e criará um .env no seu diretório, onde você preencherá os valores das variáveis de ambiente.

Com seu token copiado, abra o arquivo .env no seu editor de texto favorito e cole seu token no campo GITHUB_TOKEN.

Campo do Token GitHub

Agora você deve conseguir executar os exemplos de código deste curso.

Configuração para Exemplos usando Azure AI Foundry e Azure AI Agent Service

Passo 1: Recupere o Endpoint do Seu Projeto Azure

Siga os passos para criar um hub e projeto no Azure AI Foundry encontrados aqui: Visão geral de recursos do Hub

Depois de criar seu projeto, você precisará recuperar a string de conexão para seu projeto.

Isso pode ser feito indo à página Overview do seu projeto no portal Azure AI Foundry.

String de Conexão do Projeto

Passo 2: Crie Seu Arquivo .env

Para criar seu arquivo .env, execute o seguinte comando no terminal.

# zsh/bash
cp .env.example .env

# PowerShell
Copy-Item .env.example .env

Isso copiará o arquivo de exemplo e criará um .env no seu diretório, onde você preencherá os valores das variáveis de ambiente.

Com seu token copiado, abra o arquivo .env no seu editor de texto favorito e cole seu token no campo PROJECT_ENDPOINT.

Passo 3: Faça Login no Azure

Como prática de segurança, usaremos autenticação sem chave para autenticar no Azure OpenAI com o Microsoft Entra ID.

Em seguida, abra um terminal e execute az login --use-device-code para fazer login na sua conta Azure.

Depois de fazer login, selecione sua assinatura no terminal.

Variáveis de Ambiente Adicionais - Azure Search e Azure OpenAI

Para a lição Agentic RAG - Lição 5 - há exemplos que utilizam Azure Search e Azure OpenAI.

Se você quiser executar esses exemplos, precisará adicionar as seguintes variáveis de ambiente ao seu arquivo .env:

Página de Visão Geral (Projeto)

Centro de Gestão

Página de Modelos + Endpoints

Portal Azure

Página Externa

Configuração de autenticação sem chave

Em vez de codificar suas credenciais, usaremos uma conexão sem chave com Azure OpenAI. Para isso, importaremos DefaultAzureCredential e posteriormente chamaremos a função DefaultAzureCredential para obter a credencial.

# Python
from azure.identity import DefaultAzureCredential, InteractiveBrowserCredential

Está com dificuldades?

Se tiver algum problema ao executar esta configuração, entre no nosso Discord da Comunidade Azure AI ou crie um problema.

Próxima Aula

Agora está pronto para executar o código deste curso. Boa aprendizagem sobre o mundo dos Agentes de IA!

Introdução aos Agentes de IA e Casos de Uso de Agentes

Aviso Legal:
Este documento foi traduzido utilizando o serviço de tradução por IA Co-op Translator. Embora nos esforcemos pela precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autoritária. Para informações críticas, recomenda-se uma tradução profissional realizada por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução.

This site is open source. Improve this page.