OZY AI Agent
| 开发者 | idanishrangaiz |
|---|---|
| 更新时间 | 2026年11月14日 02:16 |
| PHP版本: | 7.4 及以上 |
| WordPress版本: | 7.1 |
| 版权: | GPLv2 or later |
| 版权网址: | 版权信息 |
详情介绍:
OZY AI Agent puts a real AI agent on your WordPress site — not just a chatbot. A chatbot answers from text; an agent uses tools to fetch live data from your site and perform actions for the visitor. Every action that changes something (cart, coupon, order, enquiry) only happens after the visitor taps Confirm — the model can never act on its own.
It adapts to your site automatically:
- Online stores (WooCommerce) — a shop assistant that searches your catalogue with real prices and stock, compares products, says which colours and sizes are in stock, explains shipping, adds items to the cart, applies coupons, sends shoppers to checkout (or, opt-in, takes the whole order inside the chat), and tracks orders after verifying the customer.
- Service businesses — explains your services from your own pages, answers FAQs, and turns interest into an enquiry emailed to you or a booked call.
- Blogs and information sites — finds the right page or article and summarises what your site says.
search_site,read_page— search and read your public pages and postshandoff— WhatsApp, email and booking buttons with a conversation summarysend_enquiry(Confirm) — emails the visitor's enquiry to youreport_gap— logs questions your site could not answer to the Content Gaps screen- WooCommerce:
search_products,get_product,compare_products,list_attribute_values,get_shipping_info,get_cart,add_to_cart(Confirm),update_cart_item(Confirm),apply_coupon(Confirm),checkout,track_order
- Confirm-before-act — state-changing tools return a Confirm button instead of running.
- Cart and checkout run through WooCommerce's own Store API in the visitor's browser, so your stock, coupon, shipping, tax and payment rules always apply. The plugin never writes carts or orders itself.
- Price guard — if a reply mentions a price no tool returned, the agent must rewrite it; if it still does, that sentence is removed.
- Order tracking is verified — order number plus billing email or phone; five failed tries per hour lock the visitor out; addresses and payment details are never shown.
- Honest — if asked, the agent says it is an AI assistant for your business.
- Page-cache safe — no nonce is printed into your HTML; the widget fetches a fresh session when it opens.
- Five AI providers with fallback order and free-text model IDs: OpenAI, Claude, Groq, Gemini, Mistral (Groq, Gemini and Mistral have free tiers)
- Exact provider errors for the admin (on the dashboard and plugin screens) while visitors see a friendly message
- Floating launcher, popup and inline chat; Gutenberg, Elementor, Divi, Avada and WPBakery elements;
[oozzy_ai_agent]and[ozy_agent_ask]shortcodes - "Ask AI about this product" button on WooCommerce product pages (optional)
- Replies in the visitor's language, including Urdu, Roman Urdu, Hindi and Arabic; RTL aware
- Voice input (Groq Whisper) and spoken replies
- Analytics: conversations, replies using live data, add-to-carts and orders via chat, handoffs, unanswered questions, tokens per provider
- Optional Google Analytics / Tag Manager events:
oozzy_open,oozzy_message,view_item,add_to_cart,begin_checkout,purchase,oozzy_handoff - HPOS and Cart/Checkout blocks compatible
- Streaming replies — text appears as it is written, and visitors see what the agent is doing ("Searching products…", "Checking delivery options…")
- WordPress 7 AI connectors — if a connector is set up under Settings → Connectors, the agent uses it first and your own keys become the fallback
- Optional conversation storage with a retention period, full transcripts in Analytics, and WordPress personal-data export and erase
- Install and activate — the Setup Wizard opens
- Pick your site type (store, service business or blog); the agent gets matching defaults
- Add a line about your business and contact details
- Paste one API key (Groq is free) — the wizard scans your site and tests the connection
add_action( 'oozzy_register_tools', function () { OOZZY_Tools::register( [ 'name' => 'calculate_fabric', 'description' => 'Metres of fabric needed for a garment.', 'parameters' => [ 'type' => 'object', 'properties' => [ 'height_cm' => [ 'type' => 'integer' ] ], 'required' => [ 'height_cm' ] ], 'callback' => function ( $args, $ctx ) { return [ 'metres' => 4.5 ]; }, 'confirm' => false, ] ); } );
Filters: oozzy_tools, oozzy_system_prompt, oozzy_messages, oozzy_tool_result, oozzy_response, oozzy_client_ip, oozzy_product_fields, oozzy_product_card, oozzy_product_search_handler, oozzy_order_lookup_allowed, oozzy_find_order, oozzy_order_view, oozzy_phone_normalize, oozzy_inchat_gateways, oozzy_currency_markers, oozzy_page_content, oozzy_context_chars, oozzy_time_budget, oozzy_front_config.
Actions: oozzy_register_tools, oozzy_tool_called, oozzy_action_confirmed, oozzy_conversation_ended, oozzy_gap_logged, oozzy_lead_captured, oozzy_handoff.
JavaScript: window.OzyAgent.open( { prompt, context: { productId } } ), OzyAgent.send( text ), OzyAgent.close(). Window events: oozzy:open, oozzy:message, oozzy:card_click, oozzy:action_confirmed, oozzy:handoff.
API keys can be set in wp-config.php instead of the database: OOZZY_GROQ_KEY, OOZZY_GEMINI_KEY, OOZZY_MISTRAL_KEY, OOZZY_OPENAI_KEY, OOZZY_CLAUDE_KEY.
POST /wp-json/oozzy/v1/chat with "stream": true answers as text/event-stream: status events while tools run, delta text as the model writes, reset when a fallback provider takes over, then one done event carrying the full response.
Tests: composer install, bin/install-wp-tests.sh <db> <user> <pass>, then vendor/bin/phpunit.
If OZY Smart Search is active, product search uses its ozy_smart_search_query() engine automatically.
Shortcodes
[oozzy_ai_agent] — inline chat panel
[oozzy_ai_agent mode="button" label="Chat with us"] — button that opens the popup
[oozzy_ai_agent mode="loader"] — load the floating widget on this page only
[ozy_agent_ask product="current" label="Ask AI about this product"] — opens the chat about a product
安装:
- Upload the
ozy-chat-assistantfolder to/wp-content/plugins/ - Activate the plugin through Plugins → Installed Plugins
- Configure at OZY AI Agent in the admin sidebar
屏幕截图:
常见问题:
Can the agent place orders or change carts by itself?
No. Tools that change anything return a Confirm button. Nothing happens until the visitor taps it, and the change itself is made by WooCommerce's Store API in the visitor's own browser session.
Will it answer questions that have nothing to do with my site?
No. It declines requests such as writing code, homework or general knowledge questions and brings the conversation back to your business.
Can it make up prices?
Prices, stock, coupons and delivery times must come from tool results. The price guard checks every reply and removes amounts no tool returned.
Does it work with page caching?
Yes. The page HTML contains no nonce; the widget asks for a fresh one when it opens.
My site is not a shop. Is this still useful?
Yes. Service sites get enquiries and bookings, blogs get a guide to their content. Choose or confirm the site type under Tools & Store.
How do I place orders in the chat?
Turn on Place orders inside the chat under Tools & Store. Payment methods that need no redirect (Cash on delivery, Bank transfer, Cheque) are offered in the chat; for any other method the visitor is sent to your checkout page.
Why did the agent say it is having trouble?
Every configured provider failed. The exact reason is shown to administrators on the WordPress dashboard and on the plugin screens. Use Test connection on the AI Provider screen.
The plugin used to be called OZY Chat Assistant — is this the same plugin?
Yes. The slug and folder stay ozy-chat-assistant, so updates arrive normally and settings carry over.
Do I need all five API keys?
No. One working key is enough; others are used as fallbacks. For tool use, Groq (openai/gpt-oss-120b), Gemini Flash, GPT-4o mini and Claude Haiku all work well. On WordPress 7 you can also use a connector from Settings → Connectors instead of a key.
Replies appear all at once instead of streaming
Some hosts, proxies or caching layers buffer responses. The chat still works; the reply simply arrives in one piece. You can turn streaming off under AI Provider.
更新日志:
4.1.0
- New: streaming replies. Text appears as the model writes it, and the visitor sees what the agent is doing while tools run. Works with Groq, OpenAI, Mistral, Claude and Gemini, and falls back to a single reply where the server buffers output.
- New: WordPress 7 AI connectors. When a connector under Settings → Connectors has credentials, the agent uses it first (with tool calling) and your own keys become the fallback. Toggle on the AI Provider screen.
- New: setup wizard on first activation — site type, business basics and one API key, then defaults for that kind of site, a site scan and a connection test.
- New: optional conversation storage with a retention period (default 30 days), transcripts on the Analytics screen, WordPress personal-data export/erase and suggested privacy-policy text. Off by default.
- New: PHPUnit test suite (tool registry, schema validation, tool loop with a fake provider, WooCommerce tools on fixture products, order verification, rate limits, price guard, streaming, privacy).
- Fixed: the price guard missed amounts written with a narrow or non-breaking space (e.g. "Rs 3,750" as some models write it).
- Fixed: default Groq and Gemini models were retired by the providers. New defaults are
openai/gpt-oss-120b(Groq) andgemini-flash-latest(Gemini); sites still set to a retired default are moved automatically. - Fixed: a reply could crash with a PHP time-limit error when one provider was slow. Each reply now has a 24-second budget (filter
oozzy_time_budget). - Fixed: Groq rejected whole replies when the model sent an out-of-range or wrongly typed tool argument. Limits are no longer sent to the model, values are clamped on the server, and a rejected tool call is retried once.
- Improved: short automatic retry when a provider asks to wait (rate limit) or is briefly overloaded.
- Improved: smaller tool definitions, so each reply uses fewer tokens and free-tier limits last longer.
- Improved: replies follow the visitor's language and script more strictly (Roman Urdu stays in Latin letters).
- Improved: the agent no longer says an item was added before the visitor taps Confirm, and suggestion chips are parsed reliably.
- Fixed: a "translation loaded too early" notice under WP_DEBUG.
- New: the chatbot is now an agent with tools and tool calling for OpenAI, Groq, Mistral, Claude and Gemini.
- New: WooCommerce module — product search with real prices and stock, product details and variations, comparisons, in-stock colours/sizes, categories, shipping info, cart, coupons, checkout and verified order tracking. Product cards in the chat.
- New: confirm-before-act. Cart, coupon, order and enquiry actions only run after the visitor taps Confirm; cart and checkout go through the WooCommerce Store API.
- New: opt-in order placement inside the chat for payment methods that need no redirect.
- New: site type (store, service, blog) detected automatically; the agent's job and tools follow it. Strict scope: unrelated requests such as writing code are declined.
- New: enquiries emailed to you, human handoff buttons (WhatsApp, email, booking), suggested-reply chips.
- New: Content Gaps screen with CSV export; agent analytics (live-data replies, add-to-carts, orders, handoffs, unanswered, tokens).
- New: price guard for store replies.
- New: REST API (
oozzy/v1) with a cache-safe session, signed actions and a real client IP option for sites behind Cloudflare/proxies. - New: tool registry and hooks for developers;
window.OzyAgentJS API and events; GA4/GTM events. - New: "Ask AI about this product" button and
[ozy_agent_ask]shortcode. - New: API keys can be defined in wp-config.php.
- Changed: the prompt no longer tells the agent to hide that it is an AI; it says so when asked.
- Changed: administrators see the exact provider error; visitors see a friendly message.
- Changed: Gemini API key is sent in a header instead of the URL.
- Changed: new installs default to a light theme and do not auto-open. Existing sites keep their current look.
- Changed: the website scan reads more of each page plus shipping, returns and policy pages.
- Fixed: boolean widget settings (floating launcher, auto-open) were passed to the browser as strings.
- Declared compatibility with WooCommerce HPOS and Cart/Checkout blocks.
- Fixed: the microphone and send buttons could pick up the active theme's button hover colours (Elementor and similar). Their colours are now painted from the plugin's own variables in every state.
- Renamed: the plugin is now OZY AI Agent. The directory slug, folder name and text domain remain
ozy-chat-assistant, so this is a normal update and all settings are preserved. - Added: drag-and-drop elements for Gutenberg, Elementor, Divi, Avada (Fusion Builder), WPBakery and classic widget areas — all rendering identical markup.
- Added: inline chat mode. The agent can now be embedded directly in the page flow instead of only opening as a popup; the popup and floating launcher are unchanged and still independent.
- Added:
mode,height,title,labelandquickattributes on the[oozzy_ai_agent]shortcode. - Changed: model selection is now a free-text field for every provider instead of a fixed dropdown, so new model releases work without waiting for a plugin update. Keys and model IDs sit together on one screen.
- Added: multi-screen dashboard — Dashboard, AI Provider, AI Agent, Widget Settings, URL Index, Analytics and Help & Setup — with a redesigned interface and a new sidebar icon.
- Added: Analytics screen with total, daily and monthly conversation counts, average response time, success rate, per-provider usage, a 14-day chart, most-asked questions and recent conversations. All data is stored locally and can be deleted or switched off.
- Added: connection tester for each provider that surfaces the provider's own error message.
- Added: rate limiting controls — requests per minute per visitor, plus optional daily and monthly caps for the whole site.
- Added: media-library uploader for the agent icon, replacing the URL-only field (pasting a URL still works).
- Added: full colour control — accent, panel background, text, visitor bubble and launcher colours, corner radius, screen offsets, light/dark base theme and six presets, with a live preview that updates as you edit.
- Added: URL Index screen listing exactly what was indexed, with per-entry source links and character counts.
- Added: quick-question chips, a custom welcome message, an agent role subtitle, an optional launcher label, and a hide-on-mobile option.
- Added: max reply length and creativity controls.
- Improved: streaming now reports which provider answered, and failed requests surface the provider's HTTP error in the log.
- Improved: the front-end widget markup and stylesheet were rebuilt so the panel, popup and inline embed share one design system.
- Removed: the automatic visibility "repair" routine, which prevented administrators from turning every display mode off on purpose.
- Fixed: the "Powered by OZY" credit no longer appears on the front-end chat widget by default. As required by the WordPress.org plugin guidelines, attribution on user-facing interfaces is now strictly opt-in.
- Added: a "Show 'Powered by OZY' Credit" toggle (off by default) in the Appearance tab. Site administrators must intentionally enable it for the credit to display.
- Changed: renamed the plugin to "OZY Chat Assistant" with the slug
ozy-chat-assistant; the text domain now matches the slug. - Changed: replaced all short
ozy/OZY_code prefixes with the uniqueoozzy/OOZZY_prefix on functions, classes, options, transients, nonces, AJAX actions, and the shortcode (now[oozzy_ai_agent]). - Changed: all upstream AI and voice requests now use the WordPress HTTP API (
wp_remote_post()) exclusively; removed all direct cURL calls. - Changed: voice transcription now uploads audio via a multipart HTTP request instead of writing a temporary file to disk.
- Removed:
load_plugin_textdomain()call — WordPress.org loads translations automatically since WP 4.6. - Fixed: corrected the Mistral terms/privacy URLs to the working Legal Center links.
- Fixed: replaced direct
<style>tag output withwp_add_inline_style()for the accent color CSS variables, as required by WordPress.org guidelines. - Fixed: updated Contributors field to correct WordPress.org username
idanishrangaiz. - Fixed: updated broken Mistral terms/privacy URLs in readme.txt.
- Fixed: replaced heredoc (<<<EOT) string syntax in the system-prompt builder with standard string concatenation, to satisfy the WordPress.org Plugin Check (PluginCheck.CodeAnalysis.Heredoc.NotAllowed).
- Fixed: bumped "Tested up to" header to 7.0 to match the current WordPress release ("Armstrong").
- Fixed: added the missing
languages/directory (with aozy-chat-assistant.pottranslation template) so theDomain Path: /languagesheader in the plugin file now resolves to an existing folder.
- Removed: developer-promotion text that was injected into the AI system prompt. The AI no longer mentions the plugin author to your visitors.
- Removed: "Allow External Suggestions" setting (no longer needed). Setting default changed to off for any existing installs.
- Changed: chat widget footer simplified to "Powered by OZY" (brand only, no link, no full plugin name).
- Removed: developer bio and "Contact" CTA button from the admin Guide tab. Author info is available via the plugin page on WordPress.org instead.
- Removed: unused
standalone/folder (Vercel/Node.js demo code unrelated to the WordPress plugin). - Improved: added an "External Services" section to readme that fully discloses every third-party endpoint contacted and exactly what data is transmitted.
- Improved: added an inline reviewer-facing comment in
class-ozy-api.phpexplaining why cURL is used in the SSE streaming path (WP HTTP API does not support response streaming). - Improved: reduced readme tags to 5 (WP.org limit) and bumped "Tested up to" to 6.8.
- Fixed: popup modal background appeared transparent on some themes — CSS variables now resolve correctly for the modal.
- Fixed: voice (mic) button no longer shows an oversized dark hover background; hover now only changes the icon color.
- Improved: chat input field is taller and wider with better padding for easier typing on both desktop and mobile.
- Improved: voice mic button is more compact (28px), giving the text input more room.
- Improved: input row uses center alignment and tighter spacing for a more polished look.
- Fixed: admin settings tab links now point to the correct top-level admin URL (admin.php instead of options-general.php).
- Fixed: resolved leftover merge artifacts in CSS that were breaking widget styling in certain browsers.
- Fixed: saving settings on one tab (e.g. AI Providers) no longer resets toggles from other tabs (floating enable, popup enable, site-wide, auto-open).
- Added: auto-repair that restores visibility settings if all three are found to be off simultaneously.
- Improved: nonce verification now uses check_ajax_referer() for AJAX handlers.
- Improved: basic per-IP rate limiting (30 req/min for chat, 10 req/min for voice).
- Improved: MIME type validation and audio size check for voice transcription.
- Improved: removed all error-suppressor (@) operators; output buffering checked before flushing.
- Improved: user message bubble now renders in solid black bold text for better readability.
- Security: escHtml() now escapes double and single quotes to prevent attribute injection.
- Added OpenAI (GPT-4o Mini, GPT-4o, GPT-3.5 Turbo) support
- Added Claude (Haiku, Sonnet, Opus) support
- Added configurable provider priority order
- Added automatic website content reader (pages, posts, products, menus)
- Redesigned dashboard with aesthetic card-based UI
- Added dual widget modes: floating button and popup modal, each independently togglable
- Added business knowledge base field
- Added external suggestions toggle
- Added agent icon URL field
- Removed contact form auto-fill (now pure AI conversation agent)
- Streaming support for all providers
- Improved system prompt with site context injection
- Updated to GPL-2.0-or-later license
- Initial release