Show HN: Fast-agent – MCP 기반 에이전트 및 워크플로우를 몇 분 만에 구성 - Insights

시작하기 (Start Here)

[!TIP]
최신 문서는 https://fast-agent.ai를 참조하세요.

**fast-agent**는 LLM과 상호작용하는 유연한 방법으로, Coding Agent, Development Toolkit, Evaluation 또는 Workflow 플랫폼으로 사용하기에 탁월합니다.

쉘 지원을 통해 대화형 세션을 시작하려면 uv를 설치하고 다음 명령어를 실행하세요:

uvx fast-agent-mcp@latest -x

Hugging Face inference providers로 코딩을 하거나 OpenAI Codex 플랜을 사용하려면:

# Hugging Face Inference Providers로 코드 작성하기
uvx fast-agent-mcp@latest --pack hf-dev

...

!를 사용하여 쉘에 진입하거나, ! cd web && npm run build와 같은 쉘 명령어를 실행할 수 있습니다.

/skills 명령어로 스킬을 관리하고, /connect로 MCP 서버에 연결하세요. 기본 fast-agent 레지스트리에는 LSP, Agent 및 Tool Hooks, Compaction 전략, 자동화 등을 설정할 수 있는 스킬이 포함되어 있습니다.

# /connect는 stdio 또는 streamable http (OAuth 사용 시)을 지원합니다.

# STDIO 서버 시작하기
...

쉘 별칭(shell aliases) 및 기타 도구링(tooling) 설정을 위해 fast-agent 설치를 권장합니다.

# fast-agent 설치하기
uv tool install -U fast-agent-mcp

...

범용 제공업체(generic provider)를 사용하여 로컬 모델을 사용하거나, llama.cpp에 대한 올바른 구성을 자동으로 생성할 수 있습니다:

fast-agent model llamacpp

모든 fast-agent 설정 또는 프로그램은 모든 ACP 클라이언트와 함께 사용할 수 있으며, 가장 간단한 방법은 fast-agent-acp를 사용하는 것입니다:

# Toad 내부에서 fast-agent 실행하기
toad acp "fast-agent-acp -x --model sonnet"

**fast-agent**는 몇 분 만에 정교한 멀티모달 에이전트(Agents)와 워크플로우(Workflows)를 생성하고 상호 작용할 수 있게 해줍니다. 샘플링(Sampling)과 엘리시테이션(Elicitations)을 포함하여 완전하고 엔드투엔드로 테스트된 MCP 기능 지원을 갖춘 최초의 프레임워크입니다.

fast-agent는 CLI 우선 방식이며, 선택적으로 prompt_toolkit 기반의 대화형 터미널 프롬프트(TUI 스타일 입력, 자동 완성 및 인터미널 메뉴)를 제공합니다. 응답은 전체 화면 curses UI나 외부 GUI 오버레이에 의존하지 않고 rich를 통해 실시간으로 터미널에 스트리밍할 수 있습니다.

간단한 선언적 구문(declarative syntax)을 사용하여 프롬프트와 MCP 서버 구성에 집중하여 효과적인 에이전트를 구축할 수 있습니다(build effective agents).

모델 지원은 포괄적이며, Anthropic, OpenAI, Google 제공업체에 대한 네이티브 지원뿐만 아니라 TensorZero를 통해 Azure, Ollama, Deepseek 및 수십 개의 다른 제공업체를 지원합니다. 구조화된 출력(Structured Outputs), PDF 및 비전(Vision) 지원은 사용하기 쉽고 잘 테스트되었습니다. Passthrough 및 Playback LLMs는 애플리케이션용 Python 접착 코드(glue-code)를 신속하게 개발하고 테스트할 수 있게 합니다.

최근 기능에는 다음이 포함됩니다:

에이전트 스킬(Agent Skills) (SKILL.md)
MCP 앱(MCP Apps)
OpenAI 앱 SDK(OpenAI Apps SDK)
셸 모드(Shell Mode)
고급 MCP 전송 진단(Advanced MCP Transport Diagnostics)
MCP 엘리시테이션(MCP Elicitations)

<img width=

⚠️ [중요] Documentation은 이 리포지토리의 docs/에서 확인할 수 있습니다. 리포지토리 루트에 있는 docs helper 스크립트를 사용하여 사이트 설치, 생성, 빌드, 서비스, 스크린샷 및 평가를 수행하세요.

에이전트 애플리케이션 개발

에이전트 애플리케이션을 정의하는 프롬프트와 구성은 간단한 파일에 저장되며, 최소한의 보일러플레이트를 사용하여 쉬운 관리와 버전 관리가 가능합니다.

워크플로우 실행 전, 중, 후에 개별 에이전트 및 컴포넌트와 채팅하여 애플리케이션을 튜닝하고 진단할 수 있습니다. 에이전트는 작업 완료를 위해 추가적인 컨텍스트를 얻기 위해 인간의 입력을 요청할 수 있습니다.

