bitsky-tech/AmphiLoop

Bridgic Amphibious

이중 모드 에이전트 프레임워크: 에이전트는 LLM 기반(on_agent) 및 결정론적(on_workflow) 모드에서 작동하며, 두 모드 간 자동 폴백을 지원합니다.

의존성

bridgic-amphibious 프로젝트에는 다음 패키지가 필요합니다:

패키지	설명
bridgic-core	핵심 프레임워크 (Worker, Automa, GraphAutoma, ASL)
bridgic-amphibious	이중 모드 에이전트 프레임워크
bridgic-llms-openai	LLM 제공자 (AGENT / AMPHIFLOW 모드에서만 필요)
python-dotenv	.env 파일 로딩

이 패키지를 사용하기 전에 제공된 설치 스크립트를 사용하여 의존성을 설치해야 합니다:

bash "skills/bridgic-amphibious/scripts/install-deps.sh" "$PWD"

이 스크립트는 uv 사용 가능 여부를 확인하고, 필요한 경우 uv 프로젝트를 초기화하며, 누락된 패키지를 uv add를 통해 설치하고, uv sync를 실행하여 환경을 최종화합니다. 스크립트가 성공적으로 종료되면 프로젝트가 완전히 초기화되어 사용할 준비가 된 것입니다. 추가로 uv add / uv sync를 수동으로 실행할 필요가 없습니다.

LLM 설정

Amphibious 에이전트는 bridgic LLM 제공자 패키지의 astructure_output 프로토콜을 가진 BaseLlm 인스턴스를 허용합니다. LLM은 AGENT 및 AMPHIFLOW 모드에 필요하며, 순수 WORKFLOW 모드는 LLM 없이 실행할 수 있습니다.

from bridgic.llms.openai import OpenAILlm, OpenAIConfiguration

llm = OpenAILlm(
    api_key="your-api-key",
    api_base="https://api.openai.com/v1",  # 또는 사용자 정의 엔드포인트
    configuration=OpenAIConfiguration(model="gpt-4o", temperature=0.0),
)

동일한 프로토콜을 가진 다른 제공자: bridgic.llms.vllm.VllmServerLlm (자체 호스팅 vLLM).

빠른 시작

from bridgic.amphibious import (
    AmphibiousAutoma, CognitiveContext, CognitiveWorker, think_unit,
)
from bridgic.core.agentic.tool_specs import FunctionToolSpec

async def get_weather(city: str) -> str:
    """도시의 날씨를 가져옵니다."""
    return f"맑음, {city}의 기온은 22°C"

class WeatherAgent(AmphibiousAutoma[CognitiveContext]):
    planner = think_unit(
        CognitiveWorker.inline("날씨를 조회하고 요약을 제공합니다."),
        max_attempts=5,
    )
    async def on_agent(self, ctx: CognitiveContext):
        await self.planner

agent = WeatherAgent(llm=llm, verbose=True)
result = await agent.arun(
    goal="도쿄와 런던의 날씨를 확인합니다.",
    tools=[FunctionToolSpec.from_raw(get_weather)],
)

프로젝트 스캐폴딩

CLI를 사용하여 새 프로젝트를 부트스트랩합니다:

bridgic-amphibious create -n my_project
bridgic-amphibious create -n my_project --task "example.com으로 이동하여 데이터 추출"
bridgic-amphibious create -n my_project --base-dir /path/to/projects

생성되는 파일: task.md, config.py, tools.py, workers.py, agents.py, skills/, result/, log/.

핵심 개념

에이전트 = Think Unit + 컨텍스트 오케스트레이션. 에이전트는 CognitiveWorker think unit을 선언하고 on_agent() 또는 on_workflow()에서 이를 오케스트레이션하여 정의됩니다.

4계층 아키텍처:

1. Exposure — 데이터 가시성 추상화 (LayeredExposure / EntireExposure)
2. CognitiveContext — 상태 컨테이너 (목표, 도구, 스킬, 히스토리)
3. CognitiveWorker — 순수 사고 유닛 (관찰-사고-행동)
4. AmphibiousAutoma — 오케스트레이션 엔진 (모드 라우팅, 라이프사이클)

