Agent Discovery

AIsa publishes several machine-readable discovery resources so that autonomous agents can find, understand, and invoke supported capabilities. This guide explains the main resources and the discovery-to-invocation flow.

Discovery Endpoints

AIsa exposes the following public URLs for agent and documentation discovery. They require no authentication to read.

Endpoint	Protocol	URL	Purpose
Agent Card	Google A2A	`https://aisa.one/.well-known/agent-card.json`	High-level capabilities with metadata, tags, examples, and I/O modes
AI Plugin	OpenAI Plugin (v1)	`https://aisa.one/.well-known/ai-plugin.json`	Backward compatibility with ChatGPT-era agent tooling
MCP Manifest	MCP discovery convention	`https://aisa.one/.well-known/mcp.json`	MCP-oriented server descriptors and status metadata
OpenAPI Spec	OpenAPI 3.1.0	`https://aisa.one/openapi.yaml`	Machine-readable request and response contracts
Product llms.txt	llms.txt	`https://aisa.one/llms.txt`	Product fit, goals, interfaces, and evaluation routes
Technical llms.txt	llms.txt	`https://aisa.one/docs/llms.txt`	Technical documentation router

How Agent Discovery Works

The discovery flow follows three steps: discover, inspect, and invoke. An autonomous agent starts by fetching the agent card to learn what AIsa can do, selects the relevant skill, and then calls the corresponding API endpoint using the OpenAPI spec for request/response schemas.

Discover

The agent fetches /.well-known/agent-card.json from aisa.one. The response contains a list of skills, each with an id, name, description, tags, and examples. The agent uses this metadata to determine whether AIsa can fulfill the current task.

Inspect

Once the agent identifies a relevant skill, it fetches /openapi.yaml to retrieve the full request/response schema for the corresponding API endpoints. The OpenAPI spec provides parameter types, required fields, authentication requirements, and example payloads.

Invoke

The agent constructs an authenticated API request using the schema from the OpenAPI spec, sends it to api.aisa.one, and processes the response. All endpoints use Bearer token authentication with an AIsa API key.

The A2A Agent Card

The Agent2Agent (A2A) Protocol defines a standard format for agents to advertise capabilities and interoperate. AIsa’s agent card lives at the well-known URL and describes the platform, authentication requirements, and public capability catalog.

Fetching the Agent Card

curl -s https://aisa.one/.well-known/agent-card.json | jq .

import requests

card = requests.get("https://aisa.one/.well-known/agent-card.json").json()
print(f"Agent: {card['name']} — {card['description']}")
print(f"Skills: {len(card['skills'])}")
for skill in card["skills"]:
    print(f"  • {skill['id']}: {skill['name']}")

const res = await fetch("https://aisa.one/.well-known/agent-card.json");
const card = await res.json();
console.log(`Agent: ${card.name} — ${card.description}`);
console.log(`Skills: ${card.skills.length}`);
card.skills.forEach((s: any) => console.log(`  • ${s.id}: ${s.name}`));

Agent Card Structure

The top-level fields describe the agent identity, authentication, and capabilities:

Field	Type	Description
`name`	string	Agent name — `"AIsa"`
`description`	string	One-line summary of the agent’s purpose
`url`	string	Base URL for API requests — `https://api.aisa.one`
`provider`	object	Organization name and website
`version`	string	Semantic version of the agent card
`documentationUrl`	string	Link to human-readable documentation
`capabilities`	object	Feature flags — streaming, push notifications, state history
`authentication`	object	Supported auth schemes and credential instructions

Skill Objects

Each entry in the skills array describes a single capability:

Field	Type	Description
`id`	string	Unique skill identifier (e.g., `chat-completions`, `twitter-autopilot`)
`name`	string	Human-readable skill name
`description`	string	What the skill does and what data it provides
`tags`	string[]	Searchable tags for filtering and matching
`examples`	string[]	Natural-language example queries the skill can handle
`inputModes`	string[]	Accepted content types (defaults to `application/json`)
`outputModes`	string[]	Response content types (e.g., `application/json`, `text/event-stream`)

