Agents docs #271
Draft
pavelgj wants to merge 17 commits into
Draft
Conversation
- Rewrite agents intro to highlight middleware support and be more concise - Add cross-link tip from agentic-patterns page to new agents page - Replace TypeScript interface examples with Zod schema-based state - Add "State management strategies" section for session state patterns - Improve beta import note formatting with callout block
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces the new Agents API (Beta) documentation, replacing the deprecated ai.chat() and legacy multi-agent patterns. It adds a comprehensive guide covering agent definition, state management, persistence, and multi-agent delegation. Review feedback highlights a runtime error in a custom agent example, suggests updating outdated model references to Gemini 2.0, and recommends defining a missing type in a code snippet for better clarity.
- Reword page description and intro to focus on app-level use cases (chatbots, approval flows, generators) instead of internals - Fix incorrect `sess.session.addMessages()` → `sess.addMessages()` - Add paragraph explaining agents as standard HTTP endpoints - Enhance custom state section framing and add client-side code example
Capitalize "agents" to "Agents" in the introductory sentence for consistent branding with the rest of the documentation.
i14h
reviewed
May 8, 2026
i14h
left a comment
i14h
left a comment
Collaborator
There was a problem hiding this comment.
Thanks. Great doc, a few feedbacks reading as a noob person
|
|
||
| For long-running tasks (report generation, deep research), run the agent | ||
| in the background. The client submits a request, receives a `snapshotId` | ||
| immediately, and polls for the result. |
Collaborator
There was a problem hiding this comment.
nit: continue with "To implement background execution, you need to make changes on the server and client:"
| ## Multi-agent delegation | ||
|
|
||
| Use the `agents()` middleware from `@genkit-ai/middleware` to let an | ||
| orchestrator agent delegate tasks to specialized sub-agents. |
| `agent.streamBidi()` creates a bidirectional streaming session - you can send | ||
| messages and receive streamed responses concurrently. This is useful for | ||
| server-side scripts or advanced scenarios where you need to queue multiple | ||
| messages before reading responses: |
Collaborator
There was a problem hiding this comment.
it's great that you explain the utility, but I don't quite understand the examples you mention. Why server-side scripts would need this? or why would I need to queue multiple messages?
| ```ts | ||
| const session = weatherAgent.streamBidi({ snapshotId: previousSnapshotId }); | ||
| ``` | ||
|
|
Collaborator
There was a problem hiding this comment.
Maybe also a section for subagents using middleware?
Expand documentation for defineAgent, definePromptAgent, and defineCustomAgent with more detailed descriptions, use-case bullet points, and inline code comments to help readers understand when and why to use each agent type.
Replaces the single interrupt example with two clearly separated patterns (resume.respond and resume.restart), adds a comparison table, and provides distinct server/client examples for each. Highlights security benefits of the restart pattern for approval-gated tools.
Revise the Agents documentation to reflect the unified API where server and client agents expose the same interface. Update import paths to include `genkit/beta/client`, make the `model` parameter optional (defaulting to the `genkit()` config), and clarify that custom status is streamed by mutating session state.
Add a quick-reference guide for the three ag
Change prompt example code fence from `none` to `handlebars` for proper syntax highlighting, and remove accidentally committed task progress metadata at the end of the file.
Expand the explanation of the agent server endpoints to distinguish the required primary endpoint from the optional snapshot and abort endpoints. Clarify that the snapshot endpoint applies only to server-managed agents with a store, and the abort endpoint only to background execution.
Contributor
|
I feel like i'd like to see an e2e example earlier on? at the moment i have to scroll past defineAgent, definePromptAgent, defineCustomAgent - the first e2e example is "Multi-turn streaming chat" right, maybe that could be moved earlier |
Update the agents guide to document `session.getCustom()` for reading state and `session.updateCustom()` for mutating it, with a new listTasks tool example. Improve state normalization to default per-field for fresh sessions, import `z` in the setup snippet, and clarify that `getSnapshotDataAction` and `abortAgentAction` are server-side agent properties rather than part of the shared `AgentAPI`.
Contributor
|
|
| [Session persistence](#session-persistence) for detailed examples of each | ||
| strategy, including session restoration, branching, and pruning. | ||
|
|
||
| ## Testing agents in the developer UI |
Collaborator
There was a problem hiding this comment.
This should have more details about the actual specific places where you can interact with agents in the DevUI.
Rewrite the agents documentation to follow a progressive disclosure approach. Replace the abstract unified-API introduction with a simpler explanation, and add "Your first agent" and "Add tools and serve over HTTP" sections that build incrementally from minimal to capable agents. Include links to advanced topics so readers can add capabilities as needed.
Streamline the agents page introduction for clarity and add a note explaining the interchangeable model reference syntax. Remove the ai.defineCustomAgent() documentation section.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Preview: https://genkit-dev-astro--pr-271-6kxlhh23.web.app