{"_id":"@cago-frame/agents-client","name":"@cago-frame/agents-client","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@cago-frame/agents-client","version":"0.1.0","description":"Headless UI library for Cago Agents - React hooks and adapters for AI agent conversations","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"scripts":{"dev":"vite","build":"tsc -p tsconfig.build.json && vite build","test":"vitest run","test:watch":"vitest","lint":"eslint src/ __tests__/","format":"prettier --write 'src/**/*.{ts,tsx}' '__tests__/**/*.{ts,tsx}'"},"peerDependencies":{"react":">=18.0.0","react-dom":">=18.0.0"},"devDependencies":{"@testing-library/react":"^16.1.0","@testing-library/jest-dom":"^6.6.0","@types/react":"^18.3.0","@types/react-dom":"^18.3.0","@typescript-eslint/eslint-plugin":"^8.0.0","@typescript-eslint/parser":"^8.0.0","eslint":"^8.57.0","eslint-config-prettier":"^9.1.0","eslint-plugin-react-hooks":"^4.6.0","jsdom":"^25.0.0","prettier":"^3.4.0","react":"^18.3.0","react-dom":"^18.3.0","typescript":"^5.6.0","vite":"^6.0.0","vite-plugin-dts":"^4.3.0","vitest":"^2.1.0"},"pnpm":{"onlyBuiltDependencies":["esbuild"]},"keywords":["ai","agent","chat","react","headless","sse","openai","streaming"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/cago-frame/agents.git"},"_id":"@cago-frame/agents-client@0.1.0","gitHead":"d9cc96a934ba9223e5cabe60771442d7f438a7e3","bugs":{"url":"https://github.com/cago-frame/agents/issues"},"homepage":"https://github.com/cago-frame/agents#readme","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-lX2bm9farjntgVRXj6G3Fz8pqRB8NSbnjnJr/Rm9qXpDSIyhpvXg0/UBjf/OX8H7hUaP4rpLDVm2+oBXa35e5Q==","shasum":"8b07902978d252979ce7445986523fc188ec4a3a","tarball":"https://registry.npmjs.org/@cago-frame/agents-client/-/agents-client-0.1.0.tgz","fileCount":7,"unpackedSize":207683,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIB2ZEZWmNxDYE8qKzHinrPJVQz/PwLBXuaKRPm3CZ9xrAiEA/w0vH4bE+udiZgeM8kW53VQZx4Ywp9E2EDhSItolC8g="}]},"_npmUser":{"name":"codfrm","email":"code.farmer@qq.com"},"directories":{},"maintainers":[{"name":"codfrm","email":"code.farmer@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agents-client_0.1.0_1772694967309_0.6308064748349607"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-05T07:16:07.115Z","0.1.0":"2026-03-05T07:16:07.479Z","modified":"2026-03-05T07:16:07.747Z"},"maintainers":[{"name":"codfrm","email":"code.farmer@qq.com"}],"description":"Headless UI library for Cago Agents - React hooks and adapters for AI agent conversations","homepage":"https://github.com/cago-frame/agents#readme","keywords":["ai","agent","chat","react","headless","sse","openai","streaming"],"repository":{"type":"git","url":"git+https://github.com/cago-frame/agents.git"},"bugs":{"url":"https://github.com/cago-frame/agents/issues"},"license":"MIT","readme":"# @cago/agents-client\n\n一个用于构建 AI Agent 聊天界面的 React Headless UI 库。提供 hooks、context、无样式组件和流式传输适配器 —— 样式完全由你掌控。\n\n## 特性\n\n- **Headless UI 组件** — 无样式、基于 render-prop 的组件（`ChatRoot`、`MessageList`、`MessageInput` 等），完全控制渲染输出\n- **React Hooks** — `useChat`、`useMessages`、`useStream`，灵活的状态管理\n- **流式传输** — 内置 SSE 流式传输，支持实时文本增量更新\n- **适配器模式** — 可插拔的适配器接口，内置 OpenAI 兼容适配器\n- **Tool Calls** — 原生支持函数/工具调用消息\n- **TypeScript** — 完整的类型定义\n\n## 安装\n\n```bash\nnpm install @cago/agents-client\n# 或\npnpm add @cago/agents-client\n```\n\n需要 peer dependencies：`react >= 18.0.0`、`react-dom >= 18.0.0`\n\n## 快速开始\n\n```tsx\nimport {\n  ChatProvider,\n  createOpenAIAdapter,\n  ChatRoot,\n  MessageList,\n  MessageInput,\n  SendButton,\n} from '@cago/agents-client';\n\nconst adapter = createOpenAIAdapter({\n  baseUrl: 'https://api.openai.com/v1',\n  apiKey: 'sk-...',\n  model: 'gpt-4',\n});\n\nfunction App() {\n  return (\n    <ChatProvider adapter={adapter}>\n      <ChatRoot>\n        <MessageList>\n          {({ messages }) =>\n            messages.map((msg) => (\n              <div key={msg.id}>\n                <strong>{msg.role}:</strong> {msg.content}\n              </div>\n            ))\n          }\n        </MessageList>\n        <MessageInput>\n          {({ inputProps }) => <input {...inputProps} placeholder=\"输入消息...\" />}\n        </MessageInput>\n        <SendButton>\n          {({ buttonProps }) => <button {...buttonProps}>发送</button>}\n        </SendButton>\n      </ChatRoot>\n    </ChatProvider>\n  );\n}\n```\n\n## Hooks\n\n### `useChat()`\n\n核心 hook，提供消息列表、状态和操作方法。\n\n```tsx\nconst { messages, status, error, sendMessage, abort, retry } = useChat();\n```\n\n### `useMessages()`\n\n直接访问和操作消息列表。\n\n```tsx\nconst { messages, setMessages, appendMessage } = useMessages();\n```\n\n### `useStream()`\n\n流式传输状态和控制。\n\n```tsx\nconst { isStreaming, status, abort, retry } = useStream();\n```\n\n## Headless 组件\n\n所有组件均支持 **render-prop** 模式，只暴露状态而不附带任何样式：\n\n| 组件 | 说明 |\n| --- | --- |\n| `ChatRoot` | 容器组件，带有 `data-status` 属性，支持多态 `as` prop |\n| `MessageList` | 通过 render-prop 渲染消息列表 |\n| `MessageItem` | 单条消息，暴露 role/content 等 render props |\n| `MessageInput` | 受控输入框，内置提交处理 |\n| `SendButton` | 发送按钮，自动管理 disabled 状态 |\n| `StreamControl` | 流式传输的中止/重试控制 |\n| `MarkdownContent` | 通过 render-prop 渲染 Markdown 内容 |\n\n## 自定义适配器\n\n实现 `ChatAdapter` 接口即可对接任意 LLM 后端：\n\n```ts\nimport type { ChatAdapter, ChatStreamEvent, SendMessageParams } from '@cago/agents-client';\n\nclass MyAdapter implements ChatAdapter {\n  async *sendMessage(params: SendMessageParams): AsyncIterable<ChatStreamEvent> {\n    // yield { type: 'text-delta', content: '...' }\n    // yield { type: 'tool-call', toolCall: { ... } }\n    // yield { type: 'finish' }\n  }\n\n  abort() {\n    // 取消请求\n  }\n}\n```\n\n## 许可证\n\nMIT\n","readmeFilename":"README.md","_rev":"1-0da33852a0e27b493c9733f842d8309d"}