Agent SDK でエージェントをカスタマイズする

Agent SDK の定義は、モデル、システムプロンプト、ツールを組み合わせたものです。SDK はこれらを使って、永続的なセッション内のメッセージに応答します。エージェントに次の機能を追加する前に、入門ガイドに沿ってエージェントを作成し、公開してください。

• システムプロンプト
• モデル
• ツール
• オントロジーとのインタラクション
• エージェントの状態と作成時の引数

システムプロンプト

systemPrompt オプションは、エージェントがどのように応答すべきかを指定します。SystemPromptRenderResult.ready でテキストパーツを返す関数を指定します。

Copied!
1
2
3
4
5
6
7
import { SystemPromptRenderResult } from "@palantir/agents";

// defineAgent({ ... }) 内
systemPrompt: () =>
    SystemPromptRenderResult.ready([
        { type: "text", text: "You are a helpful agent..." },
    ]),

システムプロンプトのその他のカスタマイズオプションについては、高度なカスタマイズガイドを参照してください。

モデル

model オプションは、各リクエストに応答する言語モデルを決定します。セットアップ時に選択したモデルに応じて、対応するモデルがテンプレートにあらかじめ設定されています。

Copied!
1
2
3
4
5
6
7
8
import { Aliases } from "@osdk/functions";
import { anthropic } from "@palantir/agents";

// defineAgent({ ... }) 内：
model: anthropic({
    modelRid: Aliases.model("model").rid,
    modelSettings: { max_tokens: 4096 },
}),

このパッケージには、openAi、openAiChat、google、xAi コンストラクターも用意されています。モデルを更新するには、リソースのインポートサイドバーから目的のモデルをインポートし、対応するコンストラクターを使います。

モデルをインポートした後は、インポート時のエイリアスを使ってコード内で利用できます。

カスタムモデルの実装、状態に基づくモデルの選択、プロバイダーの設定については、モデルの高度なカスタマイズガイドを参照してください。

ツール

ツールを使うと、モデルはセッション中に情報やアクションを要求できます。各ツールには名前、説明、引数スキーマがあり、SDK がこれらをモデルに提示します。モデルがツールを呼び出すと、SDK はその execute 関数を実行します。

Agent SDK のツールはコンテキスト項目を返します。コンテキスト項目は、次のモデルリクエストに向けて、そのツール呼び出しの結果として表示されます。

たとえば、天気情報ツールは文字列のコンテキスト項目を返せます。この項目は、モデルに対して text フィールドを表示します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
import { Message, RenderResult, UserMessagePart, zodContextItem, zodTool } from "@palantir/agents";
import { z } from "zod";

const StringContextItem = zodContextItem({
    type: "string-result",
    dataSchema: z.object({ text: z.string() }),
    createArgsSchema: z.object({ text: z.string() }),
    create: args => ({ data: args }),
    render: ({ text }) => RenderResult.ready([
        Message.user(UserMessagePart.text(text))
    ]),
});

const WeatherTool = zodTool({
    name: "get_weather",
    description: "Get the weather for a city",
    argumentSchema: z.object({ city: z.string() }),
    execute: async ({ city }) => ({
        contextItems: [{
            contextItemType: StringContextItem.type,
            createArgs: { text: `Weather in ${city} is sunny.` },
        }]
    }),
});

// defineAgent({ ... }) 内：
contextItemDefinitions: [StringContextItem],
tools: () => [WeatherTool],

ツールの実行中にエラーがスローされた場合、次のターンでモデルに失敗が表示されます。

ツールの結果、長時間実行される参照、動的なツールリスト、ユーザーインタラクションの例については、高度な概念を参照してください。

オントロジーとのインタラクション

TypeScript OSDK を使うと、エージェントからオブジェクトを読み取り、アクションを適用し、関数を実行できます。

アクションを適用する

アクションを使うと、エージェントはオントロジーを編集できます。アクションの呼び出しを有効にするには、エージェントのスコープ付きモードを有効にする必要があります。リソースのインポートサイドバーに移動し、スコープ設定を選択します。

そこで、スコープ付きモードを有効にするをオンにします。

次に、実行時にアクションを呼び出すツールを記述します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import { assignTicket } from "@ontology/sdk";
import { getClient } from "@palantir/agents-core";

const AssignTicket = zodTool({
    name: "assign_ticket",
    description: "Assign a support ticket to a user",
    argumentSchema: z.object({ ticketId: z.string(), assigneeId: z.string() }),
    execute: async ({ ticketId, assigneeId }) => {
        const client = getClient();
        await client(assignTicket).applyAction({ ticketId, assigneeId });
        return {
            contextItems: [
                {
                    contextItemType: StringContextItem.type,
                    createArgs: { text: "Ticket assigned." },
                },
            ],
            events: [],
        };
    },
});

関数を呼び出す

関数は、オントロジーを編集せずに結果を計算できます。モデルが結果を参照できるように、コンテキスト項目として返します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import { getTicketSummary } from "@ontology/sdk";
import { getClient } from "@palantir/agents-core";

const SummarizeTicket = zodTool({
    name: "summarize_ticket",
    description: "Summarize a support ticket",
    argumentSchema: z.object({ ticketId: z.string() }),
    execute: async ({ ticketId }) => {
        const client = getClient();
        const summary = await client(getTicketSummary).executeFunction({
            ticketId,
        });
        return {
            contextItems: [
                {
                    contextItemType: StringContextItem.type,
                    createArgs: { text: summary },
                },
            ],
            events: [],
        };
    },
});

オブジェクトデータをコンテキストに読み込む

OSDK を通じてオブジェクトを取得し、関連するプロパティをコンテキスト項目として返します。SDK は、次のモデルリクエストに向けて、ツールの結果内にこの項目を表示します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import { SupportTicket } from "@ontology/sdk";
import { getClient } from "@palantir/agents-core";

const GetTicket = zodTool({
    name: "get_ticket",
    description: "Load a support ticket",
    argumentSchema: z.object({ ticketId: z.string() }),
    execute: async ({ ticketId }) => {
        const ticket = await getClient()(SupportTicket).fetchOne(ticketId);
        return {
            contextItems: [
                {
                    contextItemType: StringContextItem.type,
                    createArgs: {
                        text: `Ticket ${ticket.$primaryKey}: ${ticket.title} (${ticket.status})`,
                    },
                },
            ],
            events: [],
        };
    },
});

オブジェクトの読み込みに時間がかかる場合は、カスタムコンテキスト項目を使うと、ツールの待機中に進行状況を表示できます。例示されているリソース名とパラメーターは、お使いのオントロジー用に生成されたものに置き換えてください。

エージェントの状態と作成時の引数

各エージェントは固有のエージェント状態を持ちます。エージェントの状態には厳密な型が指定されており、次の用途に使えます。

• エージェントとその現在の状態に関する情報を UI に表示する
• ツール呼び出しで使う値を保持する
• モデル、システムプロンプト、ツールを動的に導出する
• エージェントの進行状況とステータスを追跡する

さらに、エージェントは作成時に引数を受け取れます。createSessionArgsSchema を設定して、引数のデータ型を宣言します。引数はエージェントの状態に保存でき、後からツールやシステムプロンプトに公開できます。

Copied!
1
2
3
4
5
6
import { z } from "zod";

// defineAgent({ ... }) 内：
agentStateSchema: z.object({ audience: z.string() }),
createSessionArgsSchema: z.object({ audience: z.string() }),
createSession: args => ({ agentState: { audience: args.audience } }),

エージェントの実行中にエージェントの状態を変更する方法については、カスタムイベントガイドを参照してください。