Agent Engine SDK OpenAI Agents

에이전트 빌드

작업 중인 프로젝트 에서 시작하려면 agentengine create를 실행 하고 Hello World 또는 휴먼인더루프 에이전트 (--template hello-world-agent-openai 또는 --template insurance-agent-openai)의 OpenAI Agents SDK 변형을 선택합니다.

from agents import Agent, ModelSettingsfrom agent_engine_sdk_openai_agents import App
app = App(app_name="support")

@app.tool()def lookup_order(order_id: str) -> str:    """Look up an order."""    ...

@app.entrypointdef build() -> Agent:    return Agent(        name="support",        instructions="Help with orders.",        model=app.llm("gpt-4.1", settings=ModelSettings(temperature=0)),        tools=app.tools(),    )

app.llm(...)이(가) 반환한 모델과 app.tools()이(가) 반환한 도구를 사용합니다. 다른 모델은 모델이나 도구가 작동하기 전에 턴에 실패합니다. 사용자 지정 OpenAI 클라이언트 사용하려면 구성된 agents.Model를 app.llm에 전달합니다. 원격 도구는 인수를 명명된 JSON 값으로 수신하기 때문에 도구 매개변수는 이름으로 전달할 수 있는 JSON 값이어야 합니다(위치 전용 또는 *args 매개변수가 없고 tool_call_id라는 매개변수도 없음). @app.tool(timeout=...)로 도구의 시간 초과를 설정합니다. 발행된 도구의 네이티브 timeout_seconds이(가) 턴에 실패합니다. 중첩된 모델, 데이터 클래스, 열거형, 날짜/시간 등 문자열이 아닌 도구 결과는 JSON 텍스트로 모델에 도달합니다. 텍스트는 표준이므로 재생된 차례는 모델에 동일한 텍스트를 전송합니다: 키가 정렬되고 164.0과 같은 정수 실수가 164로 기록됩니다. 도구 결과에서 2**53 이상의 정수는 호출에 실패하고, 지속형 기록 의 인수도 턴에 실패합니다. 이러한 값을 문자열로 전달합니다.

각 호출은 네이티브 Runner 턴을 한 번 실행하고 결과를 반환하기 전에 이를 오케스트레이션 엔진에 커밋합니다. 를 올리는 도구는 OpenAI Agents SDK가 기본값 으로 수행하는 대로 설치된 SDK의 default_tool_error_function 텍스트와 함께 모델에 보고되고, 차례가 계속됩니다. 0.23 이전 릴리스에는 해당 텍스트에 도구의 오류 메시지가 포함됩니다. 이후 릴리스에서는 해당 메시지 없이 고정 메시지를 보냅니다. 오케스트레이션 엔진은 실패를 기록하므로 다시 재생된 차례는 모델에 동일한 텍스트를 보냅니다. 플랫폼이 중지하거나 실패한 호출은 정책 거부, 취소되거나 사용자가 중지한 호출, 도구의 결과를 승인하지 않는 오케스트레이션 엔진과 같은 플랫폼 장애와 같이 도구 경로에서 보고하는 오류로 인해 회전에 실패합니다. 도구가 이미 실행 되었을 수 있으므로 플랫폼 오류는 모델에 실패한 도구로 보고되지 않습니다. 이러한 경우에는 아무것도 커밋되지 않습니다. 한 가지 예외는 남아 있습니다. 오케스트레이션 엔진이 원격 도구의 도구 파드에 연결할 수 없는 경우 실패를 도구의 것으로 기록하여 모델에 도구가 실패했음을 알립니다. 모델이 여러 도구를 한 번에 호출하면 동시에 실행 . 각 호출은 해당 호출 ID의 오케스트레이션 엔진 활동을 유지하며, 그 결과는 모델이 호출한 순서 중 먼저 완료되는 순서대로 모델에 도달합니다. 그 중 하나가 승인을 기다리는 경우, 대기 전에 실행된 호출은 SDK가 기록하기 때문에 승인된 호출보다 먼저 출력을 유지합니다. 한 호출이 차례에 실패하면 그 옆에서 아직 실행 호출이 완료되면 실패합니다. 에이전트 후크, 호스팅된 프롬프트, 동적 지침 및 사용자 지정 tool_use_behavior는 아직 지원되지 않습니다. 에이전트의 자체 입력 및 출력 가드레일은 입력 및 출력 가드레일에 설명된 대로 실행 . 프로젝트의 가드레일 정책은 모든 모델 및 도구 호출에 적용 . 가드레일 정책을 참조하세요.

