Common Questions
Who This Is For
This page is for every reader of the xAgent documentation.
What It Is
This page provides centralized answers to common questions about using xAgent and reading the manual.
When to Use It
Check this page first when you do not know where to start, whether a capability is stable, or which page to read.
Basic Usage
Which pages should I read first?
Start with What Is xAgent and Feature Overview and Menu Entries. Then continue with Your First Task or Tasks, depending on your needs.
Why are some pages marked experimental or planned?
Those capabilities may still change. The manual explains their available boundaries without presenting unstable interfaces as commitments.
Do ordinary users need to understand AI technology?
No. Ordinary users only need to describe goals, provide materials, confirm necessary actions, and review results. Administrators or maintainers handle models, protocols, implementation details, and extensions.
Why do some pages use English names?
Some menu items use English names, such as Agent Session, Skill Management, and MCP Configuration. The manual explains them by purpose and does not require ordinary users to understand the underlying technical meaning.
Does the documentation site include login, comments, or a plugin marketplace?
No. The documentation site is a static manual.
Is the current release stable?
The current version is v0.0.6.beta. It is still a beta release intended for deployment trials, scenario validation, and community feedback. The interface, Connectors, and some experimental capabilities may still change.
How should I install or upgrade xAgent?
Use the official installer:
curl -fsSL https://downloads.xagent.xiagaogao.com/scripts/install.sh | bash
The script detects the operating system and architecture, verifies release packages, and supports pinned versions, unattended installation, and Connector selection. On Linux, it attempts to restore the previous version if activation fails. See Start Installation for the complete flow.
Is ProcessSandbox the same as Workspace isolation?
No. Workspace isolation determines which files a user and Session can see, read, and write. ProcessSandbox controls which files an external command actually mounts, which environment it inherits, and its process-tree and resource limits.
Questions Consolidated from Other Pages
The following questions were previously spread across Getting Started, User Guide, Deployment, Architecture, Developer Guide, and Reference pages. They are now collected here.
Does xAgent store the target system token for a Connector?
It should not be described that way. A target-system token belongs to the Connector or target-system boundary.
Must a Connector provide a Skill?
It may provide one, but that is not its only responsibility.
Is the Connector protocol fully stable?
It is currently marked experimental and may change.
Is long-term Memory the same as Session history or context compression?
No. Long-term Memory carries explicitly retained preferences, decisions, and boundaries across Sessions. Session history records the current interaction, while context compression allows a long Session to continue.
Does xAgent automatically write chat content to long-term Memory?
No. xAgent registers a background write only when the current user message explicitly asks it to remember, store, or retain something across Sessions. See Long-Term Memory for the complete usage boundaries.
Can older Memory override the current request?
No. Current user input, Tool results, permissions, and system rules take priority. Stale, conflicting, or low-confidence Memory also cannot be treated directly as a confirmed fact.
Can every capability be treated as an Agent responsibility?
No. An Agent is the execution owner, but different facts have their own owners.
Does architecture documentation always match the current implementation?
Not necessarily. Content marked experimental may describe a target architecture or boundaries that are still being consolidated.
What should be done when adding an architecture term?
Update the Glossary at the same time.
Does a SubAgent use a separate Session?
The current implementation uses a separate sub-Session to hold a SubAgent's goal, state, Tools, and results. The main Session creates and consolidates it when the Task requires delegation.
Can a SubAgent bypass the main Agent directly?
It should not be described that way. Long-task decomposition remains subject to platform governance.
Is SubAgent stable?
It is currently treated as an experimental capability.
Can a Tool execute outside a Session?
It should not be designed that way. Tool calls should occur within an explicit context and governance boundary.
Should a Tool store business facts?
Usually not. Business facts should belong to an explicit owner.
Where should I inspect a Tool error?
Start with the Tool result and error message in the current Session. Deployment maintainers can also use service logs for diagnosis. There is no stable public error-code table yet.
Must I use Qwen3.6-27B?
No. It is only one model used in the current development and testing environment under resource constraints, not a recommended configuration. Any model with sufficient context, stable Tool calling, and reliable reasoning can be connected for testing.
Can small models be used?
Yes. Smaller models tested so far include Gemma4-12B, which can also execute long-running tasks. Smaller models place higher demands on complex reasoning, multi-Tool planning, long-context retention, and Skill creation stability, so validate them with real tasks before making them available to ordinary users.
Is a 64k context window enough?
It can serve as a minimum recommendation, but it is not suitable for every task. xAgent's initial context may approach 20k, and file summaries, Tool results, Session history, and user additions continue to consume context during a task. A context window above 100k is recommended for complex work.
If the model service supports prompt-prefix caching, the repeated cost of fixed prompts and default Tool descriptions is significantly lower. Current testing usually reaches a cache rate above 90%, but the context window still determines how much useful information a long task can retain.
Why is Tool calling required?
xAgent is not a chat-only system. It needs to read files, write to the Workspace, call MCP, use Connectors, process Triggers, and generate artifacts. Many tasks cannot be completed reliably without stable Tool calling.
Does context compression affect results?
It can. Context compression lets long tasks continue, but compressed content is a summary rather than the complete source. Long-context models are therefore better suited to complex tasks and reduce information loss caused by early compression.
Does xAgent store target-system login state?
It should not be designed that way. Target-system login state belongs to the Connector or target system.
Can an Agent see connector_channel_id?
An Agent should not see internal system-level or channel-level IDs.
Is a Connector the same as a Skill?
No. A Connector may provide a Skill, but the Connector itself is a protocol bridge to an external system.
Can fields from another project's manifest be used as a reference?
They can be used as a reference, but they must not be added to official xAgent documentation unless xAgent implements them.
Is a Manifest used only for Skills?
The documentation should not impose that restriction in advance. Ownership depends on the implementation.
Does adding a field require updating the Glossary?
If the field introduces a new term, update the Glossary as well.
Is RuntimeConnection the same as Connector?
No. Connector connects an external system, while RuntimeConnection focuses on an execution environment.
Can an integration protocol be documented before implementation?
No. Keep only conceptual boundaries until the protocol is stable.
Is RuntimeConnection always exposed to an Agent?
Not necessarily. An Agent usually sees a Tool rather than the underlying execution environment.
Is a Skill the same as a plugin?
No. A Skill primarily describes task methods and Tool usage guidance.
Can a Skill execute code directly?
It should not be described that way. Execution capability should belong to a Tool or RuntimeConnection.
Can a Skill come from a Connector?
It can serve as runtime guidance that a Connector provides to an Agent, but the concrete format depends on the implementation.
Are unit tests required for Markdown?
Not currently. A successful build and link checks are the minimum requirements.
How should the search plugin be verified?
First confirm that npm run build passes, then verify the search box in a local server or preview.
How is documentation accuracy verified?
For behavior, commands, configuration, or APIs, check the xAgent main repository code or existing stable documentation.
What is the difference between a Skill and a Tool?
A Tool is a concrete action that can be invoked. A Skill describes how to complete a type of task and may guide an Agent to combine multiple Tools.
Is a Session the same as a Task?
No. A Session is an ongoing work context, while a Task is a goal to complete. Multiple Tasks can be advanced in one Session.
Is Memory the same as chat history?
No. Chat history belongs to the current Session, while Memory supports long-term context and reuse across Tasks.
Must I create an Agent before starting?
No. Most first Tasks can be completed directly in the default Session.
What is the relationship between an Agent and a Session?
An Agent performs the work, while a Session carries the context. An Agent can work in a Session, but files, history, Tool state, and user additions in the current Session still belong to the Session context.
When are multiple Agents useful?
Use multiple Agents or expert Sessions when different Tasks require different roles, Tool combinations, permission boundaries, or output conventions.
Is a Task always split into many steps?
No. Simple Tasks are usually completed directly. Work is more likely to proceed in stages when it has many materials, complex steps, or intermediate confirmations.
Is a Task the same as one user message?
No. A user message may create a new Task, add materials, revise requirements, or confirm one step.
What should a good Task include?
At minimum, include the goal, materials, constraints, and delivery format. The more Tool or file processing a Task requires, the more clearly its input source and result format should be described.
Is xAgent a chatbot?
No. Chat is only one entry point. xAgent focuses on completing work: reading materials, generating files, waiting for confirmation, connecting external systems, and archiving results. It can chat, but the product goal is work completion rather than casual conversation.
Does xAgent need to be installed on every computer?
No. xAgent is deployed on a server and users access it through the web or extended Connectors. A user's computer does not need to remain on while a Task runs, and users can submit Tasks remotely through IM entry points such as WeChat.
Where are Task files stored?
Task files and artifacts are stored centrally in the server Workspace and isolated by user. Users can see only their own Workspace and files within their authorized scope.
Can data be fully private?
Using a local model or self-hosted model service can keep Task data in the team's own environment. Complete privacy also depends on the model, external connections, deployment method, and administrator configuration.
Are Secrets sent to model providers?
Normally, no. xAgent Tool configuration uses Secret placeholders, and actual values are substituted only during internal Tool calls. Model providers do not need to see actual Secret values. Users should not put Secrets, tokens, or passwords in plain text in Task messages.
Does xAgent have Memory?
Yes. xAgent has basic Memory capability. Memory is shared within a user's scope and stores preferences, long-term background, and repeatedly used information. Users can also extend their own Memory system through MCP. xAgent may later expose Memory interfaces so third-party Memory systems can connect directly.
Does xAgent have a built-in knowledge base?
Not currently. Knowledge capabilities can be extended through Skill + MCP: a Skill describes how to use knowledge and organize answers, while MCP connects an external knowledge base, retrieval service, or existing team data system.
Where do Session events come from?
Session events may come from external APIs, Triggers, Connectors, or other Sessions. xAgent delivers events to the corresponding Agent Session through its built-in event queue.
What is a Connector?
A Connector brings WeChat, Telegram, Feishu, browsers, enterprise systems, or third-party services into xAgent. It can carry bidirectional messages and file references, provide external Tools, manage authorization state, and deliver external events to Agent Sessions. Ordinary users complete authorization and use the connection, while administrators prepare Connectors and safety policies.
Can Sessions communicate with each other?
Yes, but only between Sessions under the same user. xAgent uses Session events for inter-Session communication and currently supports notification and assistance events. Notifications appear only in the interface and do not enter model context. Assistance enters model context and activates an assistance Task. Cross-user Session communication is not supported because it introduces security risks.
Is xAgent a single dedicated Agent?
No. xAgent can host multiple dedicated Agent entry points. Administrators can prepare different Agents, Skills, Tools, external connections, and safety policies for different work scenarios. Ordinary users enter the relevant entry point and use it directly.
Can xAgent help me build a new dedicated Agent?
Yes. Usually you first define the Task scenario, then prepare a dedicated Agent entry point, Skills, Tools, external connections, and approval policies. If you only need to capture a fixed work method, ask xAgent to generate a Skill draft first, then test, optimize, and publish it.
Does every Session need to preload all Skills and Tools?
No. xAgent Sessions include core capabilities for discovering and loading Skills and Tools. During Task execution, xAgent can search for and load a suitable Skill or Tool if the current capabilities are insufficient. This saves context and lets the Agent extend its capabilities according to the Task.
Will xAgent automatically self-evolve?
Not by default. xAgent can continuously optimize a specific Skill through prompts or a self-evolution Skill, but this requires a clear goal, test cases, acceptance criteria, and a publication flow. Self-evolution is valuable but risky, so xAgent approaches it cautiously.
Can I adjust configuration myself?
Yes. Models, prompts, Skills, Tools, external connections, and approval policies can be maintained in the system. Many settings do not require a service restart or a new Session. A running execution round keeps its current configuration, while later rounds use the new settings.
Do ordinary users need to configure Tools and Skills themselves?
Usually not. Administrators can prepare common scenarios, dedicated Agents, Tools, Skills, and external connections first. Ordinary users then use them directly in Sessions.
What does the free binary release mean?
The free binary release is currently the v0.0.6.beta beta and serves as an entry point for understanding and evaluating xAgent. Users can deploy the standard version first and experience core capabilities such as Task submission, the file Workspace, Tools, Skills, and external connections.
A free binary release is not the same as an open-source release. xAgent will evaluate whether to open the source or expand ecosystem collaboration based on product maturity, community feedback, security boundaries, and commercial sustainability.
Enterprise internal-system integration, unified identity, complex permissions, audit and compliance, dedicated Connectors, or deep business-process changes usually require custom integration based on actual needs.
What is the difference between the commercial and free editions?
The commercial and free editions have the same product capabilities. The current difference is mainly the number of supported users; core functionality is not divided into separate free and commercial experiences.
The free edition already provides the complete core xAgent experience for home deployment, small teams, and early scenario validation, with a low deployment and usage barrier. The commercial edition is more suitable for teams and companies that need more users, related support, or custom integration.
Will xAgent provide an official SaaS?
There is currently no SaaS release plan. xAgent does not want users to store their Task files, business data, and external-system connections on an official platform. With self-hosted deployment, the deployment owner is responsible for data security, backups, permissions, and confidentiality.
What database does xAgent use?
The current version uses embedded SQLite by default to reduce deployment and maintenance difficulty. xAgent can be upgraded to PostgreSQL or another database when team size, concurrency, audit, or operational requirements increase.
Is xAgent suitable as a large-enterprise platform?
xAgent can serve as a foundation for an enterprise intelligent-work portal and business AI entry point, covering unified Task entry, the file Workspace, Tool calling, Skill capture, and external-system connections.
Large companies and complex organizations usually need custom integration with existing enterprise systems, such as unified identity, permission systems, internal business-system connections, audit requirements, data boundaries, safety policies, model gateways, and dedicated external connections. This is not a simple install-and-cover-every-process scenario. It is better understood as using xAgent as a foundation and gradually connecting and extending it around existing enterprise infrastructure.
Can xAgent replace every business system?
No. xAgent organizes Task entry points and capability calls. Permissions, login state, business data, and audit rules for external systems should remain managed by the corresponding system or external connection.
Will this documentation include technical implementation details?
The main line is the user manual. Ordinary users should start with Getting Started and User Manual. Technical material is supplementary for maintenance and customization.
Why are only a few commands documented here?
The user manual records only verified, commonly used entry points. Testing, evaluation, and migration commands belong in more specific maintenance documentation.
Is a CLI the same as an API?
No. A CLI is a command-line entry point, while an API is a programmatic interface.
Why are not all config.yml fields listed?
The user manual lists only frequently used fields. Use the current code and configuration management page as the source of truth for the complete field set.
Can a real Secret be used in an example?
No. Examples must use placeholder values.
Can common error messages be documented in advance?
Troubleshooting directions can be documented, but error codes must not be invented.
Do error codes need a stable format?
Yes. Once stable, they should be maintained centrally on this page.
Can a Connector be called a plugin?
That is not recommended. A Connector is a protocol bridge to an external system and is not the same as a general plugin.
Can Memory be called history?
No. Memory and Session history are different concepts.
Why are some terms kept in English?
Session, Task, Tool, Skill, Connector, Workspace, and Memory are fixed concepts that appear in the product and code. Keeping the English terms reduces ambiguity across the UI, logs, and code.
What is the difference between an Agent and a Skill?
An Agent is a work entry point, while a Skill is a method for completing a type of Task. One Agent can be associated with multiple Skills.
Do ordinary users need to create Agents?
Usually not. Once administrators prepare public entry points, ordinary users can use them directly. Users who are familiar with a recurring workflow can also create or adjust an Agent in their personal scope.
Why can I see only public Agents?
The current account may not have a personal Agent, or its permissions may allow only public entry points. Use what the page displays as the source of truth.
Why do I see Tool calls?
They show that xAgent is performing a concrete action, such as reading a file, accessing a web page, generating a file, or calling an external system. Ordinary users should focus on the final result and whether confirmation is required.
Why did the Task stop progressing?
Common causes include missing materials, pending approval, waiting for additional information, an unavailable Tool, an unconnected external system, or an unclear Task description. Read the notice in the Session and provide the missing information.
Can I change requirements midway?
Yes. State the new requirement directly, for example: "Keep the previous result, but change the output format to a table."
When should I create a new Session?
Create a new Session when the goal has become a different piece of work or you do not want the current context to continue. A format adjustment, additional material, model switch, or Skill switch within the same goal does not require a new Session.
What should I do if I misconfigure Advanced Settings?
Describe the problem in the Session, or reopen Advanced Settings and restore the previous prompt, model, Skills, Tools, and Secret selection. Administrators still maintain system-level configuration.
Does an Agent directly store long-term Memory?
No. Memory is an independent capability. An Agent only uses content projected into its context.
Does an Agent directly manage external-system login state?
No. External-system login state belongs to the external connection or target system.
Does an Agent always execute every Tool automatically?
No. Tool calls must follow the current Session, capability selection, permissions, and approval rules.
Must users manage SubAgents manually?
Usually not. Users only need to describe the Task goal and acceptance criteria. The main Agent and system execution process decide whether to split subtasks and how to consolidate their results.
Will approvals block every dangerous action?
Approvals reduce risk but do not replace account permissions, external-system permissions, or administrator governance. Sensitive connections should still follow least-privilege configuration.
Why does the same action sometimes require approval and sometimes not?
It may match different resource scopes, Session types, or personal policies. The effective decision is calculated from the current Tool parameters together with personal and system policies.
Does approval block the entire Task before it starts?
No. A Task can begin execution. Only a specific Tool action that matches a policy pauses for approval.
Can I handle approvals from WeChat or Telegram?
Yes. Since v0.0.4.beta, xAgent attempts to send an approval notice to every available IM channel for the current user when a Session enters the approval-waiting state. The Connector must be online, the user must be authenticated, and a working message-sending Tool must be available. Reply using the @{approval:id} reference and the explicit approval or rejection format shown in the notice.
Can ordinary users change system approval policies?
Usually not. Ordinary users may be able to configure personal approval policies, while administrators maintain system-level policies.
What is the difference between My Connections and Connector Management?
My Connections binds the current user's external accounts. Administrators use Connector Management to maintain system-level Connector services.
Are Connector Tools automatically available to every user?
No. Availability depends on whether the Connector is online, whether the user is authenticated, connection state, Tool governance, and approval policies.
Why can I receive a message but not reply?
First check Connector health, user authentication, and platform permissions. WeChat also requires valid recipient context. Sending is blocked after the context_token expires until the context is re-established.
Are long-running Tasks split automatically?
Not necessarily. You can explicitly request: "List the plan first and continue after I confirm it." This makes the process easier to control.
Where can I see long-running Task status?
Check the original Agent Session first. Generated files are usually available in Workspace Files.
Can I change direction midway?
Yes, but state which results to keep and which to discard. For example: "Keep the topic categories, but change the report to an executive briefing format."
Does switching models immediately affect a running execution round?
No. It does not rewrite the model and Tool loop already running in the current round. That round keeps the selected model, and the new configuration applies to later rounds. Switching models does not require a new Session; existing history and files are preserved.
Why are command examples omitted?
Ordinary users primarily submit long-running Tasks through the web. Low-level interfaces and internal organization are not the main line of the user manual.
Does Memory automatically save every message?
No. Long-term Memory should be valuable, traceable, and suitable for future reuse.
Does Memory replace Session history?
No. Session history supports the current Session context, while Memory supports long-term reuse.
Are Memory rules fully stable?
Not yet. Treat Memory as supporting context rather than the only source of truth.
Why do I see fewer menu items than another user?
First confirm whether an administrator enabled advanced features for your account. Simple mode hides the Session list, Triggers, Agents, Skills, Tools, MCP, and Personal Approval Policy. Administrator-only menus also require the administrator role.
Which menu should I open first?
Start with Agent Session and describe the goal, materials, constraints, and delivery requirements. Open Workspace Files when you need to inspect files, or My Connections when you need to bind a messaging channel.
Where are theme and display density settings?
Open Account Management and use the interface settings to choose light, dark, or system theme and adjust display density. These settings are no longer separate sidebar entries.
Do ordinary users need to configure models themselves?
Usually not. Once an administrator configures them, ordinary users can use them directly in a Session.
As unified model management and Task routing improve, ordinary users will need to think less about individual model selection and can focus on describing the Task goal.
Does a successful connection test mean every Task will work?
Not necessarily. A successful connection test only confirms that the model service is reachable. Task completion also depends on capability switches, Tools, Skills, external connections, and approval policies.
Why switch models in a Session?
Different models suit different Tasks. Some are better at rapid summarization, others at complex reasoning or Tool collaboration. Switching models does not mean restarting the entire Session.
Can screenshots include a Base URL and API Key?
That is not recommended. Screenshots in public documentation or public channels should redact internal addresses, Secrets, and account information.
Is a Session only a chat history?
No. Chat history is only an entry point. A Session also includes Task context, capability selection, file artifacts, and execution state.
Does a Session store every long-term fact?
It should not. Preferences, decisions, or background that need cross-Session reuse should enter Memory or another explicit location.
Can a Session be reused by a subtask execution unit?
A long-running or decomposed Task may create an independent execution unit. Ordinary users only need to follow its state and returned results in the main Session.
Is a Skill the same as a Tool?
No. A Tool performs an action, while a Skill captures a method. A Skill can guide xAgent in using Tools but does not replace Tool permissions.
Are more Skills always better?
No. Too many Skills make selection difficult. Prioritize frequent, stable workflows with clear value.
Must ordinary users select a Skill?
No. Administrators can associate Skills with an Agent so ordinary users only need to submit the Task.
Does a Skill change take effect immediately?
A draft change affects only the current draft test. After publication to the personal library, later Tasks can use the new personal Skill. A public-library Skill follows administrator review and maintenance. Whether a running Task adopts new content depends on the current page and Session behavior.
Must a Task be completed in one pass?
No. Complex Tasks can proceed in stages. Ask xAgent to list a plan first and execute only after confirmation.
Is a Task the same as a Tool call?
No. A Tool is only a means of completing a Task. Ordinary users do not need to specify a Tool name; they only need to describe the desired action.
When should a Task be split?
Split it when it has many materials, complex steps, external results to wait for, or multiple confirmation points.
Can xAgent save a result automatically?
Yes. Specify a format such as "save as a Markdown / CSV / HTML report" in the Task.
What is the difference between a Tool and a Skill?
A Tool performs an action, while a Skill records a method. For example, "read an Excel file" is a Tool action, while "how to analyze sales data" is closer to a Skill.
Can a Tool directly access files on my computer?
No. A Tool can normally access only files in the Workspace and authorized scope.
What should I do when a Tool call fails?
Read the failure reason first. Common responses include adding the file, completing authorization, enabling the connection, narrowing the Task, or asking an administrator to enable the Tool.
Why are some Tools not visible to me?
Tool visibility depends on account permissions, administrator configuration, connection state, personal MCP configuration, Connector authorization state, and personal switches.
Does a Trigger wait until a Task finishes?
No. A Trigger starts the Task. Follow execution and results in the Session.
Why did a Trigger not run?
Possible reasons include a disabled Trigger, a scheduled time that has not arrived, an unavailable external connection, an action blocked by an approval policy, or a configuration save failure.
Can a scheduled Task send a message directly?
Whether it can send depends on the Tool, connection, and approval policy. The recommended default is to generate a draft first and send it after confirmation.
When should I delete a Trigger?
Delete it only after confirming it is no longer needed and will not be reused. Prefer disabling it when the Task is only paused.
Is the Workspace the same as any local directory on my computer?
No. The Workspace has explicit visibility and permission boundaries. Users can see only files within their authorized scope.
Are uploaded files processed automatically?
Not necessarily. Uploading only provides the material. You still need to ask xAgent to read the file or analyze the spreadsheet in the Task.
Why can I not find a generated file?
The Task may have replied with the result in the Session without saving a file. Continue by asking xAgent to save the result as a Markdown file.
Can a Workspace file be sent to an external system?
Yes, but this usually requires a Tool, connection, and approval. Check whether the content is appropriate for external distribution before sending it.