Available capabilities

The Agent Card is generated from the public catalog. Fetch the live card instead of relying on a fixed capability list in documentation:

curl -s https://aisa.one/.well-known/agent-card.json \
  | jq -r '.skills[] | [.id, .name, (.tags // [] | join(","))] | @tsv'

Use each capability’s description, tags, and examples for matching. Confirm the underlying Skill or API documentation before invocation.

The OpenAI Plugin Manifest

For backward compatibility with agent frameworks that implement the original ChatGPT plugin protocol, AIsa also publishes an ai-plugin.json manifest at /.well-known/ai-plugin.json. The manifest references the same OpenAPI spec. For current OpenAI tool integration guidance, see Actions.

curl -s https://aisa.one/.well-known/ai-plugin.json | jq .

The manifest includes a description_for_model field that lists key API endpoints, helping LLM-based agents understand which tools are available without parsing the full OpenAPI spec.

The OpenAPI 3.1 Specification

The consolidated OpenAPI spec at /openapi.yaml is the authoritative machine-readable contract for constructing API requests. Parse the live specification instead of relying on a fixed path or schema count.

Fetching and Parsing the Spec

import yaml, requests

spec = yaml.safe_load(requests.get("https://aisa.one/openapi.yaml").text)
paths = list(spec["paths"].keys())
print(f"Total endpoints: {len(paths)}")
print(f"First 5: {paths[:5]}")

import YAML from "yaml";

const res = await fetch("https://aisa.one/openapi.yaml");
const spec = YAML.parse(await res.text());
const paths = Object.keys(spec.paths);
console.log(`Total endpoints: ${paths.length}`);

curl -s https://aisa.one/openapi.yaml | head -50

API Categories

The spec organizes endpoints into the following tag groups:

Category	Example Endpoints	Description
AI Models	`/v1/chat/completions`, `/v1/models`	Live LLM and media model catalog, OpenAI-compatible chat routes
Twitter/X	`/apis/v1/twitter/tweet/advanced_search`	Profile, timeline, search, posting
Financial Data	`/apis/v1/financial/prices`, `/apis/v1/financial/sec-filings`	Equities, SEC, earnings, screening
Web & News Search	`/apis/v1/tavily/search`, `/apis/v1/search/smart`	Multi-source and Tavily search
Prediction Markets	`/apis/v1/polymarket/events`, `/apis/v1/kalshi/markets`	Polymarket and Kalshi data
Crypto Data	`/apis/v1/coingecko/simple/price`	CoinGecko market data
Image Generation	`/v1/images/generations`	GPT, Seedream, Wan, and other image-capable routes
YouTube Search	`/apis/v1/youtube/search`	YouTube SERP
Scholar Search	`/apis/v1/scholar/search/scholar`	Academic paper search

End-to-End Integration Example

The following Python example demonstrates the complete discovery-to-invocation flow. An autonomous agent discovers AIsa’s capabilities, identifies the chat-completions skill, and makes an authenticated API call.

import requests

# Step 1: Discover — fetch the agent card
card = requests.get("https://aisa.one/.well-known/agent-card.json").json()

# Step 2: Find a skill by tag
target_tag = "llm"
matching = [s for s in card["skills"] if target_tag in s.get("tags", [])]
if not matching:
    raise RuntimeError(f"No skill found with tag '{target_tag}'")

skill = matching[0]
print(f"Selected skill: {skill['name']} ({skill['id']})")

# Step 3: Invoke — call the API using the base URL from the card
response = requests.post(
    f"{card['url']}/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_AISA_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-5.4-mini",
        "messages": [
            {"role": "user", "content": "Summarize the A2A protocol in two sentences."}
        ],
    },
)

result = response.json()
print(result["choices"][0]["message"]["content"])

Authentication

All AIsa API endpoints require Bearer token authentication. Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_AISA_API_KEY

