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 um Fork deste Repositório
Para começar, por favor, clone ou faça um fork do Repositório GitHub. Isso criará a sua própria versão do material do curso, permitindo que você execute, teste e ajuste o código!
Isso pode ser feito clicando no link para fazer fork do repositório.
Agora você deve ter a sua própria versão do curso no seguinte link:
Clone Raso (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ê está apenas participando do workshop ou precisa de algumas pastas de lições, um clone raso (ou clone esparso) evita a maior parte desse download, truncando o histórico e/ou ignorando blobs.
Clone raso 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 commit mais recente (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
Acesse a pasta do repositório:
cd ai-agents-for-beginners
Depois, especifique quais pastas você deseja (o 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), 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)
-
Crie um novo Codespace para este repositório através da interface do GitHub.
- No terminal do Codespace recém-criado, execute um dos comandos de clone raso/esparso acima para trazer apenas as pastas de lições necessárias para o espaço de trabalho do Codespace.
- Opcional: após clonar dentro do Codespaces, remova o .git para recuperar espaço extra (veja os comandos de remoção acima).
- Nota: Se preferir abrir o repositório diretamente no Codespaces (sem um clone extra), esteja ciente de que o Codespaces construirá o ambiente devcontainer e pode ainda provisionar mais do que você precisa. Clonar uma cópia rasa dentro de um Codespace novo dá mais controle sobre o uso do disco.
Dicas
- Sempre substitua o URL do clone pelo do seu fork se quiser editar/commitar.
- Se mais tarde precisar de mais histórico ou arquivos, você pode buscá-los ou ajustar o sparse-checkout para incluir pastas adicionais.
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 - Gratuita:
1) Framework Semantic Kernel + 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 os três tipos de exemplos para ver qual funciona melhor para você.
A opção escolhida determinará quais etapas de configuração você precisará seguir abaixo:
Requisitos
- Python 3.12+
-
NOTA: Se você não tiver o Python 3.12 instalado, certifique-se de instalá-lo. Em seguida, crie seu venv usando python3.12 para garantir que as versões corretas sejam instaladas a partir do arquivo requirements.txt.
Exemplo
Crie o diretório do ambiente virtual Python:
python -m venv venvEm seguida, ative o ambiente venv para:
# zsh/bash source venv/bin/activate# Command Prompt for Windows venv\Scripts\activate
-
-
.NET 10+: Para os códigos de exemplo que utilizam .NET, certifique-se de instalar o .NET 10 SDK ou posterior. Depois, verifique a versão do SDK .NET instalada:
dotnet --list-sdks - Uma Conta GitHub - Para acesso ao GitHub Models Marketplace
- Assinatura Azure - Para acesso ao Azure AI Foundry
- Conta Azure AI Foundry - Para acesso ao Azure AI Agent Service
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.
Configurar o VSCode
Certifique-se de que está utilizando a versão correta do Python no VSCode.
Configuração para Exemplos usando Modelos do GitHub
Passo 1: Obtenha o Seu Token de Acesso Pessoal (PAT) do GitHub
Este curso utiliza o GitHub Models Marketplace, que oferece acesso gratuito a Modelos de Linguagem de Grande Escala (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 acessando as 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 conceder ao token apenas as permissões necessárias para executar os exemplos de código deste curso.
-
Selecione a opção
Fine-grained tokensno lado esquerdo da tela, navegando até as Configurações de Desenvolvedor.
Em seguida, selecione
Generate new token.
-
Insira um nome descritivo para o seu token que reflita seu propósito, facilitando a identificação posterior.
🔐 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 mantém o ritmo de aprendizado 🚀.
-
Limite o escopo do token ao seu fork deste repositório.
-
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.
-
Verifique as permissões necessárias antes de gerar o token.
-
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 a criação.
Copie o novo token que acabou de criar. Agora você o adicionará ao arquivo .env incluído neste curso.
Passo 2: Crie o Seu Arquivo .env
Para criar o 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 o token copiado, abra o arquivo .env no seu editor de texto favorito e cole o token no campo GITHUB_TOKEN.
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: Obtenha 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 o seu projeto, você precisará obter a string de conexão do projeto.
Isso pode ser feito acessando a página Visão Geral do seu projeto no portal Azure AI Foundry.
Passo 2: Crie o Seu Arquivo .env
Para criar o 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 o token copiado, abra o arquivo .env no seu editor de texto favorito e cole o token no campo PROJECT_ENDPOINT.
Passo 3: Faça Login no Azure
Como uma prática recomendada 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 quiser executar esses exemplos, você precisará adicionar as seguintes variáveis de ambiente ao seu arquivo .env:
Página de Visão Geral (Projeto)
-
AZURE_SUBSCRIPTION_ID- Verifique Detalhes do Projeto na página Visão Geral do seu projeto. -
AZURE_AI_PROJECT_NAME- Veja no topo da página Visão Geral do seu projeto. -
AZURE_OPENAI_SERVICE- Encontre isso na aba Capacidades Incluídas para Azure OpenAI Service na página Visão Geral.
Centro de Gerenciamento
-
AZURE_OPENAI_RESOURCE_GROUP- Vá para Propriedades do Projeto na página Visão Geral do Centro de Gerenciamento. -
GLOBAL_LLM_SERVICE- Em Recursos Conectados, encontre o nome da conexão Azure AI Services. Se não listado, verifique no portal Azure no seu grupo de recursos o nome do recurso AI Services.
Página de Modelos + Endpoints
-
AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME- Selecione seu modelo de embedding (ex.:text-embedding-ada-002) e anote o Nome do Deployment nos detalhes do modelo. -
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME- Selecione seu modelo de chat (ex.:gpt-4o-mini) e anote o Nome do Deployment nos detalhes do modelo.
Portal Azure
-
AZURE_OPENAI_ENDPOINT- Procure por Azure AI services, clique nele, depois vá para Gerenciamento de Recursos, Chaves e Endpoint, role para baixo até “Endpoints do Azure OpenAI” e copie o que diz “APIs de Linguagem”. -
AZURE_OPENAI_API_KEY- Na mesma tela, copie a CHAVE 1 ou CHAVE 2. -
AZURE_SEARCH_SERVICE_ENDPOINT- Encontre seu recurso Azure AI Search, clique nele e veja Visão Geral. -
AZURE_SEARCH_API_KEY- Depois vá para Configurações e depois Chaves para copiar a chave de administrador primária ou secundária.
Página Externa
AZURE_OPENAI_API_VERSION- Visite a página Ciclo de vida da versão da API em Última versão GA da API.
Configurar autenticação sem chave
Em vez de codificar suas credenciais, usaremos uma conexão sem chave com o Azure OpenAI. Para isso, importaremos DefaultAzureCredential e posteriormente chamaremos a função DefaultAzureCredential para obter a credencial.
# Python
from azure.identity import DefaultAzureCredential, InteractiveBrowserCredential
Travado em Algum Lugar?
Se tiveres algum problema ao executar esta configuração, entra no nosso Discord da Comunidade Azure AI ou cria um problema.
Próxima Aula
Agora estás 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 para garantir a precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original no seu idioma nativo deve ser considerado a fonte autoritária. Para informações críticas, recomenda-se uma tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas resultantes do uso desta tradução.