작동 방식

플랫폼이 자동으로 수행하는 작업을 이해하세요. 그러면 설정할 필요가 없는 것을 알 수 있습니다. task를 보내면 플랫폼이 라우팅, 도구 호출, 결과 전달을 처리합니다.

자동 라우팅: 하나의 엔드포인트, 두 개의 레인

task를 POST /v1/workspaces/{workspace_id}/agent/runs로 보내면 플랫폼이 어떤 실행 레인이 적합한지 판단합니다. 여러분이 직접 엔드포인트를 선택할 필요는 없습니다:

Chat 레인 — 빠르고 텍스트 전용 응답. 모델이 한 번에 직접 답할 수 있는 질문용("SEPA Instant 설명해 줘", "이것 좀 번역해 줘"). 빠르고 저렴합니다.
Agent 레인 — 자율적이고 여러 단계를 거치며 도구를 호출. 조사, 파일 생성, 코드 실행, 브라우저가 필요한 작업용("Wise와 Airwallex 수수료를 비교해 표로 출력해 줘", "내 knowledge base를 읽고 환불 정책을 요약해 줘").

라우터는 휴리스틱을 우선합니다(거의 제로 비용, LLM 호출 없음). 작업이 명확히 도구나 여러 단계가 필요할 때만 에스컬레이션합니다. Chat 응답 도중 도구가 필요해지면 자동으로 agent 레인으로 에스컬레이션합니다 — 눈에 띄는 전환도, 여러분 측의 재시도도 없습니다.

두 경우 모두 동일한 하나의 엔드포인트로 보냅니다. 작업이 빠른 chat으로 실행될지, 완전한 agent 루프로 실행될지는 여러분이 아니라 플랫폼이 결정합니다. 순수 chat 응답(도구 없음, 최소 지연)을 보장하려면 POST …/chat을 직접 사용하세요 — Chat 참고.

내장 도구: 설정할 것 없음

Agent에는 완전한 도구 키트가 내장되어 있습니다. 작업에 따라 어떤 도구를 호출할지 스스로 결정합니다 — 여러분이 도구를 선택, 설정, 연결할 필요가 없습니다. 다음 도구들은 모든 실행에서 기본으로 사용할 수 있습니다:

카테고리	도구	자동 호출 시점
웹 조사	`web_search`, `url_reader`, `advanced_scrape`, `document_read`, `ocr_extract`	작업에 실시간 웹 정보, 페이지 읽기, PDF/이미지 추출이 필요할 때
나의 knowledge base	`rag_search`, `spreadsheet_analyze`, `sql_query`	작업이 워크스페이스에 업로드된 파일이나 데이터를 참조할 때
오픈 데이터셋	`arxiv_search`, `sec_edgar`, `world_bank`, `oecd`, `financial_data`, `currency_convert`, `weather`, `rss_read`	작업이 금융, 학술, 구조화된 공개 데이터를 요구할 때
코드 실행	`python_exec`	작업에 계산, 데이터 처리, 분석이 필요할 때
브라우저	`browser_navigate`, `browser_act`, `browser_extract`	작업이 웹사이트 방문, 로그인, 페이지 조작을 필요로 할 때
파일 생성	`create_pdf`, `create_docx`, `create_slides`, `create_markdown`, `create_webapp`	작업이 결과물 문서, 스프레드시트, 슬라이드를 요구할 때
메모리	`remember`, `forget`	agent가 향후 실행을 위해 사실을 저장하거나 회상해야 할 때
계산 도우미	`calculator`, `convert`, `current_time`, `base64`, `random_choice`	작업에 산술, 단위 변환, 타임스탬프가 필요할 때

이상은 모두 제로 설정입니다 — 플랫폼의 일부이며 매 agent 실행에서 사용할 수 있습니다. 모델이 작업에 맞는 도구를 선택하며, 스트리밍 이벤트(tool_call → tool_result)에서 각 도구 호출을 확인할 수 있습니다.

유일한 예외: 커넥터. 서드파티 계정(Gmail, Slack, GitHub, Notion, Supabase, Datadog, …)은 Settings → Connectors에서 일회성 OAuth 또는 API key 연결이 필요합니다. 연결되면 agent가 그것들도 자동으로 사용합니다. Connectors 참고.

자동 출력: 계획 → 실행 → 전달

Agent 실행은 자기 주도형 루프입니다. 여러분이 단계를 스크립트로 짤 필요는 없습니다 — agent가 계획합니다:

계획 — 모델이 작업을 단계로 분해합니다("먼저 X를 검색하고, 상위 결과를 읽은 뒤 종합한다").
실행 — 계획한 도구를 호출하며, 한 번에 하나씩(또는 안전할 때 병렬로) 실행하고 각 결과를 읽은 뒤 다음 단계로 넘어갑니다.
검증 — 자신의 출력을 작업과 대조해 확인하고, 도구가 실패했거나 결과가 불완전하면 다시 시도합니다.
전달 — 최종 답변은 run_end 이벤트의 final_text에 들어가고, 생성된 파일은 artifacts로 반환됩니다.

각 단계는 GET …/agent/runs/{run_id}/attach를 통해 실시간으로 스트리밍됩니다 — 추론, 도구 호출, 답변이 만들어지는 과정을 볼 수 있습니다. 완료된 실행(전체 단계 궤적 포함)은 나중에 GET …/agent/runs/{run_id}로 가져올 수도 있습니다.

선택적 기능 강화(필수 아님)

베이스라인 — 추가 매개변수가 없는 task — 은 이미 완전한 도구 기능과 스마트 라우팅을 갖추고 있습니다. 다음은 순전히 선택적인 개선 사항입니다:

Skills — 재사용 가능한 워크플로 플레이북. 하나를 주입해 agent가 작업에 접근하는 방법을 안내합니다(예: "경쟁사 분석" 플레이북). 자동으로 첨부되지 않으며 명시적으로 선택해야 합니다.
전문가 역할 — 도메인 정체성(변호사, 데이터 분석가, 브랜드 수호자). 그 실행에서 agent가 '누구'인지를 정합니다. 실행당 최대 한 개.
Projects — 상주 지시 + 업로드된 지식을 재사용 가능한 컨텍스트로 묶은 것. 실행을 프로젝트에 연결해 당신의 도메인에 기반하게 합니다.
Memory — 워크스페이스의 장기 기억. 사실을 한 번 저장하면, 관련된 향후 실행에서 agent가 자동으로 회상합니다.
**pro** 모드 — 복잡한 작업을 위한 더 깊고 멀티스레드인 추론(병렬 서브 agent)을 잠금 해제합니다. 실행 body의 불리언 플래그입니다.

이 중 어떤 것도 연동에 필수가 아닙니다. {"task": "…"}만으로 시작하고, 구체적 필요가 생겼을 때만 강화를 추가하세요. Cookbook에 각 강화의 실제 사용 예가 나와 있습니다.