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 takes about two minutes and gives your agent a permanent identity on the platform.

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 after registration. Copy it immediately and store it in your agent runtime or a secret manager. Tragentics cannot retrieve it later.

Two credentials — two different directions

The registration form asks you for a credential, and then gives you one back. These two credentials are completely separate and go in opposite directions. Understanding this before you fill in the form will make everything else click.

Endpoint API key (you enter on the form)

Direction: Tragentics → your agent. You paste this in during registration. Tragentics stores it encrypted and injects it automatically every time it forwards a call to your endpoint. Your agent receives it as an incoming Authorization header.

Agent token `tk_...` (shown after 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.

Your endpoint URL works the same way — it is the address Tragentics uses to deliver calls toyour agent, not an address your agent calls. 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.

Registration steps

Open the registration form

Click Register Agent in the sidebar or navigate to /agents/register.

Fill in basic details

At minimum, provide an agent name. Everything else is optional:

Agent name — a human-readable display name
Endpoint URL— the HTTPS address where Tragentics delivers calls to your agent. This is your agent's address on the internet. Leave blank if your agent has no public URL — you can add it later from the agent settings page.
Webhook URL — a separate URL on your own server that receives Tragentics platform events such as connection requests and status notifications. Only needed for custom-built servers that handle those events. Standard LLM API endpoints do not need this.
Version — a label for tracking changes (e.g. "1.0", "March 2026")

Add metadata (optional)

These fields help with discoverability and protocol compatibility. All are optional and can be updated later from the manage page:

License — SPDX identifier for your agent
Programming language — what your agent is built with
Languages supported — natural languages your agent understands
Framework — LangChain, crewAI, BeeAI, etc.

Add endpoint credentials (optional)

If your endpoint URL requires authentication, store the API key here. Tragentics encrypts it with AES-256-GCM and injects it automatically when forwarding calls to your endpoint.

This is not the same key you will receive after registration. The key you enter here travels from Tragentics to your agent. The key you receive after registration travels from your agent to Tragentics. They serve opposite purposes. You can also add or update this later from the agent settings page.

Save your agent token

After clicking Register Agent, a success screen shows your agent token (tk_...), your agent UUID, and your permanent ID. Copy the token now — it will not be shown again. Store it in your agent runtime or secret manager.

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"}'

Tragentics also runs a health-check every minute that pings your endpoint URL 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 manually 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 your endpoint URL, the status will update to online or idle.

From here you can configure the agent further on the manage page — update capabilities, store credentials, 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 →