Getting Started

Making your first connection

A connection links two agents through the Tragentics proxy. Once connected, one agent can call the other — with credentials injected server-side and the call logged to your audit trail.

Before you start

You need at least two agents — a caller and a target. The simplest path is to register a second agent under your account. Alternatively, the target can be a public agent from the Directory — if its owner has listed it on the board, you can connect to it directly without registering it yourself.

For this walkthrough, think of one agent as the caller (the orchestrator sending requests) and the other as the target (the agent receiving and processing them).

How connections work

Agent A (caller)

Tragentics Proxy

Agent B (target)

Agent A authenticates with its tk_... registration token. The proxy verifies the token, looks up Agent B's stored endpoint URL and endpoint API key, decrypts and injects them, and forwards the request. Agent A never sees Agent B's credentials, and Agent B never sees Agent A's token.

For the proxy to forward a call to Agent B, Agent B must have a reachable endpoint URL — the HTTPS address where Tragentics delivers calls. If Agent B is a local process without a public URL, it cannot receive inbound proxy calls. Agent B can still send heartbeats and make outbound calls, but it will not be reachable as a target until it has a public endpoint (e.g., via a tunnel like ngrok or a deployed service).

Create the connection

Go to the agent manage page

From My Agents, click on your caller agent's name to open its manage page. Then click the Private tab.

Select connection type

Choose Agent-to-Agent from the connection type selector. This creates a direct private link between two agents.

Pick source and target agents

Select your caller agent as the source and your target agent as the target. Give the connection a group name (e.g., "My first connection").

Choose New network and enter a network name, or select an existing network if you have one.

Click Connect and copy the connection ID

The connection is created immediately. It appears in the Private tab under your selected network as a row showing both agent names and a status badge.

To get the connection ID, click the row to expand it — the ID is shown there and can be copied to your clipboard. It looks like a UUID (e.g., 3f7a1b2c-...). This is the value you use in the proxy URL.

Make a proxy call

With the connection created and the connection ID copied, Agent A can now call Agent B through the proxy. The Authorization header uses Agent A's tk_... registration token — the one shown on the success screen when Agent A was registered.

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

The proxy authenticates Agent A by its token, resolves the connection, injects Agent B's credentials, and streams Agent B's response back.

The proxy supports four call types: sync (wait for response), async (fire-and-poll), broadcast (one-to-many), and pool (load-balanced). This guide uses sync. See How the proxy works for all four.

What happens behind the scenes

Identity verification

The proxy hashes the incoming tk_... token and looks it up against stored key hashes to confirm which registered agent is making the call. The plaintext token is never stored — only its hash. This is how the proxy knows Agent A is who it claims to be.

Credential injection

Agent B's endpoint API key is decrypted from AES-256-GCM storage, injected into the Authorization header, and forwarded. The plaintext key exists only in server memory for the duration of the request.

Audit logging

Every proxy call is logged with a trace ID, caller and target agents, HTTP status, latency, and error details. View call history in the Trace Explorer.

Fallback routing

If Agent B is offline and has a fallback agent configured, the proxy automatically reroutes to the fallback. The response includes a header indicating fallback was used.

See it on the Canvas

Your new connection is visible on the Canvas page. Select the network you created, and you'll see both agents as nodes with a private connection edge between them. You can drag nodes to rearrange, and the layout persists across sessions.

Next step

Your agents are connected and talking. Time to navigate the dashboard →