Skip to main content

Runtime Request Paths

AxonFlow has two public runtime services in the community stack:

  • Agent on 8080: the normal entry point for applications, SDKs, plugins, MCP governance checks, audit writes, health, and proxied control-plane APIs.
  • Orchestrator on 8081: the internal control-plane service for governed request processing, tenant policies, provider routing, workflow APIs, audit search, planning, and replay.

Most application traffic should enter through the Agent. Direct Orchestrator access is mainly for trusted platform automation, local debugging, or internal services that already sit inside your deployment boundary.

This page is the quick routing guide for choosing the correct path before you wire AxonFlow into an application, plugin, or workflow runtime.

Default Boundary​

Use this as the default self-hosted shape:

Application, SDK, plugin, or MCP host
        |
        v
Agent :8080
        |
        +--> auth, system policies, MCP checks, audit collection
        |
        v
Orchestrator :8081
        |
        +--> tenant policies, provider routing, workflows, audit search
        |
        v
LLM providers, connectors, PostgreSQL, Redis

That boundary keeps the low-latency ingress surface narrow while still letting richer workflow and policy operations live behind it.

Choose A Request Path​

Use caseStart withPrimary endpoint familyBest fit
Keep your existing LLM call path, but add governance before and audit after the callAgent/api/policy/pre-check, /api/audit/llm-callGateway mode
Let AxonFlow own governed request processing and provider routingAgent or Orchestrator/api/v1/processProxy mode
Govern tool and connector access from plugins or MCP hostsAgent/api/v1/mcp-server, /api/v1/mcp/check-input, /api/v1/mcp/check-outputMCP connector governance
Search audit logs, inspect decisions, manage policies, or configure providersAgent proxy or Orchestrator/api/v1/audit/*, /api/v1/decisions/*, /api/v1/dynamic-policies, /api/v1/llm-providersControl-plane operations
Plan, execute, resume, or inspect multi-step workflowsAgent proxy or Orchestrator/api/v1/plan*, /api/v1/executionsWorkflow Control Plane

When in doubt, call the Agent first. It is the stable application-facing surface and proxies many Orchestrator API families.

Gateway Mode Path​

Gateway mode is for teams that already have an application or agent framework calling LLM providers directly.

1. Application sends request details to Agent /api/policy/pre-check.
2. Agent authenticates the caller and runs system-policy checks.
3. Application receives allow/block context.
4. If allowed, the application calls the LLM provider directly.
5. Application reports the result to Agent /api/audit/llm-call.
6. AxonFlow stores the audit record and usage metadata.

Choose this path when you want governance and audit without moving provider execution into AxonFlow. It is a good fit for mature LangChain, LangGraph, CrewAI, DSPy, Semantic Kernel, or custom services where the provider call path already works and should stay in the application.

Key docs:

Proxy Mode Path​

Proxy mode is for teams that want AxonFlow to process the request end to end.

1. Application sends the governed request to /api/v1/process.
2. Agent accepts the request, or trusted internal callers send it to Orchestrator directly.
3. Orchestrator applies tenant policies and provider-routing rules.
4. Orchestrator calls the selected LLM provider or runtime path.
5. Orchestrator returns response data, policy info, provider info, and timing metadata.

Choose this path when you want one governed execution surface for policy, routing, cost metadata, response redaction, and audit. It is usually the better starting point for new AI applications because the request lifecycle is easier to reason about from one API.

Key docs:

MCP Connector Path​

MCP connector traffic needs its own mental model because a tool call may touch external systems before an LLM response is complete.

1. Plugin or MCP host sends a tool request through the Agent MCP surface.
2. Agent checks input with /api/v1/mcp/check-input before connector execution.
3. The connector runs only if the request is allowed.
4. Agent checks returned rows or payloads with /api/v1/mcp/check-output when output scanning is enabled.
5. Audit and decision records keep the tool activity inspectable.

Use this path for governed database access, HTTP connectors, storage connectors, SaaS connectors, and plugin-hosted tool calls. It is the path that lets policy, explainability, overrides, and audit apply to tools instead of only to model prompts.

Key docs:

Workflow Control Plane Path​

Workflow APIs are for multi-step plans, execution state, checkpointing, replay, and approval-aware workflow execution.

1. Application or platform automation creates or executes a plan.
2. Orchestrator stores workflow state and step metadata.
3. Policies, approvals, checkpoints, and provider routing apply at the relevant step boundary.
4. Platform teams inspect executions, replay decisions, or resume from checkpoints through the API.

Use this path when your product is not just sending one prompt, but coordinating several model calls, tools, retries, approvals, or external actions.

Key docs:

Direct Orchestrator Access​

Direct calls to 8081 are useful when:

  • the caller is an internal service inside the same trusted network boundary
  • platform automation needs audit search, policy management, provider management, planning, or replay APIs
  • you are debugging a self-hosted deployment locally

For user-facing application traffic, prefer Agent on 8080. That gives you the narrowest ingress surface and keeps system-policy, auth, audit, and MCP handling in the expected place.

Last updated on