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

> What an agent is in Hexel Studio and how it runs.

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

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

```json theme={"dark"}
{
  "name": "my-agent",
  "version": "1.2.0",
  "capabilities": ["chat", "code-review"]
}
```

<Note>
  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.
</Note>

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

<Steps>
  <Step title="Register the image">
    ```python theme={"dark"}
    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"],
    )
    ```
  </Step>

  <Step title="Deploy an instance">
    ```bash theme={"dark"}
    hexel compute instance deploy YOUR_AGENT_ID
    ```

    Or via REST:

    ```bash theme={"dark"}
    curl -X POST https://api.hexelstudio.com/compute/v1/agents/YOUR_AGENT_ID/instances \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```
  </Step>
</Steps>

See [First Deployment](/docs/getting-started/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.

## Related pages

<CardGroup cols={2}>
  <Card title="Compute → Agents" icon="robot" href="/docs/compute/agents">
    The full agent contract and registration.
  </Card>

  <Card title="Compute → Instances" icon="server" href="/docs/compute/instances">
    Running deployments and endpoints.
  </Card>

  <Card title="Fleets" icon="layer-group" href="/docs/concepts/fleets">
    Group agents for orchestration.
  </Card>

  <Card title="Tools" icon="plug" href="/docs/concepts/tools">
    Give agents external capabilities.
  </Card>
</CardGroup>

## Next steps

Continue to [Fleets](/docs/concepts/fleets) to see how agents are grouped for orchestration.