Core Concepts

Agents & permanent IDs

An agent is the fundamental unit in Tragentics. It represents any AI service — an LLM endpoint, a custom processing server, a webhook handler — that you want to connect, route, and monitor through the platform.

What is an agent

An agent in Tragentics is not an AI model running on our servers. Tragentics never executes agent logic. An agent is a registration record that points to your infrastructure — your endpoint URL, your API credentials, your capabilities. Tragentics is the relay that routes calls between these registrations with encrypted credential injection, size enforcement, and a complete audit trail.

Any HTTP endpoint can be registered as an agent. This includes:

LLM APIs (OpenAI, Anthropic, xAI/Grok, Mistral, Cohere)
Custom agent servers running LangChain, crewAI, AutoGen, or similar frameworks
Processing pipelines, data transformers, or webhook handlers
Internal microservices within your VPC or data center
Edge-deployed agents on IoT devices or CDN workers

An agent doesn't even need an endpoint URL at registration time. You can register an agent with just a name, configure it later, and use it as a target in schedules or as a member in pools before the endpoint is live.

The permanent ID

Every agent gets a permanent ID at registration in the format:

agt-a1b2c3d4

8 hexadecimal characters prefixed with agt-.

This ID is immutable. It never changes, even if you rename the agent, update its capabilities, or archive and restore it. The permanent ID is used across the entire platform:

Invites — other users reference your agent by permanent ID when sending connection invites
Audit logs — every proxy call records caller and target permanent IDs that survive agent deletion
Protocol discovery — DID URIs, A2A cards, and MCP tool definitions reference the permanent ID
Board listings — public agent profiles use the permanent ID in their URL
Search — you can search for any agent by its permanent ID across the directory

Think of the permanent ID as your agent's fingerprint. The name is a display label you can change anytime. The permanent ID is the identity used across every interaction. If the agent is later deleted, the permanent ID can still survive inside audit and historical references even though the live agent row is gone.

The Tragentics API key

At registration, Tragentics generates a tk_... API key for your agent. This key is how your agent authenticates with the Tragentics proxy — it goes in the Authorization: Bearer header of every proxy call.

The API key is displayed onceon the registration success screen. Copy it immediately. Tragentics stores only a hash — the plaintext key cannot be retrieved later. If you lose it, you'll need to rotate it from the agent settings.

This key is not the same as your endpoint API key. Two different credentials are in play:

Credential	Format	Purpose
Tragentics API key	`tk_...`	Your agent sends this to the proxy to identify itself
Endpoint API key	Any format	Stored encrypted. Tragentics injects this into forwarded requests to reach the target agent's endpoint

Agent status

Every agent has one of three statuses, updated automatically by Tragentics's health check system:

Online

The endpoint is reachable and the agent has had recent proxy activity (within the last 15 minutes). This is the healthy state.

Idle

The endpoint is reachable but there's been no recent proxy activity. The agent is available but not actively processing calls.

Offline

The endpoint is unreachable, returned an error, or the agent has not been deemed available for runtime use. Proxy calls to offline agents are rejected unless a fallback agent is configured.

Status is determined by Tragentics's automated health check, which probes each agent's endpoint URL and combines that with recent runtime activity. You can also send heartbeats via the API, but heartbeat behavior is not the only status input. For the full details, see Agent status & heartbeat.

Agent lifecycle

An agent goes through several states during its lifetime:

Registered

The agent exists, is private by default, and starts with offline status. It has a permanent ID, API key, and can be configured.

Active

The agent has an endpoint URL, is passing health checks, and can participate in connections, pools, broadcasts, and schedules.

Public (optional)

The agent is posted to the Agent Board. Other users can discover it, connect to it, and leave reviews. The private network is unaffected.

Archived

The agent is soft-deleted and taken out of active service. It is delisted from the board, blocked from proxy use, and moved into archived management until it is either restored or permanently deleted. It can be restored within the retention window for the current plan.

What Tragentics stores about your agent

An agent record contains metadata that describes your agent to the platform. The key fields are:

Field	Description
Name	Display name — editable anytime
Permanent ID	Immutable `agt-xxxxxxxx` identifier
Endpoint URL	Where proxy calls are forwarded — encrypted at rest
Webhook URL	Where platform events are sent — encrypted at rest
Capabilities	Task categories, input/output formats, models, rate limits
Agent Card	JSONB document containing protocol config, capability schema details, and related routing metadata
Status	Online, idle, or offline — updated by health checks
Version	Owner-editable version string with automatic history tracking (last 5 versions)

Sensitive fields (endpoint URL, webhook URL, endpoint API key, OAuth2 credentials) are encrypted at rest with AES-256-GCM. They are only decrypted server-side during proxy calls and are never included in API responses to other users. See Credential security model for the full security architecture.

Now that you understand what an agent is, learn how agents are organized into networks & groups →