Skip to main content

​
Agents

An agent is the thing doing the work. In MarginFront, an agent represents anything that produces billable activity — an AI agent, a microservice, a worker, a team of humans, a Lambda function, you name it. Whatever produces the usage you want to track, that’s an agent. You create an agent once. Then you attach metrics (signals) to it, attach pricing plans to it, and start logging usage events against it. Everything in MarginFront — pricing, usage tracking, invoicing — ultimately traces back to an agent.

​
Why agents exist

A common question: “Why do I need agents at all? Can’t I just track customer usage directly?” Short answer: because a single customer might use multiple different products/services you offer, and each one might bill differently. Agents let you split that up. Example: you run an AI company with three products — a chatbot, a document analyzer, and an image generator. Each one has different costs, different pricing, and different metrics. If you just tracked “usage per customer,” you’d smoosh all three together and lose the ability to bill them differently. Instead you create three agents (chatbot, doc-analyzer, image-gen), and every usage event says “customer X used agent Y.” Now you can set different prices per agent, see per-agent profitability, and give each customer an itemized bill. If you only have one product, you only need one agent. Still, create it — it’s the anchor everything else attaches to.

​
Create an agent

In plain English: Register a new agent (service, product, worker) with MarginFront so you can track and bill usage against it. Method & URL: 
POST /v1/agents
Authentication: API key in the Authorization header. See Authentication. Required fields:
  • name (string, max 255 chars) — Human-readable name for the agent. Shows up in the dashboard, on reports, and on invoices.
  • agentCode (string, max 255 chars) — A short, unique code for this agent that YOU pick. Think of it like externalId for customers — it’s the handle you’ll use to reference this agent in other API calls (especially usage events via the SDK). Pick something short and clear, like chatbot, doc-analyzer, cs-bot-v2.
Optional fields:
  • description (string) — A longer explanation of what this agent does. Useful for your team’s reference.
  • isActive (boolean, default true) — Whether the agent is currently in use. Set to false to retire an agent without deleting it.
  • context (object) — Any custom key/value pairs you want to attach. MarginFront stores them but doesn’t interpret them. Good place to stash things like { "department": "support", "tier": 1 }.
Example curl call: 
curl -X POST https://api.marginfront.com/v1/agents \
  -H "x-api-key: mf_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "agentCode": "cs-bot-v2",
    "description": "Our main GPT-4 powered support bot"
  }'
What you get back (201 Created): 
{
  "id": "b47e12fa-abcd-4567-8901-234567890abc",
  "name": "Customer Support Agent",
  "agentCode": "cs-bot-v2",
  "description": "Our main GPT-4 powered support bot",
  "isActive": true,
  "createdAt": "2026-04-10T14:30:00.000Z"
}
Common errors:
  • 400 Bad Request — You’re missing name or agentCode, or one of them is too long (255 char max). The response body tells you which.
  • 409 Conflict — An agent with that agentCode already exists in this org. Pick a different code, or update the existing agent.
  • 401 Unauthorized — Your API key is missing or wrong.
When to call this: Before you create any signals (metrics), pricing plans, or usage events. Agents are the foundation everything else builds on.

​
Read an agent

Method & URL: 
GET /v1/agents/{agentId}
What it returns: The full agent object, same shape as the create response. Common errors:
  • 404 Not Found — Agent doesn’t exist in this org.

​
List agents

Method & URL: 
GET /v1/agents
What it returns: Array of agents. When to use it: Syncing a local cache, populating dropdowns, checking what exists before creating.

​
Update an agent

Method & URL: 
PATCH /v1/agents/{agentId}
Fields: Any field from create. All optional on update — only send what you want to change. Example — retire an agent without deleting it: 
curl -X PATCH https://api.marginfront.com/v1/agents/b47e12fa-... \
  -H "x-api-key: mf_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"isActive": false}'
Common errors:
  • 404 Not Found — Agent doesn’t exist.

​
Delete an agent

Method & URL: 
DELETE /v1/agents/{agentId}
What it does: Permanently removes the agent. You have to delete or reassign any signals and pricing plans attached to this agent first — if you don’t, the delete fails with a foreign-key error.
Usually you want isActive: false instead of delete. Setting isActive: false (via PATCH) keeps all the historical usage data intact and just marks the agent as “no longer in use.” Deleting an agent is rare and mostly useful for cleaning up mistakes.
Common errors:
  • 409 Conflict — Agent still has signals or pricing plans attached. Clean those up first.

​
Using the Node SDK

The SDK doesn’t have an mf.agents resource yet, but it references agents by agentCode when you log usage events: 
await mf.usage.record({
  customerExternalId: "acme-001",
  agentCode: "cs-bot-v2", // ← this is your agent's agentCode
  signalName: "messages",
  model: "gpt-4o",
  inputTokens: 523,
  outputTokens: 117,
});
The agentCode has to match an agent you’ve already created via the admin API. If it doesn’t match anything, MarginFront will auto-create a minimal agent for you using that code — convenient for prototyping but you’ll want to go back and flesh out the agent’s name and description afterwards.