MCP 도구

모든 Agent Engine 프레임워크 에서 사용하는 동일한 키를 사용하여 agent.yaml의 mcp.servers 아래에 원격 MCP 서버 나열합니다. 도구는 에이전트 시작될 때 검색되고 app.tools()가 <server>__<tool>이라는 이름의 등록된 함수 옆에 도구를 반환합니다.

mcp:  servers:    atlas:      url: https://mcp.example.com/mcp      allowed_tools: [find]      auth:        type: bearer_env        token_env: ATLAS_MCP_TOKEN

auth 토큰을 보유하는 환경 변수의 이름을 지정합니다. 토큰 자체는 작업 공간의 시크릿(secret)에 속하며, 로컬 개발의 경우 .env에 속합니다.

이러한 도구 중 하나에 대한 호출은 다른 도구와 마찬가지로 오케스트레이션 엔진 도구 활동이며 서버의 자격 증명 과 네트워크 액세스 보유하는 도구 파드에서 실행됩니다. allowed_tools는 에이전트 사용하는 서버 도구를 제한합니다. 실패한 호출 또는 MCP 오류 결과는 실패한 도구와 마찬가지로 모델에 보고됩니다. 지속형 기록 정확히 유지할 수 없는 2**53 이상의 정수를 보유하는 구조화된 결과는 턴에 실패합니다. 서버 이러한 값을 문자열로 반환하도록 합니다.

에이전트 가 시작될 때 연결할 수 없는 서버 시작을 중지합니다. timeout_seconds는 호출을 바인딩할 때 해당 검색의 각 요청 바인딩합니다.

에이전트 런타임만 시작될 때 서버의 도구를 나열합니다. 도구 파드는 호출이 도착하면 agent.yaml의 호출에 대한 서버 찾습니다. 또한 도구 파드는 엔트리포인트를 실행하여 에이전트의 모델을 등록하며, 여기서 app.tools()는 등록된 함수만 반환합니다. 이름( 예시 : [tool for tool in app.tools() if tool.name.startswith("atlas__")])으로 조회하지 않고 MCP 도구를 에이전트 에 전달하면 양쪽 모두에서 엔트리포인트가 구축됩니다.

SDK의 자체 Agent.mcp_servers는 거부됩니다: SDK는 도구 파드 외부의 에이전트 프로세스 에서 서버 호출합니다. MCP 도구의 needs_approval은 아직 지원되지 않습니다.

핸드오프

Use the SDK's own handoffs=[...], with other agents or agents.handoff(...). The runtime reads the whole agent graph the entrypoint returns before each turn and holds every reachable agent to the same rules as the first: its model comes from app.llm(...) (give each agent's model its own llm_id) and its tools from app.tools(), from which each agent can select its own by name. Agent names must be unique.

핸드오프는 활성 상태인 에이전트 변경합니다. 턴은 한 번의 실행으로 유지됩니다. 커밋된 상태 활성 에이전트 기록하므로 다시 시작한 후에도 다음 턴은 마지막 에이전트를 종료한 에이전트 부터 시작됩니다. 전달된 에이전트 가 요청한 승인은 해당 에이전트 에서 일시 중단되었다가 다시 시작됩니다.

agents.handoff(...) 은(는) 도구 이름 및 설명을 재정의할 수 있습니다. 에이전트는 주기에서 서로에게 핸드오프할 수 있습니다. input_filter, nest_handoff_history, on_handoff 콜백, input_type, 콜러블 is_enabled 및 수제 Handoff는 모델이나 도구가 작동하기 전에 턴에 실패합니다. 도구 이름이 다른 핸드오프 또는 해당 에이전트의 도구 중 하나와 일치하는 에이전트 에 대한 핸드오프도 마찬가지입니다.

도구로서의 에이전트

