> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents モジュール

> `base44.agents` を介した AI エージェントの会話とメッセージ。

<Warning>
  このページは AI コーディングエージェントスキルの一部で、人間ではなくエージェント向けに書かれています。人間向けの Base44 ドキュメントは [デベロッパードキュメント](/developers) を参照してください。
</Warning>

# Agents モジュール

`base44.agents` を介した AI エージェントの会話とメッセージ。

> **注意:** このモジュールにはログイン済みユーザーが必要です。すべてのエージェントメソッドは認証済みユーザーのコンテキストで動作します。

## 目次

* [コンセプト](#concepts)
* [メソッド](#methods)
* [例](#examples) (Create、Get Conversations、List、Subscribe、Send Message、WhatsApp)
* [メッセージ構造](#message-structure)
* [会話構造](#conversation-structure)
* [一般的なパターン](#common-patterns)

## コンセプト

* **Conversation**: ユーザーと AI エージェント間の対話。一意の ID、エージェント名、ユーザー参照、メタデータを持ちます。
* **Message**: 会話内の単一メッセージ。role (`user`、`assistant`、`system`)、content、タイムスタンプ、オプションのメタデータを持ちます。

## メソッド

| メソッド                                     | シグネチャ                     | 説明                                                            |
| ---------------------------------------- | ------------------------- | ------------------------------------------------------------- |
| `createConversation(params)`             | `Promise<Conversation>`   | エージェントとの新規会話を作成                                               |
| `getConversations()`                     | `Promise<Conversation[]>` | ユーザーのすべての会話を取得                                                |
| `getConversation(id)`                    | `Promise<Conversation>`   | メッセージ付きの会話を取得 (完全なツール呼び出し結果を含む)                               |
| `listConversations(filterParams)`        | `Promise<Conversation[]>` | 会話のフィルター/ソート/ページ分割                                            |
| `subscribeToConversation(id, onUpdate?)` | `() => void`              | WebSocket 経由のリアルタイム更新; ツール呼び出しデータは切り詰められる (unsubscribe 関数を返す) |
| `addMessage(conversation, message)`      | `Promise<Message>`        | メッセージを送信                                                      |
| `getWhatsAppConnectURL(agentName)`       | `string`                  | エージェント用の WhatsApp 接続 URL を取得                                  |

## 例

### 会話の作成

```javascript theme={null}
const conversation = await base44.agents.createConversation({
  agent_name: "support-agent",
  metadata: {
    order_id: "ORD-123",
    category: "billing"
  }
});

console.log(conversation.id);
```

### すべての会話の取得

```javascript theme={null}
const conversations = await base44.agents.getConversations();

conversations.forEach(conv => {
  console.log(conv.id, conv.agent_name, conv.created_date);
});
```

### 単一会話の取得 (メッセージ付き)

完全なツール呼び出し結果を含む、保存された完全な会話を返します (リアルタイムサブスクリプションはツール呼び出しデータを切り詰めます)。

```javascript theme={null}
const conversation = await base44.agents.getConversation("conv-id-123");

console.log(conversation.messages);
```

### フィルター付きリスト

```javascript theme={null}
// Using filterParams object with q, sort, limit, skip, fields
const recent = await base44.agents.listConversations({
  q: { agent_name: "support-agent" },
  sort: "-created_date",
  limit: 10,
  skip: 0
});

// Filter by metadata
const highPriority = await base44.agents.listConversations({
  q: {
    agent_name: "support-agent",
    "metadata.priority": "high"
  },
  sort: "-updated_date",
  limit: 20
});
```

### 更新の購読 (リアルタイム)

このサブスクリプションを介してメッセージを受信する場合、ツール呼び出しデータは効率のために切り詰められます (`arguments_string` は 500 文字、`results` は 50 に制限)。完全なツール呼び出しデータを取得するには、メッセージが完了した後 `getConversation()` を使用してください。

```javascript theme={null}
const unsubscribe = base44.agents.subscribeToConversation(
  "conv-id-123",
  (updatedConversation) => {
    // Called when new messages arrive
    console.log("New messages:", updatedConversation.messages);
  }
);

// Later: unsubscribe
unsubscribe();
```

### メッセージの送信

```javascript theme={null}
const conversation = await base44.agents.getConversation("conv-id-123");

await base44.agents.addMessage(conversation, {
  role: "user",
  content: "What's the weather like today?"
});
```

### WhatsApp 接続 URL の取得

```javascript theme={null}
const whatsappUrl = base44.agents.getWhatsAppConnectURL("support-agent");
// Returns URL for users to connect with agent via WhatsApp
console.log(whatsappUrl);
```

## メッセージ構造

```javascript theme={null}
{
  role: "user" | "assistant" | "system",
  content: "Message text or structured object",
  created_date: "2024-01-15T10:30:00Z",
  updated_date: "2024-01-15T10:30:00Z",
  
  // Optional fields
  reasoning: {
    content: "Agent's reasoning process",
    timing: 1500
  },
  tool_calls: [{
    name: "search",
    arguments: { query: "weather" },
    result: { ... },
    status: "success"
  }],
  file_urls: ["https://..."],
  usage: {
    prompt_tokens: 150,
    completion_tokens: 50
  },
  metadata: { ... },
  custom_context: { ... }
}
```

## 会話構造

```javascript theme={null}
{
  id: "conv-id-123",
  app_id: "app-id",
  agent_name: "support-agent",
  created_by_id: "user-id",
  created_date: "2024-01-15T10:00:00Z",
  updated_date: "2024-01-15T10:30:00Z",
  messages: [ ... ],
  metadata: { ... }
}
```

## 一般的なパターン

### チャットインターフェース

```javascript theme={null}
// Load conversation
const conv = await base44.agents.getConversation(conversationId);
setMessages(conv.messages);

// Subscribe to updates
const unsubscribe = base44.agents.subscribeToConversation(conversationId, (updated) => {
  setMessages(updated.messages);
});

// Send message
async function sendMessage(text) {
  await base44.agents.addMessage(conv, { role: "user", content: text });
}

// Cleanup on unmount
return () => unsubscribe();
```

## 型定義

### AgentNameRegistry と AgentName

**型付きエージェント名の取得方法:** Base44 CLI はプロジェクトから `AgentNameRegistry` の拡張を生成できます。実行方法については、**base44-cli** スキルを使用してください。

```typescript theme={null}
/**
 * Registry of agent names.
 * Augment this interface to enable autocomplete for agent names.
 * Typically populated by the Base44 CLI type generator.
 */
interface AgentNameRegistry {}

/**
 * Agent name type - uses registry keys if augmented, otherwise string.
 */
type AgentName = keyof AgentNameRegistry extends never ? string : keyof AgentNameRegistry;
```

### AgentConversation

```typescript theme={null}
/** An agent conversation containing messages exchanged with an AI agent. */
interface AgentConversation {
  /** Unique identifier for the conversation. */
  id: string;
  /** Application ID. */
  app_id: string;
  /** Name of the agent in this conversation. */
  agent_name: string;
  /** ID of the user who created the conversation. */
  created_by_id: string;
  /** When the conversation was created. */
  created_date: string;
  /** When the conversation was last updated. */
  updated_date: string;
  /** Array of messages in the conversation. */
  messages: AgentMessage[];
  /** Optional metadata associated with the conversation. */
  metadata?: Record<string, any>;
}
```

### AgentMessage

```typescript theme={null}
/** A message in an agent conversation. */
interface AgentMessage {
  /** Unique identifier for the message. */
  id: string;
  /** Role of the message sender. */
  role: "user" | "assistant" | "system";
  /** When the message was created. */
  created_date: string;
  /** When the message was last updated. */
  updated_date: string;
  /** Message content. */
  content?: string | Record<string, any>;
  /** Optional reasoning information for the message. */
  reasoning?: AgentMessageReasoning | null;
  /** URLs to files attached to the message. */
  file_urls?: string[];
  /** Tool calls made by the agent. */
  tool_calls?: AgentMessageToolCall[];
  /** Token usage statistics. */
  usage?: AgentMessageUsage;
  /** Whether the message is hidden from the user. */
  hidden?: boolean;
  /** Custom context provided with the message. */
  custom_context?: AgentMessageCustomContext[];
  /** Model used to generate the message. */
  model?: string;
  /** Checkpoint ID for the message. */
  checkpoint_id?: string;
  /** Metadata about when and by whom the message was created. */
  metadata?: AgentMessageMetadata;
}
```

### サポートする型

```typescript theme={null}
/** Reasoning information for an agent message. */
interface AgentMessageReasoning {
  /** When reasoning started. */
  start_date: string;
  /** When reasoning ended. */
  end_date?: string;
  /** Reasoning content. */
  content: string;
}

/** A tool call made by the agent. */
interface AgentMessageToolCall {
  /** Tool call ID. */
  id: string;
  /** Name of the tool called. */
  name: string;
  /** Arguments passed to the tool as JSON string. */
  arguments_string: string;
  /** Status of the tool call. */
  status: "running" | "success" | "error" | "stopped";
  /** Results from the tool call. */
  results?: string;
}

/** Token usage statistics for an agent message. */
interface AgentMessageUsage {
  /** Number of tokens in the prompt. */
  prompt_tokens?: number;
  /** Number of tokens in the completion. */
  completion_tokens?: number;
}

/** Custom context provided with an agent message. */
interface AgentMessageCustomContext {
  /** Context message. */
  message: string;
  /** Associated data for the context. */
  data: Record<string, any>;
  /** Type of context. */
  type: string;
}

/** Metadata about when and by whom a message was created. */
interface AgentMessageMetadata {
  /** When the message was created. */
  created_date: string;
  /** Email of the user who created the message. */
  created_by_email: string;
  /** Full name of the user who created the message. */
  created_by_full_name: string;
}
```

### CreateConversationParams

```typescript theme={null}
/** Parameters for creating a new conversation. */
interface CreateConversationParams {
  /** The name of the agent to create a conversation with. */
  agent_name: AgentName;
  /** Optional metadata to attach to the conversation. */
  metadata?: Record<string, any>;
}
```

### ModelFilterParams

```typescript theme={null}
/** Parameters for filtering, sorting, and paginating conversations. */
interface ModelFilterParams {
  /** Query object with field-value pairs for filtering. */
  q?: Record<string, any>;
  /** Sort parameter (e.g., "-created_date" for descending). */
  sort?: string | null;
  /** Maximum number of results to return. */
  limit?: number | null;
  /** Number of results to skip for pagination. */
  skip?: number | null;
  /** Array of field names to include in the response. */
  fields?: string[] | null;
}
```

### AgentsModule

```typescript theme={null}
/** Agents module for managing AI agent conversations. */
interface AgentsModule {
  /** Gets all conversations from all agents in the app. */
  getConversations(): Promise<AgentConversation[]>;

  /** Gets a specific conversation by ID. Returns complete stored conversation including full tool call results. */
  getConversation(conversationId: string): Promise<AgentConversation | undefined>;

  /** Lists conversations with filtering, sorting, and pagination. */
  listConversations(filterParams: ModelFilterParams): Promise<AgentConversation[]>;

  /** Creates a new conversation with an agent. */
  createConversation(conversation: CreateConversationParams): Promise<AgentConversation>;

  /** Adds a message to a conversation. */
  addMessage(conversation: AgentConversation, message: Partial<AgentMessage>): Promise<AgentMessage>;

  /** Subscribes to realtime updates for a conversation. Returns unsubscribe function. */
  subscribeToConversation(conversationId: string, onUpdate?: (conversation: AgentConversation) => void): () => void;

  /** Gets WhatsApp connection URL for an agent. */
  getWhatsAppConnectURL(agentName: AgentName): string;
}
```

<Note>このページは AI を使用して翻訳されました。最も正確で最新の情報については、[英語版](/) を参照してください。 </Note>