OTC 사이클: 관찰 -> 사고 -> 행동, 각 단계에서 훅 포인트 제공.

네 가지 실행 모드: AGENT (LLM 기반), WORKFLOW (결정론적), AMPHIFLOW (워크플로우 + 에이전트 폴백), AUTO (재정의된 메서드에서 자동 감지, 기본값).

AUTO 해석: on_agent만 재정의됨 → AGENT; on_workflow만 재정의됨 → WORKFLOW; 둘 다 재정의됨 → AMPHIFLOW.

주요 패턴

에이전트 모드 — LLM이 결정

class MyAgent(AmphibiousAutoma[CognitiveContext]):
    worker = think_unit(CognitiveWorker.inline("다음 단계를 결정합니다."), max_attempts=10)
    async def on_agent(self, ctx):
        await self.worker

워크플로우 모드 — 개발자가 결정

from bridgic.amphibious import ActionCall

class MyWorkflow(AmphibiousAutoma[CognitiveContext]):
    async def on_workflow(self, ctx):
        result = yield ActionCall("tool_name", arg1="value")
        # result는 List[ToolResult]

# 순수 워크플로우 모드는 LLM이 필요하지 않습니다.
await MyWorkflow().arun(goal="...", tools=[...])

암피플로우 모드 — 에이전트 폴백이 있는 워크플로우

from bridgic.amphibious import RunMode, AgentCall

class MyHybrid(AmphibiousAutoma[CognitiveContext]):
    fixer = think_unit(CognitiveWorker.inline("문제를 수정합니다."), max_attempts=5)
    async def on_agent(self, ctx): await self.fixer
    async def on_workflow(self, ctx):
        yield ActionCall("fill_field", name="user", value="john")
        yield ActionCall("click_button", name="submit")

await MyHybrid(llm=llm).arun(
    goal="...", tools=[...],
    mode=RunMode.AMPHIFLOW, max_consecutive_fallbacks=2,
)

인간 참여 (Human-in-the-Loop)

from bridgic.amphibious import ActionCall, HumanCall

class MyAgent(AmphibiousAutoma[CognitiveContext]):
    worker = think_unit(CognitiveWorker.inline("단계를 실행합니다."), max_attempts=10)

    async def on_agent(self, ctx):
        await self.worker
        feedback = await self.request_human("계속할까요?")  # 진입점 1: 코드 수준

    async def on_workflow(self, ctx):
        yield ActionCall("do_something", arg="value")
        feedback = yield HumanCall(prompt="확인?")     # 진입점 2: 워크플로우 yield

# 진입점 3: LLM 도구 — `request_human`은 모든 에이전트의 도구에 자동 주입되므로
# LLM이 `tools=[...]`에 나열하지 않아도 호출할 수 있습니다.
# (`request_human_tool`을 명시적으로 전달해도 무방하며, 중복 제거됩니다.)
await MyAgent(llm=llm).arun(goal="...", tools=[my_tool])

# 명시적으로 사용하려면 `request_human_tool`을 가져와서 전달해도 됩니다.
from bridgic.amphibious.builtin_tools import request_human_tool
await agent.arun(goal="...", tools=[request_human_tool, ...])  # 역시 정상 작동

사용자 정의 Pydantic 출력

from pydantic import BaseModel

class Plan(BaseModel):
    phases: list[str]

class Planner(AmphibiousAutoma[CognitiveContext]):
    plan = think_unit(
        CognitiveWorker.inline("계획을 생성합니다.", output_schema=Plan),
        max_attempts=1,
    )
    async def on_agent(self, ctx):
        result = await self.plan  # Plan 인스턴스 반환

단계 주석 (스냅샷)

async def on_agent(self, ctx):
    async with self.snapshot(goal="연구 단계"):
        await self.researcher
    async with self.snapshot(goal="작성 단계"):
        await self.writer

참고 파일

• 아키텍처 세부사항 (실행 모드, 노출 시스템, 메모리 계층, 인지 정책): references/architecture.md 참고
• 전체 API 참조 (모든 클래스, 메서드, 매개변수, 타입): references/api-reference.md 참고
• 전체 코드 패턴 및 예제 (모든 훅 유형, 스킬, 추적, 필터링 등): references/patterns.md 참고