SDK의 자체 Agent.as_tool(...)를 사용하고 결과를 다른 에이전트의 tools에 넣습니다. 중첩된 에이전트 그래프 의 다른 모든 에이전트 와 동일한 규칙을 따릅니다. 각 호출은 중첩된 에이전트 자체 작업으로 실행합니다. 해당 모델 및 도구 호출은 도구 이름을 딴 경로 아래의 오케스트레이션 엔진 활동이며 동일한 에이전트 도구에 대한 반복 또는 동시 호출은 모델이 만든 순서대로 구별됩니다.

호출 에이전트의 모델은 도구의 답변 만 볼 수 있으며 호출 대화만 커밋됩니다. 교체 시도는 기록된 활동에서 중첩된 실행 재생합니다. 호출자의 스트림 subagent_start 이벤트와 subagent_end 이벤트 사이에 중첩된 에이전트의 텍스트를 전달하며, 호출 에이전트의 회신과는 별도로 도구 이름과 통화 ID가 태그로 지정됩니다. 실패한 중첩 실행 턴에 실패합니다.

중첩된 에이전트 사용하는 도구는 승인이 필요할 수 있으며, 에이전트 도구 자체도 승인이 필요할 수 있습니다. 다른 승인과 마찬가지로 차례가 일시 중단되고 대기가 중첩된 에이전트의 경로 아래에 기록됩니다. 호출 에이전트 와 중첩 에이전트의 대기에 한 번에 함께 응답합니다. 도구 호출 ID는 턴 내에서 고유해야 합니다. 승인을 위해 중지하는 중첩 에이전트 subagent_end를 전송하지 않습니다. 재개된 스트림 나머지 텍스트보다 먼저 subagent_start을 사용하여 스트림을 다시 열고, 호출자가 기다리기 전에 본 텍스트를 다시 전송하지 않습니다.

max_turns, custom_output_extractor 및 구조화된 입력이 지원됩니다. 교체 시도는 추출기와 구조화된 입력의 input_builder을 다시 호출하므로 둘 다 동일한 입력에 대해 동일한 값을 반환해야 하며 부작용이 없어야 합니다. 재생된 모델 호출이 기록된 모델 호출과 다를 경우 OE는 턴에 실패합니다.

중첩된 에이전트 또는 이 에이전트 가 전달하는 에이전트의 on_stream 콜백, hooks, run_config, session, 제공자 연속 ID, 호출 가능한 needs_approval 또는 is_enabled, 도구 가드레일, 입력 또는 출력 가드레일 네이티브 timeout_seconds를 해제하고 자체 에이전트 도구를 통해 자신에게 도달할 수 있는 에이전트 모델이나 도구가 작동하기 전에 턴에 실패합니다.

승인

Register a tool with @app.tool(needs_approval=True) to have a person approve each call. The argument is the SDK's own function_tool(needs_approval=...), passed through to the FunctionTool that app.tools() returns; setting needs_approval on that returned tool works too. When the model calls a tool that needs approval, the turn suspends: the invocation returns status: suspended with one interrupt per call waiting for approval, in the order the model made the calls, each naming the tool and its arguments. Calls in the same response that need no approval run first. Resume through the normal invoke endpoint on the same session, with resume_map answering every interrupt id at once:

{"resume_map": {"<interrupt id>": {"confirmed": true}}}

interrupts 보류 중인 모든 승인을 나열합니다. 단일 페이로드를 읽는 호출자의 경우 suspend_payload은(는) 첫 번째 값만 전달합니다.

{"confirmed": false, "rejection_message": "..."} 호출을 거부합니다. 모델에는 SDK의 자체 reject(..., rejection_message=...)에서와 같이 도구 결과 대신 거부 메시지가 표시됩니다. rejection_message가 없으면 모델에는 SDK의 기본값 거부 텍스트가 표시됩니다. 빈 값은 거부됩니다. 승인은 메시지를 전달하지 않습니다. 오케스트레이션 엔진은 대기와 그 답변 기록합니다. 재개는 기록된 모델 호출에서 차례를 다시 재생하고, SDK의 자체 RunState를 통해 답변 적용하고, 남은 항목만 실행하므로 승인 전에 도구가 실행되지 않으며, 접두사 출력이 반복되지 않으며, 대기 중 다시 시작하면 손실되지 않습니다. 중단된 내용을 답변하지 않은 상태로 유지하는 이력서는 거부됩니다. needs_approval는 호출 가능하지 않은 True 또는 False여야 합니다.

