Skip to content

Commit 0d1b3dc

Browse files
mmemme
authored
Add Mastra docs (CopilotKit#1804)
1 parent f610a35 commit 0d1b3dc

19 files changed

Lines changed: 1232 additions & 32 deletions

File tree

‎docs/app/(home)/layout.tsx‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import { TerminalIcon, RocketIcon } from "lucide-react";
77
import { SiCrewai } from "@icons-pack/react-simple-icons";
88
import { TopBar } from "@/components/layout/top-bar";
99
import { SiLangchain } from "react-icons/si";
10-
import { AG2Icon } from "@/lib/icons/custom-icons";
10+
import { AG2Icon, MastraIcon } from "@/lib/icons/custom-icons";
1111

1212
export default function Layout({ children }: { children: ReactNode }) {
1313
return (
@@ -63,6 +63,15 @@ export default function Layout({ children }: { children: ReactNode }) {
6363
"bg-gradient-to-b from-[#FA694C] to-[#FE8A71] text-white",
6464
selectedStyle: "ring-[#FA694C]/70 ring-2 rounded-sm",
6565
},
66+
{
67+
title: "CoAgents (Mastra)",
68+
description: "Documentation for CoAgents with Mastra",
69+
url: "/mastra",
70+
icon: <MastraIcon className="w-4 h-4 text-bold" />,
71+
bgGradient:
72+
"bg-gradient-to-b from-black to-zinc-800 text-white",
73+
selectedStyle: "ring-indigo-500/70 ring-2 rounded-sm",
74+
},
6675
{
6776
title: "CoAgents (AG2)",
6877
description: "Documentation for CoAgents with AG2",

‎docs/content/docs/mastra/agentic-chat-ui.mdx‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: Chat with an Agent
3+
icon: "lucide/SendHorizontal"
4+
description: Chat with an agent using CopilotKit's UI components.
5+
---
6+
7+
import ConnectCopilotUI from "@/snippets/copilot-ui.mdx";
8+
import SelfHostingCopilotRuntimeCreateEndpoint from "@/snippets/self-hosting-copilot-runtime-create-endpoint.mdx";
9+
import SelfHostingCopilotRuntimeConfigureCopilotKitProvider from "@/snippets/self-hosting-copilot-runtime-configure-copilotkit-provider.mdx";
10+
import CopilotCloudConfigureCopilotKitProvider from "@/snippets/cloud/cloud-copilotkit-provider.mdx";
11+
import ComponentExamples from "@/snippets/component-examples.mdx";
12+
import { UserIcon, PaintbrushIcon, WrenchIcon, RepeatIcon } from "lucide-react";
13+
14+
<video
15+
src="/images/coagents/agentic-chat-ui.mp4"
16+
className="rounded-lg shadow-xl"
17+
loop
18+
playsInline
19+
controls
20+
autoPlay
21+
muted
22+
/>
23+
<Callout>
24+
This video shows the [coagents
25+
starter](https://github.com/CopilotKit/CopilotKit/tree/main/examples/mastra/starter)
26+
repo with various Copilot UI components applied to it!
27+
</Callout>
28+
29+
## What is this?
30+
31+
Agentic chat UIs are ways for your users to interact with your agent. CopilotKit provides a variety of different components to choose from, each
32+
with their own unique use cases.
33+
34+
If you've gone through the [getting started guide](/mastra/quickstart/mastra) **you already have a agentic chat UI setup**! Nothing else is needed
35+
to get started.
36+
37+
## When should I use this?
38+
39+
CopilotKit provides a variety of different batteries-included components to choose from to create agent native applications. They scale
40+
from simple chat UIs to completely custom applications.
41+
42+
<ComponentExamples components={props.components} />

‎docs/content/docs/mastra/concepts/agentic-copilots.mdx‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
title: Agentic Copilots
3+
description: Agentic copilots provide you with advanced control and orchestration over your agents.
4+
icon: lucide/Bot
5+
---
6+
7+
import {
8+
TailoredContent,
9+
TailoredContentOption,
10+
} from "@/components/react/tailored-content";
11+
import { BsFillCloudHaze2Fill as CloudIcon } from "react-icons/bs";
12+
import { FaServer as SelfHostIcon } from "react-icons/fa6";
13+
import { LinkIcon } from "lucide-react";
14+
import {
15+
RocketIcon,
16+
GraduationCapIcon,
17+
CodeIcon,
18+
VideoIcon,
19+
} from "lucide-react";
20+
import { AG2Icon, MastraIcon } from "@/lib/icons/custom-icons";
21+
22+
23+
Before we dive into what agentic copilots are, help us help you by telling us your level of experience with Mastra. We'll explain things in a way that best suits your experience level.
24+
25+
<TailoredContent id="experience" defaultOptionIndex={0}>
26+
<TailoredContentOption
27+
id="new"
28+
title="I'm new to Mastra"
29+
description="Help me understand what agentic copilots are, where Mastra fits in, and how to get started."
30+
icon={<img src="/images/copilotkit-logo.svg" width={7} height={7} />}
31+
>
32+
<Frame>
33+
<img src="/images/coagents/SharedStateCoAgents.gif" alt="CoAgents Shared State" className="mt-0 mb-12"/>
34+
</Frame>
35+
36+
### What are Agents?
37+
AI agents are intelligent systems that interact with their environment to achieve specific goals. Think of them as 'virtual colleagues' that can handle tasks ranging from
38+
simple queries like "find the cheapest flight to Paris" to complex challenges like "design a new product layout."
39+
40+
As these AI-driven experiences (or 'Agentic Experiences') become more sophisticated, developers need finer control over how agents make decisions. This is where specialized
41+
frameworks like Mastra become essential.
42+
43+
### What is Mastra?
44+
Mastra is a framework that gives you precise control over AI agents. Mastra agents allow developers to combine and coordinate coding tasks efficiently,
45+
providing a robust framework for building sophisticated AI automations.
46+
47+
### What are Agentic Copilots?
48+
Agentic copilots are how CopilotKit brings Mastra agents into your application. If you're familiar with CopilotKit, you know that copilots are AI assistants that
49+
understand your app's context and can take actions within it. While CopilotKit's standard copilots use a simplified [ReAct pattern](https://www.perplexity.ai/search/what-s-a-react-agent-5hu7ZOaKSAuY7YdFjQLCNQ)
50+
for quick implementation, Agentic copilots give you Mastra's full orchestration capabilities when you need more control over your agent's behavior.
51+
52+
### What are CoAgents?
53+
CoAgents are what we call CopilotKit's approach to building agentic experiences! They're interchangeable with agentic copilots being a more descriptive term for the overall concept.
54+
55+
### When should I use CopilotKit's CoAgents?
56+
You should use CoAgents when you require tight control over the Agentic runloop, as facilitated by an Agentic Orchestration framework like [Mastra](https://mastra.ai/).
57+
With CoAgents, you can carry all of your existing CopilotKit-enabled Copilot capabilities into a customized agentic runloop.
58+
59+
We suggest beginning with a basic Copilot and gradually transitioning specific components to CoAgents.
60+
61+
The need for CoAgents spans a broad spectrum across different applications. At one end, their advanced capabilities might not be required at all, or only for a minimal 10% of the application's
62+
functionality. Progressing further, there are scenarios where they become increasingly vital, managing 60-70% of operations. Ultimately, in some cases, CoAgents are indispensable, orchestrating
63+
up to 100% of the Copilot's tasks (see [agent-lock mode](/mastra/multi-agent-flows) for the 100% case).
64+
65+
### Examples
66+
An excellent example of the type of experiences you can accomplish with CoAgents applications can be found in our [Research Canvas](https://github.com/CopilotKit/CopilotKit/tree/main/examples/coagents-research-canvas).
67+
68+
More specifically, it demonstrates how CoAgents allow for AI driven experiences with:
69+
- Precise state management across agent interactions
70+
- Sophisticated multi-step reasoning capabilities
71+
- Seamless orchestration of multiple AI tools
72+
- Interactive human-AI collaboration features
73+
- Real-time state updates and progress streaming
74+
75+
## Next Steps
76+
77+
Want to get started? You have some options!
78+
79+
<Cards>
80+
<Card
81+
title="Build your first CoAgent"
82+
description="Follow a step-by-step tutorial to build a travel app supercharged with CoAgents."
83+
href="/mastra/quickstart/mastra"
84+
icon={<RocketIcon />}
85+
/>
86+
<Card
87+
title="Learn more CoAgent concepts"
88+
description="Learn more about the concepts used to talk about CoAgents and how to use them."
89+
href="/mastra/concepts/terminology"
90+
icon={<GraduationCapIcon />}
91+
/>
92+
<Card
93+
title="Read the reference documentation"
94+
description="Just here for some reference? Checkout the reference documentation for more details."
95+
href="/reference"
96+
icon={<CodeIcon />}
97+
/>
98+
</Cards>
99+
</TailoredContentOption>
100+
<TailoredContentOption
101+
id="intermediate"
102+
title="I'm already using Mastra"
103+
description="Help me understand what agentic copilots are, what Copilotkit does to integrate with Mastra, and how to get started."
104+
icon={<MastraIcon />}
105+
>
106+
107+
Mastra is a framework for building deeply customizable AI agents.
108+
109+
CopilotKit's Agentic Copilots is infrastructure for in-app agent-user interaction, i.e. for transforming agents from autonomous processes to user-interactive 'virtual colleagues' that live inside applications.
110+
111+
Any Mastra-based agent can be transformed into an Agentic Copilot with a minimal amount
112+
of effort to get industry leading agentic UX such as:
113+
- Intermediate result and state progress streaming
114+
- Human-in-the-loop collaboration
115+
- Agentic generative UI
116+
- And more!
117+
118+
All of these features are essential to delight instead of frustrate your users with AI features.
119+
120+
### What are CoAgents?
121+
CoAgents are what we call CopilotKit's approach to building agentic experiences! They're interchangeable with agentic copilots being a more descriptive term for the overall concept.
122+
123+
## Next Steps
124+
Want to get started? You have some options!
125+
126+
<Cards>
127+
<Card
128+
title="Quickstart"
129+
description="Integrate your Mastra agent with CopilotKit in a few minutes."
130+
href="/mastra/quickstart/mastra"
131+
icon={<RocketIcon />}
132+
/>
133+
<Card
134+
title="Reference"
135+
description="Learn more about the terms used to talk about CoAgents and how to use them."
136+
href="/reference"
137+
icon={<CodeIcon />}
138+
/>
139+
</Cards>
140+
</TailoredContentOption>
141+
142+
</TailoredContent>

‎docs/content/docs/mastra/concepts/mastra.mdx‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
title: Mastra
3+
description: An agentic framework for building LLM applications that can be used with Copilotkit.
4+
icon: custom/mastra
5+
---
6+
7+
Mastra is an agentic framework for building LLM applications that can be used with Copilotkit. Mastra Agents allow developers
8+
to combine and coordinate tasks efficiently, providing a robust framework for building sophisticated AI automations.
9+
10+
## CoAgents and Mastra
11+
12+
How do CoAgents extend Mastra?
13+
14+
15+
- **Multi-actor**: CoAgents allow for multiple agents to interact with each other. Copilotkit acts as the "ground-truth"
16+
when transitioning between agents. Read more about how multi-actor workflows work [here](/mastra/multi-agent-flows)
17+
and how messages are managed [here](/mastra/concepts/message-management).
18+
- **LLMs**: CoAgents use large language models to generate responses. This is useful for building applications that need to
19+
generate natural language responses.
20+
- **Human in the loop**: CoAgents enabled human review and approval of generated responses. Read more about how this works
21+
[here](/mastra/human-in-the-loop).
22+
- **Tool calling**: Tool calling is a fundamental building block for agentic workflows. They allow for greater control over what
23+
the agent can do and can be used to interact with external systems. CoAgents allow you to easily render in-progress
24+
tool calls in the UI so your users know what's happening. Read more about streaming tool calls [here](/mastra/frontend-actions).
25+
26+
## Building with TypeScript
27+
28+
You can build Mastra applications using TypeScript. Check out the [Mastra docs](https://mastra.ai/en/docs) for more information.
29+
30+
## Mastra Cloud
31+
32+
Mastra Cloud is a platform for deploying and monitoring Mastra applications. Read more about it on the
33+
[Mastra website](https://mastra.ai/cloud-beta).
34+
35+
If you want to take the next step to deploy your Mastra application as an CoAgent, check out our [quickstart guide](/mastra/quickstart/mastra).

‎docs/content/docs/mastra/concepts/meta.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"title": "Concepts",
3+
"root": true,
4+
"pages": ["terminology", "agentic-copilots", "mastra"]
5+
}

‎docs/content/docs/mastra/concepts/terminology.mdx‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: Terminology
3+
icon: lucide/Book
4+
---
5+
6+
Here are the key terms and concepts used throughout CoAgents:
7+
8+
| Term | Definition |
9+
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
10+
| Agentic Copilot | An AI agent designed to collaborate with users in Agent-Native applications, rather than operate autonomously. |
11+
| CoAgent | Terminology referring to CopilotKit's suite of tools for building agentic applications. Typically interchangeable with agentic copilot. |
12+
| Agentic Generative UI | UI components that are dynamically generated and updated based on the agent's current state, providing users with visibility into what the agent is doing and building trust through transparency. |
13+
| Ground Truth | In CoAgents, CopilotKit serves as the "ground truth" for the full chat session, maintaining the persistent chat history and ensuring conversational continuity across different agents. |
14+
| Human-in-the-Loop (HITL) | A workflow pattern where human input or validation is required during agent execution, enabling quality control and oversight at critical decision points. |
15+
| [Mastra](https://mastra.ai) | The agent framework integrated with CopilotKit that provides the orchestration layer for CoAgents, enabling sophisticated multi-step reasoning and state management. |
16+
| Agent Lock Mode | A mode where CopilotKit is configured to work exclusively with a specific agent, ensuring all requests stay within a single workflow graph for precise control. |
17+
| Router Mode | A mode where CopilotKit dynamically routes requests between different agents and tools based on context and user input, enabling flexible multi-agent workflows. |
18+
19+
These terms are referenced throughout the documentation and are essential for understanding how CoAgents work and how to implement them effectively in your applications.

‎docs/content/docs/mastra/frontend-actions.mdx‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
title: Frontend Actions
3+
icon: "lucide/Wrench"
4+
description: Create frontend actions and use them within your agent.
5+
---
6+
7+
import InstallSDKSnippet from "@/snippets/install-sdk.mdx";
8+
9+
<video
10+
src="/images/frontend-actions-demo.mp4"
11+
className="rounded-lg shadow-xl"
12+
loop
13+
playsInline
14+
controls
15+
autoPlay
16+
muted
17+
/>
18+
<Callout>
19+
This video shows the [coagents
20+
starter](https://github.com/CopilotKit/CopilotKit/tree/main/examples/coagents-starter-mastra)
21+
repo with the [implementation](#implementation) section applied to it!
22+
</Callout>
23+
24+
## What is this?
25+
26+
Frontend actions are powerful tools that allow your AI agents to directly interact with and update your application's user interface. Think of them as bridges that connect your agent's decision-making capabilities with your frontend's interactive elements.
27+
28+
## When should I use this?
29+
30+
Frontend actions are essential when you want to create truly interactive AI applications where your agent needs to:
31+
32+
- Dynamically update UI elements
33+
- Trigger frontend animations or transitions
34+
- Show alerts or notifications
35+
- Modify application state
36+
- Handle user interactions programmatically
37+
38+
Without frontend actions, agents are limited to just processing and returning data. By implementing frontend actions, you can create rich, interactive experiences where your agent actively drives the user interface.
39+
40+
## Implementation
41+
42+
<Steps>
43+
<Step>
44+
### Setup CopilotKit
45+
46+
To use frontend actions, you'll need to setup CopilotKit first. For the sake of brevity, we won't cover it here.
47+
48+
Check out our [getting started guide](/mastra/quickstart/mastra) and come back here when you're setup!
49+
</Step>
50+
51+
<Step>
52+
### Create a frontend action
53+
54+
First, you'll need to create a frontend action using the [useCopilotAction](/reference/hooks/useCopilotAction) hook. Here's a simple one to get you started
55+
that says hello to the user.
56+
57+
```tsx title="page.tsx"
58+
import { useCopilotAction } from "@copilotkit/react-core" // [!code highlight]
59+
60+
export function Page() {
61+
// ...
62+
63+
// [!code highlight:16]
64+
useCopilotAction({
65+
name: "sayHello",
66+
description: "Say hello to the user",
67+
available: "remote", // optional, makes it so the action is *only* available to the agent
68+
parameters: [
69+
{
70+
name: "name",
71+
type: "string",
72+
description: "The name of the user to say hello to",
73+
required: true,
74+
},
75+
],
76+
handler: async ({ name }) => {
77+
alert(`Hello, ${name}!`);
78+
},
79+
});
80+
81+
// ...
82+
}
83+
```
84+
</Step>
85+
<Step>
86+
### Modify your agent
87+
Now, we'll need to modify the agent to access these frontend actions. Open up for your agent's folder and continue from there!
88+
</Step>
89+
<Step>
90+
### Install the CopilotKit SDK
91+
<InstallSDKSnippet components={props.components}/>
92+
</Step>
93+
<Step>
94+
### Accessing Frontend Actions
95+
96+
Since Mastra includes native support for the AG-UI protocol, frontend actions are automatically available to the agent as
97+
tools.
98+
</Step>
99+
<Step>
100+
### Give it a try!
101+
You've now given your agent the ability to directly call any CopilotActions you've defined. These actions will be available as tools to the agent where they can be used as needed.
102+
</Step>
103+
104+
</Steps>

0 commit comments

Comments
 (0)