핸드오프, 가드레일, 트레이싱을 갖춘 멀티 에이전트 리서치 및 리포트 파이프라인

# Multi-Agent Pipeline with openai-agents

## Setup

```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install openai-agents
export OPENAI_API_KEY="sk-..."
```

## Project layout

```
pipeline/
  __init__.py
  __main__.py
  agents.py
  tools.py
  guardrails.py
README.md
```

## `pipeline/__init__.py`

```python
from .agents import build_pipeline

__all__ = ["build_pipeline"]
```

## `pipeline/tools.py`

```python
from __future__ import annotations

import pathlib
from typing import Any

from agents import function_tool

OUT_DIR = pathlib.Path("./out")


@function_tool
def search(query: str) -> str:
    """Search the web for information about a topic.

    Args:
        query: The search query.
    """
    canned = {
        "default": (
            f"Stub search results for '{query}':\n"
            "- Result 1: Overview and background.\n"
            "- Result 2: Recent developments and key facts.\n"
            "- Result 3: Common pitfalls and best practices.\n"
        )
    }
    return canned["default"]


@function_tool
def write_markdown(filename: str, content: str) -> str:
    """Write markdown content to a file under ./out.

    Args:
        filename: The output filename (e.g. 'draft.md').
        content: The markdown content to write.
    """
    OUT_DIR.mkdir(parents=True, exist_ok=True)
    safe_name = pathlib.Path(filename).name
    path = OUT_DIR / safe_name
    path.write_text(content, encoding="utf-8")
    return f"Wrote {len(content)} chars to {path.resolve()}"
```

## `pipeline/guardrails.py`

```python
from __future__ import annotations

from agents import (
    Agent,
    GuardrailFunctionOutput,
    RunContextWrapper,
    TResponseInputItem,
    output_guardrail,
)


@output_guardrail
async def min_word_count_guardrail(
    ctx: RunContextWrapper[None],
    agent: Agent,
    output: str,
) -> GuardrailFunctionOutput:
    word_count = len(output.split())
    triggered = word_count < 200
    return GuardrailFunctionOutput(
        output_info={"word_count": word_count, "min_required": 200},
        tripwire_triggered=triggered,
    )
```

## `pipeline/agents.py`

```python
from __future__ import annotations

from agents import Agent, Session, SQLiteSession

from .guardrails import min_word_count_guardrail
from .tools import search, write_markdown


def build_pipeline(session: Session | None = None) -> Agent:
    """Build the triage -> (researcher | writer) pipeline."""

    researcher = Agent(
        name="Researcher",
        handoff_description="Use for requests that need information gathering or fact-finding.",
        instructions=(
            "You are a research assistant. Use the `search` tool to gather "
            "information about the user's topic. Summarize findings in 3-5 "
            "concise bullet points, then hand off to the Writer with a clear "
            "brief containing the key facts."
        ),
        tools=[search],
    )

    writer = Agent(
        name="Writer",
        handoff_description="Use for requests that need a written markdown deliverable.",
        instructions=(
            "You are a technical writer. Produce a well-structured markdown "
            "document of at least 250 words. Use headings, bullet points, and "
            "a short conclusion. When the draft is ready, call `write_markdown` "
            "with filename 'draft.md' and the full content. Then return the "
            "final markdown as your output."
        ),
        tools=[write_markdown],
        output_guardrails=[min_word_count_guardrail],
    )

    # Allow the researcher to hand off to the writer.
    researcher.handoffs = [writer]

    triage = Agent(
        name="Triage",
        instructions=(
            "You are a triage agent. Classify the user's request:\n"
            "- If it requires gathering information or research, hand off to "
            "the Researcher.\n"
            "- If it requires producing a written markdown deliverable, hand "
            "off to the Writer.\n"
            "Do not answer the request yourself; always hand off."
        ),
        handoffs=[researcher, writer],
    )

    return triage


def default_session() -> Session:
    return SQLiteSession(session_id="pipeline-cli")
```

## `pipeline/__main__.py`

```python
from __future__ import annotations

import asyncio
import sys

from agents import Runner

from .agents import build_pipeline, default_session


async def run(topic: str) -> None:
    session = default_session()
    triage = build_pipeline(session=session)

    result = await Runner.run(
        triage,
        input=f"Please produce a markdown article about: {topic}",
        session=session,
    )

    print("=" * 60)
    print("FINAL OUTPUT")
    print("=" * 60)
    print(result.final_output)
    print()
    print(f"Trace ID: {result.trace_id}")


def main() -> None:
    if len(sys.argv) != 2:
        print('Usage: python -m pipeline "<topic>"', file=sys.stderr)
        raise SystemExit(2)
    asyncio.run(run(sys.argv[1]))


if __name__ == "__main__":
    main()
```

## `README.md`

````markdown
# Multi-Agent Pipeline (openai-agents)

A triage → (Researcher | Writer) pipeline built with the `openai-agents` SDK.

## Setup

```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install openai-agents
export OPENAI_API_KEY="sk-..."
```

## Run

```bash
python -m pipeline "the history of the Rust programming language"
```

The pipeline will:

1. **Triage** classifies the request and hands off.
2. **Researcher** (if research is needed) calls the stub `search` tool and
   hands off to the Writer with a brief.
3. **Writer** drafts a markdown document (≥ 200 words, enforced by an output
   guardrail), writes it to `./out/draft.md`, and returns the final text.

The CLI prints the final output and the trace ID.

## Example run

```
$ python -m pipeline "the history of the Rust programming language"
============================================================
FINAL OUTPUT
============================================================
# The History of the Rust Programming Language

## Origins
Rust began at Mozilla in 2006 as a personal project by Graydon Hoare...

## Key Milestones
- 2010: First public announcement
- 2015: Rust 1.0 released
- 2021: Rust Foundation formed

## Conclusion
Rust has grown from an experimental systems language into one of the most
loved languages in the developer community.

Trace ID: trace_abc123def456
```

## Notes

- The `search` tool is a stub returning canned results; swap it for a real
  search API when ready.
- Sessions use `SQLiteSession` so conversation history persists across runs
  with the same `session_id`.
- The Writer's output guardrail rejects drafts under 200 words and triggers
  a tripwire, which surfaces as an exception from `Runner.run`.
````

## Notes on the implementation

- **Handoffs**: `researcher.handoffs = [writer]` lets the Researcher pass its brief to the Writer. The Triage agent can hand off to either.
- **Guardrail**: `@output_guardrail` on the Writer trips when the final output is under 200 words; `Runner.run` raises `OutputGuardrailTripwireTriggered`.
- **Sessions**: `SQLiteSession` persists history keyed by `session_id`, so repeated CLI invocations share context.
- **Trace ID**: `result.trace_id` is printed after the final output for observability.