> ## Documentation Index
> Fetch the complete documentation index at: https://hexelstudio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Register Docker images and implement the agent contract.

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](/docs/compute/sandboxes) 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](/docs/compute/instances) 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`).

<Note>
  The platform injects `AGENT_PORT` at runtime. Read it from the environment rather than hardcoding `8080`.
</Note>

### `/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.

```json theme={"dark"}
{
  "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

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    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"])
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"dark"}
    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);
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={"dark"}
    hexel compute agent register \
      --name fraud-detector \
      --image ghcr.io/your-org/fraud-agent:v1 \
      --capabilities "fraud-detection,streaming"
    ```
  </Tab>
</Tabs>

### Registration parameters

<ParamField path="name" type="string" required>
  Unique name for the agent. Used in the permanent endpoint URL.
</ParamField>

<ParamField path="image" type="string" required>
  Docker image reference (e.g., `ghcr.io/your-org/agent:v1`).
</ParamField>

<ParamField path="capabilities" type="string[]" required>
  Labels describing what the agent can do. Used for discovery and routing.
</ParamField>

<ParamField path="image_pull_secret" type="object">
  Credentials for private registries. Contains `registry`, `username`, and `password` fields.
</ParamField>

### Registration response

<ResponseField name="id" type="string">Unique agent identifier. Used to deploy instances.</ResponseField>
<ResponseField name="name" type="string">The registered agent name.</ResponseField>
<ResponseField name="image" type="string">The Docker image reference.</ResponseField>
<ResponseField name="capabilities" type="string[]">Registered capabilities.</ResponseField>
<ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>

## 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.

```python theme={"dark"}
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

```python theme={"dark"}
# 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")
```

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="How do I deploy an agent as an instance?">
    Use the REST API or CLI — see [Instances](/docs/compute/instances). The SDK does not have a `deploy` method on `client.compute.instance`.
  </Accordion>
</AccordionGroup>

## Limits & quotas

| Limit                        | Scope            | Behavior                                        |
| ---------------------------- | ---------------- | ----------------------------------------------- |
| Registered agents            | Per organization | Plan-enforced.                                  |
| Concurrent running instances | Per organization | Plan-enforced; see [Scaling](/docs/compute/scaling). |

Numeric limits depend on your plan — see the [Console](https://console.hexelstudio.com).

## 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.

## Related pages

<CardGroup cols={2}>
  <Card title="Instances" icon="server" href="/docs/compute/instances">
    Deploy a registered agent.
  </Card>

  <Card title="Skills" icon="wand-magic-sparkles" href="/docs/compute/skills">
    Reusable capabilities agents can run.
  </Card>

  <Card title="First Deployment" icon="rocket" href="/docs/getting-started/first-deployment">
    The full deploy walkthrough.
  </Card>

  <Card title="Agents (concept)" icon="robot" href="/docs/concepts/agents">
    The agent model.
  </Card>
</CardGroup>

## Next steps

Continue to [Instances](/docs/compute/instances) to deploy your agent.