commit

elithrar · elithrar · commit 3757f3045d8f · 2025-02-26T15:45:02.000-05:00
diff --git a/public/_redirects b/public/_redirects
@@ -98,6 +98,13 @@
 
 # agents
 /agents/build/prompts/ /workers/get-started/prompting/ 301
+/agents/examples/browse-the-web/ /agents/api-reference/browse-the-web/ 301
+/agents/examples/manage-and-sync-state/ /agents/api-reference/manage-and-sync-state/ 301
+/agents/examples/rag/ /agents/api-reference/rag/ 301
+/agents/examples/run-workflows/ /agents/api-reference/run-workflows/ 301
+/agents/examples/schedule-tasks/ /agents/api-reference/schedule-tasks/ 301
+/agents/examples/using-ai-models/ /agents/api-reference/using-ai-models/ 301
+/agents/examples/websockets/ /agents/api-reference/websockets/ 301
 
 # ai
 /ai/ /use-cases/ai/ 301
diff --git a/src/content/docs/agents/api-reference/browse-the-web.mdx b/src/content/docs/agents/api-reference/browse-the-web.mdx
diff --git a/src/content/docs/agents/api-reference/index.mdx b/src/content/docs/agents/api-reference/index.mdx
@@ -2,11 +2,11 @@
 title: API Reference
 pcx_content_type: navigation
 sidebar:
-  order: 5
-  group:
-    hideIndex: true
+  order: 3
 ---
 
 import { DirectoryListing } from "~/components"
 
+Learn more about what Agents can do, the `Agent` class, and the APIs that Agents expose:
+
 <DirectoryListing />
