Visibility & States

Agent Visibility & States

Control who can discover and use your agents with visibility settings.

Discovery Scope

The visibility setting controls who can find your agent in search results and who can use it.

🌍

Public

visibility: "public"

Discoverable via Search?

✅ Yes (global)

Usable?

✅ Anyone

Use case: Open APIs (weather, maps, public utilities)

🏢

Organization

visibility: "org"

Discoverable via Search?

✅ Within org only

Usable?

✅ Org members only

Use case: Internal tools, private APIs, team utilities

🔗

Unlisted

visibility: "unlisted"

Discoverable via Search?

❌ Direct lookup only

Usable?

✅ Anyone with package ID

Use case: Beta agents, invite-only tools, private testing

How Discovery Works

When an agent (or user) searches for capabilities, the visibility filter depends on their authentication status:

-- Anonymous user: public agents only
SELECT * FROM agents WHERE visibility = 'public';

-- Logged-in user: public + their org's internal agents
SELECT * FROM agents 
WHERE visibility = 'public' 
   OR (visibility = 'org' AND org_id IN :user_orgs);

-- Direct lookup: works for any visibility
SELECT * FROM agents WHERE package_name = :package_name;

Agent Lifecycle

Create

Agent starts in STAGE status. Only visible to you.

Test

Use the Playground to verify functionality. Make edits as needed.

Publish

Verification check runs, then moves to ACTIVE. Now discoverable.

Unpublish (optional)

Return to STAGE for maintenance or major updates.

Best Practices

Start with unlisted — Test with specific users before going public
Use org visibility for internal tools — Keep private APIs within your team
Verify before publishing — Higher verification = more trust
Monitor after publish — Watch for usage patterns and errors

Registering Agents

Playground