docs(sdk): add docs for client SDK #1867

PetrBulanek · 2026-01-21T15:27:26Z

Summary

Rewrote the Client SDK overview to match current SDK entrypoints and workflows.
Added new guides for A2A integration, error handling, message building, and message part rendering.
Expanded extensions and client API docs.

Notes:

Changes are limited to development docs. No stable mirror included yet.

Linked Issues

Closes: #1835

Documentation

No Docs Needed:

If this PR adds new feature or changes existing. Make sure documentation is adjusted accordingly. If the docs is not needed, please explain why.

Signed-off-by: Petr Bulánek <[email protected]>

gemini-code-assist · 2026-01-21T15:27:51Z

Summary of Changes

Hello @PetrBulanek, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly updates and expands the documentation for the AgentStack Client SDK. The primary goal is to provide developers with clearer, more detailed guidance on integrating the SDK, particularly concerning the Agent-to-Agent (A2A) protocol, managing extensions, handling API responses and errors, and constructing messages. The changes aim to streamline the developer experience by offering practical examples and structured explanations of core workflows.

Highlights

Client SDK Overview Rewrite: The Client SDK overview has been rewritten to align with current SDK entrypoints and workflows, providing a clearer architectural understanding.
New Comprehensive Guides: New detailed guides have been added covering A2A integration, robust error handling, structured message building, and effective message part rendering.
Expanded Documentation for Extensions and API: The documentation for extensions and the client API has been significantly expanded and clarified, including new sections on response handling and error patterns.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

The pull request significantly enhances the client SDK documentation by providing a more structured overview, detailed guides for A2A integration, error handling, message building, and message part rendering. The new sections on core APIs, extensions, and error helpers are very valuable. However, many of the code examples within the documentation are not self-contained, as they rely on undeclared variables or types. For a better user experience, especially in quickstart and example sections, these snippets should be runnable independently or clearly indicate where the missing variables/types originate.

docs/development/custom-ui/user-messages.mdx

docs/development/custom-ui/agent-requirements.mdx

apps/agentstack-sdk-ts/README.md

docs/development/custom-ui/getting-started.mdx

docs/development/custom-ui/platform-api-client.mdx

apps/agentstack-sdk-ts/README.md

tomkis

Overall good progress, lets fix some naunces.

tomkis · 2026-01-26T07:20:49Z

