할 수 있는 일을 물어봤습니다.

세팅 옵션에서 확인할 사항

I’ll scan both project directories to locate READMEs and high-level docs, and do a quick semantic sweep to spot entry points. Then I’ll open any discovered README files.

[5 tools called]

I’ll quickly list a couple of sample directories and search for the CLI commands to run the dev UI and server so I can give you accurate quickstart steps.

[4 tools called]

I scanned both paths. 2509qmac has no files. adk-python-main is a full Python toolkit for building and running AI agents.

한 줄 요약

Google Agent Development Kit (ADK): Python 기반 오픈소스 에이전트 프레임워크. Gemini 최적화지만 모델/배포 무관. 에이전트 정의, 도구 호출, 멀티에이전트 오케스트레이션, 평가/디버깅 UI와 CLI 제공.

핵심 기능

풍부한 도구 생태계: 내장/커스텀 함수, OpenAPI, Google 생태계 연동 도구.
코드-우선 설계: 에이전트/툴/오케스트레이션을 Python 코드로 선언.
멀티 에이전트: 계층형/협업 구조 구성.
배포 무관: 로컬, Cloud Run, Vertex AI Agent Engine 등.
Dev UI/CLI: adk web(웹 UI), adk api_server(로컬 API), adk eval(평가).

아키텍처 개념

Agent: 정체성/지시문/도구를 담는 선언적 객체.
Tool: 에이전트가 호출하는 능력(함수).
Runner: Reason-Act 루프/LLM 호출/툴 실행 오케스트레이션.
Session/Memory/Artifact Service: 대화 상태/장기기억/파일 등 아티팩트 관리.

리포지토리 구조(주요)

src/google/adk/...: ADK 핵심 라이브러리
contributing/samples/...: 다양한 샘플 에이전트와 설정
tests/...: 단위/통합 테스트
루트의 README.md, AGENTS.md, CHANGELOG.md, pyproject.toml 등 문서/설정

코드로 에이전트 정의(예시)

from google.adk.agents import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name="search_assistant",
    model="gemini-2.0-flash", # Or your preferred Gemini model
    instruction="You are a helpful assistant. Answer user questions using Google Search when needed.",
    description="An assistant that can search the web.",
    tools=[google_search]
)

빠른 시작

설치:

pip install google-adk

Dev UI 실행(프로젝트 루트에서):

adk web

로컬 API 서버:

adk api_server

평가 실행:

adk eval <AGENT_MODULE_PATH> <EVAL_SET_FILE>

샘플 위치

간단 예: contributing/samples/hello_world/ (여러 샘플 폴더에서 agent.py 확인)
요약: adk-python-main은 에이전트를 코드로 정의하고, 웹 UI/CLI로 실험·평가·배포까지 이어지는 풀스택 에이전트 개발 키트입니다. 2509qmac는 현재 비어 있습니다.

더 쉬운 설명

한눈에 이해하기

무엇인가요?
adk-python-main은 “디지털 비서(에이전트)를 만드는 공방”이에요. 질문에 답하고, 웹을 검색하고, 일정을 잡는 등 일을 대신해주는 비서를 코드로 손쉽게 만들고 시험해볼 수 있게 해줍니다.
2509qmac 폴더는 지금 비어 있어요.

무엇을 할 수 있나요?

질문에 답하는 비서: “오늘 날씨 어때?” 같은 질문 대응
도구 쓰는 비서: 웹검색, 구글 API, 스프레드시트 등 외부 도구 사용
여러 비서가 팀으로 협업: 환영 담당, 작업 담당 등 역할 나눠 함께 일함
시험하고 관찰하기: 웹 화면에서 대화해 보며 동작을 바로 확인
평가하고 개선하기: 버튼 한 번(또는 명령어)로 성능을 점검

어떻게 쓰나요? (가장 쉬운 흐름)

1) 프로그램 설치

pip install google-adk

2) 샘플 비서 실행 화면 열기(프로젝트 폴더에서)

adk web

브라우저에 개발용 화면이 열리고, 샘플 비서를 골라 바로 대화해볼 수 있어요.

3) 더 진짜같이 써보기(선택)

로컬 API 서버 열기:

adk api_server

미리 준비한 문제집으로 평가하기:

adk eval <에이전트_경로> <평가셋_파일>

폴더 안에 뭐가 있나요?

