Microsoft Agent Framework 튜토리얼 – Agent Harness와 Claw로 금융 에이전트 만들기

1. 채팅 클라이언트를 만든다
2. 지침과 도구를 붙여 Harness Agent로 감싼다
3. Harness Console에서 실행한다
4. 세션을 저장하고 이어간다
언제 유용한가
관련 문서
참고 자료

Microsoft Agent Framework의 Harness 튜토리얼은 “모델 호출 코드”를 “도구, 메모리, 플랜 모드, 세션 복구를 갖춘 에이전트”로 감싸는 방법을 보여준다. 핵심은 채팅 클라이언트는 교체 가능하게 두고, 하네스가 실행 구조를 제공하게 만드는 것이다.

1. 채팅 클라이언트를 만든다

예제는 Microsoft Foundry의 Responses API를 사용하지만, Harness Agent는 Azure OpenAI, OpenAI, Anthropic, Gemini, Ollama 등 여러 채팅 클라이언트를 감쌀 수 있다. 환경 변수로 프로젝트 엔드포인트와 모델 배포명을 읽고 인증은 Azure CLI 또는 관리 ID로 처리한다.

from azure.identity import AzureCliCredential
from agent_framework.azure import FoundryChatClient

client = FoundryChatClient(credential=AzureCliCredential())

2. 지침과 도구를 붙여 Harness Agent로 감싼다

튜토리얼의 예시는 개인 금융 어시스턴트다. 지침에는 주식 가격은 도구로 확인하고, 웹 출처를 인용하고, 관심 종목은 watchlist.md 메모리 파일로 유지하라는 규칙을 넣는다. 커스텀 도구는 일반 함수로 작성하면 프레임워크가 도구 스키마를 만든다.

def get_stock_price(symbol: str) -> dict[str, object]:
    return {"symbol": symbol.upper(), "price": 420.0, "currency": "USD"}

agent = create_harness_agent(
    client=client,
    agent_instructions=FINANCE_INSTRUCTIONS,
    tools=get_stock_price,
)

이 한 번의 래핑으로 함수 호출, 서비스 호출 단위 히스토리, TodoProvider, AgentModeProvider, 웹 검색, 파일 메모리가 기본 제공된다.

3. Harness Console에서 실행한다

공식 샘플 콘솔은 /mode, /todos, /exit, 세션 저장·복구 명령을 제공하는 스트리밍 터미널 UI다. 실행 모드는 빠른 조회용 execute와 계획 승인용 plan으로 나뉜다.

플랜 모드는 자유 텍스트가 아니라 JSON 스키마 기반 구조화 출력으로 작동한다. 모델은 명확하지 않을 때 clarification 질문을 내고, 실행 전에는 approval 형태로 계획 요약을 반환한다. 콘솔은 사용자가 승인하면 실행 모드로 전환한다.

4. 세션을 저장하고 이어간다

/session-export는 대화 히스토리와 파일 메모리 위치 같은 context provider 상태를 JSON으로 직렬화한다. /session-import로 다시 불러오면 이전 watchlist를 다시 설명하지 않아도 이어서 작업할 수 있다.

언제 유용한가

이 튜토리얼은 자체 에이전트 UI나 업무 도구를 만드는 팀에 유용하다. 플랜 승인, 파일 메모리, 웹 검색, 도구 승인 같은 하네스 기능을 직접 모두 만들지 않고 시작한 뒤, 필요 없는 기능은 disable_todo, disable_web_search, disable_memory 같은 옵션으로 줄일 수 있다.

참고 자료

Meet your agent harness and claw — Microsoft Agent Framework Blog (2026-06-24)

Like?

AI Sparkup