AI Agent Cheat Sheet

Primitives

Claude Code 명령어나 LangGraph API가 아니라, 어떤 프레임워크에서도 먼저 정의해야 하는 에이전트 계약과 런타임 표면입니다. 이걸 건너뛰면 “챗봇은 되는데 업무에는 못 쓰는” 에이전트가 만들어지기 쉽습니다.

Agent Contract

Scope

goal에이전트가 완료해야 하는 업무 결과입니다. “답변하기”보다 “승인 가능한 보고서 초안 생성”처럼 검증 가능한 결과로 씁니다.
user_intent사용자의 현재 요청과 장기 목표를 분리합니다. 도구 실행 전에 실제 의도를 다시 확인해야 할 때 기준이 됩니다.
success_metric작업 성공을 판정하는 기준입니다. 정확도, 해결률, 승인률, 테스트 통과, 처리 시간처럼 측정 가능한 값으로 둡니다.
failure_mode실패했을 때 사용자에게 숨기면 안 되는 상태입니다. 모름, 권한 부족, 도구 실패, 최신성 부족을 구분합니다.
stopping_condition언제 멈추고 결과를 내거나 사람에게 넘길지 정합니다. 무한 반복과 과도한 도구 호출을 막습니다.

Instruction

instructions역할, 우선순위, 금지 행동, 응답 톤, 도구 사용 기준을 담는 시스템 지침입니다. 짧지만 충돌 없이 써야 합니다.
policy업무 규칙과 보안 규칙입니다. 결제, 삭제, 외부 전송, 개인정보 처리처럼 모델 판단에 맡기면 안 되는 기준을 명시합니다.
output_schema최종 산출물의 구조입니다. JSON, 표, 체크리스트, 보고서 섹션처럼 후속 시스템이 파싱 가능한 형태가 좋습니다.
confidence정답처럼 말할 수 있는 조건과 추정으로 표시해야 하는 조건을 나눕니다. 근거 없는 단정과 과신을 줄입니다.
escalation도구 권한, 법무/보안 리스크, 사용자 확인 필요 상황에서 사람에게 넘기는 규칙입니다.

Autonomy

recommend읽고 판단만 합니다. 초기 도입, 민감한 업무, 근거 검토 작업에 적합합니다.
draft초안을 만들지만 외부 시스템에는 반영하지 않습니다. 사람이 승인 후 실행하는 업무에 맞습니다.
act_with_approval도구 실행 전 승인 단계를 둡니다. 파일 수정, 티켓 변경, 이메일 발송 같은 작업에 필요합니다.
act_autonomously정해진 범위 안에서 직접 실행합니다. 권한, 예산, 로그, 롤백 경로가 준비된 경우에만 사용합니다.

Runtime Surface

Context

context_window모델이 한 번에 볼 수 있는 작업 공간입니다. 큰 로그, 긴 문서, 많은 도구 결과는 요약과 선택이 필요합니다.
session_state현재 대화와 실행 상태입니다. 진행 중인 승인, 중단된 작업, 최근 도구 결과를 이어받는 데 씁니다.
memory세션 밖에 남기는 장기 정보입니다. 사용자 선호, 프로젝트 규칙, 반복 사실만 저장하고 비밀은 넣지 않습니다.
retrieval필요한 지식을 외부 저장소에서 가져오는 방식입니다. 권한 필터, 최신성, 출처 표시가 핵심입니다.
compaction긴 대화나 도구 결과를 작업 목표 중심으로 압축합니다. 중요한 결정, 제약, 열린 이슈는 보존해야 합니다. 쉽게 말하면: 회의록을 “결정 + 다음 할 일”만 남기고 줄이는 작업입니다.

Tools

tool_schema도구 이름, 설명, 입력/출력 스키마입니다. 모델이 헷갈리지 않도록 파라미터와 실패 조건을 명확히 씁니다.
mcp_server파일, DB, SaaS, 사내 API 같은 외부 시스템을 표준 방식으로 노출하는 연결 계층입니다.
permission_scope도구가 읽기만 가능한지, 쓰기까지 가능한지, 어느 리소스에 접근하는지 제한합니다.
tool_result도구 실행 결과입니다. 너무 큰 결과는 잘라내고, 구조화된 결과와 에러를 구분해야 합니다.
idempotency_key같은 작업이 재시도되어도 중복 실행되지 않도록 식별자를 둡니다. 결제, 발송, 수정 작업에 중요합니다. 쉽게 말하면: “같은 영수증 번호로는 두 번 결제 안 됨” 보장 장치입니다.