입력 및 출력 가드레일

input_guardrails 및 output_guardrails를 사용하여 SDK 문서로 에이전트 에서 가드레일을 선언합니다.

from agents import Agent, GuardrailFunctionOutput, Runner, input_guardrail

@app.entrypointdef build() -> Agent:    judge = Agent(        name="topic judge",        instructions="Answer yes if the message is about an order, else no.",        model=app.llm("gpt-4.1-mini", llm_id="judge"),    )
    @input_guardrail    async def on_topic(context, agent, input) -> GuardrailFunctionOutput:        verdict = await Runner.run(judge, input, context=context.context)        return GuardrailFunctionOutput(            output_info=None,            tripwire_triggered=verdict.final_output.strip().lower() != "yes",        )
    return Agent(        name="support",        model=app.llm("gpt-4.1"),        tools=app.tools(),        input_guardrails=[on_topic],    )

걸려 있는 가드레일은 정책 거부로 인해 회전에 실패합니다: 실행은 error_code policy_denied 및 해당 클래스에 대한 플랫폼의 자체 메시지로 종료됩니다. 거부 이유는 가드레일의 이름을 지정하고 해당 output_info를 생략합니다. 이는 저장된 실행이 아닌 런타임의 로그 와 실시간 스트림 오류 이벤트 의 메타데이터 에 있습니다. 차례는 아무것도 커밋하지 않으므로 대화는 이전 차례부터 계속됩니다. 이미 실행된 턴의 도구는 실행 취소되지 않습니다.

거부 시 가드레일에 이름이 지정되므로 모든 가드레일에는 이름이 필요합니다. @input_guardrail 또는 @output_guardrail로 선언되거나 함수에서 빌드된 함수는 다음 함수를 사용합니다. functools.partial 또는 콜러블 객체 로 빌드된 객체에는 아무것도 없으므로 name=을 전달합니다. 이름이 없는 가드레일은 모델 호출 전에 거부됩니다.

SDK의 자체 러너와 다른 점은 다음 세 가지입니다.

• 입력 가드레일은 첫 번째 모델 호출 전에 완료됩니다. SDK의 기본값run_in_parallel=True는 모델 호출 옆에서 이를 시작하며, 가드레일 트립 여부에 관계없이 모델 호출이 이루어지고 비용이 지불됩니다. 여기서는 run_in_parallel 은 효과가 없습니다.

• 에이전트의 가드레일은 에이전트 나열한 순서대로 한 번에 하나씩 실행 이동 이후의 가드레일은 실행 되지 않습니다. SDK가 이를 함께 시작합니다.

• 출력 가드레일이 있는 에이전트 텍스트를 스트림 하지 않습니다. SDK는 출력 가드레일이 보기 전에 답변 스트리밍하고 실행의 최종 값만 보류합니다. 여기에서 호출자는 가드레일이 통과한 턴의 결과에서 전체 답변 받습니다. 출력 가드레일이 없는 에이전트는 이전과 같이 스트림 .

SDK에서와 마찬가지로 입력 가드레일은 차례를 시작하는 에이전트 에 속하며 새 메시지로 지금까지의 대화를 확인합니다. 출력 가드레일은 턴의 최종 답변 제공하는 에이전트 에 속합니다. 핸드오프 후 전달된 에이전트 다음 턴을 시작하므로 입력 가드레일을 확인합니다.

