🐛 Bug: Docs for useHumanInTheLoop and other new hooks seem to be off

[tamashalasi]

♻️ Reproduction Steps

• Go to https://docs.copilotkit.ai/reference/hooks/useHumanInTheLoop
• Docs suggest using a Zod object for the parameters property, which doesn't work with current version (1.10.6)
• The image on the top is broken (same with useRenderToolCall)
• Navigation on the left is broken, seems like the new hooks are not there yet, even though useCopilotAction already says that it is deprecated and you should use useHumanInTheLoop and the other new hooks instead

✅ Expected Behavior

Working code in docs.

❌ Actual Behavior

Code in docs doesn't work.

𝌚 CopilotKit Version

├── @copilotkit/react-core@1.10.6
├── @copilotkit/react-ui@1.10.6
├── @copilotkit/runtime@1.10.6

📄 Logs (Optional)

[copilotkit-support-bot]

The documentation for useHumanInTheLoop and other new hooks is currently inaccurate and incomplete in version 1.10.6. The docs incorrectly suggest using a Zod object for parameters, navigation is missing the new hooks, and there is a broken image reference.

Details

Current Status & Issues Found

1. Navigation Issue - ROOT CAUSE 🚨

• Problem: New hooks exist as documentation files but are missing from the navigation configuration
• Root Cause: docs/content/docs/reference/hooks/meta.json only contains old hooks
• Missing Hooks: useHumanInTheLoop, useFrontendTool, useRenderToolCall, useDefaultTool

2. Parameter Type Mismatch - DOCUMENTATION ERROR 🚨

• Problem: Documentation incorrectly shows Zod object syntax (z.object())
• Reality: All hooks use Parameter[] type, not Zod objects
• Source Code Evidence:

export function useHumanInTheLoop<const T extends Parameter[] | [] = []>
export function useFrontendTool<const T extends Parameter[] | [] = []>  
export function useRenderToolCall<const T extends Parameter[] | [] = []>

3. Broken Image Reference

• Issue: Image link https://cdn.copilotkit.ai/docs/copilotkit/images/human-in-the-loop/hitl-example.gif appears to be inaccessible

Required Fixes

Fix 1: Update Navigation Configuration

File: docs/content/docs/reference/hooks/meta.json

Add the missing hooks to the meta.json file:

{
  // ... existing hooks ...
  "useHumanInTheLoop": {
    "title": "useHumanInTheLoop"
  },
  "useFrontendTool": {
    "title": "useFrontendTool" 
  },
  "useRenderToolCall": {
    "title": "useRenderToolCall"
  },
  "useDefaultTool": {
    "title": "useDefaultTool"
  }
}

Fix 2: Correct Documentation Examples

Files: All new hook documentation files in docs/content/docs/reference/hooks/

Replace Zod syntax with correct Parameter[] syntax:

Incorrect (current docs):

const { humanInTheLoop } = useHumanInTheLoop({
  parameters: z.object({
    query: z.string().describe("The user's search query")
  })
});

Correct:

const { humanInTheLoop } = useHumanInTheLoop({
  parameters: [
    {
      name: "query",
      type: "string", 
      description: "The user's search query"
    }
  ]
});

Fix 3: Image Reference

• Action: Verify and fix the broken image URL or replace with working alternative
• File: docs/content/docs/reference/hooks/useHumanInTheLoop.mdx

Workaround for Current Version 1.10.6

Until the documentation is fixed, use the correct Parameter[] syntax:

import { useHumanInTheLoop } from "@copilotkit/react-core";

const { humanInTheLoop } = useHumanInTheLoop({
  parameters: [
    {
      name: "query",
      type: "string",
      description: "The search query to process"
    }
  ]
});

Documentation References

• Hook Implementation: Source Code
• Documentation: Hook Reference (once navigation is fixed)

Confidence Level: High - Issues confirmed through source code analysis and navigation configuration inspection.

---

Was this helpful?

If this solution worked for you, please click on the appropriate option below to help us improve:

✅ Issue Solved | ❌ Need more help

[tamashalasi]

Yeah, using the parameters array works indeed, but docs have to be fixed. Btw is providing a Zod object as parameters going to be a feature at some point?

[copilotkit-support-bot]

👋 Thanks for your feedback!

I've escalated this issue to our development team. Someone from our team will review your request and provide additional assistance shortly.

If this is blocking production, please book a meeting with us at https://cal.com/nathan-tarbert-copilotkit/15min

[ziggy6792]

Here is a workaround for now
Wrapped it in useValidatedHumanInTheLoop which does work as the docs show

https://gist.github.com/ziggy6792/131179eefc3f54317f29e55e7477bcae

[rtruong]

Please add first class support for Zod schemas. Zod can describe more complex schemas that can't be translated by jsonSchemaToActionParameters(). For example, there's no way to specify discriminated unions using the action parameter types.