Control

guardrail입력, 도구 호출, 출력 단계에서 차단하거나 수정하는 검증 장치입니다. 지침만으로 대체하지 않습니다. 쉽게 말하면: 모델이 잘못된 길로 가도 코드로 한 번 더 막아 주는 안전봉입니다.
handoff전문 에이전트나 사람에게 작업 소유권을 넘기는 흐름입니다. 넘길 때 대화 이력과 책임 범위를 정리합니다. 쉽게 말하면: 콜센터 1차 상담원이 전문 부서로 전화를 “인계”하는 그 동작입니다.
approval_gate쓰기, 삭제, 외부 전송, 고비용 호출 전에 사람 승인이나 정책 엔진을 통과시키는 단계입니다.
trace모델 호출, 도구 호출, handoff, guardrail, 에러를 하나의 실행 기록으로 남깁니다. 디버깅과 감사의 기본 단위입니다.
rollback잘못된 실행을 되돌리는 계획입니다. 자동화 수준이 높을수록 작업 전 스냅샷과 복구 절차가 필요합니다.

Patterns

에이전트가 필요하지 않은 단순 LLM 호출부터, 도구 사용 루프와 멀티에이전트 조율까지 단계별로 선택합니다. “일단 에이전트로 만들자”가 가장 흔한 초보자 함정이라 단순 호출로 충분한 작업부터 거꾸로 점검하는 게 안전합니다.

Workflow Patterns

Composable workflows

single_call검색이나 도구가 필요 없는 단순 생성/분류입니다. 먼저 이 방식으로 충분한지 확인합니다.
prompt_chaining큰 작업을 고정된 단계로 나눕니다. 각 단계 출력이 다음 단계 입력이 되므로 중간 검증을 넣기 좋습니다.
routing요청 유형을 분류해 서로 다른 프롬프트, 모델, 도구 경로로 보냅니다. 고객지원, 난이도 분기, 정책 분기에 적합합니다.
parallelization독립 하위 작업을 동시에 실행한 뒤 합칩니다. 속도 개선이나 여러 관점의 검토가 필요할 때 씁니다.
voting같은 문제를 여러 프롬프트나 모델로 판단해 합의나 임계값으로 결정합니다. 보안 리뷰와 정책 판정에 유용합니다.

Agentic loops

tool_use_loop모델이 계획하고 도구를 호출하고 결과를 관찰한 뒤 다음 행동을 정합니다. 관찰 가능한 환경 피드백이 핵심입니다. 쉽게 말하면: “생각 → 도구 실행 → 결과 보고 다시 생각”을 반복하는 게 에이전트의 기본 사이클입니다.
planner_executor계획 수립과 실행을 분리합니다. 긴 작업에서 계획 품질과 실행 검증을 따로 관리할 수 있습니다.
evaluator_optimizer생성자와 평가자가 반복 개선합니다. 평가 기준이 명확하고 품질 개선 가치가 비용보다 클 때 사용합니다. 쉽게 말하면: 한쪽이 초안을 쓰고 다른 쪽이 빨간펜으로 고치는 과정을 자동화한 것입니다.
reflection실행 결과를 스스로 점검하고 다음 시도를 조정합니다. 반복 횟수와 중단 조건을 반드시 둡니다. 쉽게 말하면: “이번에 왜 틀렸지?”를 모델이 한 번 더 묻고 다음 시도에 반영하는 단계입니다.
human_in_loop불확실성, 정책 리스크, 외부 영향이 큰 지점에서 사람 판단을 넣습니다. 승인 피로를 줄이도록 조건을 좁힙니다. 쉽게 말하면: 위험한 결정만 사람이 “OK” 눌러 주는 체크포인트입니다.

Knowledge patterns