contributing/samples/ 샘플 비서 모음(바로 실행해보기 좋음)
src/google/adk/ 비서가 돌아가는 핵심 엔진
README.md 쉬운 소개서

원하시면 “검색 도구 쓰는 간단 비서” 같은 구체 예시부터 바로 같이 돌려드릴게요.

구체적으로 할 수 있는 일은.

예제로 보는 “무엇을 할 수 있나요?”

일반 질문 답변/요약: 웹을 찾아 최신 정보 요약, 링크와 함께 정리.
샘플: contributing/samples/google_search_agent/, hello_world/
일정·업무 자동화: Google Calendar에 일정 만들기/수정, 리마인드 설정.
샘플: contributing/samples/oauth_calendar_agent/
사내 문서 Q&A (RAG): 문서/위키를 넣어 “사내 규정 알려줘” 같은 질의에 정확히 답변.
샘플: contributing/samples/adk_answering_agent/, Vertex AI Search 연동 스크립트 포함
동영상/콘텐츠 탐색: 유튜브에서 찾고 핵심만 요약.
샘플: contributing/samples/langchain_youtube_search_agent/
데이터 조회/리포트: BigQuery/Bigtable/Spanner에서 쿼리해 요약 리포트 만들기.
샘플: contributing/samples/bigquery/, bigtable/, spanner/, spanner_rag_agent/
코드 보조: PR 요약/리뷰 포인트 추출, 이슈 템플릿 자동화.
샘플: contributing/samples/adk_pr_agent/, adk_pr_triaging_agent/, adk_issue_formatting_agent/
파일 작업 도우미: 로컬 파일 찾기/읽기/정리, 결과 저장.
샘플: contributing/samples/toolbox_agent/
여러 에이전트 협업(워크플로): 접수→분류→처리 같은 단계형 자동화.
샘플: contributing/samples/workflow_triage/, workflow_agent_seq/, multi_agent_*
사람 확인이 필요한 업무: 중요한 행동 전 “확인해 주세요”로 멈추고 승인 시 진행.
샘플: contributing/samples/human_in_loop/, tool_human_in_the_loop_config/
실시간 음성/영상 대화: 마이크/카메라로 대화하며 즉시 응답(회의 메모, 요약 등).
샘플: contributing/samples/live_bidi_streaming_*
외부 서비스 도구 붙이기(MCP 등): 노션/파일시스템 같은 외부 기능을 도구로 추가.
샘플: contributing/samples/mcp_*
세션/기억: 대화 맥락과 사용자 선호를 기억해 다음 대화에 반영.
샘플: contributing/samples/session_state_agent/, memory/
평가·점검 자동화: 시나리오(문제집)로 성능을 재현·비교, 개선 추적.
사용: adk web(대화형), adk eval(명령행)

바로 시작하시려면

“원하는 시나리오”를 알려주세요. 예: “캘린더에 회의 잡아주고 요약 메일 보내기”.
해당 샘플 경로와 실행 방법을 딱 필요한 만큼 안내드리고, 필요하면 간단히 커스터마이즈해 드릴게요.

I’ll check if there’s a built-in google_search tool and locate a sample we can copy from, then I’ll propose a minimal news_assistant agent with files you can drop into the repo and run via adk web.

[1 tool called]

I’ll open a couple of sample files to mirror their structure for a new news_assistant under contributing/samples/, then I’ll draft the three files (__init__.py, agent.py, main.py) and give you exact run steps.

[3 tools called]

우리가 만들 것

“최신 뉴스를 찾아 요약해 주는 비서”를 샘플로 추가해서 웹 화면에서 바로 대화해볼 거예요.

파일 만들기

폴더: contributing/samples/news_assistant/
파일 1: contributing/samples/news_assistant/__init__.py

from . import agent

파일 2: contributing/samples/news_assistant/agent.py

from google.adk.agents import Agent
from google.adk.tools import google_search

