@artinet/sdk 0.5.17 → 0.6.0-preview.1

package/README.md

@@ -8,623 +8,117 @@
 
 # artinet-sdk
 
-Give your AI agent the power to communicate with any other agent, no matter the framework.
+Create agents that communicate across frameworks.
 
-The artinet-sdk is a TypeScript library that adds a standardized, interoperable communication layer to your agents.
+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).
 
 ## Features
 
-- **Easy To Use:** The AgentBuilder lets you quickly create an Agent2Agent API, while handling all of the communication complexity.
-- **No Vendor Lock-In:** Create agents that can communicate with other agents across frameworks and ecosystems with just a few lines of code.
+- **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.
 - **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.
 
 ## Quick Start
 
-Use the [`create-agent`](https://www.npmjs.com/package/@artinet/create-agent) command:
+**Use the [`create-agent`](https://www.npmjs.com/package/@artinet/create-agent) command:**
 
 ```bash
 npx @artinet/create-agent@latest
 ```
 
-It has [serveral template projects](https://github.com/the-artinet-project/create-agent/tree/main/templates) that you can use to jump right into agent building.
-
-## Table of Contents
-
-- [artinet-sdk](#artinet-sdk)
-  - [Features](#features)
-  - [Quick Start](#quick-start)
-  - [Table of Contents](#table-of-contents)
-  - [Installation](#installation)
-  - [Requirements](#requirements)
-  - [Example](#example)
-  - [Running Tests](#running-tests)
-  - [Usage](#usage)
-    - [Client](#client)
-      - [Basic Client Usage](#basic-client-usage)
-      - [Streaming Updates](#streaming-updates)
-      - [Authentication](#authentication)
-    - [Server](#server)
-      - [Implementing an A2A Agent](#implementing-an-a2a-agent)
-        - [AgentBuilder](#agentbuilder)
-        - [AgentEngine](#agentengine)
-      - [Event Handling/Monitoring \& Message Streaming](#event-handlingmonitoring--message-streaming)
-      - [Persistent Storage](#persistent-storage)
-      - [Advanced Server Customization](#advanced-server-customization)
-      - [Cross Protocol Support](#cross-protocol-support)
-  - [Contributing](#contributing)
-  - [License](#license)
-  - [Acknowledgements](#acknowledgements)
-
-**Breaking Changes since v0.5.8**
-
-- Pino has been removed and replaced with console for better portability and is set to silent by default.
-- The default handler for streamMessage no longer automatically emits an initial `submitted` and `working` event.
-- Agent Registration, Bundling and Deployment utils have been removed (email us: humans@artinet.io for support).
-- `@artinet/metadata-validator` has been removed due to build issues.
-- getTask now correctly takes TaskQueryParams as an argument vs TaskIdParams in accordance with the A2A spec.
-- AgentBuilder now returns a unique messageId for each status update instead of the original user provided messageId.
-- AgentBuilder now prefers the contextId & taskId from the calling context.
-- In a future release the following packages will be set as peer dependancies to reduce the size of the build: `@modelcontextprotocol/sdk`, `@trpc/server`, `cors`, `express`
-- The `history` object from `TaskAndHistory` is deprecated and no longer being updated. Use `Task.history` instead.
-- The `A2AClient` now checks `/.well-known/agent-card.json` as a opposed to `/.well-known/agent.json` in-line with the A2A spec.
-- The `A2AClient` now uses uses the `AgentCard`.url if an `AgentCard` has been successfully retrieved, else it will default to the `baseUrl`.
-- The examples folder will be removed in favor of [`create-agent`](https://github.com/the-artinet-project/create-agent).
-- In `Task` the `contextId` field is now required (inline with the A2A spec).
-- In `AgentSkill` the `tag` field is now required (inline with the A2A spec).
-- ~~Optional fields in Agent2Agent Zod schemas are now nullable for better interoperability.~~ **Nullable Schemas have been reverted.**
-- The `EngineBuilder` constructor is now protected and open for extension.
-- `AgentBuilder` will now throw an error if it recieves an invalid `FilePart`.
-- `createAgent`/`createService` can now take a single string (i.e. agentName) as valid value for the AgentCard and will populate the rest of the required fields with placeholder values (see `src/services/a2a/helpers/agentcard-builder.ts` for reference).
+It has [several template projects](https://github.com/the-artinet-project/create-agent/tree/main/templates) to jump right into agent building.
 
-## Installation
-
-```bash
-npm install @artinet/sdk
-```
-
-## Requirements
-
-- [Node.js](https://nodejs.org/en/download) ≥ 18.9.1
-  - Recommended: 20 || ≥ 22
-
-<!--
-
-## Documentation
-
-For more detailed documentation visit our documentation site [here](https://the-artinet-project.github.io/artinet-documentation/). -->
-
-## Example
-
-A basic A2A server and client interaction (For simple agents see the [AgentBuilder](#agentbuilder) section). For more detailed examples, see the `examples/` directory.
-
-**1. Server (`quick-server.ts`)**
+**Or use [`easy-a2a`](https://github.com/the-artinet-project/easy-a2a):**
 
 ```typescript
-import {
-  createAgentServer,
-  AgentBuilder,
-  Task
-} from "@artinet/sdk";
-
-// Create an agent server
-const { app, agent } = createAgentServer({
-  agent: AgentBuilder()
-  .text(async ({ content: userInput, context }) => {
-    const task: Task = context.State().task;
-    ...
-    return `You said: ${userInput}`;
-  })
+const agent = a2a({
+  baseURL: "https://your-api.com/api/v1",
+  apiKey: "your-api-key",
+})
+  .ai("You are a helpful assistant.")
   .createAgent({
-    agentCard: "QuickStart Agent",
-  }),
-  basePath: "/a2a"
-});
-
-app.listen(3000, () => {
-  console.log("A2A Server running at http://localhost:3000/a2a");
-});
-```
-
-**2. Client (`quick-client.ts`)**
-
-```typescript
-import { A2AClient, TaskStatusUpdateEvent } from "@artinet/sdk";
-
-async function runClient() {
-  const client = new A2AClient("http://localhost:3000/a2a");
-
-  const stream = client.sendStreamingMessage("Hello World!");
-
-  for await (const update of stream) {
-    // process the updates
-    ...
-  }
-  console.log("Stream finished.");
-}
-
-await runClient().catch(console.error);
+    agentCard: "MyAgent",
+  });
 ```
 
-## Running Tests
-
 ```bash
-npm test
+npm install easy-a2a
 ```
 
-## Usage
-
-### Client
-
-Interact with A2A-compliant agents using the `A2AClient`. See `examples/` for more.
-
-#### Basic Client Usage
-
-Send a message using `message/send`.
-
-```typescript
-import { A2AClient, Task } from "@artinet/sdk";
-
-const client = new A2AClient("https://your-a2a-server.com/a2a");
-
-const task: Task = await client.sendMessage("What is the capital of France?");
-```
-
-#### Streaming Updates
-
-Receive real-time updates via SSE using `message/stream`.
+## Installation
 
-```typescript
-import {
-  A2AClient,
-  Message,
-  TaskStatusUpdateEvent,
-  TaskArtifactUpdateEvent,
-} from "@artinet/sdk";
-
-async function runStreamingTask() {
-  const client = new A2AClient("https://your-a2a-server.com/a2a");
-
-  const stream = client.sendStreamingMessage("Tell me a short story.");
-
-  for await (const update of stream) {
-    if ((update as TaskStatusUpdateEvent).status) {
-      console.log("Status:", (update as TaskStatusUpdateEvent).status.state);
-    } else if ((update as TaskArtifactUpdateEvent).artifact) {
-      console.log(
-        "Artifact:",
-        (update as TaskArtifactUpdateEvent).artifact.name
-      );
-    }
-  }
-  console.log("Stream finished.");
-}
+```bash
+npm install @artinet/sdk
 ```
 
-#### Authentication
-
-Add headers using `addHeader` or `setHeaders`.
+**Peer dependencies (required):**
 
-```typescript
-import { A2AClient } from "@artinet/sdk";
-
-const client = new A2AClient("https://your-secure-a2a-server.com/a2a");
-
-// Add a single header
-client.addHeader("Authorization", "Bearer your-api-token");
-
-// Set multiple headers (overwrites existing)
-client.setHeaders({ Authorization: "Bearer ...", "X-Custom": "value" });
+```bash
+npm install @a2a-js/sdk @modelcontextprotocol/sdk
 ```
 
-### Server
-
-Use `createAgentServer()` to embed your Agents in an Express App.
-
-#### Implementing an A2A Agent
-
-The SDK provides a variety of options for creating complex ([AgentEngines](#agentengine)) or simple agents ([AgentBuilder](#agentbuilder)).
+## Requirements
 
-##### AgentBuilder
+- [Node.js](https://nodejs.org/en/download) ≥ 18.9.1 (Recommended: 20 or ≥ 22)
 
-**Option 1: Using the AgentBuilder (Recommended)**
+## Example
 
-For simple agents with one or more processing steps, use the `AgentBuilder` pattern:
+**Server:**
 
 ```typescript
 import { createAgentServer, AgentBuilder } from "@artinet/sdk";
 
-//create a simple agent
-const simpleAgent = AgentBuilder().text(() => "hello world!");
-
-//or design a powerful multi-step agent
-const { app, agent } = createAgentServer({
+const { app } = createAgentServer({
   agent: AgentBuilder()
-    .text(({ content, context }) => {
-      const userMessage = content ?? "no message detected";
-      return {
-        parts: [`Processing: ${userMessage}`], //parts are immediately sent back to the caller as TaskStatusUpdateEvents
-        args: [userMessage], //args are passed to the next step
-      };
-    })
-    .file(({ args }) => {
-      const processedText = args[0];
-      return {
-        parts: [
-          {
-            name: "result.txt",
-            mimeType: "text/plain",
-            bytes: `Processed result: ${processedText}`,
-          },
-        ],
-        args: ["file-generated"],
-      };
+    .text(async ({ content }) => {
+      return `You said: ${content}`;
     })
-    .text(({ args }) => {
-      const status = args[0];
-      return `Task completed. Status: ${status}`;
-    }) //A final Task is returned to the caller which contains all of the emitted parts.
     .createAgent({
-      agentCard: "Multi-Step Agent",
+      agentCard: "QuickStart Agent",
     }),
   basePath: "/a2a",
 });
 
 app.listen(3000, () => {
-  console.log("Multi-Step A2A Server running on http://localhost:3000/a2a");
-});
-```
-
-The `AgentBuilder` approach is particularly useful when you need:
-
-- **Step-by-step processing**: Break down complex tasks into discrete, manageable steps
-- **Data flow between steps**: Pass results from one step to the next using the `args` parameter
-- **Different content types**: Mix text, file, and data processing in a single flow
-- **Reusable components**: Build modular agents that can be easily edited or extended
-
-##### AgentEngine
-
-**Option 2: Direct AgentEngine Implementation**
-
-When you need full control over the execution flow, implement an `AgentEngine` directly:
-
-```typescript
-import {
-  createAgentServer,
-  Context,
-  AgentEngine,
-} from "@artinet/sdk";
-
-const myAgent: AgentEngine = async function* (context: Context) {
-  const task: TaskAndHistory = context.State();
-  yield {
-    state: "working",
-    message: {
-      ...
-      role: "agent",
-      parts: [{ kind: "text", text: "Processing..." }],
-    },
-    ...
-  };
-  yield {
-    ...
-    name: "result.txt",
-    mimeType: "text/plain",
-    parts: [{ kind: "text", text: "Report data" }],
-  };
-
-  yield {
-    ...
-    state: "completed",
-    message: {
-      kind: "message"
-      role: "agent",
-      parts: [{ kind: "text", text: "Finished processing." }],
-      ...
-    },
-  };
-};
-
-const { app, agent } = createAgentServer({
-  agent: {
-    engine: myAgent,
-    agentCard: {
-      name: "Example Agent",
-      url: "http://localhost:3000/a2a",
-      version: "1.0.0",
-      capabilities: { streaming: true },
-      skills: [{ id: "processor", name: "Text Processor" }],
-      ...
-    },
-  },
-  basePath: "/a2a",
-  agentCardPath: "/.well-known/agent-card.json",
-});
-```
-
-#### Event Handling/Monitoring & Message Streaming
-
-The SDK provides comprehensive event handling & message streaming capabilities that allow you to modify agent execution, subscribe to events, stream commands, and respond to state changes in real-time.
-
-**Override Event Behaviour**
-
-When using the service layer, you can provide your own Event Handlers:
-
-```typescript
-import { createAgent, TaskManager, ContextManager, Command, SendCommandInterface } from "@artinet/sdk";
-
-const customContextManager = new ContextManger();
-const agent = createAgent({
-  engine: (context: Context){
-    context.events.on("update", (currentState, nextState) => {
-      //allow other processes to subscribe to your agent
-    })
-    ...
-    //handle command streams directly within an agent
-    for await (const command of context.command) {
-      console.log("new command recieved: ", command);
-      //will continue polling until the command stream is closed by calling command.close();
-    }
-    //or process them via events
-    context.command.on("send", (command) => {
-      ...
-    });
-  },
-  agentCard: "Event-Monitored Agent",
-  contexts: customContextManager,
-  tasks: new TaskManager(),
-  eventOverrides: { //for even greater control create your own Event Handlers
-    onStart: async (context) => {
-      ...
-      return currentState;
-    },
-    onUpdate: async (currentState, nextState) => {
-      ...
-      return currentState;
-    },
-    ...
-  },
-});
-
-const resultPromise = agent.sendMessage({
-  contextId: "123"
-  ...
-});
-
-const currentContext = customContextManager.getContext("123");
-
-//subscribe to the events from a specific context
-currentContext.events.on("complete", () {
-  ...
-  //errors thrown here will be triggered in the original context
-});
-
-// Advanced: stream new commands into a running context
-(currentContext.command as SendCommandInterface<Command>).send({
-  ...
-});
-
-currentContext.command.close();
-```
-
-**Available Event Types**
-
-The EventManager supports the following event types:
-
-- **`OnStart`/`start`**: Fired when agent execution begins
-- **`OnUpdate`/`update`**: Fired on each state update during execution
-- **`OnError`/`error`**: Fired when an error occurs during execution
-- **`OnComplete`/`complete`**: Fired when agent execution completes successfully
-- **`OnCancel`/`cancel`**: Fired when agent execution is cancelled
-
-#### Persistent Storage
-
-For Task storage, use one our simple storage providers like `FileStore`. Or implement the `Store` interface to create your own.
-
-```typescript
-import path from "path";
-import fs from "fs";
-import { FileStore } from "@artinet/sdk";
-
-//make sure the directory exists
-const dataDir = path.join(process.cwd(), "a2a-data");
-if (!fs.existsSync(dataDir)) {
-  fs.mkdirSync(dataDir, { recursive: true });
-}
-
-const myStore = new FileStore(dataDir);
-
-const { app, agent } = createAgentServer({
-  agent: {
-    engine: myAgent,
-    agentCard: {
-      ...
-    },
-    tasks: myStore,
-  },
-  ...
-});
-```
-
-#### Advanced Server Customization
-
-Our architecture provides multiple ways to customize your agent server:
-
-**1. Using `createAgentServer`:**
-Easily spin up an A2A Express app `createAgentServer()`:
-
-```typescript
-const initialApp = express();
-
-// custom middleware
-initialApp.use((req, res, next) => {
-  ...
-  next();
-});
-
-const { app, agent } = createAgentServer({
-  app: initialApp
-  agent: {
-    ...
-  },
-});
-
-// more custom middleware
-app.use("/custom", (req, res, next) => {
-  ...
-});
-
-```
-
-**2. Using our JSON-RPC Middleware:**
-Directly import our preconfigured JSON-RPC middleware:
-
-```typescript
-import express from "express";
-import { createAgent, jsonRPCMiddleware, errorHandler } from "@artinet/sdk";
-
-const customApp = express();
-
-const agent = createAgent({
-  engine: myAgentLogic,
-  agentCard: {
-    ...
-  },
-});
-
-customApp.use("/auth", yourAuthMiddleware);
-customApp.use("/metrics", yourMetricsMiddleware);
-customApp.use(express.json());
-
-// Add A2A middleware
-customApp.post("/", async (req, res, next) => {
-  return await jsonRPCMiddleware(agent, req, res, next);
-});
-// Dont forget to add error handling*
-customApp.use(errorHandler);
-
-// Serve the agent card
-customApp.get("/.well-known/agent-card.json", (req, res) => {
-  res.json(agent.agentCard);
-});
-
-// Start your custom server
-const server = customApp.listen(3000, () => {
-  console.log("Custom A2A server running on port 3000");
+  console.log("A2A Server running at http://localhost:3000/a2a");
 });
 ```
 
-**3. Using Custom Transport Layers:**
-
-Use our preconfigured TRPC router, or create your own integration with WebSockets & other protocols:
-
-```typescript
-import { createAgentRouter } from "@artinet/sdk";
-
-const agentRouter = createAgentRouter();
-```
-
-**Use the Agent:**
-
-Directly invoke the agent to use it locally:
+**Client:**
 
 ```typescript
-import { createAgent } from "@artinet/sdk";
-
-const agent = createAgent({
-  engine: myAgentLogic,
-  agentCard: {
-    ...
-  },
-});
+import { A2AClient } from "@artinet/sdk";
 
-// Wrap these calls in your desired transport logic
-const result = await agent.sendMessage({
-  ...
-});
+const client = new A2AClient("http://localhost:3000/a2a");
 
-// Directly process streams
-const stream = agent.streamMessage({
-  ...
-});
+const stream = client.sendStreamingMessage("Hello World!");
 
 for await (const update of stream) {
-  ...
+  console.log(update);
 }
 ```
 
-**Important:** When using custom implementations, ensure you handle:
-
-- Server-Sent Events (SSE) for `message/stream` and `tasks/resubscribe`
-- Agent card endpoints at `/.well-known/agent-card.json`
-- Proper error handling and JSON-RPC compliance
-- CORS headers if needed for web clients
-
-#### Cross Protocol Support
-
-**MCP (Model Context Protocol) Integration**
-
-The SDK provides a Model Context Protocol (MCP) <-> A2A compatability layer.
-
-Use `createMCPAgent` to expose your agent via MCP:
-
-```typescript
-import { createMCPAgent, createAgent } from "@artinet/sdk";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-
-// Wrap your agent in an MCP Server
-const mcpAgent = createMCPAgent({
-  serverInfo: {
-    name: "My MCP Agent",
-    version: "1.0.0",
-  },
-  options: {
-    ...
-  },
-  agent: createAgent({
-    engine: myAgentEngine,
-    agentCard: "MCP Agent",
-  }),
-  agentCardUri: "agent://card", //customize the URI for your AgentCard
-});
-
-// The MCPAgent is a fully compliant MCP Server so you can use it as you normally would.
-mcpAgent.registerTool({
-  ...
-});
+## Documentation
 
-await mcpAgent.connect(new StdioServerTransport());
-```
+| 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                       |
 
-Use an MCP Client to interact with an mcpAgent:
+## Running Tests
 
-```typescript
-...
-// Access the AgentCard as a Resource
-const agentCard = await client.readResource({ uri: "agent://card" });
-
-// or send messages via Tool Calling
-const result = await client.callTool({
-  name: "send-message",
-  arguments: {
-    ...
-    message: {
-      ...
-      parts: [{ kind: "text", text: "Hello from MCP!" }],
-    },
-  },
-});
+```bash
+npm test
 ```
 
-**MCP Tools & Resources:**
-
-- `send-message`: Send messages to the A2A agent
-- `get-task`: Retrieve tasks by ID
-- `cancel-task`: Cancel a running task
-- `agent://card`: Retrieve the AgentCard
-- `send-streaming-message`, `task-resubscribe` & `push-notifications` etc are currently not supported by default.
-- Leverage the A2A Zod Schemas to manually implement your own tools.
-
 ## Contributing
 
 Contributions are welcome! Please open an issue or submit a Pull Request on [GitHub](https://github.com/the-artinet-project/artinet-sdk).

package/dist/browser/browser.d.ts

@@ -0,0 +1,9 @@
+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 "./config/index.js";
+export { A2AClient } from "./client/a2a-client.js";

package/dist/browser/browser.js

@@ -0,0 +1,10 @@
+//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 "./config/index.js";
+export { A2AClient } from "./client/a2a-client.js";