rag_agent검색, 인용, 요약, 검증을 묶은 지식 기반 에이전트입니다. 권한 필터와 출처 표시가 없으면 위험합니다.
research_agent여러 출처를 탐색하고 비교해 결론을 냅니다. 최신성, 원문 확인, 상충 근거 표시가 필요합니다.
code_agent파일 읽기, 수정, 테스트 실행이 가능한 에이전트입니다. 작업 범위와 되돌리기 전략이 선행되어야 합니다.
ops_agent알림, 로그, 배포 상태를 보고 대응안을 제시합니다. 자동 조치는 runbook과 승인 기준이 있어야 합니다.

Multi-Agent Patterns

Coordination

supervisor중앙 에이전트가 요청을 분석하고 전문 에이전트에 일을 배분한 뒤 결과를 통합합니다. 책임 경로가 명확합니다.
orchestrator_workers예측하기 어려운 하위 작업을 실행 중 동적으로 나눕니다. 코딩, 리서치, 복합 분석에 맞습니다.
agent_as_tool전문 에이전트를 하나의 도구처럼 호출합니다. 외부 사용자 대화는 supervisor가 유지하고 내부 전문성만 빌립니다.
handoff_agent대화 소유권을 전문 에이전트에게 넘깁니다. 고객지원의 환불, 기술지원, 결제 문의처럼 역할 전환이 뚜렷할 때 씁니다.
integrator여러 에이전트 결과의 충돌, 중복, 누락을 정리합니다. 병렬 작업 후 반드시 필요한 역할입니다.

Collaboration

blackboard공유 작업판에 각 에이전트가 사실, 가설, 결정 사항을 기록합니다. 상태 오염과 권한 분리가 중요합니다.
event_driven에이전트가 이벤트를 발행하고 구독해 느슨하게 연결됩니다. 긴 업무와 비동기 자동화에 유리합니다.
peer_review한 에이전트의 산출물을 다른 에이전트가 기준표로 검토합니다. 취향 평가가 되지 않도록 rubric이 필요합니다.
specialist_pool법무, 보안, 데이터, 작성 등 전문 역할을 준비해 두고 필요한 경우만 호출합니다. 비용 통제가 쉽습니다.
fallback_agent실패, 권한 부족, 낮은 신뢰도일 때 더 보수적인 경로로 전환합니다. 사용자 경험을 안정화합니다.

When not to use

over_agentic고정 규칙이나 단순 API 호출로 충분한 작업에 에이전트 루프를 쓰면 비용과 지연만 늘어납니다.
hidden_state에이전트가 왜 그런 결정을 했는지 추적할 수 없으면 운영 중 원인 분석이 어렵습니다.
unclear_owner여러 에이전트가 같은 파일, 티켓, 고객 상태를 수정하면 충돌과 책임 공백이 생깁니다.
unbounded_loop최대 반복, 비용 상한, timeout이 없으면 작은 실패가 큰 비용 사고로 번질 수 있습니다.

Production

실험 데모를 제품 기능으로 바꿀 때 필요한 평가, 관측성, 보안, 운영 체크리스트입니다. “데모는 잘 도는데 출시는 못 하겠다”의 정체는 보통 이 단계의 누락이라, 출시 전에 한 번씩 훑어 보면 좋습니다.

Evaluation & Observability

Evaluation

eval_dataset대표 사용자 요청, 실패 사례, 경계 사례를 모은 평가 데이터입니다. 출시 후에도 계속 추가합니다.
golden_task항상 통과해야 하는 핵심 업무 시나리오입니다. 프롬프트, 모델, 도구 변경 전후 회귀 확인에 씁니다.
rubric좋은 답변과 나쁜 답변의 기준표입니다. 정확성, 완전성, 근거, 안전성, 형식을 분리해 평가합니다.
tool_call_accuracy올바른 도구를 올바른 인자로 호출했는지 측정합니다. 에이전트 품질은 답변보다 도구 선택에서 자주 무너집니다.
task_success_rate최종 업무가 실제로 끝났는지 보는 지표입니다. 대화 만족도와 별도로 추적합니다.

Observability