diff --git a/src/content/docs/agents/api-reference/manage-and-sync-state.mdx b/src/content/docs/agents/api-reference/manage-and-sync-state.mdx
@@ -198,7 +198,7 @@ The SQL API exposed to an Agent is similar to the one [within Durable Objects](/
 
 ### Use Agent state as model context
 
-You can combine the state and SQL APIs in your Agent with its ability to [call AI models](/agents/examples/using-ai-models/) to include historical context within your prompts to a model. Modern Large Language Models (LLMs) often have very large context windows (up to millions of tokens), which allows you to pull relevant context into your prompt directly.
+You can combine the state and SQL APIs in your Agent with its ability to [call AI models](/agents/api-reference/using-ai-models/) to include historical context within your prompts to a model. Modern Large Language Models (LLMs) often have very large context windows (up to millions of tokens), which allows you to pull relevant context into your prompt directly.
 
 For example, you can use an Agent's built-in SQL database to pull history, query a model with it, and append to that history ahead of the next call to the model:
 
diff --git a/src/content/docs/agents/api-reference/rag.mdx b/src/content/docs/agents/api-reference/rag.mdx
@@ -8,9 +8,9 @@ sidebar:
 
 import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";
 
-Agents can use Retrieval Augmented Generation (RAG) to retrieve relevant information and use it augment [calls to AI models](/agents/examples/using-ai-models/). Store a user's chat history to use as context for future conversations, summarize documents to bootstrap an Agent's knowledge base, and/or use data from your Agent's [web browsing](/agents/examples/browse-the-web/) tasks to enhance your Agent's capabilities.
+Agents can use Retrieval Augmented Generation (RAG) to retrieve relevant information and use it augment [calls to AI models](/agents/api-reference/using-ai-models/). Store a user's chat history to use as context for future conversations, summarize documents to bootstrap an Agent's knowledge base, and/or use data from your Agent's [web browsing](/agents/api-reference/browse-the-web/) tasks to enhance your Agent's capabilities.
 
-You can use the Agent's own [SQL database](/agents/examples/manage-and-sync-state) as the source of truth for your data and store embeddings in [Vectorize](/vectorize/) (or any other vector-enabled database) to allow your Agent to retrieve relevant information.
+You can use the Agent's own [SQL database](/agents/api-reference/manage-and-sync-state) as the source of truth for your data and store embeddings in [Vectorize](/vectorize/) (or any other vector-enabled database) to allow your Agent to retrieve relevant information.
 
 ### Vector search
 
diff --git a/src/content/docs/agents/api-reference/run-workflows.mdx b/src/content/docs/agents/api-reference/run-workflows.mdx
diff --git a/src/content/docs/agents/api-reference/schedule-tasks.mdx b/src/content/docs/agents/api-reference/schedule-tasks.mdx
diff --git a/src/content/docs/agents/api-reference/sdk.mdx b/src/content/docs/agents/api-reference/sdk.mdx
@@ -100,7 +100,7 @@ export default MyAgent;
 
 :::note
 
-To learn more about how to manage state within an Agent, refer to the documentation on [managing and syncing state](/agents/examples/manage-and-sync-state/).
+To learn more about how to manage state within an Agent, refer to the documentation on [managing and syncing state](/agents/api-reference/manage-and-sync-state/).
 
 :::
 
diff --git a/src/content/docs/agents/api-reference/using-ai-models.mdx b/src/content/docs/agents/api-reference/using-ai-models.mdx
@@ -16,15 +16,15 @@ A user can disconnect during a long-running response from a modern reasoning mod
 
 ## Calling AI Models
 
-You can call models from any method within an Agent, including from HTTP requests using the [`onRequest`](/agents/api-reference/sdk/) handler, when a [scheduled task](/agents/examples/schedule-tasks/) runs, when handling a WebSocket message in the [`onMessage`](/agents/examples/websockets/) handler, or from any of your own methods.
+You can call models from any method within an Agent, including from HTTP requests using the [`onRequest`](/agents/api-reference/sdk/) handler, when a [scheduled task](/agents/api-reference/schedule-tasks/) runs, when handling a WebSocket message in the [`onMessage`](/agents/api-reference/websockets/) handler, or from any of your own methods.
 
 Importantly, Agents can call AI models on their own — autonomously — and can handle long-running responses that can take minutes (or longer) to respond in full.
 
 ### Long-running model requests {/*long-running-model-requests*/}
 
 Modern [reasoning models](https://platform.openai.com/docs/guides/reasoning) or "thinking" model can take some time to both generate a response _and_ stream the response back to the client.
 
-Instead of buffering the entire response, or risking the client disconecting, you can stream the response back to the client by using the [WebSocket API](/agents/examples/websockets/).
+Instead of buffering the entire response, or risking the client disconecting, you can stream the response back to the client by using the [WebSocket API](/agents/api-reference/websockets/).
 
 <TypeScriptExample filename="src/index.ts">
 
@@ -75,7 +75,7 @@ export class MyAgent extends Agent<Env> {
 
 </TypeScriptExample>
 
-You can also persist AI model responses back to [Agent's internal state](/agents/examples/manage-and-sync-state/) by using the `this.setState` method. For example, if you run a [scheduled task](/agents/examples/schedule-tasks/), you can store the output of the task and read it later. Or, if a user disconnects, read the message history back and send it to the user when they reconnect.
+You can also persist AI model responses back to [Agent's internal state](/agents/api-reference/manage-and-sync-state/) by using the `this.setState` method. For example, if you run a [scheduled task](/agents/api-reference/schedule-tasks/), you can store the output of the task and read it later. Or, if a user disconnects, read the message history back and send it to the user when they reconnect.
 
 ### Workers AI
 
@@ -214,7 +214,7 @@ export class MyAgent extends Agent<Env> {
 
 Agents can call models across any service, including those that support the OpenAI API. For example, you can use the OpenAI SDK to use one of [Google's Gemini models](https://ai.google.dev/gemini-api/docs/openai#node.js) directly from your Agent.
 
-Agents can stream responses back over HTTP using Server Sent Events (SSE) from within an `onRequest` handler, or by using the native [WebSockets](/agents/examples/websockets/) API in your Agent to responses back to a client, which is especially useful for larger models that can take over 30+ seconds to reply.
+Agents can stream responses back over HTTP using Server Sent Events (SSE) from within an `onRequest` handler, or by using the native [WebSockets](/agents/api-reference/websockets/) API in your Agent to responses back to a client, which is especially useful for larger models that can take over 30+ seconds to reply.
 
 <TypeScriptExample filename="src/index.ts">
 
diff --git a/src/content/docs/agents/api-reference/websockets.mdx b/src/content/docs/agents/api-reference/websockets.mdx
@@ -120,7 +120,7 @@ function AgentInterface() {
 ```
 </TypeScriptExample>
 
-The `useAgent` hook automatically handles the lifecycle of the connection, ensuring that it is properly initialized and cleaned up when the component mounts and unmounts. You can also [combine `useAgent` with `useState`](/agents/examples/manage-and-sync-state/) to automatically synchronize state across all clients connected to your Agent.
+The `useAgent` hook automatically handles the lifecycle of the connection, ensuring that it is properly initialized and cleaned up when the component mounts and unmounts. You can also [combine `useAgent` with `useState`](/agents/api-reference/manage-and-sync-state/) to automatically synchronize state across all clients connected to your Agent.
 
 ## Handling WebSocket events
 
diff --git a/src/content/docs/agents/examples/index.mdx b/src/content/docs/agents/examples/index.mdx
diff --git a/src/content/docs/agents/getting-started/quickstart.mdx b/src/content/docs/agents/getting-started/quickstart.mdx
@@ -0,0 +1,33 @@
+---
+title: Quickstart
+pcx_content_type: get-started
+sidebar:
+  order: 1
+
+---
+
+import { Render, PackageManagers, WranglerConfig } from "~/components"
+
+Get up and running with the `agents-sdk`.
+
+### Create a new project
+
+<PackageManagers type="create" pkg="cloudflare@latest" args={"my-agent", "--", "--type=agent"} />
+
+TODO
+
+### Understand the Agent class
+
+TODO
+
+### Deploy your Agent
+
+TODO
+
+### Teach your Agent
+
+TODO
+
+### Next steps
+
+TODO
diff --git a/src/content/docs/agents/getting-started/testing-your-agent.mdx b/src/content/docs/agents/getting-started/testing-your-agent.mdx
@@ -2,7 +2,7 @@
 title: Testing your Agents
 pcx_content_type: get-started
 sidebar:
-  order: 10
+  order: 9
 
 ---
 
diff --git a/src/content/docs/agents/index.mdx b/src/content/docs/agents/index.mdx
@@ -50,9 +50,9 @@ Dive into the [Agent SDK reference](/agents/api-reference/sdk/) to learn more ab
 
 We built the `agents-sdk` with a few things in mind:
 
-- **Batteries (state) included**: Agents come with [built-in state management](/agents/examples/manage-and-sync-state/), with the ability to automatically sync state between an Agent and clients, trigger events on state changes, and read+write to each Agent's SQL database.
-- **Communicative**: You can connect to an Agent via [WebSockets](/agents/examples/websockets/) and stream updates back to client in real-time. Handle a long-running response from a reasoning model, the results of an [asynchronous workflow](/agents/examples/run-workflows/), or build a chat app that builds on the `useAgent` hook included in the `agents-sdk`.
-- **Extensible**: Agents are code. Use the [AI models](/agents/examples/using-ai-models/) you want, bring-your-own headless browser service, pull data from your database hosted in another cloud, add your own methods to your Agent and call them.
+- **Batteries (state) included**: Agents come with [built-in state management](/agents/api-reference/manage-and-sync-state/), with the ability to automatically sync state between an Agent and clients, trigger events on state changes, and read+write to each Agent's SQL database.
+- **Communicative**: You can connect to an Agent via [WebSockets](/agents/api-reference/websockets/) and stream updates back to client in real-time. Handle a long-running response from a reasoning model, the results of an [asynchronous workflow](/agents/api-reference/run-workflows/), or build a chat app that builds on the `useAgent` hook included in the `agents-sdk`.
+- **Extensible**: Agents are code. Use the [AI models](/agents/api-reference/using-ai-models/) you want, bring-your-own headless browser service, pull data from your database hosted in another cloud, add your own methods to your Agent and call them.
 
 Agents built with `agents-sdk` can be deployed directly to Cloudflare and run on top of [Durable Objects](/durable-objects/) — which you can think of as stateful micro-servers that can scale to tens of millions — and are able to run wherever they need to. Run your Agents close to a user for low-latency interactivity, close to your data for throughput, and/or anywhere in between.
 
diff --git a/src/content/docs/agents/platform/limits.mdx b/src/content/docs/agents/platform/limits.mdx
@@ -24,6 +24,6 @@ Many limits are inherited from those applied to Workers scripts and/or Durable O
 
 [^1]: Yes, really. You can have tens of millions of Agents running concurrently, as each Agent is mapped to a [unique Durable Object](/durable-objects/what-are-durable-objects/) (actor).
 [^2]: You can deploy up to [500 scripts per account](/workers/platform/limits/), but each script (project) can define multiple Agents. Each deployed script can be up to 10 MB on the [Workers Paid Plan](/workers/platform/pricing/#workers)
-[^3]: Compute (CPU) time per Agent is limited to 30 seconds, but this is refreshed when an Agent receives a new HTTP request, runs a [scheduled task](/agents/examples/schedule-tasks/), or an incoming WebSocket message.
+[^3]: Compute (CPU) time per Agent is limited to 30 seconds, but this is refreshed when an Agent receives a new HTTP request, runs a [scheduled task](/agents/api-reference/schedule-tasks/), or an incoming WebSocket message.
 
 <Render file="limits_increase" product="workers" />
