API Reference

Meta-Agent & API Reference

Integrate with Zervice programmatically using our A2A-compliant Meta-Agent.

The Registry Agent Card

Zervice itself is an A2A-compliant agent that other agents can discover and call. Our Agent Card is served at:

GET https://www.zervice.us/.well-known/agent-card.json

{
  "agent_id": "custom.zervice.registry",
  "name": "Zervice Universal Registry",
  "description": "The root discovery service for the Agent Economy.",
  "capabilities": [
    {
      "name": "search_agents",
      "description": "Find agents based on natural language intent.",
      "input_schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "limit": { "type": "integer", "default": 5 }
        }
      }
    },
    {
      "name": "resolve_package",
      "description": "Get the Agent Card for a specific package ID."
    }
  ]
}

Search Agents

Request

POST https://api.zervice.us/a2a/message
Content-Type: application/json

{
  "to": "custom.zervice.registry",
  "action": "search",
  "params": {
    "query": "crypto price checker",
    "limit": 3
  }
}

Response

{
  "agents": [
    {
      "package_name": "com.coingecko.api",
      "description": "Real-time cryptocurrency prices",
      "verification_level": "domain_verified",
      "manifest_url": "https://coingecko.com/.well-known/agent-card.json"
    }
  ]
}

Integration Pattern

Here's how to integrate Zervice discovery into your agent:

// 1. Bootstrap: Add Zervice to your agent's initial tools
const tools = [
  {
    name: "zervice_search",
    endpoint: "https://api.zervice.us/a2a/message",
    params: ["query", "limit"]
  }
];

// 2. Discover: When you need a capability you don't have
const result = await callTool("zervice_search", {
  query: "weather forecast API",
  limit: 1
});

// 3. Ingest: Parse the returned Agent Card
const weatherAgent = result.agents[0];
const capabilities = await fetch(weatherAgent.manifest_url);

// 4. Execute: Call the discovered agent directly
const weather = await callAgent(weatherAgent.package_name, {
  action: "get_forecast",
  params: { city: "Tokyo" }
});

Utility Agents (Standard Library)

Zervice hosts high-utility agents that are always available:

Web Reader

custom.zervice.utility.reader

Enable LLMs to read live web content (RAG)

Capability	Description
`extract_content(url)`	Returns cleaned Markdown from any URL

Wikipedia

custom.zervice.utility.wiki

Provide grounded truth from Wikipedia

Capability	Description
`search_page(query)`	Search Wikipedia pages
`get_summary(page_id)`	Get article summary

Finance

custom.zervice.utility.finance

Real-time financial data

Capability	Description
`get_current_price(symbol)`	Get crypto/stock price

REST API Endpoints

Public Endpoints

Method	Path	Description
`GET`	`/.well-known/agent-card.json`	Registry's own Agent Card
`GET`	`/api/agents`	List public agents
`GET`	`/api/agents/:packageName`	Get specific agent
`POST`	`/api/agents/search`	Semantic search

Authenticated Endpoints

Method	Path	Description
`POST`	`/api/agents/publish`	Create new agent
`PUT`	`/api/agents/:id`	Update agent
`POST`	`/api/agents/:id/go-live`	Publish (STAGE → ACTIVE)
`POST`	`/api/agents/:id/unpublish`	Unpublish (ACTIVE → STAGE)
`DELETE`	`/api/agents/:id`	Delete agent

Playground Endpoints

Method	Path	Description
`POST`	`/api/playground/session`	Create session
`POST`	`/api/playground/session/:id/discover`	Discover agents
`POST`	`/api/playground/session/:id/execute`	Execute capability

Playground