Build with OAN

Building with OAN means adding trusted resource identity, registration, discovery, and verification to products that already have their own runtime behavior. You do not need to turn every service into an OAN-native runtime. You use OAN to make the resource discoverable and verifiable, then continue through the resource’s native protocol.

This section is for developers who want to integrate OAN into applications, assistants, SDKs, resource packages, MCP workflows, tool catalogs, and hosted services. It is intentionally public-facing. Private deployment, governance voting, pressure testing, and server runbooks belong elsewhere.

The most important design habit is to keep OAN’s responsibility narrow and strong. OAN should answer whether a resource identity, publication path, package facts, lifecycle state, and Discovery result are verifiable. It should not absorb every runtime protocol, tool schema, or business approval process into the core.

OAN resource types

Developer Surfaces

Surface Use it for Avoid using it for
TypeScript SDK Registration calls, Discovery queries, endpoint configuration, package lookup, verification helpers. Replacing all native protocol security.
Community skill AI-assisted registration and Discovery workflows for users. Official private operations or chain governance.
Website forms Quick official registration and Discovery trials. Heavy automation or private key custody.
Resource profiles Consistent modeling of Agent Service, Skill, MCP Server, and Tool/API resources. Pretending all resource types have the same runtime shape.

The SDK is the main programmatic surface. The community skill is the adoption surface for assistant-led workflows. The website is the easiest manual surface. They should all use the same vocabulary: baseUrl, resource type, authorizedDomains, capabilityTags, lifecycle, package proof, and verification.

That shared vocabulary is not only documentation polish. It prevents ecosystem fragmentation. If the website calls something a domain, the SDK calls it a category, and the skill treats it as a tag, users will make mistakes. OAN’s integration surfaces should teach the same model in different forms.

Integration Pattern

A typical integration has six steps:

  1. Model the resource with the correct resource type.
  2. Prepare or validate did:oan identity material.
  3. Add resource metadata, domains, tags, endpoint or artifact references, and version facts.
  4. Submit through Registrar using SDK, website, or skill.
  5. Query Discovery and receive candidates with evidence.
  6. Verify the chosen candidate before native protocol use.

Developers should not collapse steps 5 and 6. Discovery finds candidates; verification decides whether a candidate should be trusted enough to continue.

A strong integration should make the unsafe shortcut inconvenient. If an application receives a Discovery candidate, the next helper should be verify or equivalent, not “call URL immediately.” That default becomes more important as agents begin to select tools without constant human supervision.

Resource Type Matters

Agent Services, Skills, MCP Servers, and Tool/API resources share the OAN trust envelope, but their native material differs. A Skill should expose manifest and package references. An MCP Server should expose MCP endpoint and tool/resource/prompt summaries. A Tool/API should expose endpoint and schema references. An Agent Service should expose service endpoint and protocol binding.

This lets OAN remain interoperable. OAN does not replace MCP, OpenAPI, skill packaging, or service protocols. It gives each of them a governed discovery and verification path.

This is also the easiest adoption story for existing projects. A team with an MCP server does not have to rewrite it. A team with a REST API does not have to pretend it is an agent. A team with a skill package does not need to host a new runtime. They add an OAN resource envelope around what already exists.

Configuration Model

Client configuration should be simple for ordinary users and flexible for advanced users. Use baseUrl as the normal entry point. Let explicit endpoints override service routes when needed. This supports official services, third-party compatible nodes, and diagnostic workflows without making every user learn local node ports.

const client = new OanClient({
  baseUrl: "https://api.openagenet.xyz",
  discoveryEndpoint: "https://discovery.example.org"
});

In this example, Discovery uses the explicit endpoint while other service calls can still derive from baseUrl. Real SDK names may evolve, but the configuration idea should stay stable.

The configuration should be easy to migrate. Early deployments may use temporary IP-based official services; production deployments should use domain-backed official services; third-party operators may expose their own public entries. Applications should read these settings from configuration rather than bury them in business logic.

Verification Is Part of the Integration

Developer integrations should preserve verification output. Do not reduce an OAN result to only name, url, and score. Keep DID, package reference, lifecycle, Root proof, hashes, domains, tags, and verification status available to the application. A product may render a simplified UI, but the evidence should not disappear from the programmatic model.

For applications that automatically select tools or services, verification should happen before the selected resource is installed, connected, or invoked. That is where OAN becomes useful inside agent workflows.

Keep the evidence in logs and audit records when possible. For regulated or enterprise environments, it is valuable to know which DID, package version, Root proof, Discovery node, and lifecycle state led to a particular integration decision.

Further Reading