Aspeckd 0.1.8

Aspeckd

A .NET library that surfaces agent-readable spec endpoints alongside your existing ASP.NET Core API.
Instead of pointing an AI agent at a large OpenAPI document, aspeckd serves a small set of purpose-built JSON endpoints that describe your API in a compact, agent-friendly format — analogous to llms.txt for APIs.

Looking for just the abstractions? See Aspeckd.Core for the companion package that carries no ASP.NET Core dependency.

Installation

dotnet add package Aspeckd

Quick start

1 — Register services

Call AddAgentSpec() in your service-registration code (typically Program.cs):

builder.Services.AddAgentSpec(opt =>
{
    opt.Title       = "My API";
    opt.Description = "What this API does, in one or two sentences.";
});

2 — Map the routes

After app.Build(), call MapAgentSpec() to activate the three agent spec endpoints:

app.MapAgentSpec();

That's it. Three new routes are now live:

Annotating endpoints

Aspeckd discovers endpoints through ASP.NET Core's built-in IApiDescriptionGroupCollectionProvider. Three companion attributes let you control how each endpoint appears in the agent spec.

[AgentDescription]

Provides an agent-focused description for an endpoint. Use it instead of (or alongside) WithSummary() / WithDescription() to write a description optimised for agent consumption.

app.MapGet("/api/weather/{city}", [AgentDescription("Returns the current weather for the given city.")] (string city) =>
    Results.Ok(WeatherService.Get(city)));

[AgentName]

Overrides the display name used for an endpoint in the agent spec index. When omitted, aspeckd auto-generates a name from the HTTP method and route template (e.g. GET /api/weather/{city}).

app.MapGet("/api/weather/{city}", [AgentName("GetWeather")] [AgentDescription("...")] (string city) =>
    Results.Ok(WeatherService.Get(city)));

[AgentExclude]

Suppresses an endpoint from the agent spec entirely. Useful for internal or administrative endpoints that agents should not discover.

app.MapGet("/internal/ping", [AgentExclude] () => Results.Ok());

Configuration reference

All options are set through the AspeckdOptions delegate passed to AddAgentSpec():

Custom base path

builder.Services.AddAgentSpec(opt => opt.BasePath = "/ai-spec");
// Endpoints are now at /ai-spec, /ai-spec/schemas, /ai-spec/{id}

Reusing OpenAPI metadata

If your endpoints already have WithSummary() / WithDescription() / WithName() annotations you can avoid duplicating them:

builder.Services.AddAgentSpec(opt => opt.UseOpenApiMetadataFallback = true);

With fallback enabled the resolution priority for name is:

1. [AgentName] attribute
2. WithName() / IEndpointNameMetadata
3. Auto-generated "METHOD /route"

And for description:

1. [AgentDescription] attribute
2. WithSummary()
3. WithDescription()
4. null

Example responses

GET /agents

{
  "title": "My API",
  "description": "What this API does, in one or two sentences.",
  "schemasUrl": "/agents/schemas",
  "endpoints": [
    {
      "id": "get-api-weather-city",
      "name": "GetWeather",
      "httpMethod": "GET",
      "route": "/api/weather/{city}",
      "description": "Returns the current weather for the given city.",
      "detailUrl": "/agents/get-api-weather-city"
    }
  ]
}

GET /agents/get-api-weather-city

{
  "id": "get-api-weather-city",
  "name": "GetWeather",
  "httpMethod": "GET",
  "route": "/api/weather/{city}",
  "description": "Returns the current weather for the given city.",
  "consumesContentTypes": [],
  "responseTypes": {
    "200": ["application/json"]
  },
  "parameters": [
    {
      "name": "city",
      "source": "Route",
      "type": "String",
      "isRequired": true
    }
  ]
}

GET /agents/schemas

[
  { "name": "WeatherForecast", "jsonSchema": null }
]

Links

• GitHub repository
• Full documentation & contributing guide
• Aspeckd.Core package — stable abstractions with no ASP.NET Core dependency