간단한 모델 선택 기능은 Model <-> MCP 서버 상호작용 테스트를 수월하게 만듭니다. 이 프로젝트의 배경에 대한 더 많은 정보는 여기에서 읽을 수 있습니다.

2025-03-23-fast-agent

시작하기:

Python용 uv 패키지 매니저를 설치하는 것부터 시작하세요. 그리고 다음 명령어를 실행합니다:

uv pip install fast-agent-mcp          # fast-agent 설치!
fast-agent go                          # 대화형 세션 시작
fast-agent go --url https://hf.co/mcp  # 원격 MCP 사용 시
...

모델이 설정되지 않은 경우, 대화형 실행(interactive run)에서 모델 선택기(model picker)가 열립니다.
자동화 및 서버 실행은 --model을 전달하거나, FAST_AGENT_MODEL을 설정하거나, default_model을 구성하거나, 에이전트에서 모델을 선언해야 합니다.

패키지화된 스타터 에이전트를 사용하려면 fast-agent go --pack <name> --model <model>을 사용하세요. 이는 필요에 따라 해당 팩을 선택된 fast-agent 홈 디렉토리에 설치한 다음, 정상적으로 go를 시작합니다. --model은 명시적인 모델 설정이 없는 카드(card)의 대체 수단이며, AgentCard 내에서 직접 선언된 모델이 여전히 우선권을 가집니다.

다른 빠른 시작 예제로는 리서처 에이전트(Evaluator-Optimizer 워크플로우 포함)와 데이터 분석 에이전트(ChatGPT 경험과 유사)가 있으며, MCP Roots 지원을 시연합니다.

[팁] Windows 사용자 - 파일 시스템 및 Docker MCP 서버의 경우 몇 가지 구성 변경이 필요하며, 필요한 변경 사항은 구성 파일 내에 자세히 설명되어 있습니다.

기본 에이전트 (Basic Agents)

에이전트를 정의하는 것은 다음과 같이 간단합니다:

@fast.agent(
  instruction="Given an object, respond only with an estimate of its size."
)

그런 다음 이 에이전트에 메시지를 보낼 수 있습니다:

async with fast.run() as agent:
    moon_size = await agent("the moon")
    print(moon_size)

또는 에이전트와 대화형 채팅을 시작할 수 있습니다:

async with fast.run() as agent:
    await agent.interactive()

여기에 보일러플레이트 코드가 포함된 전체 sizer.py 에이전트 애플리케이션이 있습니다:

import asyncio
from fast_agent import FastAgent

...

에이전트는 uv run sizer.py로 실행할 수 있습니다.

--model 스위치를 사용하여 모델을 지정하세요. 예를 들어, uv run sizer.py --model sonnet입니다.

모델 문자열은 쿼리 오버라이드(query overrides)도 허용합니다. 예를 들면:

uv run sizer.py --model "gpt-5?reasoning=low"
uv run sizer.py --model "claude-sonnet-4-6?web_search=on"
uv run sizer.py --model "claude-sonnet-4-5?context=1m"
uv run sizer.py --model "gpt-5?poll_period=240"

Anthropic 모델의 경우, ?context=1m은 여전히 명시적인 1M 컨텍스트 옵트인(opt-in)이 필요한 초기 Sonnet 4 / Sonnet 4.5 모델에만 필요합니다. Claude Sonnet 4.6과 Claude Opus 4.6은 이미 기본적으로 긴 컨텍스트 창을 사용하므로, ?context=1m은 하위 호환성을 위해 허용되지만 필수는 아닙니다.

에이전트 결합 및 MCP 서버 사용 (Combining Agents and using MCP Servers)

예제를 생성하려면 fast-agent quickstart workflow를 사용하세요. 이 예제는 uv run workflow/chaining.py로 실행할 수 있습니다. fast-agent.yaml 파일을 활성 fast-agent 홈 디렉터리에 두거나, 필요할 때 명시적인 설정 경로를 전달하세요.

에이전트는 MCP 서버(MCP Servers)를 사용하여 워크플로우를 구축하기 위해 연결(chain)될 수 있으며, 이 MCP 서버는 fast-agent.yaml 파일에 정의됩니다:

