OpenAI Agents SDK: Agents, Tools, Handoffs, Guardrails

작은 primitive, 진지한 workflow

OpenAI Agents SDK는 instruction과 tool을 가진 agent, delegated ownership을 위한 handoff, boundary를 위한 guardrail과 human review, resumable run을 위한 result/state, 점검을 위한 tracing/evaluation으로 agent app을 정리한다.

loop와 guardrail을 전부 직접 만들지 않고 agent orchestration을 세우고 싶을 때 유용해. 그렇다고 loop 이해를 생략해도 된다는 뜻은 아니야. raw loop가 불투명하면 framework는 버그를 더 우아하게 숨길 뿐이다.

guardrail은 boundary check야

input guardrail은 비싸거나 위험한 work가 시작되기 전에 early user input을 검사해. output guardrail은 final answer를 검사한다. tool/executor check는 side effect를 막고, human review는 민감한 action 전에 run을 멈춘다. 위치가 중요해. 모든 guardrail이 모든 step에서 돌지 않는다.

그러니까 risk가 어디 사는지 설계해야 해. risk가 매 tool call 안에 있으면 final output check만 두지 말고 tool-level check와 approval gate를 써야 한다.

기억한 snippet보다 현재 문서가 이긴다

SDK surface는 architecture보다 빨리 움직인다. provider-specific quest에서 install command, class name, guardrail signature를 가르치기 전에는 현재 공식 문서를 확인해야 해. 이 lesson은 architecture와 현재 Python shape를 주고, 전용 SDK 퀘스트는 publish 직전에 다시 검증해야 한다.

Code

Current Python Agents SDK shape·python

import asyncio
from agents import Agent, Runner, function_tool

@function_tool
def get_order_status(order_id: str) -> str:
    """Look up one order by public order id."""
    return "shipped"

agent = Agent(
    name="Order assistant",
    instructions="Help users with order status. Use tools for order facts.",
    model="gpt-5.5",
    tools=[get_order_status],
)

async def main() -> None:
    result = await Runner.run(agent, "Where is ORD-1042?")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

Risk placement checklist·text

Input risk?        input guardrail before the run does expensive work
Tool side effect?  executor permission + human approval gate
Final answer risk? output guardrail or reviewer pass
Debugging risk?    tracing + replayable run state
Regression risk?   eval dataset from real failures

OpenAI Agents SDK: Agents, Tools, Handoffs, Guardrails

작은 primitive, 진지한 workflow

guardrail은 boundary check야

기억한 snippet보다 현재 문서가 이긴다

Code

External links

Exercise

Progress

댓글 0