지난 몇 년간, "에이전트가 도구를 사용한다"는 하나의 특정 메커니즘을 의미했다: 모델이 구조화된 블롭 — 보통 JSON —을 내보낸다. 함수와 그 인수를 이름 짓고, 런타임이 파싱하고, 함수를 호출하고, 결과를 모델의 컨텍스트로 다시 피드한다. 이 도구 호출 패턴이 첫 번째 세대의 에이전트 프레임워크를 구동했고 그것이 작동한다. 하지만 그것이 당신이 찾으면 명백해지는 조용한 비효율성이 있다: 모든 동작이 모델을 통한 별도의 왕복이다. 세 개의 도구를 호출하고 결과를 결합하고 싶은가? 그것이 적어도 3개의 모델 호출이다. 각각은 누적된 컨텍스트를 다시 읽는데, 왜냐하면 모델이 한 번에 하나의 JSON 도구 호출만 내보낼 수 있고 각 결과를 보기 전에 기다려야 하기 때문이다. 2026의 성장하는 생각의 학파는 더 나은 방법이 있고, 그것은 평범한 시야에 숨어 있다고 주장한다: 에이전트에게 코드를 작성하도록 하자.
이것이 코드 우선 에이전트 패러다임이고, 그것은 더 효율적인 에이전트 프레임워크가 어떻게 작동하는지를 재정의하고 있다. JSON을 내보내는 대신, 에이전트는 여러 도구를 호출하고, 루프를 사용하고, 변수를 사용하고, 결과를 결합할 수 있는 Python 스니펫을 작성한다. 그 런타임이 코드를 실행한다. 이 가이드는 그 전환이 왜 중요한지, 에이전트 성능과 비용을 어떻게 변경하는지, 그리고 선도적 프레임워크가 어떻게 그것을 구현하는지 설명한다. smolagents (그 가장 순수한 형태로 코드 우선 방법)와 Pydantic AI (Pydantic 팀에서의 타입 안전 에이전트)를 통해. 또한 본질적인 플립 사이드도 다룬다: 모델 생성 코드를 안전하게 실행하기.
JSON 도구 호출의 문제
코드 우선이 왜 중요한지 보려면, JSON 도구 호출이 무엇을 비용하는지 자세히 본다. API에서 데이터를 가져오고, 필터링하고, 요약을 계산하는 것이 필요한 작업을 생각해보자. 도구 호출로, 모델은 가져오기 도구에 호출을 내보내고, 결과를 기다리고, 필터 도구에 호출을 내보내고, 기다리고, 계산 도구에 호출을 내보내고, 기다리고, 마지막으로 답변을 조합한다. 그것이 4개의 모델 호출이고, 각각은 전체 성장하는 컨텍스트 — 원래 작업, 더하기 지금까지 누적된 모든 중간 결과를 재처리한다. 토큰 비용과 레이턴시는 단계 수에 따라 스케일되고, 복잡한 작업은 많은 단계를 가진다.
더 미묘한 문제도 있다: JSON 도구 호출이 어떻게 에이전트가 동작을 조합할 수 있는지를 제약한다. 각 단계는 리터럴 인수가 있는 단일 함수 호출이다. 모델은 쉽게 "이 도구를 그 리스트의 각 항목에 대해 호출하거나", "결과가 비어 있으면, 다른 쿼리를 시도하거나", "이 두 결과를 계산으로 결합"을 표현할 수 없다. 각각을 별도의 왕복으로 나누지 않고. 일반적인 프로그래밍의 표현 — 루프, 조건, 변수, 조합 — 이것이 정확히 빠지는 것이고, 다중 단계 논리를 자연스럽게 만드는 구성 요소다. 도구 호출은 모델에게 한 번에 하나의 명령을 내보내는 프로그램 카운터가 되도록 요청한다. 작업이 필요로 하는 것이 프로그램이다.
코드 우선 통찰
코드 우선 접근은 두 문제를 한 번에 해결한다. 단일 JSON 도구 호출을 내보내는 대신, 에이전트는 여러 도구를 호출하고, 제어 흐름을 사용하고, 변수에 중간 값을 홀드하고, 결과를 반환할 수 있는 Python 코드 블록을 작성한다. 런타임이 코드를 실행하고, 에이전트가 호출할 수 있는 도구는 단순히 그 실행 환경에서 사용 가능한 Python 함수다. 앞의 예에서의 API 가져오기, 필터, 계산이 하나의 코드 블록이 되고 세 함수 호출과 그들 사이의 약간의 논리 — 단일 단계에서 실행되고, 단일 모델 호출에서 나온다.
효율 이득이 실제적이고 측정 가능하다. 이전에 여러 도구 호출 왕복을 취했을 하나의 코드 블록이 의미 있게 더 적은 LLM 호출을 만들기 때문에 — 약 30% 감소를 보고했다 — 그것은 비용과 레이턴시를 줄인다. 그리고 에이전트가 실제 프로그래밍 언어로 동작을 표현하기 때문에, (반복 결과, 조건 분기, 계산 결합)을 자연스럽게 처리한다. 훨씬 더 좋다. 또한 훈련 데이터 주장이 있다: 모델은 엄청난 양의 코드를 봤고 그것을 작성하는 데 진정으로 좋다. 아마도 그들이 새로운 스키마에 대해 완벽하게 형식화된 도구 호출 JSON을 생성하는 데 더 좋다. 모델에게 의도를 코드로 표현하도록 요청하는 것이 강점을 한다.
smolagents: 그 가장 순수한 형태로 패러다임
smolagents, Hugging Face에서, 코드 우선 아이디어의 가장 명확한 표현이다. 그것은 CodeAgent를 중심으로 구축한 의도적으로 최소한의 라이브러리다: 동작이 Python 코드인 에이전트. 도구 세트 (일반 Python 함수) 및 모델을 주고, 작업을 건네고, 이것이 도구를 호출하고, 루프하고, 계산하는 코드를 작성하고 실행하여 답변을 가지고 있을 때까지 작동한다. 라이브러리는 의도적으로 작고 해킹 가능하게 유지된다 — 이 철학은 에이전트 루프가 읽고 수정하기에 충분히 간단해야 한다. 지능이 모델과 코드 실행 방법이 아닌 무거운 프레임워크에서 나온다.
smolagents를 효율성을 넘어서 매력적인 것은 그것이 실제 작업을 얼마나 자연스럽게 처리하는지다. 에이전트가 코드를 작성하기 때문에, 연구 작업은 검색하고, 결과를 파싱하고, 필터링하고, 계산할 수 있다. 하나의 일관된 단계에서; 데이터 작업은 로드하고, 변환하고, 분석할 수 있다. JSON 왕복 없이. 그것은 모델 불가지론적이다 — Hugging Face 모델, 로컬 모델, 또는 LiteLLM을 통한 모든 공급자와 작동 — 그래서 당신은 하나의 백엔드로 잠기지 않고, 코드 우선이 근본적으로 필요로 하는 샌드박스 실행을 지원한다 (아래 참고). 작은, 이해 가능한 패키지에서 코드 우선 효율을 원하는 팀에 대해, smolagents는 참고 구현이고, smolagents 치트시트가 에이전트, 도구, 샌드박싱을 다룬다.
smolagents의 최소화의 트레이드오프는 무거운 프레임워크보다 덜 스캐폴딩을 제공한다는 것이다 — 복잡한 다중 에이전트 오케스트레이션, 내구 상태, 또는 정교한 제어 흐름에 대한 더 적은 내장 추상화. 단일 에이전트 코드 루프에 대해 이것이 제한이 아닌 기능; 광활한 상태 시스템에 대해 당신은 무언가 더 무거움에 닿을 수도 있다. 하지만 코드 우선 에이전트의 가장 순수하고 가장 효율적인 표현으로서, 그것을 이기기는 어렵다.
Pydantic AI: 타입 안전이 에이전트를 만난다
Pydantic AI, Pydantic 팀 (Pydantic이 FastAPI와 Python AI 생태계의 많은 부분을 지탱하는 검증 라이브러리)의, 다른 각도에서 에이전트에 접근한다: 타입 안전 및 개발자 경험. 그 내기는 Pydantic이 데이터 검증에 가져온 동일한 엄격성 — Python 타입 힌트와 자동 검증로 데이터의 형태를 선언 — 에이전트에 적용되어야 한다는 것이다. 모든 에이전트 입력, 출력, 도구 호출이 타입 설정되고, 프레임워크가 모델 출력이 예상 구조와 일치함을 검증하고, 출력이 일치하지 않을 때 자신을 정정하도록 모델에게 자동으로 요청할 수 있다. 결과는 에이전트 빌딩을 위한 FastAPI-스타일의 개발자 경험다: 친숙하고, 타입-확인되고, 프로덕션-지향적.
타입 안전이 에이전트에 대해 생각보다 중요하다. LLM 애플리케이션의 반복적인 고통이 모델 출력이 비구조화된 텍스트고 그것을 신뢰할 수 있게 당신의 프로그램이 필요로 하는 구조화된 데이터로 바꾸는 것이 까다롭고 에러-프론이라는 것이다. Pydantic AI는 구조화된 출력을 첫 클래스 보장으로 만든다: 당신이 출력 타입을 선언하고, 프레임워크가 그것을 강제하고, 필요한 경우 모델로 재시도한다. 그것이 "모델의 텍스트를 파싱하고 그것이 유효하기를 희망"을 "유효화되고, 타입된 객체를 받기"로 전환한다. 이것이 정확히 프로덕션 코드가 원하는 것이다. 그 V2 재설계는 2026에서 도구, 명령, 설정을 결합 가능한 기능으로 번들링하는 하네스-우선 모델로 더 추진되었다. Pydantic AI 치트시트가 그 타입 에이전트와 도구를 다룬다.
Pydantic AI와 smolagents는 정말 경쟁자가 아니라 다른 우선 순위의 표현이다. smolagents가 코드-as-action의 효율성과 표현성을 최적화한다; Pydantic AI가 타입 안전, 유효화된 구조화된 출력, 프로덕션 인체공학을 최적화한다. 더 적은 LLM 호출과 자연스러운 다중 단계 논리를 중시하는 팀이 smolagents에 기울어진다; 타입-확인됨, 유효화됨, FastAPI-스타일 에이전트 코드를 중시하는 팀이 Pydantic AI에 기울어진다. 둘 다 첫 세대, JSON 전용 프레임워크에서 멀어져 무언가 더 프로그래머-네이티브로 지적한다.
안전 문제: 모델 생성 코드 실행
코드 우선 에이전트는 명백하고 심각한 함정을 가진다: 그들이 언어 모델에 의해 작성된 코드를 실행하고, 모델 생성 코드는 정의에 의해 신뢰할 수 없다. 생성된 Python을 작성하고 실행할 수 있는 에이전트는, 만약 프롬프트 주입에 의해 손상되거나 단순히 틀렸다면, 파일을 삭제하고, 데이터를 유출하고, 네트워크 호출을 하고, 제한 없이 리소스를 소비할 수 있다. 이것은 가설적 관심이 아니다 — 그것이 전체 패러다임의 중심 작동 위험이고, 프로덕션 배포를 위해 그것을 진지하게 취급하는 것이 필수적이지 않는다.
답변은 샌드박싱이다: 생성된 코드를 제한된 기능을 가진 격리된 환경에서 실행한다. 프레임워크가 이것을 직접 지원한다 — smolagents가 E2B, Docker, 또는 Modal과 같은 원격 샌드박스에서 코드를 실행하거나, 호스트 프로세스가 아닌 컨테이너에서, 그리고 당신이 생성된 코드가 심지어 임포트할 수 있는 모듈을 제한할 수 있다. 원칙은 최소 권한이다: 샌드박스는 작업이 진정으로 필요로 하는 접근만 가져야 한다 — 필요하지 않은 파일시스템 접근, 필요한 것을 넘어서는 네트워크 이그레스, 호스트를 영향시킬 능력 없다. 에이전트 생성 코드를 애플리케이션 프로세스에 직접, 애플리케이션의 권한으로 실행하는 것이 유용한 에이전트를 원격 코드 실행 취약점으로 입은 실수다.
실용적인 지도는 직진하지만 따라야 한다. 개발에서, 로컬 실행은 편하고 신뢰할 수 있는, 비-민감한 작업에 허용 가능하다. 프로덕션에 접근하는 어떤 것이나, 신뢰할 수 없는 입력이나 민감한 시스템에 터치하는 모든 작업에서, 최소-권한 접근으로 샌드박스에서 코드를 실행하고, 임포트를 제한하고, 에이전트의 코드 출력을 신뢰할 수 없는 입력처럼 취급하자 — 왜냐하면 그것이 무엇이기 때문이다. 코드 우선 에이전트의 효율성과 힘이 실제하지만, 그들은 당신이 부주의하게 일반적인 책임을 함께 온다. 그 책임을 수용하고 올바르게 샌드박스하고, 패러다임은 강력하고 안전하다.
JSON 도구 호출이 여전히 올바른 선택일 때
코드 우선 에이전트가 더 효율적이고 표현적이지만, JSON 도구 호출이 구식이라고 결론지을 것이 실수다. 제약 있는, 일회 호출-at-a-time 모델이 더 나은 적합인 실제 상황이 있고, 그들을 이해하는 것이 선택을 정직하게 유지한다. 가장 명확한 것은 동작이 엄격히 제어되고 감사되어야 할 때다. JSON 도구 호출은 이산, 검사 가능, 쉽게-유효화된 이벤트다: 에이전트가 이 함수를 이 인수로 호출하고 싶고, 당신이 어떤 것이 실행되기 전에 승인, 로그, 또는 거부할 수 있다. 감사 능력이 높은-스테이크 도메인에서 — 금융 동작, 인프라 변경, 돌이킬 수 없는 부작용이 있는 어떤 것 — 당신이 에이전트의 의도와 그 실행 사이에 인간이나 정책 체크를 원하는 곳에서 값어치가 있다. 블록으로 실행되는 코드는 그 세분화성을 게이팅하기가 더 어렵다.
두 번째 경우는 단순함이다. 많은 에이전트가 정말로 한 번에 하나의 도구만 직진한 루프에서 호출할 필요가 있다 — 검색 도구를 호출하여 질문에 답하고, 무언가를 찾고, 하나의 동작을 수행한다. 그것을 위해, 코드-as-action의 표현성은 미사용 능력이고, 코드 샌드박스의 추가 기계장치는 급여 없이 오버헤드다. 간단한 도구 호출 에이전트가 작업이 더 필요한 것보다 이해하고 배포할 더 쉽다. 세 번째 경우는 안전 자세다: JSON 도구 호출이 에이전트가 사전 정의 함수만 호출할 수 있도록 제약하기 때문에, 그것이 고유하게 더 제한되고, 일부 위협 모델에 대해 그 더 작은 폭발 반경이 효율성 비용을 정당화할 만큼 가치가 있다. 그것도 코드 실행이 하지 않는 설계에 의해 제약된다.
성숙한 보기는 이들이 다른 작업에 대해 두 도구고, 패러다임이 당신이 대량으로 채택하는 교리가 아니라 당신이 개별적으로 정하는 선택이라는 것이다. 작업이 진정한 다중 단계 조합, 반복, 또는 중간 결과에 대한 계산을 관여할 때 코드 우선에 도달하고, 당신이 올바르게 샌드박스할 수 있다. 동작이 세분화 제어 및 감사를 필요로 할 때, 작업이 간단할 때, 또는 사전 정의 함수만이 당신의 안전 요구를 맞춤할 때 JSON 도구 호출에 도달하자. 여러 프레임워크, smolagents를 포함하여, 정확히 이 이유를 위해 CodeAgent와 도구 호출 에이전트를 모두 지원한다 — 패러다임은 교리가 아닌 개별 케이스별로 당신이 만드는 선택이다.
최종 결론
JSON 도구 호출에서 코드 우선 에이전트로의 이동이 2026에 에이전트가 구축되는 방식의 의미 있는 전환이고, 그것은 간단한 관찰에 의해 구동된다: 에이전트에게 코드를 작성하도록 하는 것이 한 번에 하나의 도구 호출을 내보내는 것보다 더 효율적이고 더 표현적이다. 더 적은 LLM 호출, 자연스러운 다중 단계 논리, 모델이 그들의 코드 쓰기 강점을 재생하는 것이 급여다. 코드 우선 프레임워크가 보고하는 대략 30% 호출 감소에서 눈에 띈다. smolagents가 패러다임을 가장 순수하고, 가장 최소한의 형태로 표현한다; Pydantic AI가 에이전트 빌딩에 타입 안전과 유효화된 구조화된 출력을 가져온다. 둘 다 첫 세대, JSON 전용 프레임워크에서 멀어져 무언가 더 프로그래머-네이티브로 지적한다. 당신이 건너뛸 수 없는 하나의 규칙: 모델 생성 코드는 신뢰할 수 없으므로 샌드박스 그것이 최소 권한과 함께. 그렇게 하고, 코드 우선 에이전트는 더 빠르고, 더 능력 있는 방법을 구축한다.
참고 자료 및 리소스
프레임워크
배경 및 분석
- 2026의 AI 에이전트를 구축하기 위한 최고의 오픈소스 프레임워크 — Firecrawl
- Python AI 에이전트 라이브러리 비교 2026 — Pydantic AI vs Instructor vs Smolagents
- 2026의 최고의 Python AI 에이전트 프레임워크 — Uvik
관련 1337skills 치트시트