AgentField: AI 에이전트를 API와 마이크로서비스처럼 운영하기 위한 오픈소스 컨트롤 플레인

9bow · 5월 18, 2026, 9:30오전

AgentField 소개

AgentField는 AI 에이전트를 일반적인 API나 마이크로서비스처럼 빌드하고, 운영하고, 확장하기 위해 만들어진 오픈소스 컨트롤 플레인(Control Plane)입니다. 챗봇이나 단순 프롬프트 오케스트레이터 수준을 넘어, 백엔드 시스템 안에서 실제 의사결정을 내리는 에이전트가 필요해질수록 라우팅, 비동기 실행, 사용자 승인, 분산 메모리, 신원·정책 같은 인프라가 함께 요구됩니다. AgentField는 이러한 요구를 한곳에서 다루기 위해 Go 기반의 컨트롤 플레인과 Python·Go·TypeScript용 SDK를 함께 제공하며, 개발자가 작성한 함수(Function)를 자동으로 REST 엔드포인트로 노출하고, 호출 사이의 라우팅과 추적, 그리고 암호화 기반 감사 기록까지 일괄적으로 처리하도록 설계되어 있습니다.

AgentField가 다른 멀티 에이전트 프레임워크와 구분되는 가장 큰 지점은 "에이전트를 인프라로 다룬다"는 관점입니다. 각 에이전트는 시작과 동시에 W3C DID(분산 신원자)와 Ed25519 키 쌍을 부여받아 자체적인 암호화 신원(Cryptographic Identity)을 가지게 되며, 다른 에이전트나 서비스에 보내는 모든 호출은 서명되고 검증 가능한 자격 증명(Verifiable Credentials)으로 기록됩니다. 이 덕분에 "어떤 에이전트가, 언제, 무슨 권한으로, 어떤 결정을 내렸는가"를 사후에도 변조 불가능한 형태로 추적할 수 있고, "재무 태그가 붙은 에이전트만 이 함수를 호출할 수 있다"와 같은 정책을 인프라 수준에서 강제할 수 있습니다.

이 프로젝트는 Apache 2.0 라이선스로 공개되어 있으며, 현재 GitHub에서 Go 코드 기반으로 빠르게 성장하고 있는 인프라 계열 오픈소스 중 하나입니다. Claude Code, Codex CLI, Gemini CLI, OpenCode 같은 다중 턴 코딩 에이전트를 작업 실행기로 호출할 수 있는 Harness 기능, LiteLLM을 통한 100여 종 이상의 LLM 백엔드 지원, Pydantic/Zod 스키마 기반의 구조화된 LLM 출력, KV와 벡터 검색을 함께 제공하는 분산 메모리 등 백엔드 인프라가 요구하는 기능들을 한 번에 제공하며, 도커 컴포즈와 쿠버네티스 배포까지 같은 코어로 다룬다는 점이 특징입니다.

AgentField의 아키텍처와 구성 요소

AgentField의 코어는 상태를 가지지 않는(stateless) Go 기반 컨트롤 플레인입니다. 사용자의 노트북, 도커 컨테이너, 쿠버네티스 파드 어디서든 에이전트가 기동되면, 시작과 동시에 자신의 능력(reasoner, skill, harness 등)을 컨트롤 플레인에 등록(Auto-Registration)합니다. 컨트롤 플레인은 등록된 에이전트들의 호출을 라우팅하고, 각 실행을 워크플로우 DAG로 추적하며, 정책에 따라 호출 허용/거부를 결정합니다. 이 모든 트래픽과 결정이 영속적인 큐(PostgreSQL 기반)와 감사 기록 위에 올라가기 때문에, 에이전트 인스턴스가 죽거나 재배포되어도 진행 중인 워크플로우가 유실되지 않도록 설계되어 있습니다.

AgentField가 제공하는 기능은 크게 세 축으로 정리됩니다.

Build (빌드): Python, Go, TypeScript SDK를 통해 함수 단위로 에이전트를 정의합니다. @app.reasoner() 데코레이터는 LLM 기반 판단을, @app.skill() 데코레이터는 결정론적인 코드를 함수로 묶어 노출합니다. app.ai(schema=MyModel) 호출은 LLM 출력을 Pydantic·Zod 스키마로 강제해 타입 안정성을 확보하며, app.harness("작업") 호출은 Claude Code, Codex, Gemini CLI, OpenCode 같은 다중 턴 코딩 에이전트에 작업을 위임할 수 있도록 해줍니다. app.call("agent.func") 호출은 다른 에이전트로 라우팅되며 전 구간에서 추적이 유지됩니다.

Run (실행): 비동기 실행, 사람-참여형(Human-in-the-Loop) 승인, 카나리 배포, 관측 가능성(Observability)을 컨트롤 플레인이 직접 책임집니다. 비동기 호출은 웹훅과 SSE 스트리밍을 지원하며, app.pause() 로 호출을 중단하면 외부 승인이 도착할 때까지 상태가 지속적으로 보존됩니다. 트래픽 가중치 라우팅을 통해 5%, 50%, 100% 단계로 점진적 롤아웃을 진행하거나 즉시 블루-그린 전환이 가능합니다. 표준 Prometheus /metrics, 구조화된 로그, 워크플로우 DAG API가 모두 기본 제공되어 별도의 운영 도구 없이도 모니터링 체계를 구축할 수 있습니다.

