@artinet/sdk
Version:
A TypeScript SDK for building collaborative AI agents.
890 lines (889 loc) • 34.9 kB
TypeScript
/**
* Copyright 2025 The Artinet Project
* SPDX-License-Identifier: Apache-2.0
*/
import { A2ARequestHandler, ServerCallContext, ExtendedAgentCardProvider, PushNotificationSender, PushNotificationStore } from "@a2a-js/sdk/server";
import { A2A } from "../../types/index.js";
import { PushNotifications } from "./notifications.js";
export declare class Native implements A2ARequestHandler {
protected _service: A2A.Service;
protected _pushNotifications?: PushNotifications | undefined;
protected _extendAgentCard?: (A2A.AgentCard | ExtendedAgentCardProvider) | undefined;
constructor(_service: A2A.Service, _pushNotifications?: PushNotifications | undefined, _extendAgentCard?: (A2A.AgentCard | ExtendedAgentCardProvider) | undefined);
get service(): A2A.Service;
getAgentCard(): Promise<{
protocolVersion: string;
name: string;
description: string;
url: string;
version: string;
capabilities: {
streaming?: boolean | undefined;
pushNotifications?: boolean | undefined;
stateTransitionHistory?: boolean | undefined;
extensions?: {
uri: string;
description?: string | undefined;
required?: boolean | undefined;
params?: Record<string, unknown> | undefined;
}[] | undefined;
};
defaultInputModes: string[];
defaultOutputModes: string[];
skills: {
id: string;
name: string;
description: string;
tags: string[];
examples?: string[] | undefined;
inputModes?: string[] | undefined;
outputModes?: string[] | undefined;
security?: Record<string, string[]>[] | undefined;
}[];
preferredTransport?: string | undefined;
additionalInterfaces?: {
url: string;
transport: string;
}[] | undefined;
iconUrl?: string | undefined;
provider?: {
organization: string;
url: string;
} | undefined;
documentationUrl?: string | undefined;
securitySchemes?: Record<string, {
type: "apiKey";
in: "query" | "header" | "cookie";
name: string;
description?: string | undefined;
} | {
type: "http";
scheme: string;
description?: string | undefined;
bearerFormat?: string | undefined;
} | {
type: "oauth2";
flows: {
authorizationCode?: {
authorizationUrl: string;
tokenUrl: string;
scopes: Record<string, string>;
refreshUrl?: string | undefined;
} | undefined;
clientCredentials?: {
tokenUrl: string;
scopes: Record<string, string>;
refreshUrl?: string | undefined;
} | undefined;
implicit?: {
authorizationUrl: string;
scopes: Record<string, string>;
refreshUrl?: string | undefined;
} | undefined;
password?: {
tokenUrl: string;
scopes: Record<string, string>;
refreshUrl?: string | undefined;
} | undefined;
};
description?: string | undefined;
oauth2MetadataUrl?: string | undefined;
} | {
type: "openIdConnect";
openIdConnectUrl: string;
description?: string | undefined;
} | {
type: "mutualTLS";
description?: string | undefined;
}> | undefined;
security?: Record<string, string[]>[] | undefined;
supportsAuthenticatedExtendedCard?: boolean | undefined;
signatures?: {
protected: string;
signature: string;
header?: Record<string, unknown> | undefined;
}[] | undefined;
}>;
getTask(params: A2A.TaskQueryParams, context?: ServerCallContext): Promise<{
id: string;
contextId: string;
status: {
state: "unknown" | "submitted" | "working" | "input-required" | "completed" | "canceled" | "failed" | "rejected" | "auth-required";
message?: {
role: "user" | "agent";
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
messageId: string;
kind: "message";
metadata?: Record<string, unknown> | undefined;
extensions?: string[] | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
contextId?: string | undefined;
} | undefined;
timestamp?: string | undefined;
};
kind: "task";
history?: {
role: "user" | "agent";
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
messageId: string;
kind: "message";
metadata?: Record<string, unknown> | undefined;
extensions?: string[] | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
contextId?: string | undefined;
}[] | undefined;
artifacts?: {
artifactId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
name?: string | undefined;
description?: string | undefined;
metadata?: Record<string, unknown> | undefined;
extension?: string[] | undefined;
}[] | undefined;
metadata?: Record<string, unknown> | undefined;
}>;
cancelTask(params: A2A.TaskIdParams, context?: ServerCallContext): Promise<{
id: string;
contextId: string;
status: {
state: "unknown" | "submitted" | "working" | "input-required" | "completed" | "canceled" | "failed" | "rejected" | "auth-required";
message?: {
role: "user" | "agent";
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
messageId: string;
kind: "message";
metadata?: Record<string, unknown> | undefined;
extensions?: string[] | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
contextId?: string | undefined;
} | undefined;
timestamp?: string | undefined;
};
kind: "task";
history?: {
role: "user" | "agent";
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
messageId: string;
kind: "message";
metadata?: Record<string, unknown> | undefined;
extensions?: string[] | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
contextId?: string | undefined;
}[] | undefined;
artifacts?: {
artifactId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
name?: string | undefined;
description?: string | undefined;
metadata?: Record<string, unknown> | undefined;
extension?: string[] | undefined;
}[] | undefined;
metadata?: Record<string, unknown> | undefined;
}>;
sendMessage(params: A2A.MessageSendParams, context?: ServerCallContext): Promise<{
role: "user" | "agent";
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
messageId: string;
kind: "message";
metadata?: Record<string, unknown> | undefined;
extensions?: string[] | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
contextId?: string | undefined;
} | {
id: string;
contextId: string;
status: {
state: "unknown" | "submitted" | "working" | "input-required" | "completed" | "canceled" | "failed" | "rejected" | "auth-required";
message?: {
role: "user" | "agent";
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
messageId: string;
kind: "message";
metadata?: Record<string, unknown> | undefined;
extensions?: string[] | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
contextId?: string | undefined;
} | undefined;
timestamp?: string | undefined;
};
kind: "task";
history?: {
role: "user" | "agent";
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
messageId: string;
kind: "message";
metadata?: Record<string, unknown> | undefined;
extensions?: string[] | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
contextId?: string | undefined;
}[] | undefined;
artifacts?: {
artifactId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
name?: string | undefined;
description?: string | undefined;
metadata?: Record<string, unknown> | undefined;
extension?: string[] | undefined;
}[] | undefined;
metadata?: Record<string, unknown> | undefined;
}>;
sendMessageStream(params: A2A.MessageSendParams, context?: ServerCallContext): AsyncGenerator<{
role: "user" | "agent";
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
messageId: string;
kind: "message";
metadata?: Record<string, unknown> | undefined;
extensions?: string[] | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
contextId?: string | undefined;
} | {
id: string;
contextId: string;
status: {
state: "unknown" | "submitted" | "working" | "input-required" | "completed" | "canceled" | "failed" | "rejected" | "auth-required";
message?: {
role: "user" | "agent";
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
messageId: string;
kind: "message";
metadata?: Record<string, unknown> | undefined;
extensions?: string[] | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
contextId?: string | undefined;
} | undefined;
timestamp?: string | undefined;
};
kind: "task";
history?: {
role: "user" | "agent";
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
messageId: string;
kind: "message";
metadata?: Record<string, unknown> | undefined;
extensions?: string[] | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
contextId?: string | undefined;
}[] | undefined;
artifacts?: {
artifactId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
name?: string | undefined;
description?: string | undefined;
metadata?: Record<string, unknown> | undefined;
extension?: string[] | undefined;
}[] | undefined;
metadata?: Record<string, unknown> | undefined;
} | {
taskId: string;
contextId: string;
kind: "status-update";
status: {
state: "unknown" | "submitted" | "working" | "input-required" | "completed" | "canceled" | "failed" | "rejected" | "auth-required";
message?: {
role: "user" | "agent";
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
messageId: string;
kind: "message";
metadata?: Record<string, unknown> | undefined;
extensions?: string[] | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
contextId?: string | undefined;
} | undefined;
timestamp?: string | undefined;
};
final: boolean;
metadata?: Record<string, unknown> | undefined;
} | {
taskId: string;
contextId: string;
kind: "artifact-update";
artifact: {
artifactId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
name?: string | undefined;
description?: string | undefined;
metadata?: Record<string, unknown> | undefined;
extension?: string[] | undefined;
};
append?: boolean | undefined;
lastChunk?: boolean | undefined;
metadata?: Record<string, unknown> | undefined;
}, void, any>;
resubscribe(params: A2A.TaskIdParams, context?: ServerCallContext): AsyncGenerator<{
id: string;
contextId: string;
status: {
state: "unknown" | "submitted" | "working" | "input-required" | "completed" | "canceled" | "failed" | "rejected" | "auth-required";
message?: {
role: "user" | "agent";
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
messageId: string;
kind: "message";
metadata?: Record<string, unknown> | undefined;
extensions?: string[] | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
contextId?: string | undefined;
} | undefined;
timestamp?: string | undefined;
};
kind: "task";
history?: {
role: "user" | "agent";
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
messageId: string;
kind: "message";
metadata?: Record<string, unknown> | undefined;
extensions?: string[] | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
contextId?: string | undefined;
}[] | undefined;
artifacts?: {
artifactId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
name?: string | undefined;
description?: string | undefined;
metadata?: Record<string, unknown> | undefined;
extension?: string[] | undefined;
}[] | undefined;
metadata?: Record<string, unknown> | undefined;
} | {
taskId: string;
contextId: string;
kind: "status-update";
status: {
state: "unknown" | "submitted" | "working" | "input-required" | "completed" | "canceled" | "failed" | "rejected" | "auth-required";
message?: {
role: "user" | "agent";
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
messageId: string;
kind: "message";
metadata?: Record<string, unknown> | undefined;
extensions?: string[] | undefined;
referenceTaskIds?: string[] | undefined;
taskId?: string | undefined;
contextId?: string | undefined;
} | undefined;
timestamp?: string | undefined;
};
final: boolean;
metadata?: Record<string, unknown> | undefined;
} | {
taskId: string;
contextId: string;
kind: "artifact-update";
artifact: {
artifactId: string;
parts: ({
kind: "text";
text: string;
metadata?: Record<string, unknown> | undefined;
} | {
kind: "file";
file: {
bytes: string;
name?: string | undefined;
mimeType?: string | undefined;
uri?: undefined;
} | {
uri: string;
name?: string | undefined;
mimeType?: string | undefined;
bytes?: undefined;
};
metadata?: Record<string, unknown> | undefined;
} | {
kind: "data";
data: Record<string, unknown>;
metadata?: Record<string, unknown> | undefined;
})[];
name?: string | undefined;
description?: string | undefined;
metadata?: Record<string, unknown> | undefined;
extension?: string[] | undefined;
};
append?: boolean | undefined;
lastChunk?: boolean | undefined;
metadata?: Record<string, unknown> | undefined;
}, void, any>;
get pushNotifications(): PushNotifications | undefined;
protected pushNotificationsEnabled(taskId?: string): Promise<void>;
setTaskPushNotificationConfig(_params: A2A.TaskPushNotificationConfig, _context?: ServerCallContext): Promise<A2A.TaskPushNotificationConfig>;
getTaskPushNotificationConfig(_params: A2A.GetTaskPushNotificationConfigParams, _context?: ServerCallContext): Promise<A2A.TaskPushNotificationConfig>;
listTaskPushNotificationConfigs(_params: A2A.ListTaskPushNotificationConfigParams, _context?: ServerCallContext): Promise<A2A.TaskPushNotificationConfig[]>;
deleteTaskPushNotificationConfig(_params: A2A.DeleteTaskPushNotificationConfigParams, _context?: ServerCallContext): Promise<void>;
protected registerConfig: (taskId: string, config: A2A.PushNotificationConfig) => Promise<void>;
protected notify: (task: A2A.Task, _update: A2A.Update, _context?: A2A.Context) => Promise<void>;
getAuthenticatedExtendedAgentCard(context?: ServerCallContext): Promise<A2A.AgentCard>;
static create(service: A2A.Service, _pushNotifications?: {
store?: PushNotificationStore;
sender?: PushNotificationSender;
} | PushNotifications, extendAgentCard?: A2A.AgentCard | ExtendedAgentCardProvider): A2ARequestHandler;
}
/**
* native adapter for `@a2a-js/sdk`
* @param service - The service to wrap
* @param pushNotifications - (optional) arguments for creating {@link PushNotifications}
* @param extendAgentCard - (optional) The extend agent card/provider to use
* @returns A {@link A2ARequestHandler} instance
* @example
* ```typescript
* const agent = cr8("Custom Agent")
* .text("Hello!")
* .agent;
* const nativeAdapter = native(agent, pushNotifications, extendAgentCard);
* ```
*/
export declare const native: typeof Native.create;