root_agent = Agent(
  model="gemini-2.0-flash",
  name="news_assistant",
  description="주제별 최신 뉴스를 찾아 출처와 함께 간단히 요약해 주는 비서.",
  instruction="""
당신은 뉴스 큐레이터입니다.
- 사용자가 주제를 말하면, 기본적으로 '최근 24시간' 또는 '오늘' 기준의 최신 소식을 Google 검색으로 찾아 요약하세요.
- 한국어로 3~5개 핵심 포인트를 불릿으로 정리하고, 각 항목에
  (제목) — (한 줄 요약) — (출처명) — (링크) — (가능하면 게시 시각)을 포함하세요.
- 중복/낚시성 기사, 오래된 정보는 제외하고 신뢰도 높은 출처를 우선하세요.
- 지역/기간/매체 선호가 있으면 반영하세요. 없으면 간단히 물어봐도 돼요.
- 답변 끝에 "더 좁혀드릴까요? (예: IT/경제/스포츠, 한국/해외, 오늘/이번 주)" 같은 짤막한 후속 질문을 제안하세요.
""",
  tools=[google_search],
)

실행 방법

1) (필요시) Gemini API 키 설정 후 프로젝트 루트로 이동
2) 루트에서 실행:

adk web

3) 브라우저에서 에이전트 드롭다운에서 news_assistant 선택 후 대화

바로 써볼 질문

“오늘의 테크 주요 뉴스 5개만, 한국 매체 위주로 알려줘”
“카카오 관련 최신 기사 3개 요약해줘. 각 기사 링크와 시각 포함해줘”
“해외 증시 뉴스 중 중요한 헤드라인만 뽑아줘. 오늘자 기준으로”
핵심: google_search 도구로 최신 검색 결과를 근거로 요약하고, 출처/링크를 함께 보여줍니다.

나는 아무것도 할 줄 몰라, 네가 필요한 일을 처음부터 끝 까지 다 해서 실행까지 해줘야해.

알겠습니다! 제가 처음부터 끝까지 다 준비하고 실행까지 해드릴게요. 걱정하지 마세요!

단계별 진행:

새 폴더 만들기: contributing/samples/news_assistant
필요한 파일 만들기: __init__.py와 agent.py 두 파일을 해당 폴더 안에 만들 거예요. 이 파일들이 뉴스 비서의 작동 방식과 역할을 정의합니다.
개발 UI 실행: 만든 뉴스 비서를 웹 브라우저에서 바로 사용해볼 수 있도록 개발용 웹 화면을 띄울 겁니다.

시작할게요!

[3 tools called]

뉴스 비서 (news_assistant)가 성공적으로 생성되었고, 개발용 웹 UI가 백그라운드에서 실행되고 있습니다!

이제 웹 브라우저에서 직접 확인하고 대화해볼 수 있습니다.

