Services and APIs

Package names on this page are preview naming and may change before launch.

From console agent to REST API

You will add the HTTP server package to the scope that needs it with ael pack add (command names may change before launch):

ael pack add server/http

The scope's pack.ael will then declare the package, with its request to listen on the network. Version numbers in examples are illustrative.

pack {
    schema = 1;
    dependencies = [
        { name = "server/http"; version = "^1.2.0"; kind = "runtime";
          source = { kind = "registry"; };
          features = []; targets = []; capabilities = ["net.listen"];
          publisher = "openeng"; }
    ];
}

Routes will live in a .routes.ael file, a file role that server/http adds:

# src/api/api.routes.ael
routes api(base_route = "/api/v1") {
    # Route declarations map methods and paths to typed handlers.
}

• base_route will default to /. An explicit base such as /api/v1 will be joined to each route's path; an empty or malformed base will be refused instead of becoming /.
• Declaring routes will open no port. main will mount the routes and start the server, and main will decide when the server stops and drains.
• A file will name the package exports it uses in its header, such as refer server/http select get;, and every selected export will have to be used. See Using packages.
• How a route maps a method and a path to a handler will be confirmed when the syntax is final.

Back to console-only

Delete the routes and the code in main that mounts them, then remove the package with ael pack remove server/http. The next build will carry no server code; if anything still refers to the package, the check will point to it. Calls your agent makes to models, MCP tools or other APIs will not need a server package either: they will be outbound client calls, made with the built-in HTTP client.

What every request goes through

• Authentication first. A request will be authenticated before your handler runs. The tenant and the caller's identity will be set where the request enters, from its authentication, never from fields in the request body.
• Authorization hooks. Hooks attached before a handler will run first and fail closed; see Hooks.
• Typed input. Path, query, headers, cookies and body will decode into your input types within size limits. A malformed or oversized request will be refused with a documented status.
• The right reply. Each reply will be bound to the connection, or the durable run, that asked for it. Nothing in a request will be able to choose where a reply goes.
• Disconnects. When a client disconnects, your policy will decide what happens to its work: it will be cancelled, or it will continue as a durable run that outlives the request.
• Overload. Requests beyond your limits will be rejected or deferred with the protocol's own status. A multi-core, nonblocking runtime will need no thread per user.

One agent, several protocols

You will be able to serve the same typed agent over any of these, each a separate package:

Adding one will never bring the others: an HTTP-only app will carry no gRPC or WebSocket code, and a GET-only API no POST handlers. Servers will drain gracefully on shutdown, report their health and take their TLS settings from configuration.

Reports in every response

Time and token usage will be reported by default on every channel: the command line, HTTP, gRPC, WebSocket and sockets. You will be able to turn off each field without disabling the limits behind it. A response will carry the values known when it is sent; a streamed response will get its final totals when the stream ends. See Reporting, logs and replay.

Services your agent calls

Code will call a typed service, and the deployment will decide whether it runs in the same process, on another machine, over HTTPS or over gRPC. Connections will be resilient, with idempotency-aware retries, backpressure, circuit breakers and health checks. See Tools and MCP.

A service will also be able to start work on its own: event, polling and scheduled triggers will have overlap, missed-run and time-zone policies, and will survive restarts. See Workflows.

Honest limits

• No connection, request-rate or user-count figures will be stated until they are measured; capacity at large scale will depend on your deployment.
• A client that disconnects before a stream ends will not receive the stream's final totals.
• Support for native gRPC clients will not imply support for gRPC from web browsers.

Related

• Package catalog: every server package.
• Desktop and server and Containers: native executables and container images for your service.
• Deployment and rollback: staging a new version of your service, and rolling it back.
• Teams of agents: delegating to remote agents over A2A.