Feat/skills for client sdk #1868
Conversation
Signed-off-by: Tomas Weiss <tomas.weiss2@gmail.com>
Signed-off-by: Tomas Weiss <tomas.weiss2@gmail.com>
Summary of ChangesHello @tomkis, I'm Gemini Code Assist1! 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 enhances the project's documentation by introducing two new skill guides. One guide provides detailed instructions and code examples for developers looking to integrate with the Agent Stack client SDK, covering essential functionalities from agent interaction to extension handling. The other offers a foundational understanding of the Agent Stack platform, outlining its core purpose and the primary user roles it serves. Highlights
🧠 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 AssistThe 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
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 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. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces two new markdown files that serve as documentation for the Agent Stack, covering an overview and essential SDK usage guidelines. My review focuses on enhancing the clarity, correctness, and consistency of these documents and their code examples. I've identified several areas for improvement, including a critical correction to an API call in a TypeScript snippet, fixing typos, improving code style in examples for better readability, and ensuring consistent use of terminology throughout the documentation. Addressing these points will significantly improve the quality and usability of the new documentation.
| const context = await agentstack.createContext(agentId); | ||
|
|
||
| const { token } = await agentstack.createContextToken({ | ||
| contextId: context.id, | ||
|
|
||
| globalPermissions: { llm: ['*'], a2a_proxy: ['*'] }, | ||
|
|
||
| contextPermissions: { | ||
| files: ['*'], | ||
| vector_stores: ['*'], | ||
| context_data: ['*'], | ||
| }, | ||
| }); | ||
|
|
||
| const contextId = context.id; |
There was a problem hiding this comment.
This code snippet has a few issues that will cause it to fail:
- The
createContextfunction is called with a stringagentId, but it expects an object, likely of the form{ provider_id: agentId }. - The return values of
createContextandcreateContextTokenareResultobjects. You must check if the operation was successful (e.g.,result.ok) before trying to access thedataproperty. - Because
contextwill hold theResultobject fromcreateContext,context.idwill be undefined, causing an error in thecreateContextTokencall.
Here is a corrected version of this block for your reference:
const contextResult = await agentstack.createContext({ provider_id: agentId });
if (!contextResult.ok) {
throw contextResult.error;
}
const context = contextResult.data;
const tokenResult = await agentstack.createContextToken({
contextId: context.id,
globalPermissions: { llm: ['*'], a2a_proxy: ['*'] },
contextPermissions: {
files: ['*'],
vector_stores: ['*'],
context_data: ['*'],
},
});
if (!tokenResult.ok) {
throw tokenResult.error;
}
const { token } = tokenResult.data;
const contextId = context.id;| description: Basic implementation guidelines how to work with Agent Stack client SDK | ||
| --- | ||
|
|
||
| Custom GUI integration with Agent Stack requires dependency on both [A2A](https://a2a-protocol.org/latest/specification) as well as [Agent Stack](https://agentstack.beeai.dev/llms.txt). |
There was a problem hiding this comment.
The link for 'Agent Stack' points to a llms.txt file. This seems incorrect for a general reference to the Agent Stack project. It would be more helpful for users if this link pointed to the main project or documentation page.
| Custom GUI integration with Agent Stack requires dependency on both [A2A](https://a2a-protocol.org/latest/specification) as well as [Agent Stack](https://agentstack.beeai.dev/llms.txt). | |
| Custom GUI integration with Agent Stack requires dependency on both [A2A](https://a2a-protocol.org/latest/specification) as well as [Agent Stack](https://agentstack.beeai.dev/). |
|
|
||
| Agent Stack SDK extends [A2A - Agent to Agent](https://a2a-protocol.org/latest/specification) protocol. | ||
|
|
||
| You need to create the client with a caveat that we need to provide fetch implemneation that packs in context token as authorization header. |
There was a problem hiding this comment.
There is a typo in the word 'implementation'.
| You need to create the client with a caveat that we need to provide fetch implemneation that packs in context token as authorization header. | |
| You need to create the client with a caveat that we need to provide fetch implementation that packs in context token as authorization header. |
| DefaultAgentCardResolver, | ||
| JsonRpcTransportFactory, | ||
| } from '@a2a-js/sdk/client'; | ||
| import { createAuthenticatedFetch } from "agentstack-sdk"; |
There was a problem hiding this comment.
The import statements in this file use a mix of single and double quotes. For consistency, it's best to stick to one style. The prevailing style in this file seems to be single quotes.
| import { createAuthenticatedFetch } from "agentstack-sdk"; | |
| import { createAuthenticatedFetch } from 'agentstack-sdk'; |
| TaskStatusUpdateEvent, | ||
| } from '@a2a-js/sdk'; | ||
|
|
||
| const conversationHistory: Message[] = [] |
There was a problem hiding this comment.
The conversationHistory array is declared but never used in the code example. This could be confusing for readers. Please consider either removing it or demonstrating how it could be used to maintain conversation state.
| } | ||
| } | ||
|
|
||
| console.log(`Client prompted ${clientPrompt} and agent responded with ${agentReply}) |
There was a problem hiding this comment.
There's a typo in the console.log template literal. It includes an extra closing parenthesis ) inside the string, which will be printed in the output.
| console.log(`Client prompted ${clientPrompt} and agent responded with ${agentReply}) | |
| console.log(`Client prompted ${clientPrompt} and agent responded with ${agentReply}`) |
|
|
||
| Agents declare demands via agent card extensions. Client fulfills demands using dependency injection: | ||
|
|
||
| 1. Fetch agent card from `/.well-known/agent-card.json` |
There was a problem hiding this comment.
This line states that the agent card should be fetched from /.well-known/agent-card.json. However, the code example on line 85 uses a different path: ${agentstackUrl}/api/v1/a2a/${agentId}/agent-card.json. This inconsistency can be confusing. Please update the documentation to be consistent with the code example.
| 3. Fulfill the demands in the client | ||
| 4. Assemble and send the fulfillment via Message metadata. | ||
|
|
||
| ### Example of how fulfill LLM extension |
There was a problem hiding this comment.
There is a minor grammatical error in the heading. It should be 'how to fulfill'.
| ### Example of how fulfill LLM extension | |
| ### Example of how to fulfill LLM extension |
|
|
||
| ```ts | ||
| import { | ||
| buildApiClient, |
There was a problem hiding this comment.
The buildApiClient function is imported but not used in this section's code examples. To avoid confusion, it's best to remove unused imports.
| llm_fulfillments: Object.entries(demand.llm_demands).reduce((memo, [demandKey]) => { | ||
| return { | ||
| ...memo, | ||
| [demandKey]: { | ||
| api_model: 'gpt5', | ||
| api_base: 'http://openai-endpoint', | ||
| api_key: 'API_KEY' | ||
| } | ||
| } | ||
|
|
||
| }, {}) |
There was a problem hiding this comment.
The use of Object.entries with reduce to build the llm_fulfillments object can be simplified. Using Object.fromEntries with Object.keys().map() is a more modern and often more readable approach for this pattern.
| llm_fulfillments: Object.entries(demand.llm_demands).reduce((memo, [demandKey]) => { | |
| return { | |
| ...memo, | |
| [demandKey]: { | |
| api_model: 'gpt5', | |
| api_base: 'http://openai-endpoint', | |
| api_key: 'API_KEY' | |
| } | |
| } | |
| }, {}) | |
| llm_fulfillments: Object.fromEntries( | |
| Object.keys(demand.llm_demands).map((demandKey) => [ | |
| demandKey, | |
| { | |
| api_model: 'gpt5', | |
| api_base: 'http://openai-endpoint', | |
| api_key: 'API_KEY' | |
| } | |
| ]) | |
| ) |
Summary
Linked Issues
Documentation
If this PR adds new feature or changes existing. Make sure documentation is adjusted accordingly. If the docs is not needed, please explain why.