エージェント

エージェントは、エンドユーザーが対話する AI アシスタントです — ヘルプ デスクの副操縦士、営業の BDR、社内向け HR Q&A ボットなど。これらは、 すでに定義済みのデータとアクションの上に構築されます。新しいコードを書く 必要はなく、既存のプリミティブを組み合わせて 1 つのペルソナを作り上げます。

Salesforce Agentforce、Microsoft Copilot Studio、ServiceNow Now Assist と整合する 3 階層アーキテクチャ:

Agent  ──→  Skill  ──→  Tool
(persona)   (capability)  (callable function)

エージェントを定義する（1 ファイル）

// src/agents/tier1_support.agent.ts
import { defineAgent } from '@objectstack/spec/ai';

export const tier1Support = defineAgent({
  name: 'tier1_support',
  label: 'First Line Support',
  role: 'Help Desk Assistant',
  instructions: `
    You are a friendly first-line support agent.
    Always verify the user's identity before discussing account specifics.
    Escalate to tier 2 if the issue involves billing or security.
  `,
  skills: ['ticket_management', 'knowledge_search'],
  knowledge: {
    topics:  ['faq', 'policies'],
    indexes: ['support_docs'],
  },
  model: { provider: 'openai', model: 'gpt-4o', temperature: 0.3 },
  memory: { shortTerm: { maxMessages: 30 } },
});

または Console から: Console → Agents → New Agent。

あるいは — そしてこれが本質ですが — AI Builder にこう伝えます:

「チケット管理を扱い、FAQ を検索する tier-1 サポートエージェントを作成して。 アカウントの詳細を話す前に本人確認を行うようにして。」

スキルを定義する

// src/skills/ticket_management.skill.ts
import { defineSkill } from '@objectstack/spec/ai';

export const ticketManagement = defineSkill({
  name: 'ticket_management',
  label: 'Ticket Management',
  instructions: `
    Always confirm the ticket subject and priority before creating one.
    Use 'urgent' priority sparingly — only for outages or security incidents.
  `,
  tools: [
    'create_ticket',
    'update_ticket',
    'close_ticket',
    'escalate_ticket',
    'action_*',         // wildcard: pick up any future actions on the active object
  ],
});

スキルは再利用に適した単位です。1 つのスキルは多くのエージェントにまたがって 機能します。

ツールは宣言したメタデータから生成される

宣言したすべての *.action.ts は、自動的に action_<name> ツールとして 具現化されます — 個別の配線は不要です。したがって、support_ticket オブジェクト 上のアクションとして escalate_ticket をすでに定義していれば、AI Builder と あなたのエージェントの両方がそれを呼び出せます。権限は引き続き適用されます。 エージェントはユーザーとしてアクションを呼び出すため、それが成功するかどうかは ユーザーの権限セットが決定します。

次のものも公開できます:

アンビエントアシスタントパターン

ユーザーにエージェントを選ばせる代わりに、アプリ全体で 1 つのチャットボックス （Claude Code / Agentforce スタイル）を使いたい場合は、App メタデータに defaultAgent を宣言し、アプリのコンテキストとともにアンビエントチャット エンドポイントを呼び出します:

POST /api/v1/ai/chat   { context: { appName: 'crm' }, ... }

context.appName が defaultAgent を宣言するアプリに解決されると、ランタイムは そのエージェントを自動選択します — ユーザーがリストから選ぶことはありません。 Console の組み込み AI パネルはこれを使用しています。ランタイムは次を解決します:

1. アクティブなアプリのデフォルトエージェント（アプリの defaultAgent）、 またはユーザーがアクセスできる最初のエージェント。
2. アクティブなスキル — Skill Registry から読み込まれたエージェントの skills: リストで、ユーザーの権限セットと現在のオブジェクト／レコードの コンテキストでフィルタリングされたもの。
3. エージェントに付属するナレッジ。

どのエージェントをどこに表示するかを配線する必要はありません。アプリを宣言し、 その defaultAgent を設定すれば、表示されます。

権限

会話はユーザー単位にスコープされます — あるユーザーは、委任された付与がない限り、 別のユーザーのチャット履歴を見ることはできません。

メモリと会話の状態

エージェントの memory ブロックには 2 つの階層があります:

ライブコンテキストウィンドウのプルーニングは、会話のトークン予算戦略によって 管理されます — sliding_window（デフォルト）、fifo、importance、semantic、 または summary。

会話の行は ai_conversations に存在します。ツール呼び出しの結果と保留中の アクションは、監査のために発生元の会話への相互参照を保持します。

オブザーバビリティ

すべてのエージェント実行は次を発行します:

• audit:ai:chat イベント（ターンごと）
• audit:ai:tool イベント（ツール呼び出しごと、入力 + 出力付き）
• audit:ai:pending_action イベント（ミューテーションがキューに入ったとき）
• トークン数のメトリクス（モデルごと、プロバイダーごと）をチャージバックのために 監査ログへ

これらは通常のオブザーバビリティスタックに配線できます — Observability を参照してください。

マルチテナントに関する注意

エージェントは Environment 単位です。テナント A の tier1_support エージェントは、 marketplace パッケージで同じエージェント定義を出荷していても、テナント B の データ、会話、ナレッジを決して見ることはありません。

次に進む先

• AI Builder — ビルド時のアシスタント
• IDE Skills — npx skills add objectstack-ai/framework で、IDE エージェントがメタデータを正しく作成できるようにします
• Actions — エージェントが使用するツールを宣言します
• AI Service — プロバイダー、エンベッダー、MCP のセットアップ
• @objectstack/spec/ai — 完全なスキーマ