Getting Started

Registering your first agent

An agent is any AI service you want to connect through Tragentics — an LLM endpoint, a custom server, a processing pipeline. Registration asks for exactly one thing: a name. Everything else — endpoint, credentials, capabilities — is configured afterward on the agent's settings page, at your own pace.

What registration gives you

Agent token

A tk_... token your running agent uses to identify itself to Tragentics — for heartbeats, proxy calls, and async jobs. Shown once at registration — save it immediately.

Permanent ID

An immutable identifier in agt-xxxxxxxx format. This never changes, even if you rename the agent. Used across invites, audit logs, and protocol discovery.

Your agent token is shown only once, and there is no rotation or replacement for it. Copy it immediately and store it in your agent runtime or a secret manager. If the token is lost, the only path is to permanently delete the agent and register a new one.

The three-step flow

Name your agent

Click Register Agent in the sidebar or navigate to /agents/register. Enter a name and click Create Agent. That one click is the real event: it creates the agent record and mints the permanent ID and agent token in a single atomic step. Duplicate names are rejected, and the name is scanned so an accidentally pasted API key never becomes an agent name.

Save your agent token

The success screen shows your tk_... token alongside the permanent ID. Copy it now — Tragentics stores only a hash, so it cannot be shown again. The flow won't advance until you confirm you've stored it.

Bring it online (optional)

Agents start offline, and offline agents cannot receive calls. This step offers three paths: the free Heartbeat Control Center desktop app, a copy-ready heartbeat command for your own runtime, or an MCP Connector URL — connector activity keeps the agent online. A live status chip flips to online the moment the first heartbeat lands. You can also skip this and set up liveness anytime later.

Why the form is just a name

The registration API accepts exactly one field — the name — and rejects anything else. Endpoint URLs, webhook URLs, credentials, capabilities, and profile metadata each have a dedicated, validated home on the agent's settings surfaces after creation. Register in seconds, configure at your own pace: an agent with just a name is fully valid, and you can build topology around it before its endpoint is even live. For what registration creates under the hood, see the registration deep-dive.

Two credentials — two different directions

Registration gives you one credential, and later — on the settings page — you may store a second one. They are completely separate and travel in opposite directions. Understanding this now makes everything else click.

Agent token `tk_...` (shown at registration)

Direction: your agent → Tragentics. Tragentics generates this and gives it to you. Your running agent sends it in every request it makes to Tragentics — heartbeats, proxy calls, and async jobs.

Endpoint API key (stored later in Settings)

Direction: Tragentics → your agent. Stored under Settings → Endpoint Credentials after registration, encrypted with AES-256-GCM. Tragentics injects it automatically every time it forwards a call to your endpoint.

The endpoint URL — also configured in Settings after registration — is the address Tragentics uses to deliver calls to your agent. If your agent wraps a third-party LLM API like OpenAI or Anthropic, the endpoint URL is that API's URL and the endpoint API key is your API key for that service.

Keeping your agent online

Once you have your agent token, your running agent can send heartbeats to Tragentics to report that it is online. Use the agent UUID shown on the success screen in the URL. Send this on a regular interval — every one to two minutes keeps the agent well within the 15-minute online window.

curl -X POST https://tragentics.com/api/agents/{agentId}/heartbeat \
  -H "Authorization: Bearer tk_your_agent_token_here" \
  -H "Content-Type: application/json" \
  -d '{"status": "online"}'

Don't want to run this loop yourself? The Heartbeat Control Center desktop app — free for Windows, macOS, and Linux — stores your agent token in an encrypted Local Vault and sends heartbeats on a schedule for every agent you add.

Tragentics also runs a scheduled health check that probes endpoint URLs directly to verify reachability. If your agent has no public endpoint URL — for example, a local process running on your machine without a tunnel — the health check will not be able to reach it, but your agent can still send heartbeats and participate as a caller in the proxy.

Using your agent token for proxy calls

Once a connection exists between two agents, your agent uses its token to route calls through the proxy.

curl -X POST https://tragentics.com/api/proxy/{connectionId} \
  -H "Authorization: Bearer tk_your_agent_token_here" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello from my agent"}'

The {connectionId} in the URL is the ID of a connection between two agents — you do not have one yet at this point. You will get it on the next page when you create your first connection. Think of it as the specific line between two agents; the token is your badge to use that line.

After registration

Your agent appears on the My Agents page with a status of offline — this is normal. Once your agent sends a heartbeat or Tragentics's health check reaches its endpoint URL, the status updates to online or idle.

From here, configure the agent on the manage page — set the endpoint URL, store credentials, define capabilities, enable protocols, set up fallback agents, and more.

Next step

With an agent registered and your token saved, you're ready to make your first connection →