trace_id한 번의 사용자 요청에서 발생한 모델 호출, 도구 호출, handoff, guardrail을 묶는 식별자입니다.
span각 모델 호출, 도구 실행, 검색, 승인, 에러를 시간 구간으로 기록합니다. 병목과 실패 지점을 찾습니다.
replay실패한 실행을 같은 입력과 상태로 재현합니다. 비결정성이 있어도 원인 후보를 좁힐 수 있습니다.
annotation운영자가 실패 원인, 기대 답변, 정책 위반 여부를 기록합니다. 다음 eval과 프롬프트 개선의 원천입니다.
dashboard성공률, 도구 실패율, 평균 비용, 지연, 승인 대기, 사용자 중단을 함께 봅니다.

Cost & latency

cost_budget요청당 또는 작업당 허용 비용입니다. 모델 선택, 병렬 호출, 반복 횟수의 상한이 됩니다.
latency_budget사용자가 기다릴 수 있는 시간입니다. 실시간 응답, 백그라운드 작업, 이메일 보고로 UI 경로를 나눕니다.
model_tier쉬운 요청은 작은 모델, 어려운 요청은 강한 모델로 보내는 전략입니다. routing eval이 같이 필요합니다.
cache_policy반복되는 시스템 지침, 긴 문서, 검색 결과를 재사용해 비용과 지연을 줄입니다. 민감 데이터 캐싱은 금지 기준을 둡니다.

Safety & Operations

Security

least_privilege에이전트와 도구는 필요한 최소 권한만 가져야 합니다. 읽기, 쓰기, 삭제, 외부 전송 권한을 분리합니다.
prompt_injection사용자 입력이나 검색 문서가 숨은 지시를 포함할 수 있습니다. 외부 컨텍스트는 명령이 아니라 데이터로 취급합니다.
tool_misuse합법적인 도구도 잘못된 맥락에서 쓰이면 피해를 만듭니다. 인자 검증, 승인, allowlist가 필요합니다.
memory_poisoning악성 또는 잘못된 정보가 장기 메모리에 저장되면 이후 행동이 계속 오염됩니다. 저장 전 검증과 삭제 경로를 둡니다.
secret_exposureAPI key, 토큰, 개인정보가 프롬프트, 로그, 도구 결과, 메모리에 남지 않도록 마스킹과 보존 정책을 둡니다.

Governance

audit_log누가, 언제, 어떤 입력으로, 어떤 도구를 실행했고, 어떤 결과가 나왔는지 남깁니다. 외부 영향이 있는 작업은 필수입니다.
approval_policy금액, 데이터 민감도, 외부 전송, 권한 상승 기준에 따라 자동/수동 승인 경로를 나눕니다.
data_boundary사용자별, 조직별, 프로젝트별 접근 가능한 데이터 범위를 강제합니다. 검색과 메모리에도 동일하게 적용합니다.
retention_policy대화, trace, 로그, 첨부 파일을 얼마나 보관할지 정합니다. 개인정보와 영업비밀은 짧고 명확해야 합니다.
vendor_boundary모델 제공자, MCP 서버, 관측성 도구로 어떤 데이터가 나가는지 문서화합니다.

Operations

retry_backoff일시적 도구 실패는 재시도하되, 같은 외부 작업이 중복 실행되지 않게 합니다.
rate_limit모델, API, MCP 서버별 요청 제한을 둡니다. 폭주와 비용 사고를 같이 막습니다.
circuit_breaker오류율이나 비용이 임계값을 넘으면 자동 실행을 멈추고 읽기 전용 또는 사람 검토로 전환합니다.
incident_playbook잘못된 발송, 데이터 노출, 과도한 비용, 잘못된 삭제가 발생했을 때의 대응 순서를 준비합니다.
release_gate프롬프트, 모델, 도구, 메모리 정책 변경은 eval, 보안 체크, 롤백 계획을 통과한 뒤 배포합니다.

Sources

출처

공식 문서와 1차 보안 가이드를 기준으로 구조를 잡고, Habix 실무 관점의 설명을 붙였습니다. 깊게 파고 싶은 항목이 생기면 아래 원문으로 바로 넘어가서 확인하면 됩니다.

OpenAI Agents Guide OpenAI Agents SDK OpenAI Evals Anthropic Building Effective Agents Model Context Protocol MCP Tools Specification OWASP Agentic Applications OWASP MCP Top 10