0x38A

상위: Agno

요약

AgentOS는 Agno의 프로덕션 런타임이다. Agent, Team, Workflow를 FastAPI 기반 API 서버로 변환하고, 세션 관리, 보안, 모니터링, 수평 확장을 제공한다. 단일 에이전트에서 수천 동시 세션까지 확장할 수 있다.

아키텍처

AgentOS (FastAPI App)
├── HTTP API (50+ 엔드포인트)
│   ├── 에이전트 실행, 스트리밍
│   ├── 세션 관리
│   └── 백그라운드 실행
├── Session Manager
│   ├── 사용자별/세션별 격리
│   └── 컨테이너 간 세션 유지
├── Security
│   ├── JWT 인증
│   ├── RBAC (역할 기반 접근 제어)
│   └── 요청 수준 격리
└── Storage (PostgreSQL)
    ├── 세션, 메모리
    ├── 지식 (Knowledge)
    └── 실행 트레이스

2-컴포넌트 배포

컴포넌트	역할
AgentOS 컨테이너	FastAPI 앱. `get_app()`으로 생성
PostgreSQL	세션, 메모리, 지식, 트레이스 저장

런타임은 Stateless 설계이다. 모든 상태는 PostgreSQL에 저장되므로, 로드밸런서 뒤에 여러 인스턴스를 배치하여 수평 확장이 가능하다.

코드 예시

from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.models.anthropic import Claude
from agno.os import AgentOS
from agno.tools.mcp import MCPTools

db = PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

agent = Agent(
    name="My Agent",
    model=Claude(id="claude-sonnet-4-6"),
    db=db,
    tools=[MCPTools(url="https://docs.agno.com/mcp")],
    add_history_to_context=True,
    num_history_runs=3,
    markdown=True,
)

# AgentOS로 래핑 → FastAPI 앱 생성
agent_os = AgentOS(
    agents=[agent],
    tracing=True,
)
app = agent_os.get_app()

# 실행
uvx --python 3.12 --with "agno[os]" --with anthropic fastapi dev

프로덕션 기능

보안

기능	설명
JWT 인증	토큰 기반 인증
RBAC	역할 기반 접근 제어
요청 격리	사용자/세션 수준 격리
데이터 프라이버시	모든 데이터가 사용자 인프라에 잔류. 외부 전송 없음

관측성 (Observability)

OpenTelemetry 기반 자동 계측을 제공한다.

기능	설명
Auto-Instrumentation	에이전트, 도구, 팀, 워크플로우, Knowledge, Reasoning Tools를 자동 계측
트레이싱	실행 흐름 시각화. Agent/Team/Workflow별 트레이스
유연한 Export	모든 OTel 호환 백엔드로 전송

지원 관측성 플랫폼 (10+):

플랫폼	주요 기능
Arize Phoenix	오픈소스 LLM 관측성
Langfuse	오픈소스 LLM 엔지니어링 플랫폼
LangSmith	LangChain 공식 트레이싱
Langtrace	오픈소스 관측성
LangWatch	LLM 모니터링 + 평가
Logfire	Pydantic 기반 관측성
Maxim	레이턴시/비용/에러율 모니터링 + 자동 평가
OpenLIT	OTel 네이티브 관측성
Traceloop	OTel 기반 LLM 트레이싱
Weave	W&B의 LLM 관측성

Evals (평가)

에이전트/팀의 품질을 측정하는 내장 평가 프레임워크이다.

평가 차원	설명	방법
Accuracy	응답의 정확도	LLM-as-a-Judge (더 큰 모델이 채점)
Reliability	올바른 도구를 호출하는가	예상 도구 호출과 비교
Performance	레이턴시, 메모리 사용량	런타임 측정

from agno.eval.accuracy import AccuracyEval

evaluation = AccuracyEval(
    model=OpenAIChat(id="o4-mini"),           # 채점 모델
    agent=my_agent,                            # 평가 대상
    input="What is 10*5 to the power of 2?",
    expected_output="2500",
)
result = evaluation.run(print_results=True)
assert result.avg_score >= 8

from agno.eval.reliability import ReliabilityEval

response = agent.run("Calculate 10*5^2")
evaluation = ReliabilityEval(
    agent_response=response,
    expected_tool_calls=["multiply", "exponentiate"],
)
result = evaluation.run()
result.assert_passed()

세션 메트릭

RunOutput에 상세 메트릭이 포함된다:

토큰 사용량: 입력/출력 토큰, 비용
레이턴시: 응답 시간
도구 호출: 어떤 도구를 몇 번 호출했는지
세션 메트릭: AgentSession.session_metrics에 세션 전체 합산

스케줄링

Cron 기반 자동 실행을 지원한다. SchedulePoller가 AgentOS 백그라운드 태스크로 실행되며, 예약된 시간에 에이전트/팀/워크플로우를 트리거한다.

Cron 표현식으로 스케줄 정의
타임존, 재시도, 타임아웃 설정
에이전트, 팀, 워크플로우 모두 스케줄 가능

스트리밍 & 복구

스트리밍: 연결 끊김을 graceful하게 처리
복구: 실패를 투명하게 처리 (사용자에게 보이지 않음)
백그라운드 실행: 긴 작업을 백그라운드에서 실행
Background Hooks: 글로벌/개별 훅으로 백그라운드 이벤트 처리

인터페이스

인터페이스	설명
AG-UI	Agent-User Interface 프로토콜. 프론트엔드와 표준화된 연결
A2A	Google Agent-to-Agent 프로토콜
Slack	Slack 봇 통합
WhatsApp	WhatsApp Business API
Discord	Discord 봇
Telegram	Telegram 봇 (지원됨)

AG-UI Protocol

AG-UI는 에이전트와 프론트엔드 UI를 연결하는 표준 프로토콜이다. ChatGPT 스타일 웹 인터페이스를 AgentOS에 플러그인으로 붙인다:

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from agno.os.interfaces.agui import AGUI

chat_agent = Agent(model=OpenAIResponses(id="gpt-5.2"))

agent_os = AgentOS(
    agents=[chat_agent],
    interfaces=[AGUI(agent=chat_agent)],  # AG-UI 인터페이스 등록
)
app = agent_os.get_app()

AG-UI 호환 프론트엔드 라이브러리(React 등)와 바로 연동 가능하다.

배포 템플릿

템플릿	구성
Docker	Docker Compose. 로컬 개발 + 프로덕션
AWS	ECS Fargate + RDS PostgreSQL + ALB
Railway	간편 클라우드 배포

AWS 배포는 agno-infra SDK로 인프라를 Python 코드로 관리한다. 커스텀 FastAPI 앱에 AgentOS를 마운트할 수도 있다.

Agno AgentOS

요약