웹 브라우저 열기: 웹 브라우저를 열어주세요. (일반적으로 http://localhost:8080 으로 접속하면 됩니다. 만약 다른 포트가 사용 중이라면 자동으로 다른 포트로 열릴 수 있습니다. 터미널의 출력 메시지를 확인해주세요.)
에이전트 선택: 개발 UI 화면에서 “Select Agent” 드롭다운 메뉴를 찾아 클릭하세요.
news_assistant 선택: 목록에서 news_assistant를 찾아서 선택해주세요.
대화 시작: 아래와 같은 질문을 입력창에 넣고 엔터키를 눌러 대화를 시작해보세요.
- “오늘의 IT 뉴스 3개 알려줘”
- “최근 경제 뉴스 요약해줘”
- “어제 한국 스포츠 소식은?”

이제 뉴스 비서와 대화하며 최신 뉴스를 받아볼 수 있습니다!

에러 및 구글 API KEY 발급후 진행

이전에 실행 중이던 adk web 서버 때문에 포트 충돌이 발생하고, 모델(Gemini)을 사용하기 위한 API 키가 없어서 에러가 발생하고 있습니다. “Cannot find specified session. Creating a new one.” 메시지는 에러라기보다는 정보 메시지이므로 괜찮습니다.

두 번째 오류인 “Missing key inputs argument!”를 해결하기 위해 다음 단계를 진행할게요.

실행 중인 서버 종료: 현재 포트 8000을 사용 중인 adk web 프로세스를 먼저 종료할 거예요.
API 키 설정 코드 추가: news_assistant 에이전트 코드에 Gemini API 키를 환경 변수에서 가져와 사용하도록 수정할 거예요.
API 키 설정 및 재실행 안내: 사용자의 Gemini API 키를 설정하는 방법과 함께 뉴스 비서를 다시 실행하는 명령어를 알려드릴게요.

먼저, 실행 중인 서버를 종료하겠습니다.

[1 tool called]

실행 중이던 서버를 종료했습니다. 이제 news_assistant/agent.py 파일에 API 키를 환경 변수에서 로드하는 코드를 추가하겠습니다. 이 코드는 GOOGLE_API_KEY 환경 변수에서 API 키를 가져오도록 설정할 것입니다.

[1 tool called]

API 키 설정 코드를 agent.py 파일에 추가했습니다.

이제 가장 중요한 단계입니다! Gemini API 키를 설정해야 합니다.

Gemini API 키 발급: 만약 Gemini API 키가 없다면, Google AI Studio 또는 Google Cloud Console에서 발급받으세요.
환경 변수 설정: 터미널에 다음 명령어를 입력하여 API 키를 환경 변수에 등록합니다. <YOUR_GEMINI_API_KEY> 부분은 발급받은 실제 키로 바꿔주세요. export GOOGLE_API_KEY='<YOUR_GEMINI_API_KEY>' (이 환경 변수는 현재 터미널 세션에만 유효합니다. 터미널을 닫았다면 다시 설정해야 합니다.)
뉴스 비서 다시 실행: 이제 API 키가 설정되었으므로, 뉴스 비서를 다시 시작합니다.

cd /Users/qmini/Downloads/adk-python-main && adk web contributing/samples

이 명령어를 실행하면 웹 UI가 다시 열리고, 이제 news_assistant 에이전트와 대화하면서 최신 뉴스를 받아볼 수 있을 거예요!

api 키 입력후에는 에러 없이 답변을 주지 않음.

두 번째 오류인 “Missing key inputs argument!”를 해결하기 위해 다음 단계를 진행할게요.

실행 중인 서버 종료: 현재 포트 8000을 사용 중인 adk web 프로세스를 먼저 종료할 거예요.
API 키 설정 코드 추가: news_assistant 에이전트 코드에 Gemini API 키를 환경 변수에서 가져와 사용하도록 수정할 거예요.
API 키 설정 및 재실행 안내: 사용자의 Gemini API 키를 설정하는 방법과 함께 뉴스 비서를 다시 실행하는 명령어를 알려드릴게요.

먼저, 실행 중인 서버를 종료하겠습니다.

[1 tool called]

API 키 설정 코드를 agent.py 파일에 추가했습니다.

이제 가장 중요한 단계입니다! Gemini API 키를 설정해야 합니다.

Gemini API 키 발급: 만약 Gemini API 키가 없다면, Google AI Studio 또는 Google Cloud Console에서 발급받으세요.
환경 변수 설정: 터미널에 다음 명령어를 입력하여 API 키를 환경 변수에 등록합니다. <YOUR_GEMINI_API_KEY> 부분은 발급받은 실제 키로 바꿔주세요. export GOOGLE_API_KEY='<YOUR_GEMINI_API_KEY>' (이 환경 변수는 현재 터미널 세션에만 유효합니다. 터미널을 닫았다면 다시 설정해야 합니다.)
뉴스 비서 다시 실행: 이제 API 키가 설정되었으므로, 뉴스 비서를 다시 시작합니다.

cd /Users/qmini/Downloads/adk-python-main && adk web contributing/samples

이 명령어를 실행하면 웹 UI가 다시 열리고, 이제 news_assistant 에이전트와 대화하면서 최신 뉴스를 받아볼 수 있을 거예요!

google adk-python-main 설치, 실행과정 스크랩

한 줄 요약

핵심 기능

아키텍처 개념

리포지토리 구조(주요)

코드로 에이전트 정의(예시)

빠른 시작

샘플 위치

더 쉬운 설명

한눈에 이해하기

무엇을 할 수 있나요?

어떻게 쓰나요? (가장 쉬운 흐름)

폴더 안에 뭐가 있나요?

구체적으로 할 수 있는 일은.

예제로 보는 “무엇을 할 수 있나요?”

바로 시작하시려면

우리가 만들 것

파일 만들기

실행 방법

바로 써볼 질문

나는 아무것도 할 줄 몰라, 네가 필요한 일을 처음부터 끝 까지 다 해서 실행까지 해줘야해.

에러 및 구글 API KEY 발급후 진행

api 키 입력후에는 에러 없이 답변을 주지 않음.

댓글

답글 남기기 응답 취소