docs/development/custom-ui/getting-started.mdx

  }
 }
 ```

-### Agent Stack API Client
+### 3. Build user metadata


I'd add <tip> with more explaination of the concept of "User metadata"

(tip for power users)

tomkis · 2026-01-26T07:22:48Z

docs/development/custom-ui/getting-started.mdx


-The SDK provides `handleTaskStatusUpdate` to parse A2A `TaskStatusUpdate` and extract structured information:
+When you stream A2A task events, `handleTaskStatusUpdate` maps status updates into actionable UI events.


We need to cover more thoroughly are opinion on chat interface and streaming.

Eg. why task, why status update, why TaskStatusUpdate actually is used for each token streaming.

(should be a tip for power users)

tomkis · 2026-01-26T07:24:06Z

docs/development/custom-ui/getting-started.mdx


- **Service extensions** (LLM, embeddings, MCP, OAuth, secrets): Agent asks for a demand and it is client's responsibility to fulfill the demand. Think of a Dependency Injection where the client is injecting the dependency.
- **UI extensions** (forms, citations, trajectory visualization): Extends basic A2A messaging with a structure that simplifies working with GUIs.
+### 1. Handle agent card demands


I'd start with construction of the A2A clientsdk.

tomkis · 2026-01-26T07:25:32Z

docs/development/custom-ui/getting-started.mdx

+
+All API calls return `ApiResult<T>`. Use `unwrapResult` if you want exceptions, and then handle errors with `isHttpError`, `isNetworkError`, `isParseError`, and `isValidationError`.
+
+## Extension Helpers at a Glance


I'd omit this section from here. It makes this unnecessarily complex.

tomkis · 2026-01-26T07:26:30Z

docs/development/custom-ui/a2a-client.mdx

+import { createAuthenticatedFetch } from "agentstack-sdk";
+
+async function getAgentClient(baseUrl: string, providerId: string, token?: string) {
+  const fetchImpl = token ? createAuthenticatedFetch(token) : fetch;


Lets explain why createAuthenticatedFetch and that's basically the only reason behind custom factory.

And I believe sending the token is required now.

tomkis · 2026-01-26T07:27:06Z

docs/development/custom-ui/a2a-client.mdx

+
+## 2. Resolve agent card demands
+
+Once you have the client, read the agent card and resolve its demands.


Point demands to extensions page. It seems very out of context.

tomkis · 2026-01-26T07:27:31Z

docs/development/custom-ui/client-sdk/overview.mdx


-The SDK helps you work with this extension system by providing **typing and parsing** for extensions. Instead of manually parsing extension URIs and metadata, the SDK gives you type-safe functions to extract data from agent cards.
+- A2A extensions and helpers that map agent demands to client fulfillments and UI metadata.


I would VERY briefly explain concept of demands and fulfillments hre.

tomkis · 2026-01-26T07:28:42Z

docs/development/custom-ui/client-sdk/message-building.mdx

@@ -0,0 +1,56 @@
+---
+title: Message Building


A2A Message Building.

tomkis · 2026-01-26T07:30:12Z

@PetrBulanek please test the documentation via some coding Agent. basically prompt it to build simple client and as a an input tell him about this docs. Dont provide too much details. Then look into trajectory of the agent if it misses something to figure out some inaccuracies.

kapetr · 2026-01-26T08:34:23Z

docs/development/custom-ui/getting-started.mdx

+
+const api = buildApiClient({
+  baseUrl: "https://your-agentstack-instance.com",
+  fetch: createAuthenticatedFetch("token-value"),


I'd briefly explain where the token-value comes from, as it can be either accessToken or token from createContextToken, if I'm correct. Possibly with a link to more detailed explanation.

I guess I'm not correct :) For ApiClient it's always access token.

kapetr · 2026-01-26T09:01:57Z

docs/development/custom-ui/a2a-client.mdx

+
+This guide shows how to integrate `@a2a-js/sdk` with the AgentStack SDK helpers. It mirrors the flow used in `agentstack-ui`.
+
+## 1. Create an A2A client


I'd prepend a step explaining how the context token is created, with a link to the "Permissions and Tokens" page, since it is required to create the agent client.

Signed-off-by: jenna-winkler <[email protected]>

PetrBulanek · 2026-01-29T10:32:38Z

@jenna-winkler Thanks for the edits! 👍

Are you planning any further updates? Alternatively, can I/should I incorporate the review comments from the guys?

jenna-winkler · 2026-01-29T13:16:11Z

@PetrBulanek yes I’m all set, go ahead and incorporate the review comments from the guys!

PetrBulanek added 5 commits January 21, 2026 14:07

docs(sdk): add docs for client SDK's api client

fbb8be7

Signed-off-by: Petr Bulánek <[email protected]>

docs(sdk): add extensions docs

d196426

Signed-off-by: Petr Bulánek <[email protected]>

docs(sdk): update docs

fc5f591

Signed-off-by: Petr Bulánek <[email protected]>

fixup! docs(sdk): update docs

8a9a480

Signed-off-by: Petr Bulánek <[email protected]>

fixup! fixup! docs(sdk): update docs

04b0990

Signed-off-by: Petr Bulánek <[email protected]>

PetrBulanek requested review from kapetr and tomkis January 21, 2026 15:27

github-project-automation bot added this to Agent Stack Jan 21, 2026

mintlify bot deployed to staging - docs January 21, 2026 15:27 View deployment

gemini-code-assist bot reviewed Jan 21, 2026

View reviewed changes

PetrBulanek requested a review from jenna-winkler January 21, 2026 15:35

tomkis requested changes Jan 26, 2026

View reviewed changes

kapetr reviewed Jan 26, 2026

View reviewed changes

PetrBulanek changed the title ~~[DRAFT] docs(sdk): add docs for client SDK~~ docs(sdk): add docs for client SDK Jan 27, 2026

PetrBulanek marked this pull request as ready for review January 27, 2026 15:14

dosubot bot added the size:XXL This PR changes 1000+ lines, ignoring generated files. label Jan 27, 2026

docs: headers and intros

559f6bb

Signed-off-by: jenna-winkler <[email protected]>

mintlify bot deployed to staging - docs January 29, 2026 00:07 View deployment


		The SDK provides `handleTaskStatusUpdate` to parse A2A `TaskStatusUpdate` and extract structured information:
		When you stream A2A task events, `handleTaskStatusUpdate` maps status updates into actionable UI events.


		All API calls return `ApiResult<T>`. Use `unwrapResult` if you want exceptions, and then handle errors with `isHttpError`, `isNetworkError`, `isParseError`, and `isValidationError`.

		## Extension Helpers at a Glance


		## 2. Resolve agent card demands

		Once you have the client, read the agent card and resolve its demands.


		The SDK helps you work with this extension system by providing typing and parsing for extensions. Instead of manually parsing extension URIs and metadata, the SDK gives you type-safe functions to extract data from agent cards.
		- A2A extensions and helpers that map agent demands to client fulfillments and UI metadata.


		This guide shows how to integrate `@a2a-js/sdk` with the AgentStack SDK helpers. It mirrors the flow used in `agentstack-ui`.

		## 1. Create an A2A client

docs(sdk): add docs for client SDK #1867

Are you sure you want to change the base?

docs(sdk): add docs for client SDK #1867

Uh oh!

Conversation

PetrBulanek commented Jan 21, 2026

Summary

Linked Issues

Documentation

Uh oh!

gemini-code-assist bot commented Jan 21, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tomkis left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tomkis commented Jan 26, 2026

Uh oh!

kapetr Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PetrBulanek commented Jan 29, 2026

Uh oh!

jenna-winkler commented Jan 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

kapetr Jan 26, 2026 •

edited

Loading