このページは AI コーディングエージェントスキルの一部で、人間ではなくエージェント向けに書かれています。人間向けの Base44 ドキュメントは デベロッパードキュメント を参照してください。
Agents モジュール
base44.agents を介した AI エージェントの会話とメッセージ。
注意: このモジュールにはログイン済みユーザーが必要です。すべてのエージェントメソッドは認証済みユーザーのコンテキストで動作します。
目次
コンセプト
- 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 を取得 |
例
会話の作成
const conversation = await base44.agents.createConversation({
agent_name: "support-agent",
metadata: {
order_id: "ORD-123",
category: "billing"
}
});
console.log(conversation.id);
すべての会話の取得
const conversations = await base44.agents.getConversations();
conversations.forEach(conv => {
console.log(conv.id, conv.agent_name, conv.created_date);
});
単一会話の取得 (メッセージ付き)
完全なツール呼び出し結果を含む、保存された完全な会話を返します (リアルタイムサブスクリプションはツール呼び出しデータを切り詰めます)。const conversation = await base44.agents.getConversation("conv-id-123");
console.log(conversation.messages);
フィルター付きリスト
// 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() を使用してください。
const unsubscribe = base44.agents.subscribeToConversation(
"conv-id-123",
(updatedConversation) => {
// Called when new messages arrive
console.log("New messages:", updatedConversation.messages);
}
);
// Later: unsubscribe
unsubscribe();
メッセージの送信
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 の取得
const whatsappUrl = base44.agents.getWhatsAppConnectURL("support-agent");
// Returns URL for users to connect with agent via WhatsApp
console.log(whatsappUrl);
メッセージ構造
{
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: { ... }
}
会話構造
{
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: { ... }
}
一般的なパターン
チャットインターフェース
// 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 スキルを使用してください。
/**
* 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
/** 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
/** 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;
}
サポートする型
/** 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
/** 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
/** 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
/** 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;
}
このページは AI を使用して翻訳されました。最も正確で最新の情報については、英語版 を参照してください。