Skip to main content

Agent Registry

AxonFlow supports both file-based agent definitions and an enterprise database-backed agent catalog. The managed catalog lets platform teams treat agent definitions as operational assets rather than only static YAML checked into a repo.

Use this page when you need to understand which agent operations are available in every deployment and which require the enterprise registry.

What Is Available​

Community read APIs​

The base runtime exposes:

  • GET /api/v1/agents
  • GET /api/v1/agents/{id}
  • GET /api/v1/agents/domain/{domain}
  • POST /api/v1/agents/validate

Those routes are primarily file-registry views.

Enterprise write and test APIs​

The enterprise binary adds:

  • POST /api/v1/agents
  • PUT /api/v1/agents/{id}
  • DELETE /api/v1/agents/{id}
  • POST /api/v1/agents/{id}/activate
  • POST /api/v1/agents/{id}/deactivate
  • POST /api/v1/agents/{id}/test
  • GET /api/v1/agents/{id}/versions

The practical model is:

  • read-only registry access in all editions
  • managed registry lifecycle in enterprise deployments

Authentication and Scope​

Enterprise registry operations are organization-scoped. The handler accepts:

  • X-Org-ID
  • tenant context derived from Basic auth credentials as a compatibility fallback
  • X-User-ID for change attribution

If X-Org-ID is missing, write operations return an authorization error. For enterprise customers using the protected portal, this context is usually injected by the portal session and proxy layer.

List and Filter Agents​

GET /api/v1/agents?page=1&page_size=20&domain=travel&search=booking&sort_by=updated_at&sort_dir=desc

Supported query parameters:

ParameterPurpose
page1-based page index
page_sizepage size, capped at 100
domainFilter to one domain
searchFree-text filter
sort_byname, domain, created_at, or updated_at
sort_dirasc or desc
is_activeFilter active or inactive agents

The enterprise response follows the familiar list shape:

{
  "agents": [],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_items": 0,
    "total_pages": 0
  }
}

Create and Update Requests​

Create requests use this shape:

{
  "name": "travel-coordinator",
  "domain": "travel",
  "description": "Coordinates travel search and approval flows",
  "config": {
    "type": "coordinator"
  },
  "is_active": true
}

Update requests are partial:

{
  "description": "Coordinates regulated travel and approval flows",
  "is_active": false
}

That partial-update model is useful when platform teams want to change activation state or metadata without resubmitting the whole agent specification.

Activation, Deactivation, and Testing​

Activate or deactivate​

POST /api/v1/agents/{id}/activate
POST /api/v1/agents/{id}/deactivate

Use these routes when you want to stage an agent definition before exposing it, pause an unstable agent without deleting history, or switch traffic between old and new registry entries.

Sandbox test​

POST /api/v1/agents/{id}/test

Request body:

{
  "query": "Book a business trip to London next week",
  "context": {
    "department": "finance"
  }
}

This returns a test result with whether the run succeeded, the matched rule or agent, the result payload when available, execution duration, and any error message.

It is not a full production canary, but it is a useful pre-check before enabling an agent in a live environment.

Version History​

Every enterprise registry change is captured in agent-version records:

GET /api/v1/agents/{id}/versions

Version entries include:

  • the agent snapshot
  • version number
  • change type such as create, update, delete, activate, or deactivate
  • who changed it
  • when it changed

For regulated or high-accountability environments, this is one of the most important differences from file-only workflows.

How It Fits With File-Based Agents​

Enterprise does not remove the file-based registry. It adds a managed database-backed layer on top of it.

Teams often use:

  • file-based agents for bootstrap or shared defaults
  • database-backed agents for tenant-specific or organization-specific operations

This hybrid model is often the right answer during migration from prototype to production.

Rollout Pattern​

  1. Validate the new configuration with POST /api/v1/agents/validate.
  2. Create the enterprise registry entry.
  3. Run POST /api/v1/agents/{id}/test against representative queries.
  4. Activate the agent only after policy and approval paths are configured.
  5. Keep the version history link in incident and audit runbooks.
Last updated on