Sharing Agents

Xagent offers two distinct ways to expose an agent beyond its owner. They solve different problems and can be used together.

Publishing makes an agent visible as a reusable asset to authenticated internal users. Share links create a public, token-based guest entry point for a published agent.

Capability	Published agent	Share link
Internal reuse	Yes	No
Guest access	No	Yes
Appears in agents list	Yes	No
Public token-based entry	No	Yes

Only the agent owner manages share links. There are four operations — read the current state, turn sharing on, rotate the token, and turn sharing off:

GET    /api/agents/{agent_id}/share-link           # current state (does not create a token)
POST   /api/agents/{agent_id}/share-link           # enable sharing
POST   /api/agents/{agent_id}/share-link/rotate    # replace the token
DELETE /api/agents/{agent_id}/share-link           # disable sharing

All four return the same shape. The raw share_token is included, so treat the response as sensitive:

{
  "agent_id": 42,
  "share_enabled": true,
  "share_token": "shr_8fa2c1d4e6b7",
  "share_updated_at": "2026-08-10T09:15:00Z"
}

Operation	Behaviour
Enable	Turns sharing on. Mints a token only if the agent does not already have one, so re-enabling keeps existing links working.
Rotate	Always issues a new token and turns sharing on. Every previously shared link stops working immediately.
Disable	Turns sharing off and clears the token — `share_token` comes back `null`.

The agent must be published first

Enabling or rotating a share link requires a published agent — otherwise the request fails with 400 Only published agents can be shared. Reading the state and disabling sharing work regardless.

Treat the token like a secret

The share token is owner-only state. Anyone with the link can reach the agent as a guest — rotate it if it leaks, remembering that rotation breaks every link already handed out.

Guest activity is billed to you

Every conversation a guest starts through your share link runs as your agent and counts against your team's usage. Treat a public link as spending authority you have handed out, and disable it when you no longer need it.

What a Guest Can Do

Someone who opens your link is an anonymous guest. They can do exactly three things:

Open the link and start a guest session (valid for 30 days)
Upload files for the agent to work with
Hold a conversation with the agent

They cannot see other guests' conversations, view or change the agent's configuration, or reach anything else in your account. Each visitor is isolated from the others automatically.

Built-in Abuse Protection

Share links carry automatic limits so a single public link cannot drain your team's quota. You do not configure these; they simply apply.

Limit	Default
Conversations started per link, per day	500
Conversations per visitor, per hour	60
Messages per visitor, per minute	60
Link opens per minute	60

These are rolling windows, so a busy link recovers on its own rather than staying blocked. If your deployment is self-hosted, an administrator can adjust them.

Unpublishing also closes the door

Guest access requires the agent to be published. If you unpublish an agent, existing share links stop working immediately — even though the token itself is still in place.

Share links are meant for agents that are ready for outside use. Before enabling one:

Finalise instructions and prompts
Test the suggested prompts
Review file-handling behaviour
Confirm the agent should be publicly reachable

Safety checklist for public exposure

A share link exposes the agent to unauthenticated users. Verify that:

The agent does not expose sensitive internal knowledge by default — review any attached knowledge bases.
Tool access is appropriate for a public audience.
Output style is suitable for external, unauthenticated users.
File handling is acceptable for guest sessions.

Publishing vs. Share Links

Share Link Lifecycle

What a Guest Can Do

Built-in Abuse Protection

Preparing an Agent for Sharing

Next Steps