5639606163
This pull request introduces the following changes: 1. **Exclude translated pages from search**: I explored ways to make the search plugin work with the i18n plugin, but it would require extensive custom JavaScript hacks. So for now, I’m holding off on this work. 2. **Switch from GPT-4.1 to o3 for even better translation quality**: While 4.1 performs well, o3 shows even greater quality for this task, and there’s no reason to avoid using it.
117 lines
No EOL
5.7 KiB
Markdown
117 lines
No EOL
5.7 KiB
Markdown
---
|
|
search:
|
|
exclude: true
|
|
---
|
|
# ハンドオフ
|
|
|
|
ハンドオフを使用すると、エージェント がタスクを別の エージェント に委譲できます。これは、複数の エージェント がそれぞれ異なる分野を専門とするシナリオで特に便利です。たとえばカスタマーサポートアプリでは、注文状況、返金、 FAQ などのタスクを個別に担当する エージェント を用意できます。
|
|
|
|
ハンドオフは LLM からはツールとして認識されます。そのため、`Refund Agent` という エージェント へのハンドオフであれば、ツール名は `transfer_to_refund_agent` になります。
|
|
|
|
## ハンドオフの作成
|
|
|
|
すべての エージェント には [`handoffs`][agents.agent.Agent.handoffs] パラメーターがあり、直接 `Agent` を渡すことも、ハンドオフをカスタマイズする `Handoff` オブジェクトを渡すこともできます。
|
|
|
|
Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、引き継ぎ先の エージェント を指定し、オーバーライドや入力フィルターをオプションで設定できます。
|
|
|
|
### 基本的な使い方
|
|
|
|
シンプルなハンドオフを作成する例を示します。
|
|
|
|
```python
|
|
from agents import Agent, handoff
|
|
|
|
billing_agent = Agent(name="Billing agent")
|
|
refund_agent = Agent(name="Refund agent")
|
|
|
|
# (1)!
|
|
triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)])
|
|
```
|
|
|
|
1. `billing_agent` のように エージェント を直接指定することも、`handoff()` 関数を使用することもできます。
|
|
|
|
### `handoff()` 関数によるハンドオフのカスタマイズ
|
|
|
|
[`handoff()`][agents.handoffs.handoff] 関数を使うと、ハンドオフを細かくカスタマイズできます。
|
|
|
|
- `agent`: ここで指定した エージェント に処理が引き渡されます。
|
|
- `tool_name_override`: デフォルトでは `Handoff.default_tool_name()` が使用され、`transfer_to_<agent_name>` という名前になります。これを上書きできます。
|
|
- `tool_description_override`: `Handoff.default_tool_description()` が返すデフォルトのツール説明を上書きします。
|
|
- `on_handoff`: ハンドオフ実行時に呼び出されるコールバック関数です。ハンドオフが呼ばれたタイミングでデータ取得を開始するなどに便利です。この関数は エージェント のコンテキストを受け取り、オプションで LLM が生成した入力も受け取れます。渡されるデータは `input_type` パラメーターで制御します。
|
|
- `input_type`: ハンドオフが受け取る入力の型（任意）。
|
|
- `input_filter`: 次の エージェント が受け取る入力をフィルタリングできます。詳細は後述します。
|
|
|
|
```python
|
|
from agents import Agent, handoff, RunContextWrapper
|
|
|
|
def on_handoff(ctx: RunContextWrapper[None]):
|
|
print("Handoff called")
|
|
|
|
agent = Agent(name="My agent")
|
|
|
|
handoff_obj = handoff(
|
|
agent=agent,
|
|
on_handoff=on_handoff,
|
|
tool_name_override="custom_handoff_tool",
|
|
tool_description_override="Custom description",
|
|
)
|
|
```
|
|
|
|
## ハンドオフ入力
|
|
|
|
場合によっては、 LLM がハンドオフを呼び出す際に追加のデータを渡してほしいことがあります。たとえば「Escalation エージェント」へのハンドオフでは、ログ用に理由を渡してもらいたいかもしれません。
|
|
|
|
```python
|
|
from pydantic import BaseModel
|
|
|
|
from agents import Agent, handoff, RunContextWrapper
|
|
|
|
class EscalationData(BaseModel):
|
|
reason: str
|
|
|
|
async def on_handoff(ctx: RunContextWrapper[None], input_data: EscalationData):
|
|
print(f"Escalation agent called with reason: {input_data.reason}")
|
|
|
|
agent = Agent(name="Escalation agent")
|
|
|
|
handoff_obj = handoff(
|
|
agent=agent,
|
|
on_handoff=on_handoff,
|
|
input_type=EscalationData,
|
|
)
|
|
```
|
|
|
|
## 入力フィルター
|
|
|
|
ハンドオフが発生すると、新しい エージェント が会話を引き継ぎ、これまでの会話履歴全体を閲覧できる状態になります。これを変更したい場合は [`input_filter`][agents.handoffs.Handoff.input_filter] を設定してください。入力フィルターは、[`HandoffInputData`][agents.handoffs.HandoffInputData] として渡される既存の入力を受け取り、新しい `HandoffInputData` を返す関数です。
|
|
|
|
よくあるパターン（たとえば履歴からすべてのツール呼び出しを削除するなど）は [`agents.extensions.handoff_filters`][] に実装済みです。
|
|
|
|
```python
|
|
from agents import Agent, handoff
|
|
from agents.extensions import handoff_filters
|
|
|
|
agent = Agent(name="FAQ agent")
|
|
|
|
handoff_obj = handoff(
|
|
agent=agent,
|
|
input_filter=handoff_filters.remove_all_tools, # (1)!
|
|
)
|
|
```
|
|
|
|
1. これにより `FAQ agent` が呼ばれた際に、履歴からすべてのツール呼び出しが自動で削除されます。
|
|
|
|
## 推奨プロンプト
|
|
|
|
LLM がハンドオフを正しく理解できるよう、エージェント にハンドオフに関する情報を含めることを推奨します。事前に用意したプレフィックス [`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] を利用するか、[`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出してプロンプトに推奨情報を自動で追加できます。
|
|
|
|
```python
|
|
from agents import Agent
|
|
from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX
|
|
|
|
billing_agent = Agent(
|
|
name="Billing agent",
|
|
instructions=f"""{RECOMMENDED_PROMPT_PREFIX}
|
|
<Fill in the rest of your prompt here>.""",
|
|
)
|
|
``` |