Generate an API key from the AIsa console. For detailed key management guidance — scoping, rotation, and secure storage — see the Authentication guide.

The discovery resources (agent-card.json, mcp.json, ai-plugin.json, openapi.yaml, and llms.txt files) are publicly readable and require no authentication. API calls to api.aisa.one require the authentication documented for the selected route.

Integration Patterns

Pattern 1: Tag-Based Skill Matching

Agents can match tasks to skills using the tags array. This is the recommended approach for agents that need to dynamically select capabilities at runtime.

def find_skills_by_tags(card, required_tags):
    """Return skills that match ALL required tags."""
    return [
        skill for skill in card["skills"]
        if all(tag in skill.get("tags", []) for tag in required_tags)
    ]

# Find skills for financial research
finance_skills = find_skills_by_tags(card, ["finance", "stocks"])
# Returns: [MarketPulse Financial Data]

Pattern 2: Example-Based Intent Matching

For LLM-powered agents, the examples field provides natural-language queries that can be used for semantic similarity matching against the user’s intent.

# Collect all examples with their skill IDs
example_index = []
for skill in card["skills"]:
    for example in skill.get("examples", []):
        example_index.append({"text": example, "skill_id": skill["id"]})

# Use an embedding model to find the closest match to the user's query
# user_query = "What's the stock price of Apple?"
# → Matches MarketPulse skill via "Get the current stock price for AAPL"

Interactive Explorer

AIsa provides two browser-based tools for exploring the discovery surface:

API Explorer — Interactive API reference for browsing documented endpoints and request/response examples.
Agent Discovery — Visual skill explorer with search and tag filtering, plus integration code examples.

CORS Support

The discovery endpoints include permissive CORS headers (Access-Control-Allow-Origin: *) so that browser-based agents and web applications can fetch them directly without a proxy server. This applies to:

/.well-known/agent-card.json
/.well-known/ai-plugin.json
/openapi.yaml

Authentication

API key generation, scoping, rotation, and secure storage.

Agent Skills

Browse and install composable skills for Claude Code, Cursor, and OpenClaw.

Getting Started

Make your first authenticated API request in minutes.

AIsa Documentation

Product Discovery

Tutorials

Pricing

AIsa Console

Learn

Compare

Changelog

Agent Discovery – Let Autonomous Agents Find and Use AIsa

Discovery Endpoints

How Agent Discovery Works

The A2A Agent Card

Fetching the Agent Card

Agent Card Structure

Skill Objects

Available capabilities

The OpenAI Plugin Manifest

The OpenAPI 3.1 Specification

Fetching and Parsing the Spec

API Categories

End-to-End Integration Example

Authentication

Integration Patterns

Pattern 1: Tag-Based Skill Matching

Pattern 2: Example-Based Intent Matching

Interactive Explorer

CORS Support

Authentication

Agent Skills

Getting Started

​Discovery Endpoints

​How Agent Discovery Works

​The A2A Agent Card

​Fetching the Agent Card

​Agent Card Structure

​Skill Objects

​Available capabilities

​The OpenAI Plugin Manifest

​The OpenAPI 3.1 Specification

​Fetching and Parsing the Spec

​API Categories

​End-to-End Integration Example

​Authentication

​Integration Patterns

​Pattern 1: Tag-Based Skill Matching

​Pattern 2: Example-Based Intent Matching

​Interactive Explorer

​CORS Support

​Related

Authentication

Agent Skills

Getting Started

Discovery Endpoints

How Agent Discovery Works

The A2A Agent Card

Fetching the Agent Card

Agent Card Structure

Skill Objects

Available capabilities

The OpenAI Plugin Manifest

The OpenAPI 3.1 Specification

Fetching and Parsing the Spec

API Categories

End-to-End Integration Example

Authentication

Integration Patterns

Pattern 1: Tag-Based Skill Matching

Pattern 2: Example-Based Intent Matching

Interactive Explorer

CORS Support

Related