{"_id":"@a2alite/sdk","_rev":"5-cfd6e987606a0e8b3e3bd372af47732b","name":"@a2alite/sdk","dist-tags":{"latest":"0.0.5"},"versions":{"0.0.1":{"name":"@a2alite/sdk","version":"0.0.1","keywords":["A2A","AI","Agents","LLM","Agent to Agent"],"author":{"name":"Hamid Alipour"},"license":"Apache-2.0","_id":"@a2alite/sdk@0.0.1","maintainers":[{"name":"hamidra","email":"hamid.alipour@gmail.com"}],"dist":{"shasum":"48a8bcb08cb50549bc9b835ea4410317e2fea83a","tarball":"https://registry.npmjs.org/@a2alite/sdk/-/sdk-0.0.1.tgz","fileCount":85,"integrity":"sha512-28kwC97rLWsqyjJcnMTfY8o7aAm+JRZ+eT3JZFaKFqYzkNbq10y2wxXwSbstEwcU+00NAp2fL+hFQFlhGxfkVQ==","signatures":[{"sig":"MEYCIQDlOJeT+sxtS9Yrt6n31xGIqzaDu1xBMQM+CtsTqXNwbAIhAM9iWwNMOcHyzLhGXQ8oYWNkPmcXsfgjrbVNGNfFk1U6","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":541935},"type":"module","_from":"file:a2alite-sdk-0.0.1.tgz","types":"dist/index.d.ts","exports":{"./*":{"import":"./dist/esm/*","require":"./dist/cjs/*"}},"scripts":{"build":"pnpm run clean && pnpm run build:esm && pnpm run build:cjs","clean":"rimraf dist","build:cjs":"tsc --project tsconfig.cjs.json","build:esm":"tsc --project tsconfig.esm.json"},"_npmUser":{"name":"hamidra","actor":{"name":"hamidra","type":"user","email":"hamid.alipour@gmail.com"},"email":"hamid.alipour@gmail.com"},"_resolved":"/private/var/folders/c9/mbk_yy_51xzfhcgzkg4h7v5m0000gn/T/917937ecfe486f194a2226ffdd363527/a2alite-sdk-0.0.1.tgz","_integrity":"sha512-28kwC97rLWsqyjJcnMTfY8o7aAm+JRZ+eT3JZFaKFqYzkNbq10y2wxXwSbstEwcU+00NAp2fL+hFQFlhGxfkVQ==","_npmVersion":"11.3.0","description":"A Modular SDK (Server & Client) for Agent to Agent (A2A) protocol, with easy task lifecycle management","directories":{},"_nodeVersion":"22.13.0","dependencies":{"zod":"^3.25.30","hono":"^4.7.11","uuid":"^11.1.0","@hono/node-server":"^1.14.4"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^5.0.5","typescript":"^5.8.3"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.0.1_1751251115187_0.7309143449136564","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@a2alite/sdk","version":"0.0.2","keywords":["A2A","AI","Agents","LLM","Agent to Agent"],"author":{"name":"Hamid Alipour"},"license":"Apache-2.0","_id":"@a2alite/sdk@0.0.2","maintainers":[{"name":"hamidra","email":"hamid.alipour@gmail.com"}],"dist":{"shasum":"9120587fe7382b984ae075e666e6bf1ffcd945e7","tarball":"https://registry.npmjs.org/@a2alite/sdk/-/sdk-0.0.2.tgz","fileCount":85,"integrity":"sha512-x5lDnWIv/sH66E0DNvIa5RAxhkYiSrqAdusYoYtxKuB1AumwX3iNPZpLDjAIvs+RFF3tsFGpvNEmXivgxWc4Kg==","signatures":[{"sig":"MEUCIEI6gitqb+JroTmQj3sgjOJuJeAOsfJXnbo7y3eAKXTVAiEAmPqSbdHHoPwVVdL1ciM0S/D6ryAfPplqea7cFFllLlA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":541935},"type":"module","_from":"file:a2alite-sdk-0.0.2.tgz","types":"dist/index.d.ts","exports":{"./*":{"import":"./dist/esm/*","require":"./dist/cjs/*"}},"scripts":{"build":"pnpm run clean && pnpm run build:esm && pnpm run build:cjs","clean":"rimraf dist","build:cjs":"tsc --project tsconfig.cjs.json","build:esm":"tsc --project tsconfig.esm.json"},"_npmUser":{"name":"hamidra","actor":{"name":"hamidra","type":"user","email":"hamid.alipour@gmail.com"},"email":"hamid.alipour@gmail.com"},"_resolved":"/private/var/folders/c9/mbk_yy_51xzfhcgzkg4h7v5m0000gn/T/1c20b83779cdd01af9ab10c9bd74f537/a2alite-sdk-0.0.2.tgz","_integrity":"sha512-x5lDnWIv/sH66E0DNvIa5RAxhkYiSrqAdusYoYtxKuB1AumwX3iNPZpLDjAIvs+RFF3tsFGpvNEmXivgxWc4Kg==","_npmVersion":"11.3.0","description":"A Modular SDK (Server & Client) for Agent to Agent (A2A) protocol, with easy task lifecycle management","directories":{},"_nodeVersion":"22.13.0","dependencies":{"zod":"^3.25.30","hono":"^4.7.11","uuid":"^11.1.0","@hono/node-server":"^1.14.4"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^5.0.5","typescript":"^5.8.3"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.0.2_1751251378290_0.6826170200433579","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@a2alite/sdk","version":"0.0.3","keywords":["A2A","AI","Agents","LLM","Agent to Agent"],"author":{"name":"Hamid Alipour"},"license":"Apache-2.0","_id":"@a2alite/sdk@0.0.3","maintainers":[{"name":"hamidra","email":"hamid.alipour@gmail.com"}],"dist":{"shasum":"c951debfd8266fd39ef1e721cebda30b5dceb5c6","tarball":"https://registry.npmjs.org/@a2alite/sdk/-/sdk-0.0.3.tgz","fileCount":97,"integrity":"sha512-BIawiD8gtk7cgwraIy3iBJG2hbN8Ry5pw0Jcxi6760BsgKR4VnmTIoBoqrRUebLnTrJoanBcrwN9u7KKu3bDqQ==","signatures":[{"sig":"MEUCIQCh4JMN7nBVglcyoTLjFJpC9CzFa412qUin215rcFWiRgIgVEAVW1SMy6cqyeBsdCAzm9vOLllsKZD81vwGjSdoLb8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":551513},"type":"module","_from":"file:a2alite-sdk-0.0.3.tgz","types":"dist/index.d.ts","exports":{"./types":{"import":"./dist/esm/types/types.js","require":"./dist/cjs/types/types.js"},"./utils":{"import":"./dist/esm/utils/index.js","require":"./dist/cjs/utils/index.js"},"./client":{"import":"./dist/esm/client/index.js","require":"./dist/cjs/client/index.js"},"./server":{"import":"./dist/esm/server/index.js","require":"./dist/cjs/server/index.js"}},"scripts":{"build":"pnpm run clean && pnpm run build:esm && pnpm run build:cjs","clean":"rimraf dist","build:cjs":"tsc --project tsconfig.cjs.json","build:esm":"tsc --project tsconfig.esm.json"},"_npmUser":{"name":"hamidra","actor":{"name":"hamidra","type":"user","email":"hamid.alipour@gmail.com"},"email":"hamid.alipour@gmail.com"},"_resolved":"/private/var/folders/c9/mbk_yy_51xzfhcgzkg4h7v5m0000gn/T/a3ce0427aece6ef399a21ba8211dc3d6/a2alite-sdk-0.0.3.tgz","_integrity":"sha512-BIawiD8gtk7cgwraIy3iBJG2hbN8Ry5pw0Jcxi6760BsgKR4VnmTIoBoqrRUebLnTrJoanBcrwN9u7KKu3bDqQ==","_npmVersion":"11.3.0","description":"A Modular SDK (Server & Client) for Agent to Agent (A2A) protocol, with easy task lifecycle management","directories":{},"_nodeVersion":"22.13.0","dependencies":{"zod":"^3.25.30","hono":"^4.7.11","uuid":"^11.1.0","@hono/node-server":"^1.14.4"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^5.0.5","typescript":"^5.8.3"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.0.3_1751572426528_0.5595081449366845","host":"s3://npm-registry-packages-npm-production"}},"0.0.4":{"name":"@a2alite/sdk","version":"0.0.4","keywords":["A2A","AI","Agents","LLM","Agent to Agent"],"author":{"name":"Hamid Alipour"},"license":"Apache-2.0","_id":"@a2alite/sdk@0.0.4","maintainers":[{"name":"hamidra","email":"hamid.alipour@gmail.com"}],"dist":{"shasum":"95dd472367502a4649e6ae84ae37e29b4a79aefb","tarball":"https://registry.npmjs.org/@a2alite/sdk/-/sdk-0.0.4.tgz","fileCount":97,"integrity":"sha512-FKrd5WE7/j/lZRIf58FpPNDR9a25QxI+p5WjxAxfvwtSClT/07Mvu/GPaDgfyZ43rYCuY4JviMumalpT+HF9qw==","signatures":[{"sig":"MEQCICjBLGPM/oLdflmJNkOVEr0JiApdm5reyAHX0qiaTnOEAiApCaj/EkAV4hBRvW1+VarOTAtmO4t2nCtjUgjXKvyVww==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":551513},"type":"module","_from":"file:a2alite-sdk-0.0.4.tgz","types":"dist/index.d.ts","exports":{"./types":{"import":"./dist/esm/types/types.js","require":"./dist/cjs/types/types.js"},"./utils":{"import":"./dist/esm/utils/index.js","require":"./dist/cjs/utils/index.js"},"./client":{"import":"./dist/esm/client/index.js","require":"./dist/cjs/client/index.js"},"./server":{"import":"./dist/esm/server/index.js","require":"./dist/cjs/server/index.js"}},"scripts":{"build":"pnpm run clean && pnpm run build:esm && pnpm run build:cjs","clean":"rimraf dist","build:cjs":"tsc --project tsconfig.cjs.json","build:esm":"tsc --project tsconfig.esm.json"},"_npmUser":{"name":"hamidra","actor":{"name":"hamidra","type":"user","email":"hamid.alipour@gmail.com"},"email":"hamid.alipour@gmail.com"},"_resolved":"/private/var/folders/c9/mbk_yy_51xzfhcgzkg4h7v5m0000gn/T/0ecf5c21578d7a97b5e2b981a979ec4e/a2alite-sdk-0.0.4.tgz","_integrity":"sha512-FKrd5WE7/j/lZRIf58FpPNDR9a25QxI+p5WjxAxfvwtSClT/07Mvu/GPaDgfyZ43rYCuY4JviMumalpT+HF9qw==","_npmVersion":"11.3.0","description":"A Modular SDK (Server & Client) for Agent to Agent (A2A) protocol, with easy task lifecycle management","directories":{},"_nodeVersion":"22.13.0","dependencies":{"zod":"^3.25.30","hono":"^4.7.11","uuid":"^11.1.0","@hono/node-server":"^1.14.4"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^5.0.5","typescript":"^5.8.3"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.0.4_1751572856067_0.29159863167545197","host":"s3://npm-registry-packages-npm-production"}},"0.0.5":{"name":"@a2alite/sdk","version":"0.0.5","description":"A Modular SDK (Server & Client) for Agent to Agent (A2A) protocol, with easy task lifecycle management","repository":{"type":"git","url":"git+https://github.com/hamidra/a2alite.git","directory":"packages/sdk"},"bugs":{"url":"https://github.com/hamidra/a2alite/issues"},"homepage":"https://github.com/hamidra/a2alite","keywords":["A2A","AI","Agents","LLM","Agent to Agent"],"license":"Apache-2.0","author":{"name":"Hamid Alipour"},"type":"module","exports":{"./server":{"types":"./dist/esm/server/index.d.ts","import":"./dist/esm/server/index.js","require":"./dist/cjs/server/index.js"},"./client":{"types":"./dist/esm/client/index.d.ts","import":"./dist/esm/client/index.js","require":"./dist/cjs/client/index.js"},"./utils":{"types":"./dist/esm/utils/index.d.ts","import":"./dist/esm/utils/index.js","require":"./dist/cjs/utils/index.js"},"./types":{"types":"./dist/esm/types/types.d.ts","import":"./dist/esm/types/types.js","require":"./dist/cjs/types/types.js"}},"devDependencies":{"rimraf":"^5.0.5","typescript":"^5.8.3"},"dependencies":{"@hono/node-server":"^1.14.4","hono":"^4.7.11","uuid":"^11.1.0","zod":"^3.25.30"},"scripts":{"build":"pnpm run clean && pnpm run build:esm && pnpm run build:cjs","build:esm":"tsc --project tsconfig.esm.json","build:cjs":"tsc --project tsconfig.cjs.json","clean":"rimraf dist"},"_id":"@a2alite/sdk@0.0.5","_integrity":"sha512-8TZXf6ig7wbt51muZxTiSV2uxjZ5oXH4t4nTSpeQSQl15vRR8i5CSi0a6f4mqfXEsclsc58FZDYWLvaO7leZZA==","_resolved":"/private/var/folders/c9/mbk_yy_51xzfhcgzkg4h7v5m0000gn/T/d30e72182495265988ff51dab48ce5bf/a2alite-sdk-0.0.5.tgz","_from":"file:a2alite-sdk-0.0.5.tgz","_nodeVersion":"22.13.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-8TZXf6ig7wbt51muZxTiSV2uxjZ5oXH4t4nTSpeQSQl15vRR8i5CSi0a6f4mqfXEsclsc58FZDYWLvaO7leZZA==","shasum":"5ede9740b25c6b2d8fe6fcc29353e1e266edbd68","tarball":"https://registry.npmjs.org/@a2alite/sdk/-/sdk-0.0.5.tgz","fileCount":102,"unpackedSize":614496,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDBiFlB2obYVm9bF0tz0IPoetLuKEO/uQKsb30nFZDUFAIgA91CR39eCX3LL6MxI1rXN/2EBmGbQg/usMKUqauOQs4="}]},"_npmUser":{"name":"hamidra","email":"hamid.alipour@gmail.com","actor":{"name":"hamidra","email":"hamid.alipour@gmail.com","type":"user"}},"directories":{},"maintainers":[{"name":"hamidra","email":"hamid.alipour@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.0.5_1752169291292_0.6846100546719971"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-30T02:38:35.095Z","modified":"2025-07-10T17:41:31.668Z","0.0.1":"2025-06-30T02:38:35.377Z","0.0.2":"2025-06-30T02:42:58.466Z","0.0.3":"2025-07-03T19:53:46.766Z","0.0.4":"2025-07-03T20:00:56.255Z","0.0.5":"2025-07-10T17:41:31.465Z"},"author":{"name":"Hamid Alipour"},"license":"Apache-2.0","keywords":["A2A","AI","Agents","LLM","Agent to Agent"],"description":"A Modular SDK (Server & Client) for Agent to Agent (A2A) protocol, with easy task lifecycle management","maintainers":[{"name":"hamidra","email":"hamid.alipour@gmail.com"}],"readme":"# 🤖 A2A SDK Developer Guide\n\n**A2ALite** is a lightweight, modular SDK designed to make building **A2A-compliant servers** as simple as building HTTP servers. Inspired by familiar patterns from frameworks like Hono and Express, it offers a minimal, intuitive interface for rapid development.\n\nA2ALite handles the complexity of messaging, streaming, context and task management, and the JSON-RPC protocol, so you can focus entirely on your **agent’s execution logic**. It provides high-level primitives for managing A2A requests and responses, background tasks, and streaming data with ease.\n\nFor comprehensive examples of how to implement an A2A-compliant server, explore the [examples](examples) directory.\n\n## Installation\n\n```bash\n// using npm\nnpm install @a2alite/sdk\n\n// using pnpm\npnpm add @a2alite/sdk\n```\n\n## Key Features and Benefits\n\n- Simplest way to build A2A-compliant servers.\n- Minimal interface, abstracting away A2A protocol complexity.\n- Modular, allowing you to easily swap out implementations of components.\n\n## What Needs to Be Implemented\n\nThe only thing that needs to be implemented ro enable an agent to process A2A requests is the `IAgentExecutor` interface:\n\n```ts\nimport { taskNotCancelableError } from \"@a2a/sdk/utils/errors\";\nimport {\n  MessageHandler,\n  ArtifactHandler,\n  createTextPart,\n} from \"@a2a/sdk/utils\";\n\ninterface IAgentExecutor {\n  execute(context: AgentExecutionContext): Promise<AgentExecutionResult>;\n  cancel(task: Task): Promise<Task | JSONRPCError>;\n}\n\nclass MyAgentExecutor implements IAgentExecutor {\n  execute(context: AgentExecutionContext): Promise<AgentExecutionResult> {\n    // Read the input text message from the request\n    const messageText = MessageHandler(\n      context.request.params.message\n    ).getText();\n    const echoCount = 5;\n\n    // return an stream to stream the response\n    return context.stream(async (stream) => {\n      for (let i = 0; i < echoCount; i++) {\n        await stream.writeArtifact({\n          artifact: ArtifactHandler.fromText(\n            `echo ${i}: ${messageText}`\n          ).getArtifact(),\n        });\n      }\n      // complete the task\n      await stream.complete();\n    });\n  }\n\n  cancel(task: Task): Promise<Task | JSONRPCError> {\n    return taskNotCancelableError(\"Task is not cancelable\");\n  }\n}\n```\n\nYour implementation gets invoked automatically by the SDK when a message is received.\n\n## Start the A2A server\n\n```ts\nimport { A2AServer, createHonoApp } from \"@a2a/sdk/server\";\nimport { serve } from \"@hono/node-server\";\n\n// your implementation of IAgentExecutor\nimport { MyAgentExecutor } from \"./myAgent.ts\";\n\nconst server = new A2AServer({\n  agentExecutor: new MyAgentExecutor(),\n  agentCard: {\n    name: \"My Agent\",\n    description: \"A helpful AI assistant that can summarize documents\",\n    version: \"1.0.0\",\n    url: \"http://localhost:3000/a2a\",\n    skills: [\n      {\n        id: \"doc_summarize\",\n        name: \"document summarization\",\n        description: \"Summarize a document\",\n      },\n    ],\n    defaultInputModes: [\"text/plain\"],\n    defaultOutputModes: [\"text/plain\"],\n  },\n});\n\nconst app = await createHonoApp({ a2aServer: server });\n\nserve(app);\n```\n\n---\n\n## Core Concepts\n\nUnderstanding these four key concepts is essential for building A2A-compatible agents using A2ALite:\n\n### **A2AServer** - Main server orchestrator\n\nThe `A2AServer` is the central component that orchestrates all A2A protocol operations:\n\n```ts\nconst server = new A2AServer({\n  agentExecutor: new MyAgent(), // Your agent logic\n  agentCard: {\n    /* metadata */\n  }, // Agent capabilities\n  taskStoreFactory, // Optional factory method to create a custom storage\n  queueFactory, // Optional factory method to create a custom queuing used by streams\n});\n```\n\n**Key responsibilities:**\n\n- Handles JSON-RPC protocol communication\n- Manages task lifecycle and state transitions\n- Provides agent discovery endpoint (`/.well-known/agent.json`)\n- Coordinates streaming and real-time updates\n\n### **IAgentExecutor** - Your agent implementation\n\nThis is the only interface you need to implement. Your agent logic goes here:\n\n```ts\ninterface IAgentExecutor {\n  execute(context: AgentExecutionContext): Promise<AgentExecutionResult>;\n  cancel(task: Task): Promise<Task | JSONRPCError>;\n}\n```\n\n**The `execute()` method can return:**\n\n- **Message** - Immediate replies (`context.message()`)\n- **Task** - Operations with final or pending results (`context.complete(), context.reject(), context.authRequired(), context.inputRequired()`)\n- **Stream** - Long-running operations that stream results and artifacts (`context.stream()`)\n- **Error** - possible A2A errors during execution (e.g. `invalidAgentResponseError()`)\n\n### **AgentExecutionContext** - Provided Execution Environment\n\nThe `AgentExecutionContext` provides all necessary tools for processing requests and managing responses. It includes methods to create different types of responses, automatically handling the association of context and task IDs. This means you don't need to manually track these IDs, they're automatically handled based on the current context and task when using the context's response methods:\n\n```ts\nasync execute(context: AgentExecutionContext) {\n  // Access request data\n  const userMessage = context.request.params.message;\n  const currentTask = context.currentTask;  // Continuing a task?\n\n  // process and generate the result artifact\n  // ...\n\n  // Create different response types\n  return context.complete({\n    artifacts: [...resultArtifacts]\n  });\n}\n```\n\n**Available response methods:**\n\n- [`context.message()`](packages/sdk/src/server/agent/context.ts#L274) - return an immediate message response\n- [`context.complete()`](packages/sdk/src/server/agent/context.ts#L262) - return a completed task with results\n- [`context.reject()`](packages/sdk/src/server/agent/context.ts#L226) - return a rejected task\n- [`context.authRequired()`](packages/sdk/src/server/agent/context.ts#L238) - return a task requiring authentication\n- [`context.inputRequired()`](packages/sdk/src/server/agent/context.ts#L250) - return a task requiring additional input\n- [`context.stream()`](packages/sdk/src/server/agent/context.ts#L206) - return a streaming task allowing for incremental updates (e.g. progress updates, artifacts)\n\n### **AgentTaskStream** - Real-time streaming\n\nFor long-running operations, use streaming to provide real-time updates to the client, this is decoupled from how the client receives the updates. If the client has initiated the request as streaming, the updates will be streamed to the client as they are generated. If the client has not initiated the request as streaming, the updates will get aggregated in taskStore allowing the client to either resubscribe to the task or poll for updates.\n\n```ts\nreturn context.stream(async (stream) => {\n  // Optional: Set initial state to working,\n  await stream.start({\n    message: { parts: [createTextPart(\"Processing...\")] },\n  });\n\n  // Stream progress updates and artifacts as they are generated ...\n  await stream.writeArtifact({\n    artifact: ArtifactHandler.fromText(\n      \"some generated artifact ...\"\n    ).getArtifact(),\n  });\n\n  // check if more input is required\n  if (moreInputRequired) {\n    // Ask for more input\n    await stream.inputRequired({\n      message: { parts: [createTextPart(\"Please provide more input.\")] },\n    });\n  } else {\n    // Finalize the stream as the task is completed\n    await stream.complete({\n      message: { parts: [createTextPart(\"Complete!\")] },\n      artifacts: [finalResults],\n    });\n  }\n});\n```\n\n**Stream capabilities:**\n\n- Stream artifact updates with `writeArtifact()`\n- Handle task state transitions (working → completed/failed/canceled/rejected/input-required/auth-required)\n- Automated task lifecycle management with real-time streaming of status updates to clients on state changes.\n- Flexible response handling: Clients can choose between streaming responses or polling for updates, regardless of if the agent returns or streams results.\n\n---\n\n## Implementing `execute()`\n\nThe `execute(context)` method is called when a new message is received.\nUse the `context.stream(callback)` to emit streaming task updates. the callback function is passed an `AgentTaskStream` instance that can be used to stream progress updates and artifacts as they are generated.\n\n---\n\n## `AgentExecutionContext` Cheatsheet\n\n```ts\n// access the request context\ncontext.request; // Incoming AgentRequest\ncontext.currentTask; // Possible existing task in this context\ncontext.referenceTasks; // Possible referenced tasks in this context\n\n// generate execution result to return as response\ncontext.complete(params); // Mark task as complete\ncontext.reject(params); // Mark task as rejected\ncontext.authRequired(params); // Request user auth\ncontext.inputRequired(params); // Request user input\n\n// generate the result as a task stream to stream artifacts as they are generated\ncontext.stream(callback); // Begin a task stream\n```\n\n---\n\n## Streaming with `AgentTaskStream`\n\nInside your stream callback, use the stream to emit task events or stream artifacts as they are generated:\n\n```ts\nawait stream.writeArtifact(...);   // Send one or more artifacts\nawait stream.complete(...);        // Mark the task as complete\n```\n\nif any input is required, use `stream.inputRequired(params)` to request input.\n\n```ts\nawait stream.inputRequired({\n  message: { parts: [createTextPart(\"Please provide input.\")] },\n});\n```\n\nsimilarly if authentication is required, use `stream.authRequired(params)` to request authentication.\n\n```ts\nawait stream.authRequired({\n  message: { parts: [createTextPart(\"Please provide authentication.\")] },\n});\n```\n\nThe SDK handles:\n\n- Finalizing the stream\n- Aborting if needed\n- Managing subscribers\n- Updating the task status in the task store\n- Keeping the Task, Message, Artifacts context and task id's consistent with the current task and context\n\n---\n\n## Recommended Utilities\n\nUse these helpers to avoid manual object construction.\n\n### Parts\n\nUse [`createTextPart`](packages/sdk/src/utils/part.ts#L12), [`createFilePart`](packages/sdk/src/utils/part.ts#L26), and [`createDataPart`](packages/sdk/src/utils/part.ts#L52) to create parts for messages and artifacts.\n\n```ts\ncreateTextPart(\"Hello\");\ncreateFilePart({ name: \"report.pdf\", uri: \"...\" });\ncreateDataPart({ name: \"John Doe\", age: 42 });\n```\n\n### MessageHandler\n\nUse [`MessageHandler`](packages/sdk/src/utils/message.ts#L17) to create messages or parse message parts.\n\n```ts\n// create message\nconst message = new MessageHandler()\n  .withRole(\"agent\")\n  .addTextPart(\"Hi there\")\n  .addFilePart({ name: \"report.pdf\", uri: \"...\" })\n  .addDataPart({ name: \"John Doe\", age: 42 })\n  .getMessage();\n\n// parse message parts\nconst text = new MessageHandler(message).getText();\nconst files = new MessageHandler(message).getFiles();\nconst data = new MessageHandler(message).getData();\n```\n\n### ArtifactHandler\n\nUse [`ArtifactHandler`](packages/sdk/src/utils/artifact.ts#L13) to create artifacts or parse artifact parts.\n\n```ts\n// create artifact\nconst artifact = ArtifactHandler.fromText(\"Hello\")\n  .addFilePart({ name: \"report.pdf\", uri: \"...\" })\n  .addDataPart({ name: \"John Doe\", age: 42 })\n  .getArtifact();\n\n// parse artifact parts\nconst text = new ArtifactHandler(artifact).getText();\nconst files = new ArtifactHandler(artifact).getFiles();\nconst data = new ArtifactHandler(artifact).getData();\n```\n\n### TaskHandler (for advanced logic)\n\nUse [`TaskHandler`](packages/sdk/src/utils/task.ts#L13) to create tasks.\n\n```ts\nnew TaskHandler().withStatus({ state: \"working\", ... })\n```\n\n### Error Builders\n\nUse [error builders](packages/sdk/src/utils/errors.ts) to create A2A errors.\n\n```ts\nimport { taskNotFoundError } from \"@a2a/sdk/utils\";\n\nreturn taskNotFoundError(\"No such task\");\n```\n\n---\n\n## Testing Tips\n\n- Use `/a2a` endpoint to POST A2A messages (JSON-RPC).\n- Use the `.well-known/agent.json` endpoint to advertise the agent card.\n- If streaming, use SSE or re-subscribe via `tasks/resubscribe`.\n\n## Acknowledgments\n\n- [A2A Specification](https://google.github.io/A2A/specification/)\n- Inspired by various http server frameworks and communication protocols (express, hono)\n","readmeFilename":"README.md","homepage":"https://github.com/hamidra/a2alite","repository":{"type":"git","url":"git+https://github.com/hamidra/a2alite.git","directory":"packages/sdk"},"bugs":{"url":"https://github.com/hamidra/a2alite/issues"}}