Agents - Hexel Studio

An agent is a Docker image that responds to HTTP requests. You register one when you have a service that needs to run persistently behind a stable URL — a fraud detection service that scores transactions, a coding assistant that streams completions, a RAG pipeline that answers questions against your docs. If you only need one-off execution without a permanent endpoint, a sandbox is simpler. Registering an agent tells the platform “this image exists and is ready to be deployed.” Once registered, an agent can be deployed as an instance with a permanent endpoint. To run on the platform, your image must implement a small HTTP contract.

The agent contract

Your image serves these endpoints. The platform handles authentication in front of them — your application code never validates tokens.

Endpoint	Method	Purpose
`/health`	GET	Liveness check. Return `{"status": "ok"}`.
`/.well-known/agent.json`	GET	Agent manifest describing identity and capabilities.
`/stream`	POST	Streaming response over Server-Sent Events.
`/invoke`	POST	Single blocking response.
`/execute`	POST	Run code or a command (for sandbox-style agents).

Your server listens on the port given by the AGENT_PORT environment variable (default 8080).

The platform injects AGENT_PORT at runtime. Read it from the environment rather than hardcoding 8080.

`/stream` and `/invoke` request shape

Both receive the caller’s JSON body (e.g., {"query": "..."}) and respond with the agent’s output — a stream of Server-Sent Events for /stream, or a single JSON response for /invoke.

Manifest (`/.well-known/agent.json`)

Returns a JSON document advertising the agent’s identity and capabilities for discovery and routing. Serve the capabilities you registered the agent with.

{
  "name": "fraud-detector",
  "version": "1.0.0",
  "capabilities": ["fraud-detection", "streaming"],
  "description": "Analyzes transactions for fraud indicators."
}

SDK methods

Method	Description
`client.compute.agent.register(...)`	Register a new agent from a Docker image.
`client.compute.agent.list()`	List registered agents.
`client.compute.agent.get(id)`	Get agent details.
`client.compute.agent.update(id, ...)`	Update agent metadata or image.
`client.compute.agent.delete(id)`	Delete an agent registration.
`client.compute.agent.search(q=...)`	Search agents by name or capabilities.

Register an agent

Python
TypeScript
CLI

from hexel import Hexel

client = Hexel(api_key="YOUR_API_KEY")

agent = client.compute.agent.register(
    name="fraud-detector",
    image="ghcr.io/your-org/fraud-agent:v1",
    capabilities=["fraud-detection", "streaming"],
)
print(agent["id"])

import { Hexel } from "hexel-sdk";

const client = new Hexel({ apiKey: "YOUR_API_KEY" });

const agent = await client.compute.agent.register({
  name: "fraud-detector",
  image: "ghcr.io/your-org/fraud-agent:v1",
  capabilities: ["fraud-detection", "streaming"],
});
console.log(agent.id);

hexel compute agent register \
  --name fraud-detector \
  --image ghcr.io/your-org/fraud-agent:v1 \
  --capabilities "fraud-detection,streaming"

Registration parameters

string

required

Unique name for the agent. Used in the permanent endpoint URL.

string

required

Docker image reference (e.g., ghcr.io/your-org/agent:v1).

string[]

required

Labels describing what the agent can do. Used for discovery and routing.

object

Credentials for private registries. Contains registry, username, and password fields.

Registration response

string

Unique agent identifier. Used to deploy instances.

string

The registered agent name.

string

The Docker image reference.

string[]

Registered capabilities.

string

ISO 8601 creation timestamp.

Private registries

For images in a private registry, provide pull credentials at registration. Credentials are encrypted at rest and used only to pull the image.

agent = client.compute.agent.register(
    name="my-agent",
    image="YOUR_REGISTRY/agent:v1",
    image_pull_secret={
        "registry": "YOUR_REGISTRY",
        "username": "YOUR_REGISTRY_USERNAME",
        "password": "YOUR_REGISTRY_TOKEN",
    },
)

List, search, update, and delete

# List all registered agents
agents = client.compute.agent.list()

# Search by name or capability
results = client.compute.agent.search(q="fraud")

# Update image or capabilities
client.compute.agent.update("YOUR_AGENT_ID", image="ghcr.io/your-org/fraud-agent:v2")

# Get details
agent = client.compute.agent.get("YOUR_AGENT_ID")

# Delete
client.compute.agent.delete("YOUR_AGENT_ID")

What happens when I update an agent's image?

Existing running instances are not affected. The updated image takes effect on the next deploy or redeploy.

Can I register the same name twice?

No. Agent names are unique within your organization. Delete the existing agent first, or use update to change its image.

How do I deploy an agent as an instance?

Use the REST API or CLI — see Instances. The SDK does not have a deploy method on client.compute.instance.

Limits & quotas

Limit	Scope	Behavior
Registered agents	Per organization	Plan-enforced.
Concurrent running instances	Per organization	Plan-enforced; see Scaling.

Numeric limits depend on your plan — see the Console.

Errors

`error_code`	HTTP	When
`invalid_request`	400	Missing `name` or `image`, or malformed pull secret.
`not_found`	404	The agent ID doesn’t exist.
`forbidden`	403	Credentials lack permission for this workspace.
`internal_error`	500	Transient platform error. Retry or contact support.

Security

Concern	How it’s handled
Agent authentication	The platform authenticates traffic to deployed agents; your image never validates tokens.
Image pull credentials	Encrypted at rest and used only to pull the image. Never returned by the API.
Scoping	Agents and instances are scoped to your organization, workspace, and environment.

Common mistakes

Missing /health or the manifest. Without them, instances never pass health checks and stay in deploying.
Validating tokens in your code. The platform handles auth; don’t reimplement it.
Hardcoding the port. Read AGENT_PORT from the environment rather than assuming 8080.

Best practices

Tag images with explicit versions (:v1), not :latest.
Advertise accurate capabilities so discovery and routing work.
Keep /health cheap so health checks stay reliable.

Instances

Deploy a registered agent.

Skills

Reusable capabilities agents can run.

First Deployment

The full deploy walkthrough.

Agents (concept)

The agent model.

Next steps

Continue to Instances to deploy your agent.

​The agent contract

​/stream and /invoke request shape

​Manifest (/.well-known/agent.json)

​SDK methods

​Register an agent

​Registration parameters

​Registration response

​Private registries

​List, search, update, and delete

​Limits & quotas

​Errors

​Security

​Common mistakes

​Best practices

​Related pages

Instances

Skills

First Deployment

Agents (concept)

​Next steps

The agent contract

`/stream` and `/invoke` request shape

Manifest (`/.well-known/agent.json`)

SDK methods

Register an agent

Registration parameters

Registration response

Private registries

List, search, update, and delete

Limits & quotas

Errors

Security

Common mistakes

Best practices

Related pages

Next steps