@artinet/sdk 0.6.0-preview.2 → 0.6.0

package/README.md

@@ -1,23 +1,34 @@
-[![Website](https://img.shields.io/badge/website-artinet.io-black)](https://artinet.io/)
-[![npm version](https://img.shields.io/npm/v/@artinet/sdk.svg?logoColor=black)](https://www.npmjs.com/package/@artinet/sdk)
-[![npm downloads](https://img.shields.io/npm/dt/@artinet/sdk.svg)](https://www.npmjs.com/package/@artinet/sdk)
-[![Apache License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
-[![Known Vulnerabilities](https://snyk.io/test/npm/@artinet/sdk/badge.svg)](https://snyk.io/test/npm/@artinet/sdk)
-[![GitHub stars](https://img.shields.io/github/stars/the-artinet-project/artinet-sdk?style=social)](https://github.com/the-artinet-project/artinet-sdk/stargazers)
-[![Discord](https://dcbadge.limes.pink/api/server/DaxzSchmmX?style=flat)](https://discord.gg/DaxzSchmmX)
-
-# artinet-sdk
+<p align="center">
+<a href="https://artinet.io"><img src="https://img.shields.io/badge/website-artinet.io-black" alt="Website"></a>
+<a href="https://www.npmjs.com/package/@artinet/sdk"><img src="https://img.shields.io/npm/v/@artinet/sdk?color=black" alt="Version"></a>
+<a href="https://www.npmjs.com/package/@artinet/sdk"><img src="https://img.shields.io/npm/dt/@artinet/sdk?color=black" alt="Downloads"></a>
+<a><img src="https://img.shields.io/badge/License-Apache_2.0-black.svg" alt="License"></a>
+<a href="https://reddit.com/r/artinet"><img src="https://img.shields.io/reddit/subreddit-subscribers/theartinet?label=reddit&style=flat&color=black" alt="Subreddit"></a>
+<a><img src="https://img.shields.io/github/stars/the-artinet-project/artinet-sdk?style=social&color=black" alt="Github"></a>
+<a href="https://snyk.io/test/npm/@artinet/sdk"><img src="https://snyk.io/test/npm/@artinet/sdk/badge.svg" alt="Known Vulnerabilities"></a>
+</p>
+
+<h1 align="center"><em>artinet-sdk</em></h1>
 
 Create agents that communicate across frameworks.
 
-The artinet-sdk is a TypeScript library that adds a standardized, interoperable communication layer to your agents using the [Agent2Agent (A2A) Protocol](https://github.com/google-a2a/A2A).
+The <em><u>@artinet/sdk</u></em> is a universal, robust and production ready <code>AgentExecutor</code> library that adds a standardized, interoperable communication layer to any agent.
+
+> Runs on the <a href="https://github.com/google-a2a/A2A">Agent2Agent (A2A) Protocol</a> from the <a href="https://aaif.io/">Agentic AI Foundation</a>.
+
+## Installation
+
+```bash
+npm install @artinet/sdk express @a2a-js/sdk @modelcontextprotocol/sdk
+```
 
 ## Features
 
-- **Hassle Free:** Use the AgentBuilder to quickly setup an AgentServer.
-- **No Vendor Lock-In:** Let your agents communicate with other agents across frameworks and ecosystems.
+- **Hassle Free:** Use [**`cr8`**](./docs/create.md) to quickly spin-up an A2A compatible agent.
+- **No Vendor Lock-In:** Let your agents communicate with other agents no matter the framework and across ecosystems.
 - **Flexible Design:** Everything you need to build collaborative agents while remaining modular enough for advanced configuration.
-- **Pluggable Observability:** Bring your own logger (Pino, Winston) and tracer (OpenTelemetry) with zero-config defaults.
+- **Pluggable Observability:** Bring your own logger ([Pino](https://www.npmjs.com/package/pino), [Winston](https://www.npmjs.com/package/winston)) and/or tracer ([OpenTelemetry](https://www.npmjs.com/package/@opentelemetry/sdk-node)).
+- **Persistent Storage:** Roll your own `Task` storage or use our built-in [`SQLiteStore`](./docs/storage.md#sqlite-store) (backed by [`drizzle-orm`](https://www.npmjs.com/package/drizzle-orm)).
 
 ## Quick Start
 
@@ -27,9 +38,9 @@ The artinet-sdk is a TypeScript library that adds a standardized, interoperable
 npx @artinet/create-agent@latest
 ```
 
-It has [several template projects](https://github.com/the-artinet-project/create-agent/tree/main/templates) to jump right into agent building.
+It has [several template projects](https://github.com/the-artinet-project/artinet/tree/main/create-agent) to jump right into agent building.
 
-**Or use [`easy-a2a`](https://github.com/the-artinet-project/easy-a2a):**
+**Or use [`easy-a2a`](https://github.com/the-artinet-project/artinet/tree/main/easy):**
 
 ```typescript
 const agent = a2a({
@@ -46,72 +57,99 @@ const agent = a2a({
 npm install easy-a2a
 ```
 
-## Installation
+## Examples
 
-```bash
-npm install @artinet/sdk
-```
+**Create an A2A Server**
 
-**Peer dependencies (required):**
+Turn your agent into an express server so it can receive messages from anywhere:
 
-```bash
-npm install @a2a-js/sdk @modelcontextprotocol/sdk @trpc/server
+```typescript
+import { cr8 } from "@artinet/sdk";
+
+cr8("QuickStart Agent")
+  .text(async ({ content }) => `The user said: ${content}`)
+  //starts an express a2a server on port 3000
+  .server.start(3000);
 ```
 
-## Requirements
+- _ensure that the url/path of your AgentCard matches the server._
 
-- [Node.js](https://nodejs.org/en/download) ≥ 18.9.1 (Recommended: 20 or ≥ 22)
+> 🚧 Coming Soon: Support for Hono.
 
-## Example
+**No Servers Needed**
 
-**Server:**
+Embed agents directly into your app:
 
 ```typescript
-import { createAgentServer, AgentBuilder } from "@artinet/sdk";
-
-const { app } = createAgentServer({
-  agent: AgentBuilder()
-    .text(async ({ content }) => {
-      return `You said: ${content}`;
-    })
-    .createAgent({
-      agentCard: "QuickStart Agent",
-    }),
-  basePath: "/a2a",
-});
+import { cr8, A2A } from "@artinet/sdk";
 
-app.listen(3000, () => {
-  console.log("A2A Server running at http://localhost:3000/a2a");
-});
+const agent = cr8("Local Agent").text(
+  ({ content }) => `The user said: ${content}`
+).agent;
+
+const response: A2A.Task | A2A.Message = await agent.sendMessage("Hello");
 ```
 
-**Client:**
+- _See [**`cr8`**](./docs/create.md) for more information_
+
+**Connect to Remote Agents**
+
+[`AgentMessenger`](./docs/messenger.md#agentmessenger) provides a streamlined `Client` interface for communicating with remote A2A Servers:
 
 ```typescript
-import { A2AClient } from "@artinet/sdk";
+import { AgentMessenger, createMessenger } from "@artinet/sdk";
 
-const client = new A2AClient("http://localhost:3000/a2a");
+const messenger: AgentMessenger = await createMessenger({
+  baseUrl: "http://localhost:3000/a2a",
+  headers: {
+    Bearer: "xxxx",
+  },
+});
 
-const stream = client.sendStreamingMessage("Hello World!");
+const stream = messenger.sendMessageStream("Hello World!");
 
 for await (const update of stream) {
   console.log(update);
 }
 ```
 
+- _See [**messenger**](./docs/messenger.md#agentmessenger) for more information._
+
+**Simple Multi-Agent Orchestration**
+
+[**`cr8`**](./docs/create.md#agent-orchestration) provides easy to use tools for orchestrating multiple agents:
+
+```typescript
+import { cr8 } from "@artinet/sdk";
+import { localAgent } from "./local.ts";
+import { remoteAgentMessenger as remoteAgent } from "./remote.ts";
+
+const orchestrator = cr8("Director")
+  .text("Request Received")
+  .sendMessage({ agent: localAgent, message: "initiate billing" })
+  .text("Billing Started")
+  .sendMessage({ agent: remoteAgent, message: "Retrieve Secrets" }).agent;
+```
+
+> _For more robust multi-agent support, checkout [**orc8**](https://github.com/the-artinet-project/artinet), our dynamic agent orchestration library that can be used with any openai compatible API._
+
 ## Documentation
 
-| Topic                                       | Description                                           |
-| ------------------------------------------- | ----------------------------------------------------- |
-| [**API Reference**](docs/api-reference.md)  | Complete reference of SDK objects, types, and methods |
-| [**Configuration**](docs/configuration.md)  | Logging (Pino, Winston) and OpenTelemetry setup       |
-| [**Client Usage**](docs/client.md)          | A2AClient methods, streaming, browser support         |
-| [**Server Implementation**](docs/server.md) | AgentBuilder, AgentEngine, and AgentCard              |
-| [**Event Handling**](docs/events.md)        | Event subscriptions and custom handlers               |
-| [**Storage**](docs/storage.md)              | FileStore and custom storage backends                 |
-| [**Customization**](docs/customization.md)  | Middleware, tRPC, custom transports                   |
-| [**MCP Integration**](docs/mcp.md)          | Model Context Protocol compatibility                  |
-| [**Migration Guide**](docs/migration.md)    | Upgrading from v0.5.x to v0.6.0                       |
+| Topic                                      | Description                                           |
+| ------------------------------------------ | ----------------------------------------------------- |
+| [**Agent Creation**](docs/create.md)       | Scaffolding agents with `cr8`                         |
+| [**API Reference**](docs/api-reference.md) | Complete reference of SDK objects, types, and methods |
+| [**Execution**](docs/execution.md)         | Subscriptions and custom event handlers               |
+| [**Messenger**](docs/messenger.md)         | `Messenger` methods, streaming, browser support       |
+| [**Storage**](docs/storage.md)             | `FileStore`, `SQLiteStore`, custom storage backends   |
+| [**Configuration**](docs/configuration.md) | Logging (Pino, Winston) and OpenTelemetry setup       |
+| [**Customization**](docs/customization.md) | `native`, tRPC, and `AgentEngine`s                    |
+| [**MCP Integration**](docs/mcp.md)         | Model Context Protocol compatibility                  |
+| [**Migration Guide**](docs/migration.md)   | Upgrading from v0.5.x to v0.6.0                       |
+
+## Requirements
+
+- [Node.js](https://nodejs.org/en/download) ≥ 18.9.1 (Recommended: 20 or ≥ 22)
 
 ## Running Tests
 
@@ -127,8 +165,11 @@ Ensure code adheres to the project style and passes linting (`npm run lint`) and
 
 ## License
 
-This project is licensed under the Apache License 2.0 - see the `LICENSE` file for details.
+This project is licensed under Apache License 2.0.
+
+See the [`LICENSE`](./LICENSE) for details.
 
-## Acknowledgements
+## Join the Community
 
-This SDK builds upon the concepts and specifications of the [Agent2Agent (A2A) Protocol](https://github.com/google-a2a/A2A).
+- **Reddit:** [r/theartinet](https://www.reddit.com/r/theartinet/)
+- **Discord:** [the artinet channel](https://discord.gg/DaxzSchmmX)

package/dist/browser/browser.d.ts

@@ -1,9 +1,4 @@
 export * from "./types/index.js";
-export * from "./client/index.js";
-export { executeJsonRpcRequest, executeGetRequest, createJsonRpcRequest, sendJsonRpcRequest, } from "./transport/rpc/rpc-client.js";
-export { executeStreamEvents } from "./transport/streaming/event-stream.js";
-export * from "./utils/common/constants.js";
-export * from "./utils/common/errors.js";
-export * from "./utils/common/utils.js";
+export * from "./messenger/index.js";
+export * from "./utils/index.js";
 export * from "./config/index.js";
-export { A2AClient } from "./client/a2a-client.js";

package/dist/browser/browser.js

@@ -1,10 +1,5 @@
 //browser only entry point
 export * from "./types/index.js";
-export * from "./client/index.js";
-export { executeJsonRpcRequest, executeGetRequest, createJsonRpcRequest, sendJsonRpcRequest, } from "./transport/rpc/rpc-client.js";
-export { executeStreamEvents } from "./transport/streaming/event-stream.js";
-export * from "./utils/common/constants.js";
-export * from "./utils/common/errors.js";
-export * from "./utils/common/utils.js";
+export * from "./messenger/index.js";
+export * from "./utils/index.js";
 export * from "./config/index.js";
-export { A2AClient } from "./client/a2a-client.js";

package/dist/browser/config/observability.d.ts

@@ -2,7 +2,7 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-/** //todo move to @artinet/sdk from core v0.1
+/**
  * @fileoverview Zero-dependency observability interfaces for the Artinet ecosystem.
  *
  * Provides minimal interfaces for logging and tracing that consumers can implement

package/dist/browser/create/message-builder.d.ts

@@ -54,7 +54,7 @@ export type MessageSendParamsParams = Partial<Kindless<A2A.MessageSendParams>> |
  * @returns New {@link A2A.MessageSendParams} with default parameters
  * @defaults {
  *   message: {
- *     role: "agent",
+ *     role: "user",
  *     parts: [],
  *     messageId: uuidv4(),
  *     kind: "message",

package/dist/browser/create/message-builder.js

@@ -7,8 +7,6 @@ import { v4 as uuidv4 } from "uuid";
 export class Message {
     constructor(params = {}) {
         const messageId = params.messageId ?? uuidv4();
-        // TODO: Consider whether default role should be "user" when used in messageSendParams context.
-        // Currently defaults to "agent" which may be incorrect for MessageSendParams.
         this._message = {
             ...params,
             role: params.role ?? "agent",
@@ -77,7 +75,7 @@ export const MessageSendConfigurationBuilder = MessageSendConfiguration;
  * @returns New {@link A2A.MessageSendParams} with default parameters
  * @defaults {
  *   message: {
- *     role: "agent",
+ *     role: "user",
  *     parts: [],
  *     messageId: uuidv4(),
  *     kind: "message",
@@ -94,11 +92,25 @@ export const MessageSendConfigurationBuilder = MessageSendConfiguration;
  * @since 0.6.0
  */
 export function messageSendParams(params) {
-    const _isMessageParams = isMessageParams(params);
+    if (!isMessageParams(params)) {
+        return {
+            message: message(params.message),
+            configuration: new MessageSendConfiguration(params.configuration)
+                .configuration,
+            metadata: params.metadata,
+        };
+    }
+    if (typeof params === "string") {
+        return {
+            message: message({
+                role: "user",
+                parts: [{ text: params, kind: "text" }],
+            }),
+        };
+    }
+    params.role = params.role ?? "user";
     return {
-        message: message(_isMessageParams ? params : params.message),
-        configuration: new MessageSendConfiguration(_isMessageParams ? undefined : params.configuration).configuration,
-        metadata: _isMessageParams ? undefined : params.metadata,
+        message: message(params),
     };
 }
 /**

package/dist/browser/create/task-builder.js

@@ -4,7 +4,7 @@
  */
 import { A2A } from "../types/index.js";
 import { v4 as uuidv4 } from "uuid";
-import { getCurrentTimestamp } from "../utils/common/utils.js";
+import { getCurrentTimestamp } from "../utils/utils.js";
 import { isMessageParams, Message,
 // type BuilderMessageParams,
  } from "./message-builder.js";

package/dist/browser/messenger/index.d.ts

@@ -0,0 +1 @@
+export { createMessenger, A2AClient, AgentMessenger, type MessengerParams, } from "./messenger.js";

package/dist/browser/messenger/index.js

@@ -0,0 +1 @@
+export { createMessenger, A2AClient, AgentMessenger, } from "./messenger.js";

package/dist/browser/messenger/messenger.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../types/index.js";
+import * as describe from "../create/describe.js";
+import { ClientFactoryOptions, ClientConfig, Client, Transport, RequestOptions } from "@a2a-js/sdk/client";
+export interface MessengerParams {
+    baseUrl: URL | string;
+    headers?: Record<string, string>;
+    fallbackPath?: string;
+    factory?: ClientFactoryOptions;
+    config?: ClientConfig;
+}
+/**
+ * Messenger is the main communication client for interacting with remote A2A-compatible services.
+ * It provides methods for sending messages, retrieving tasks, canceling operations, and handling streaming responses.
+ */
+declare class Messenger implements Omit<Transport, "getAuthenticatedExtendedAgentCard" | "getExtendedAgentCard"> {
+    private _headers;
+    private _fallbackPath?;
+    private _baseUrl;
+    private _factory;
+    private clientPromise;
+    constructor(baseUrl: URL | string, _headers?: Record<string, string>, _fallbackPath?: string | undefined, factory?: ClientFactoryOptions, config?: ClientConfig);
+    reset(baseUrl?: URL | string, fallbackPath?: string | undefined): Promise<Client>;
+    get baseUrl(): string;
+    get headers(): Record<string, string>;
+    set headers(headers: Record<string, string>);
+    protected get _client(): Promise<Client>;
+    /**
+     * Retrieves the AgentCard from the A2A server.
+     * @returns A promise resolving to the AgentCard.
+     */
+    getAgentCard(requestOptions?: RequestOptions): Promise<A2A.AgentCard>;
+    sendMessage(params: A2A.MessageSendParams, options?: RequestOptions): Promise<A2A.SendMessageSuccessResult>;
+    sendMessage(params: describe.MessageParams, options?: RequestOptions): Promise<A2A.SendMessageSuccessResult>;
+    sendMessage(params: describe.MessageSendParamsParams, options?: RequestOptions): Promise<A2A.SendMessageSuccessResult>;
+    sendMessageStream(params: A2A.MessageSendParams, options?: RequestOptions): AsyncGenerator<A2A.Update, void, undefined>;
+    sendMessageStream(params: describe.MessageSendParamsParams, options?: RequestOptions): AsyncGenerator<A2A.Update, void, undefined>;
+    sendMessageStream(params: describe.MessageParams, options?: RequestOptions): AsyncGenerator<A2A.Update, void, undefined>;
+    /**
+     * Retrieves the current state of a task.
+     * @param params The parameters for the tasks/get method.
+     * @returns A promise resolving to the Task object or null.
+     */
+    getTask(params: A2A.TaskQueryParams, options?: RequestOptions): Promise<A2A.Task>;
+    /**
+     * Cancels a currently running task.
+     * @param params The parameters for the tasks/cancel method.
+     * @returns A promise resolving to the updated Task object (usually canceled state) or null.
+     */
+    cancelTask(params: A2A.TaskIdParams, options?: RequestOptions): Promise<A2A.Task>;
+    /**
+     * Sets or updates the push notification config for a task.
+     * @param params The parameters for the tasks/pushNotificationConfig/set method (which is TaskPushNotificationConfig).
+     * @returns A promise resolving to the confirmed TaskPushNotificationConfig or null.
+     */
+    setTaskPushNotificationConfig(params: A2A.TaskPushNotificationConfig, options?: RequestOptions): Promise<A2A.TaskPushNotificationConfig>;
+    /**
+     * Retrieves the currently configured push notification config for a task.
+     * @param params The parameters for the tasks/pushNotificationConfig/get method.
+     * @returns A promise resolving to the TaskPushNotificationConfig or null.
+     */
+    getTaskPushNotificationConfig(params: A2A.TaskIdParams, options?: RequestOptions): Promise<A2A.TaskPushNotificationConfig>;
+    listTaskPushNotificationConfig(params: A2A.ListTaskPushNotificationConfigParams, options?: RequestOptions): Promise<A2A.ListTaskPushNotificationConfigResult>;
+    deleteTaskPushNotificationConfig(params: A2A.DeleteTaskPushNotificationConfigParams, options?: RequestOptions): Promise<void>;
+    /**
+     * Resubscribes to an existing task's update stream.
+     * @param params Parameters identifying the task to resubscribe to
+     * @returns An AsyncIterable that yields TaskStatusUpdateEvent or TaskArtifactUpdateEvent payloads.
+     */
+    resubscribeTask(params: A2A.TaskQueryParams, options?: RequestOptions): AsyncGenerator<A2A.Update>;
+    /**
+     * Checks if the server supports a specific capability based on the agent card.
+     * @param capability The capability to check (e.g., 'streaming', 'pushNotifications').
+     * @returns A promise resolving to true if the capability is supported.
+     */
+    supports(capability: "streaming" | "pushNotifications" | "stateTransitionHistory" | "extentions"): Promise<boolean>;
+    /**
+     * Adds a single header to be included in all requests.
+     * @param name The header name.
+     * @param value The header value.
+     */
+    addHeader(name: string, value: string): void;
+    /**
+     * Removes a header.
+     * @param name The header name to remove.
+     */
+    removeHeader(name: string): void;
+    static create({ baseUrl, headers, fallbackPath, factory, config, }: MessengerParams): Promise<Messenger>;
+}
+/**
+ * Creates a new Messenger instance.
+ * @param baseUrl The base URL for the A2A server.
+ * @param headers Optional custom headers to include in all requests.
+ * @param fallbackPath Optional fallback path to use if the agent card is not found at the base URL.
+ * @example
+ * const messenger = createMessenger({
+ *   baseUrl: "http://localhost:4000/a2a",
+ * });
+ * const card = await messenger.getAgentCard();
+ * console.log(card);
+ * @example
+ * const messenger = createMessenger({
+ *   baseUrl: "http://localhost:4000/a2a",
+ *   fallbackPath: "/agent-card",
+ * });
+ * const card = await messenger.getAgentCard();
+ * console.log(card);
+ */
+export declare const createMessenger: typeof Messenger.create;
+export declare const AgentMessenger: typeof Messenger;
+export type AgentMessenger = Messenger;
+/**
+ * @deprecated Use {@link createMessenger} instead.
+ */
+export declare const A2AClient: typeof Messenger;
+export {};