docs(llamaindex): adding missing shared state doc (CopilotKit#2523)

Signed-off-by: Tyler Slaton <tyler@copilotkit.ai>

Author: tylerslaton

docs/content/docs/llamaindex/meta.json

@@ -13,6 +13,7 @@
     "generative-ui",
     "human-in-the-loop",
     "frontend-actions",
+    "shared-state",
     "multi-agent-flows",
     "---Premium Features---",
     "...premium",

docs/content/docs/llamaindex/shared-state.mdx

@@ -0,0 +1,145 @@
+---
+title: Shared state
+icon: "lucide/Repeat"
+description: Write to agent's state from your application.
+---
+
+<video
+  src="https://cdn.copilotkit.ai/docs/copilotkit/images/coagents/write-agent-state.mp4"
+  className="rounded-lg shadow-xl"
+  loop
+  playsInline
+  controls
+  autoPlay
+  muted
+/>
+<Callout>
+  This video shows the result of `npx copilotkit@latest init` with the [implementation](#implementation) section applied to it!
+</Callout>
+
+## What is this?
+
+This guide shows you how to read and write to your agent's state from your application. LlamaIndex's `get_ag_ui_workflow_router` handler allows you to have stateful concepts that are automatically loaded into the LLM's context.
+
+From the front-end you can modify this state directly or via tools - enabling a bi-directional concept of state.
+
+## When should I use this?
+
+You can use this when you want to provide the user with feedback about what your agent is doing, specifically when your agent is calling tools. CopilotKit allows you to fully customize how these tools are rendered in the chat.
+
+## Implementation
+
+<Steps>
+  <Step>
+    ### Run and Connect Your Agent to CopilotKit
+
+    You'll need to run your agent and connect it to CopilotKit before proceeding. If you haven't done so already,
+    you can follow the instructions in the [Getting Started](/llamaindex/quickstart) guide.
+
+  </Step>
+  <Step>
+    ### Define the Agent State
+
+    First, define the agent's state in the workflow router.
+
+    ```python title="agent/agent/agent.py"
+    from llama_index.llms.openai import OpenAI
+    from llama_index.protocols.ag_ui.router import get_ag_ui_workflow_router
+
+    agentic_chat_router = get_ag_ui_workflow_router(
+      llm=OpenAI(model="gpt-4.1"),
+      system_prompt=SYSTEM_PROMPT,
+      initial_state={
+        "language": "english"
+      },
+    )
+    ```
+
+  </Step>
+  <Step>
+    ### Call `setState` function from the `useCoAgent` hook
+    `useCoAgent` returns a `setState` function that you can use to update the agent state. Calling this
+    will update the agent state and trigger a rerender of anything that depends on the agent state.
+
+    ```tsx title="ui/app/page.tsx"
+    import { useCoAgent } from "@copilotkit/react-core";
+
+    // Define the agent state type, should match the actual state of your agent
+    type AgentState = {
+      language: "english" | "spanish";
+    }
+
+    // Example usage in a pseudo React component
+    function YourMainContent() {
+      const { state, setState } = useCoAgent<AgentState>({
+        name: "sample_agent",
+        initialState: { language: "spanish" }  // optionally provide an initial state
+      });
+
+      // ...
+
+      const toggleLanguage = () => {
+        setState({ language: state.language === "english" ? "spanish" : "english" });
+      };
+
+      // ...
+
+      return (
+        // style excluded for brevity
+        <div>
+          <h1>Your main content</h1>
+          <p>Language: {state.language}</p> // [!code highlight:2]
+          <button onClick={toggleLanguage}>Toggle Language</button>
+        </div>
+      );
+    }
+    ```
+
+  </Step>
+  <Step>
+    ### Give it a try!
+    You can now use the `setState` function to update the agent state and `state` to read it. Try toggling the language button
+    and talking to your agent. You'll see the language change to match the agent's state.
+  </Step>
+</Steps>
+
+## Advanced Usage
+
+### Re-run the agent with a hint about what's changed
+
+The new agent state will be used next time the agent runs.
+If you want to re-run it manually, use the `run` argument on the `useCoAgent` hook.
+
+The agent will be re-run, and it will get not only the latest updated state, but also a **hint** that can depend on the data delta between the previous and the current state.
+
+```tsx title="ui/app/page.tsx"
+import { useCoAgent } from "@copilotkit/react-core";
+import { TextMessage, MessageRole } from "@copilotkit/runtime-client-gql";  // [!code highlight]
+
+// ...
+
+function YourMainContent() {
+  const { state, setState, run } = useCoAgent<AgentState>({
+    name: "sample_agent",
+    initialState: { language: "spanish" }  // optionally provide an initial state
+  });
+
+  // setup to be called when some event in the app occurs
+  const toggleLanguage = () => {
+    const newLanguage = state.language === "english" ? "spanish" : "english";
+    setState({ language: newLanguage });
+
+    // re-run the agent and provide a hint about what's changed
+    run(({ previousState, currentState }) => { // [!code highlight:6]
+      return new TextMessage({
+        role: MessageRole.User,
+        content: `the language has been updated to ${currentState.language}`,
+      });
+    });
+  };
+
+  return (
+    // ...
+  );
+}
+```