@fast.agent(
    "url_fetcher",
    "Given a URL, provide a complete and comprehensive summary",
...

모든 에이전트와 워크플로우는 채팅 세션을 시작하기 위해 `.send(

uv run workflow/chaining.py --agent post_writer --message "<url>"

--quiet 스위치를 추가하여 진행 상황 및 메시지 표시를 비활성화하고 최종 응답만 반환할 수 있습니다. 이는 간단한 자동화에 유용합니다.

MAKER

MAKER는 “K-voting 오류 감소를 통한 대규모 분해 에이전트 프로세스(Massively decomposed Agentic processes with K-voting Error Reduction)”의 약자입니다. 이 기능은 워커 에이전트를 감싸서 응답이 모든 대안에 대해 k표 차이로 달성될 때까지 반복적으로 샘플링합니다 (“first-to-ahead-by-k” 투표). 이는 드문 오류가 복합적으로 작용할 수 있는 간단한 단계의 긴 체인에 유용합니다.

참고 자료: Zero Errors를 통한 백만 단계 LLM 작업 해결
기여자: Lucid Programmer (PR 작성자)

@fast.agent(
    name="classifier",
    instruction="A, B 또는 C만 응답으로 반환하세요.",
...

도구로서의 에이전트(Agents As Tools)

'도구로서의 에이전트' 워크플로우는 복잡한 작업을 받아 하위 작업으로 분해하고, 메인 에이전트 지침에 따라 다른 에이전트를 도구로 호출합니다.

이 패턴은 OpenAI Agents SDK의 Agents as tools 기능에서 영감을 받았습니다.

자식 에이전트들을 도구로 노출함으로써, 지침 내에서 라우팅(routing), 병렬화(parallelization), 오케스트레이터-워커(orchestrator-workers) 분해(decomposition)를 직접 구현하고 결합할 수 있습니다. 턴당 여러 도구 호출이 지원되며 병렬로 실행됩니다.

일반적인 사용 패턴은 다음을 조합할 수 있습니다:

라우팅(Routing): 사용자 프롬프트에 따라 적절한 전문 도구를 선택합니다.
병렬화(Parallelization): 독립적인 항목/프로젝트를 대상으로 분산 처리한 후 집계합니다.
오케스트레이터-워커(Orchestrator-workers): 작업을 범위가 지정된 하위 작업으로 분해하고 (종종 간단한 JSON 계획을 통해), 실행을 조정합니다.

@fast.agent(
    name="NY-Project-Manager",
    instruction="뉴욕 시간대와 타임존, 그리고 한 줄짜리 프로젝트 상태를 반환하세요.",
...

확장된 예제와 모든 매개변수 샘플은 리포지토리의 examples/workflows/agents_as_tools_extended.py에서 확인할 수 있습니다.

MCP OAuth (v2.1)

SSE 및 HTTP MCP 서버의 경우, 최소한의 설정만으로 OAuth가 기본 활성화됩니다. 인증 코드를 캡처하기 위해 로컬 콜백 서버를 사용하며, 포트가 사용할 수 없는 경우 paste-URL 폴백(fallback)을 제공합니다.

fast-agent.yaml에서 서버별로 최소한의 설정을 지정합니다:

mcp:
  servers:
    myserver:
...

OAuth 클라이언트는 PKCE와 인메모리 토큰 저장소(디스크에 토큰을 쓰지 않음)를 사용합니다.
토큰 지속성(Token persistence): 기본적으로, 토큰은 keyring을 통해 OS 키체인에 안전하게 저장됩니다. 만약 키체인이 사용할 수 없는 경우(예: 헤드리스 컨테이너), 세션에는 인메모리 스토리지가 사용됩니다.
서버별로 강제로 인메모리만 사용하려면 다음을 설정합니다:

mcp:
  servers:
    myserver:
...

특정 서버에 대해 OAuth를 비활성화하려면 해당 서버의 auth.oauth: false를 설정합니다.

MCP Ping (선택 사항)

MCP ping 유틸리티는 피어(클라이언트 또는 서버) 중 어느 한 쪽에서 활성화할 수 있습니다. Ping 개요를 참조하십시오.

클라이언트 측 핑은 서버별로 구성됩니다(기본값: 간격 30초, 누락된 핑 3회):

mcp:
  servers:
    myserver:
...

워크플로우

체인 (Chain)

chain 워크플로우는 에이전트를 순차적으로 호출하는 보다 선언적(declarative) 접근 방식을 제공합니다:


@fast.chain(

에이전트는 작업을 지원하거나 추가 컨텍스트를 얻기 위해 사용자 입력을 요청할 수 있습니다:

```python
@fast.agent(
    instruction="기본적인 작업을 돕는 AI 에이전트입니다. 필요할 때 사용자 입력을 요청하세요.",
    human_input=True,
...

예제 human_input.py에서 에이전트는 작업을 완료하기 위해 사용자에게 추가 정보를 프롬프트합니다.

병렬 처리 (Parallel)

병렬 워크플로우는 동일한 메시지를 여러 에이전트에게 동시에 전송(fan-out)한 다음, 결합된 콘텐츠를 처리하기 위해 fan-in 에이전트를 사용합니다.

Show HN: Fast-agent – MCP 기반 에이전트 및 워크플로우를 몇 분 만에 구성

요약

핵심 포인트