@a2alite/sdk
Version:
A Modular SDK (Server & Client) for Agent to Agent (A2A) protocol, with easy task lifecycle management
546 lines (545 loc) • 21.1 kB
TypeScript
import type { Task, TaskState } from "../../types/types.ts";
import type { AgentMessageParams, AgentRequest, AgentTaskParams, StreamQueueFactory, StreamResult } from "./types.ts";
import { AgentTaskStream } from "./stream.ts";
/**
* Determines if a request should block until completion
* @param request - The agent request to check
* @returns true if the request is configured as blocking, false otherwise
*/
declare function requestIsBlocking(request: AgentRequest): boolean;
/**
* Manages the execution context for an agent task, handling task lifecycle,
* message creation, and streaming functionality.
*/
declare class AgentExecutionContext {
/** Unique contextId for this execution context */
id: string;
/** The original recieved request that initiated this context */
request: AgentRequest;
/** Factory method for creating stream queues */
streamQueueFactory: StreamQueueFactory;
/** The current active task being processed */
currentTask?: Task;
/** Reference tasks related to this context */
referenceTasks?: Task[];
/**
* Ensures a current task exists, throwing an error if not
* @throws Error when no current task is set
*/
private _ensureTask;
/**
* Creates a new AgentExecutionContext
* @param request - The received request
* @param streamQueueFactory - Factory for creating stream queues
* @param task - Optional existing task if the context is running an existing task received from the client
* @param referenceTasks - Optional reference tasks received from the client
* @param id - Optional custom context ID, used as a fallback if there is no task or request to extract a contextId from, if not provided a auto generated uuid is used as a fallback.
*/
constructor(request: AgentRequest, streamQueueFactory: StreamQueueFactory, task?: Task, referenceTasks?: Task[], id?: string);
/**
* Creates a message in this context, automatically setting contextId
* @param messageParams - Message content and metadata
* @param taskId - Optional task ID
* @param messageId - Optional custom message ID (auto-generated if not provided)
* @returns Message with context and task metadata
* @private
*/
private _createMessage;
/**
* Creates a new task or updates the current task with new parameters
* @param taskParams - Task parameters including artifacts and metadata
* @param taskState - New state for the task
* @param taskId - Optional task ID for new tasks
* @returns The created or updated task
*/
/**
* Creates a task status object with timestamp and optional message
* @param state - The task state
* @param message - Optional status message
* @returns TaskStatus object with timestamp
* @private
*/
private _createStatus;
/**
* Merges existing artifacts with new artifacts
* @param existing - Current artifacts array
* @param newArtifacts - New artifacts to add
* @returns Combined artifacts array
* @private
*/
private _mergeArtifacts;
/**
* Creates a new task or updates the current task with new parameters
* @param taskParams - Task parameters including artifacts and metadata
* @param taskState - New state for the task
* @param taskId - Optional task ID for new tasks
* @returns The created or updated task
* @private
*/
private _createOrUpdateTask;
/**
* Sets or updates the current task and returns it
* @param taskParams - Task parameters
* @param taskState - Task state
* @param taskId - Optional task ID
* @returns The updated task
*/
setOrUpdateTask(taskParams: AgentTaskParams | null | undefined, taskState: TaskState, taskId?: string): Task;
/**
* Initiates a streaming response with callback execution
* @param cb - Callback function to handle the task stream
* @param taskId - Optional task ID
* @param initialTaskState - Initial state for the task (default: "submitted")
* @returns Promise resolving to stream result
*/
stream(cb: (taskStream: AgentTaskStream) => Promise<void> | void, taskId?: string, initialTaskState?: "submitted" | "working"): Promise<StreamResult>;
/**
* Rejects the current task with provided parameters
* @param taskParams - Task parameters including rejection reason
* @param taskId - Optional task ID
* @returns The rejected task
*/
reject(taskParams: AgentTaskParams, taskId?: string): Promise<{
contextId: string;
id: string;
kind: "task";
status: {
state: "submitted" | "working" | "input-required" | "completed" | "canceled" | "failed" | "rejected" | "auth-required" | "unknown";
message?: {
kind: "message";
messageId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, any> | undefined;
} | {
kind: "file";
file: {
bytes: string;
mimeType?: string | undefined;
name?: string | undefined;
} | {
uri: string;
mimeType?: string | undefined;
name?: string | undefined;
};
metadata?: Record<string, any> | undefined;
} | {
kind: "data";
data: Record<string, any>;
metadata?: Record<string, any> | undefined;
})[];
role: "agent" | "user";
contextId?: string | undefined;
metadata?: Record<string, any> | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
} | undefined;
timestamp?: string | undefined;
};
artifacts?: {
artifactId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, any> | undefined;
} | {
kind: "file";
file: {
bytes: string;
mimeType?: string | undefined;
name?: string | undefined;
} | {
uri: string;
mimeType?: string | undefined;
name?: string | undefined;
};
metadata?: Record<string, any> | undefined;
} | {
kind: "data";
data: Record<string, any>;
metadata?: Record<string, any> | undefined;
})[];
description?: string | undefined;
metadata?: Record<string, any> | undefined;
name?: string | undefined;
}[] | undefined;
history?: {
kind: "message";
messageId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, any> | undefined;
} | {
kind: "file";
file: {
bytes: string;
mimeType?: string | undefined;
name?: string | undefined;
} | {
uri: string;
mimeType?: string | undefined;
name?: string | undefined;
};
metadata?: Record<string, any> | undefined;
} | {
kind: "data";
data: Record<string, any>;
metadata?: Record<string, any> | undefined;
})[];
role: "agent" | "user";
contextId?: string | undefined;
metadata?: Record<string, any> | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
}[] | undefined;
metadata?: Record<string, any> | undefined;
}>;
/**
* Sets task state to require authentication
* @param taskParams - Task parameters
* @param taskId - Optional task ID
* @returns The task requiring authentication
*/
authRequired(taskParams: AgentTaskParams, taskId?: string): Promise<{
contextId: string;
id: string;
kind: "task";
status: {
state: "submitted" | "working" | "input-required" | "completed" | "canceled" | "failed" | "rejected" | "auth-required" | "unknown";
message?: {
kind: "message";
messageId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, any> | undefined;
} | {
kind: "file";
file: {
bytes: string;
mimeType?: string | undefined;
name?: string | undefined;
} | {
uri: string;
mimeType?: string | undefined;
name?: string | undefined;
};
metadata?: Record<string, any> | undefined;
} | {
kind: "data";
data: Record<string, any>;
metadata?: Record<string, any> | undefined;
})[];
role: "agent" | "user";
contextId?: string | undefined;
metadata?: Record<string, any> | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
} | undefined;
timestamp?: string | undefined;
};
artifacts?: {
artifactId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, any> | undefined;
} | {
kind: "file";
file: {
bytes: string;
mimeType?: string | undefined;
name?: string | undefined;
} | {
uri: string;
mimeType?: string | undefined;
name?: string | undefined;
};
metadata?: Record<string, any> | undefined;
} | {
kind: "data";
data: Record<string, any>;
metadata?: Record<string, any> | undefined;
})[];
description?: string | undefined;
metadata?: Record<string, any> | undefined;
name?: string | undefined;
}[] | undefined;
history?: {
kind: "message";
messageId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, any> | undefined;
} | {
kind: "file";
file: {
bytes: string;
mimeType?: string | undefined;
name?: string | undefined;
} | {
uri: string;
mimeType?: string | undefined;
name?: string | undefined;
};
metadata?: Record<string, any> | undefined;
} | {
kind: "data";
data: Record<string, any>;
metadata?: Record<string, any> | undefined;
})[];
role: "agent" | "user";
contextId?: string | undefined;
metadata?: Record<string, any> | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
}[] | undefined;
metadata?: Record<string, any> | undefined;
}>;
/**
* Sets task state to require additional input
* @param taskParams - Task parameters
* @param taskId - Optional task ID
* @returns The task requiring input
*/
inputRequired(taskParams: AgentTaskParams, taskId?: string): Promise<{
contextId: string;
id: string;
kind: "task";
status: {
state: "submitted" | "working" | "input-required" | "completed" | "canceled" | "failed" | "rejected" | "auth-required" | "unknown";
message?: {
kind: "message";
messageId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, any> | undefined;
} | {
kind: "file";
file: {
bytes: string;
mimeType?: string | undefined;
name?: string | undefined;
} | {
uri: string;
mimeType?: string | undefined;
name?: string | undefined;
};
metadata?: Record<string, any> | undefined;
} | {
kind: "data";
data: Record<string, any>;
metadata?: Record<string, any> | undefined;
})[];
role: "agent" | "user";
contextId?: string | undefined;
metadata?: Record<string, any> | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
} | undefined;
timestamp?: string | undefined;
};
artifacts?: {
artifactId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, any> | undefined;
} | {
kind: "file";
file: {
bytes: string;
mimeType?: string | undefined;
name?: string | undefined;
} | {
uri: string;
mimeType?: string | undefined;
name?: string | undefined;
};
metadata?: Record<string, any> | undefined;
} | {
kind: "data";
data: Record<string, any>;
metadata?: Record<string, any> | undefined;
})[];
description?: string | undefined;
metadata?: Record<string, any> | undefined;
name?: string | undefined;
}[] | undefined;
history?: {
kind: "message";
messageId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, any> | undefined;
} | {
kind: "file";
file: {
bytes: string;
mimeType?: string | undefined;
name?: string | undefined;
} | {
uri: string;
mimeType?: string | undefined;
name?: string | undefined;
};
metadata?: Record<string, any> | undefined;
} | {
kind: "data";
data: Record<string, any>;
metadata?: Record<string, any> | undefined;
})[];
role: "agent" | "user";
contextId?: string | undefined;
metadata?: Record<string, any> | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
}[] | undefined;
metadata?: Record<string, any> | undefined;
}>;
/**
* Marks the task as completed
* @param taskParams - Task parameters including completion details
* @param taskId - Optional task ID
* @returns The completed task
*/
complete(taskParams: AgentTaskParams, taskId?: string): Promise<{
contextId: string;
id: string;
kind: "task";
status: {
state: "submitted" | "working" | "input-required" | "completed" | "canceled" | "failed" | "rejected" | "auth-required" | "unknown";
message?: {
kind: "message";
messageId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, any> | undefined;
} | {
kind: "file";
file: {
bytes: string;
mimeType?: string | undefined;
name?: string | undefined;
} | {
uri: string;
mimeType?: string | undefined;
name?: string | undefined;
};
metadata?: Record<string, any> | undefined;
} | {
kind: "data";
data: Record<string, any>;
metadata?: Record<string, any> | undefined;
})[];
role: "agent" | "user";
contextId?: string | undefined;
metadata?: Record<string, any> | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
} | undefined;
timestamp?: string | undefined;
};
artifacts?: {
artifactId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, any> | undefined;
} | {
kind: "file";
file: {
bytes: string;
mimeType?: string | undefined;
name?: string | undefined;
} | {
uri: string;
mimeType?: string | undefined;
name?: string | undefined;
};
metadata?: Record<string, any> | undefined;
} | {
kind: "data";
data: Record<string, any>;
metadata?: Record<string, any> | undefined;
})[];
description?: string | undefined;
metadata?: Record<string, any> | undefined;
name?: string | undefined;
}[] | undefined;
history?: {
kind: "message";
messageId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, any> | undefined;
} | {
kind: "file";
file: {
bytes: string;
mimeType?: string | undefined;
name?: string | undefined;
} | {
uri: string;
mimeType?: string | undefined;
name?: string | undefined;
};
metadata?: Record<string, any> | undefined;
} | {
kind: "data";
data: Record<string, any>;
metadata?: Record<string, any> | undefined;
})[];
role: "agent" | "user";
contextId?: string | undefined;
metadata?: Record<string, any> | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
}[] | undefined;
metadata?: Record<string, any> | undefined;
}>;
/**
* Creates a standalone message (not associated with a task)
* @param messageParams - Message content and metadata
* @param messageId - Optional custom message ID
* @returns The created message
*/
message(messageParams: AgentMessageParams, messageId?: string): Promise<{
kind: "message";
messageId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, any> | undefined;
} | {
kind: "file";
file: {
bytes: string;
mimeType?: string | undefined;
name?: string | undefined;
} | {
uri: string;
mimeType?: string | undefined;
name?: string | undefined;
};
metadata?: Record<string, any> | undefined;
} | {
kind: "data";
data: Record<string, any>;
metadata?: Record<string, any> | undefined;
})[];
role: "agent" | "user";
contextId?: string | undefined;
metadata?: Record<string, any> | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
}>;
}
export { requestIsBlocking, AgentExecutionContext };