교체 시도는 가드레일을 포함하여 처음부터 턴을 다시 실행하며 승인을 기다리는 턴은 재개될 때 가드레일을 다시 실행합니다. 따라서 가드레일은 동일한 입력에 대해 동일한 평결을 반환해야 하며 프로세스 외부에서는 아무 것도 변경하지 않아야 합니다. 모델을 요청하는 가드레일은 위의 judge와 같이 엔트리포인트가 앱 빌드하는 동안 호출된 app.llm(...) 에서 모델을 가져온 에이전트 통해 이를 수행합니다. 그러면 심사관의 모델 호출은 프로젝트 정책에 따른 오케스트레이션 엔진 활동이며, 다시 요청하는 대신 기록된 응답을 반환합니다. 실행 에는 턴을 수행하는 context=context.context가 필요합니다. 일반 모델 이름을 가진 저지는 런타임에 제공자 자격 증명 없으므로 턴에 실패합니다. 심사 에이전트 의 도구, 승인 및 핸드오프는 자격이 없습니다. 검토 위해 심사자의 응답을 보류하는 프로젝트 정책은 차례대로 실패했습니다. 즉, 앱 그래프 의 에이전트 만 리뷰어를 기다릴 수 있습니다. 외부 서비스를 직접 호출하는 가드레일은 지원되지 않습니다. 즉, 플랫폼의 네트워크 정책을 벗어나는 모든 재생에서 호출이 다시 이루어집니다.

도구 가드레일과 도구로 사용되는 에이전트 의 가드레일은 아직 지원되지 않습니다.

가드레일 정책

프로젝트의 가드레일 정책은 오케스트레이션 엔진에 의해 도구로 사용되는 에이전트 의 모델 및 도구 호출을 포함하여 턴의 모든 모델 및 도구 호출에 적용되며 애플리케이션 코드가 필요하지 않습니다. 변경 사항을 기록, 수정 또는 차단하는 정책은 호출이 반환하는 내용만 변경합니다.

A policy that requires review of a model response suspends the turn as an approval does: the response is withheld, and the invocation returns status: suspended with an interrupt whose value names the review under guardrail_review. It waits beside any tool approval of the same turn, and one resume_map answers them together:

{"resume_map": {"<interrupt id>": {"decision": "approve", "reviewer_notes": "checked"}}}

승인하면 다른 제공자 호출 없이 보류된 응답(도구 호출 포함)이 해제됩니다. 거부하면 턴이 실패하고 아무것도 릴리스하지 않습니다. 오케스트레이션 엔진은 응답을 보유하고 결정을 기록합니다. 어댑터는 승인되기 전에 보류된 텍스트를 절대 볼 수 없습니다.

Runner를 중지하기 위해 어댑터는 모든 에이전트 agent_engine_guardrail_review라는 이름의 도구를 제공하며, 이 도구는 모델이 제공되지 않습니다. 중지는 대화 내용이 아니므로 이후 모델 호출이나 커밋된 기록 모두 이를 전달하지 않습니다. 실행 에 대한 Runner의 자체 결과는 여전히 나열되므로 도구로 사용되는 에이전트 의 custom_output_extractor는 해당 에이전트 의 응답을 검토할 때 해당 실행 항목 중에서 호출과 빈 출력을 볼 수 있습니다. 검토 에 이름을 지정하고 보류된 응답을 지정하지 않습니다. 각 검토 실행의 max_turns 중 하나를 사용합니다. 해당 이름을 가진 도구나 핸드오프 또는 이를 호출하는 모델 응답은 턴에 실패합니다.

메모리

agent.yaml의 memory: true을 사용하면 도구는 app.memory를 통해 프로젝트의 장기 메모리를 읽고 쓰기 (write). 이는 LangGraph 및 ADK 앱이 사용하는 것과 동일한 파사드입니다.

@app.tool()def remember_preference(preference: str) -> str:    """Remember how the customer likes to be contacted."""    result = app.memory.save_semantic(text=preference, label="contact_preference")    return "saved" if result.acknowledged else "not saved"

요청 실행되는 동안 이루어진 호출은 해당 요청의 사용자를 사용합니다. 쓰기 (write) 지속형 활동이 아닌 라이브로 이루어집니다. 충돌 후 도구 호출이 재생되면 쓰기 (write) 가 다시 실행되므로 반복하기에 안전한 쓰기를 선호합니다.

지속 상태

커밋된 각 차례는 러너의 전체 입력 목록을 __agent_engine_openai_agents__ 상태 속성 아래에 해당 목록이 속한 앱 및 세션, 차례를 종료한 에이전트 의 이름과 함께 저장합니다. 다음 차례는 해당 에이전트 와 함께 해당 목록에서 계속됩니다. 커밋된 메시지는 기록 판독기에게 명시적 필드 프로젝션 입니다. 다시 읽지 않습니다.

