Escolher o ambiente de desenvolvimento
Para começar, você vai precisar de um ambiente de desenvolvimento Python com o Python 3.11 ou mais recente. As etapas aqui foram testadas no Google Colab.
Também é possível adaptar as etapas mostradas aqui em outros ambientes de desenvolvimento, como o Colab Enterprise, o editor do Cloud Shell ou a máquina local.
Quando o ambiente estiver pronto, você poderá instalar o SDK do Agent Framework.
Instalar o SDK do Agent Framework
Agora, você vai instalar o SDK do Agent Framework. Durante o período de visualização particular, o acesso ao SDK exige a inclusão na lista de permissões. Confira se você está na lista de permissões antes de prosseguir com as etapas de download e instalação abaixo.
Primeiro, autentique sua conta do Google Cloud usando a CLI gcloud. Essa etapa garante que você tenha as permissões necessárias para acessar os serviços do Google Cloud. Consulte a documentação do gcloud para mais informações, se necessário.
gcloud auth login
Faça o download do pacote Python do SDK do Agent Framework para o ambiente de desenvolvimento usando a CLI gcloud:
gcloud storage cp gs://agent_framework/latest/google_genai_agents-0.0.2.dev20250204+723246417-py3-none-any.whl .
Você precisa estar na lista de permissões para que o Agent Framework acesse os builds de desenvolvimento no comando anterior.
Por fim, instale o pacote do SDK do Agent Framework baixado usando pip:
pip install google_genai_agents-0.0.2.dev20250204+723246417-py3-none-any.whl
Com o SDK do Agent Framework instalado, agora você pode importar as bibliotecas necessárias para começar a criar seu agente.
Importar as bibliotecas necessárias
Importe as seguintes bibliotecas Python, que são necessárias para usar este início rápido com o Agent Framework:
import os
from agents import Runner, Agent
from datetime import datetime
Depois de importar as bibliotecas, a próxima etapa é configurar o acesso aos modelos do Gemini.
Configurar o acesso à API Gemini
O Agent Framework pode ser configurado para usar modelos do Gemini do Google. É possível configurar o acesso aos modelos do Gemini pelo Google AI Studio (usando uma chave de API) ou pela Vertex AI (usando seu projeto do Google Cloud). Escolha o método de configuração que atenda às suas necessidades e siga as instruções correspondentes abaixo.
Para configurar o acesso aos modelos do Gemini usando o Google AI Studio, execute o seguinte
código Python. Substitua YOUR_API_KEY pela sua chave de API do Google AI Studio.
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "0"
os.environ["GOOGLE_API_KEY"] = "YOUR_API_KEY"
Para configurar o acesso aos modelos do Gemini usando a Vertex AI, execute o código
Python abaixo. Substitua YOUR_PROJECT_ID pelo ID do projeto do Google Cloud. Verifique se
GOOGLE_CLOUD_LOCATION está definido como uma região da Vertex AI com suporte.
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "1"
os.environ["GOOGLE_CLOUD_PROJECT"] = "YOUR_PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "us-central1"
Com o acesso à API Gemini configurado, você já pode definir as ferramentas que seu agente vai usar.
Definir ferramentas para o agente
Os agentes costumam usar ferramentas para interagir com serviços e dados externos. Nesta
etapa, você vai definir uma função Python chamada get_exchange_rate. Essa
função vai servir como uma ferramenta para que o agente recupere as taxas de câmbio
em tempo real de uma API externa.
def get_exchange_rate(
currency_from: str,
currency_to: str,
currency_date: str,
):
"""Retrieves the exchange rate between two currencies on a specified date."""
import requests
response = requests.get(
f"https://api.frankfurter.app/{currency_date}",
params={"from": currency_from, "to": currency_to},
)
return response.json()
Agora você definiu uma ferramenta para o agente. Na próxima seção, você vai definir o agente, incorporando essa ferramenta.
Definir o agente
Agora, você vai definir seu agente de IA usando o SDK do Agent Framework. A definição do agente especifica o modelo que ele vai usar, as instruções, as ferramentas que ele pode acessar e o fluxo de interação.
root_agent = Agent(
model="gemini-2.5-pro-exp-03-25",
name='currency_exchange_agent',
instruction="""
Help users retrieve exchange rates for different currencies
""",
tools=[
get_exchange_rate,
],
flow='single',
)
Com o agente definido, a próxima etapa é inicializá-lo no Agent Framework.
Inicializar o agente
Nesta seção, você vai inicializar o agente. O código abaixo configura sessões na memória e serviços de artefato, instancia um Runner para seu agente e define uma função auxiliar para enviar solicitações.
from agents.sessions.in_memory_session_service import InMemorySessionService
from agents.artifacts.in_memory_artifact_service import InMemoryArtifactService
from google.genai import types
session_service = InMemorySessionService()
artifact_service = InMemoryArtifactService()
runner = Runner(app_name="currency_exchange_agent", agent=root_agent, artifact_service=artifact_service, session_service=session_service)
session = session_service.create(app_name="currency_exchange_agent", user_id="1")
def run_prompt(new_message: str):
content = types.Content(role='user', parts=[types.Part.from_text(text=new_message)])
print (content)
for event in runner.run(
session=session,
new_message=content,
):
if event.content:
print(event.content.model_dump(exclude_none=True))
Seu agente foi inicializado e está pronto para receber comandos. Na próxima seção, você vai enviar um comando de teste para conferir como ele funciona.
Enviar uma solicitação para o agente
Agora é hora de testar o agente. Envie a seguinte solicitação ao agente usando a função run_prompt que você definiu anteriormente.
run_prompt("What's the exchange rate from US dollars to Swedish currency today?")
Execute a função run_prompt com a entrada fornecida. O agente vai produzir uma saída semelhante a esta:
parts=[Part(video_metadata=None, thought=None, code_execution_result=None, executable_code=None, file_data=None, function_call=None, function_response=None, inline_data=None, text="What's the exchange rate from US dollars to Swedish currency today?")] role='user'
{'parts': [{'function_call': {'args': {'currency_from': 'USD', 'currency_to': 'SEK', 'currency_date': '2025-02-21'}, 'name': 'get_exchange_rate'}}], 'role': 'model'}
{'parts': [{'function_response': {'name': 'get_exchange_rate', 'response': {'amount': 1.0, 'base': 'USD', 'date': '2025-02-21', 'rates': {'SEK': 10.6474}}}}], 'role': 'user'}
{'parts': [{'text': 'The exchange rate from US dollars to Swedish currency (SEK) today, 2025-02-21, is 1 USD to 10.6474 SEK.\n'}], 'role': 'model'}
Essa saída mostra as etapas internas do agente, incluindo a chamada de função feita e a resposta final.
Examine a parte final da saída. Você vai receber uma mensagem do agente
com a taxa de câmbio recuperada, demonstrando que o agente
usou a ferramenta get_exchange_rate:
The exchange rate from US dollars to Swedish currency (SEK) today, 2025-02-21,
is 1 USD to 10.6474 SEK.
Parabéns! Você enviou uma solicitação ao agente e observou a resposta dele. Para saber mais sobre o Agent Framework, consulte a próxima seção para conferir recursos e próximas etapas.
Próximas etapas e recursos
Parabéns! Você criou um agente de IA com o Agent Framework.
Para entender melhor e conhecer recursos mais avançados do Agent Framework, consulte outras seções da documentação, exemplos de código ou notebooks. Esses recursos vão orientar você na criação de agentes mais complexos e na integração deles aos seus aplicativos.