Agents - Hexel Studio

An agent is a deployable unit of work in Hexel Studio: a Docker image that serves requests behind a stable, permanent endpoint. Agents are the things that fleets group, tasks route to, and tools attach to.

Key ideas

Term	Meaning
Agent	A registered Docker image with a name and capabilities.
Capabilities	Labels describing what an agent can do, used for discovery and routing.
Instance	A running deployment of an agent with a permanent endpoint.
Manifest	The `/.well-known/agent.json` document an agent serves, describing itself.

How it works

An agent image implements a small contract so the platform can host it, check its health, and route requests to it:

Endpoint	Method	Purpose
`/health`	GET	Liveness check.
`/.well-known/agent.json`	GET	Self-description and capabilities.
`/stream`	POST	Streaming responses (Server-Sent Events).
`/invoke`	POST	Single blocking responses.
`/execute`	POST	Run code or commands (sandbox-style agents).

Authentication is enforced by the platform — your agent code never validates tokens. The server listens on AGENT_PORT (default 8080).

`AGENT_PORT` environment variable

The platform injects AGENT_PORT into your container at runtime. Your HTTP server must bind to this port — not a hardcoded value. The platform routes traffic and health checks to this port exclusively. If your server binds to a different port, health checks fail and the instance never reaches Running.

import os
port = int(os.environ.get("AGENT_PORT", "8080"))
app.run(host="0.0.0.0", port=port)

Manifest: `/.well-known/agent.json`

The manifest declares your agent’s identity and capabilities to the platform. It must be served as a static JSON response at GET /.well-known/agent.json. Required fields:

Field	Type	Description
`name`	string	Human-readable agent name. Must match the registered name.
`version`	string	Semantic version of the running image (e.g., `"1.2.0"`).
`capabilities`	string[]	Array of capability labels (e.g., `["chat", "code-review"]`). Used for fleet routing and discovery.

{
  "name": "my-agent",
  "version": "1.2.0",
  "capabilities": ["chat", "code-review"]
}

If the manifest is missing or returns a non-200 status, the instance fails health checks and remains in deploying state indefinitely. The platform does not retry — fix the image and redeploy.

When you deploy, the instance gets a permanent endpoint derived from the agent identity and configuration:

https://agent-<name>-<hash>.compute.hexelstudio.com

Same configuration always resolves to the same URL.

Register and deploy

from hexel import Hexel

client = Hexel(api_key="YOUR_API_KEY")

agent = client.compute.agent.register(
    name="my-agent",
    image="ghcr.io/your-org/agent:v1",
    capabilities=["chat"],
)

Deploy an instance

hexel compute instance deploy YOUR_AGENT_ID

Or via REST:

curl -X POST https://api.hexelstudio.com/compute/v1/agents/YOUR_AGENT_ID/instances \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

See First Deployment for the full walkthrough.

Common mistakes

Confusing an agent with an instance. An agent is the registered image; an instance is a running deployment of it.
Skipping the contract. Without /health and a manifest, an instance can’t pass health checks and stays in deploying.

Best practices

Use clear, searchable capability labels.
Version your images explicitly so deployments are reproducible.

Compute → Agents

The full agent contract and registration.

Compute → Instances

Running deployments and endpoints.

Fleets

Group agents for orchestration.

Tools

Give agents external capabilities.

Next steps

Continue to Fleets to see how agents are grouped for orchestration.

​Key ideas

​How it works

​AGENT_PORT environment variable

​Manifest: /.well-known/agent.json

​Register and deploy

​Common mistakes

​Best practices

​Related pages

Compute → Agents

Compute → Instances

Fleets

Tools

​Next steps

Key ideas

How it works

`AGENT_PORT` environment variable

Manifest: `/.well-known/agent.json`

Register and deploy

Common mistakes

Best practices

Related pages

Next steps