오케스트레이션 엔진 기록의 독자는 해당 프로젝션, 즉 사용자 및 어시스턴트 메시지, 각 도구 호출 및 각 출력을 볼 수 있습니다. 핸드오프 및 도구로 사용되는 에이전트 에 대한 통화는 출력과 함께 일반 통화로 표시됩니다. 중첩된 에이전트의 자체 대화는 커밋되지 않으므로 기록에 없습니다. 모델 및 도구 호출은 실행의 활동 기록에 있습니다.

지원되는 항목은 문자 메시지, 함수 호출 및 텍스트 함수 출력입니다. 하나의 모델 응답이 수행한 호출은 함께 모인 다음, 다른 호출보다 먼저 호출당 정확히 하나의 출력이 출력됩니다. 다른 모든 항목, 다른 앱 또는 세션에 속한 모든 상태 및 활성 에이전트 앱 새 모델 또는 도구 작업이 시작되기 전에 더 이상 실패하지 않습니다.

세션 및 브랜치

오케스트레이션 엔진의 커밋된 상태 는 유일한 대화 저장 입니다. 어댑터는 해당 상태 입력으로 사용하여 자체적으로 Runner 호출을 수행하므로 SDK Session 객체와 공급자 호스팅 연속성(previous_response_id, 대화 ID 또는 호스팅된 프롬프트가 러너에 전달되었는지 여부에 관계없이 사용되지 않습니다. Agent.as_tool로, 또는 등록된 모델의 extra_body 또는 extra_args) 모델이 작동하기 전에 실패합니다.

브랜치는 다른 세션의 커밋된 상태 에서 시작하는 새 세션입니다. 첫 번째 차례는 소스의 대화 및 활성 에이전트 로 계속 진행되며 자체 세션에서 커밋하고 이후에는 소스와 아무것도 공유하지 않습니다. 승인은 어떤 순서로든 작동합니다. 어댑터는 턴당 한 번씩 커밋하기 때문에 완료된 턴이 끝날 때 대화를 분기할 수 있습니다. 플랫폼은 커밋된 단계에서만 분기하므로 승인을 기다리는 턴은 완료될 때까지 분기할 수 없습니다.

브랜치 생성은 SDK 작업이 아닌 플랫폼 작업입니다. 이 어댑터는 분기 API 추가하지 않으며 SDK의 자체 세션 분기(AdvancedSQLiteSession.create_branch_from_turn)를 사용할 수 없으므로 앱 자체 대화를 분기할 수 없습니다. 플랫폼의 브랜치 API 작동합니다.

모델 호출

네이티브 Runner가 수행하는 모든 모델 호출은 오케스트레이션 엔진 LLM 활동이 됩니다. 에이전트의 모델은 기록된 활동에서 응답하고 모델 자체는 도구 파드에서 실행됩니다. 교체 시도는 기록된 응답을 재생하고 Runner 동일한 출력 항목을 제공합니다.

플랫폼에서 전달하는 호출별 설정만 해당 경계를 넘습니다: max_tokens, top_p, frequency_penalty, presence_penalty, timeout, parallel_tool_calls, reasoning.effort, verbosity 및 명명된 tool_choice . temperature와(과) 같은 제공자 설정은 등록한 모델에 속하며, 도구 파드가 이를 적용합니다. 등록된 모델은 제공자 저장된 대화를 계속하도록 하는 tool_choice 또는 timeout ( 에이전트 에서 설정하다 ), 또는 extra_body / extra_args 필드 (previous_response_id, conversation, conversation_id , prompt) 또는 각 호출에 대해 어댑터가 빌드하는 항목(예: tools, input, instructions 또는 출력 형식)을 설정하다 하거나, reasoning, reasoning_effort 또는 verbosity를 원시 필드로 변환합니다(ModelSettings.reasoning 및 ModelSettings.verbosity 사용). 네이티브 추적, 공급자 호스팅 연속성 및 중지 시퀀스는 호출이 전송되기 전에 실패합니다.