Govern (거버넌스): AgentField가 가장 강조하는 IAM 계층입니다. 각 에이전트는 공유 API 키 대신 W3C DID 기반의 암호 신원을 가지며, 매 실행은 변조 불가능한 자격 증명(VC)으로 기록됩니다. 이 자격 증명은 af vc verify audit.json 명령으로 오프라인에서도 검증할 수 있으며, 태그 기반 정책으로 호출자 ↔ 대상 사이의 ALLOW/DENY 규칙을 인프라 차원에서 강제할 수 있습니다. 즉, "Prompt만 잘 짜는" 보안이 아니라 암호 서명 기반의 보안 모델을 기본으로 한다는 점이 특징입니다.

AgentField의 코드 작성 방식

AgentField의 API는 "어떤 함수가 곧 어떤 엔드포인트"라는 모델을 따릅니다. 다음은 보험 청구 처리(claims-processor) 에이전트의 예시로, 구조화된 LLM 판단, 사람 승인, 다른 에이전트로의 라우팅이 한 함수 안에 깔끔하게 어떻게 묶이는지를 보여줍니다.

from agentfield import Agent, AIConfig
from pydantic import BaseModel

app = Agent(
    node_id="claims-processor",
    version="2.1.0",  # 카나리/AB/블루-그린 롤아웃 단위
    ai_config=AIConfig(model="anthropic/claude-sonnet-4-20250514"),
)

class Decision(BaseModel):
    action: str          # "approve", "deny", "escalate"
    confidence: float
    reasoning: str

@app.reasoner(tags=["insurance", "critical"])
async def evaluate_claim(claim: dict) -> dict:
    # 구조화된 LLM 판단 (Pydantic 스키마로 출력 강제)
    decision = await app.ai(
        system="Insurance claims adjuster. Evaluate and decide.",
        user=f"Claim #{claim['id']}: {claim['description']}",
        schema=Decision,
    )

    if decision.confidence < 0.85:
        # 사람 승인이 필요할 때 실행을 중단하고 외부에서 재개
        await app.pause(
            approval_request_id=f"claim-{claim['id']}",
            approval_request_url=f"https://internal.acme.com/approvals/claim-{claim['id']}",
            expires_in_hours=48,
        )

    # 다른 에이전트로 라우팅 — 컨트롤 플레인이 호출을 추적합니다
    await app.call("notifier.send_decision", input={
        "claim_id": claim["id"],
        "decision": decision.model_dump(),
    })

    return decision.model_dump()

app.run()
# → POST /api/v1/execute/claims-processor.evaluate_claim 자동 노출

위 코드 한 줄의 app.run() 만으로 함수가 REST 엔드포인트로 노출되고, 에이전트는 컨트롤 플레인에 자동 등록되며, 각 실행마다 검증 가능한 감사 기록이 생성됩니다.

AgentField 설치 및 사용법

가장 빠른 진입은 설치 스크립트와 슬래시 커맨드를 사용하는 방식입니다. Claude Code, Codex, Gemini CLI, OpenCode, Aider, Windsurf, Cursor 같은 다양한 코딩 도구 위에서 동일하게 동작합니다.

# AgentField 설치 스크립트
curl -fsSL https://agentfield.ai/install.sh | bash

/agentfield a claims processor with risk scoring and human approval

위 슬래시 커맨드를 호출하면 컨트롤 플레인과 에이전트, 그리고 즉시 호출해 볼 수 있는 curl 예시까지 포함된 Docker Compose 스택이 생성됩니다.

직접 스캐폴딩(Scaffolding)해서 작업하려면 af CLI를 사용합니다.

# Python 에이전트 스캐폴딩
af init my-agent --defaults
cd my-agent && pip install -r requirements.txt

# 컨트롤 플레인 실행 (대시보드: http://localhost:8080)
af server          # Terminal 1
python main.py     # Terminal 2 — 에이전트가 자동으로 등록됩니다

# 호출 예시
curl -X POST http://localhost:8080/api/v1/execute/my-agent.demo_echo \
  -H "Content-Type: application/json" \
  -d '{"input": {"message": "Hello!"}}'

Go와 TypeScript도 동일한 CLI에서 다음 명령으로 시작할 수 있습니다.

# Go
af init my-agent --defaults --language go && cd my-agent && go run .

# TypeScript
af init my-agent --defaults --language typescript && cd my-agent && npm install && npm run dev

# 컨트롤 플레인만 도커로 실행
docker run -p 8080:8080 agentfield/control-plane:latest

AgentField 라이선스

AgentField 프로젝트는 Apache 2.0 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용·수정·배포할 수 있으며, 특허권 부여 조항이 포함되어 있어 사내 인프라 도입 시에도 활용도가 높습니다.

AgentField 공식 홈페이지

AgentField 문서 사이트

AgentField 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~