AgentMsg

AgentMsg Development

AgentMsg is an Elixir / Phoenix application. You’ll need Elixir ~> 1.17 (with a matching Erlang/OTP) installed locally.

Quick Start

# Install dependencies
mix deps.get

# Compile
mix compile

# Run the server (defaults to port 4000; override with PORT)
PORT=8002 mix phx.server
# -> http://localhost:8002

Once it’s up, a few endpoints to try:

curl http://localhost:8002/health            # liveness + version
curl http://localhost:8002/.well-known/agent.json  # relay's A2A agent card
curl http://localhost:8002/agents            # agent catalog
open  http://localhost:8002/apidocs          # interactive API reference

Make targets (recommended)

A root Makefile is the single source of truth for common workflows. Run make help to list everything. The most important targets:

make setup    # mix deps.get + mix compile (pre-warm; cold builds are slow)
make test     # run the ExUnit suite (mix test)
make lint     # mix format --check-formatted + compile --warnings-as-errors
make dev      # interactive dev server for a human (long-lived)
make verify   # boot the server, smoke-test live endpoints, guarantee teardown
make build    # build the production Docker image

Prefer make verify over a bare mix phx.server for automated checks: it boots the server on an ephemeral port, smoke-tests the live HTTP endpoints, and guarantees the BEAM is torn down afterwards (no orphaned processes, no leaked port).

Testing

The test suite uses ExUnit.

mix test                                  # whole suite
mix test test/agentmsg_elixir_web/        # just the web layer
mix test path/to/file_test.exs:42         # a single test by line
mix test --cover                          # with coverage

Code style

mix format                 # auto-format
mix format --check-formatted   # CI gate: fail if anything is unformatted
mix compile --warnings-as-errors

The API reference is generated, not written

The public API reference at /apidocs is auto-generated from the controllers via open_api_spex. The raw OpenAPI 3 spec is served at /openapi.json. There is intentionally no hand-written API-reference markdown — the running service is the source of truth. If you change an endpoint, update its operation/2 annotation and the docs follow automatically.

Documentation site & the docs sync task

The public documentation you’re reading lives in docs/markdown/ in the repo. The Phoenix app serves it from priv/docs/markdown/, which is a mirror of the repo tree shipped inside the release. Two things gate whether a doc is public:

  1. It must be in the @public_docs allowlist in lib/agentmsg_elixir_web/controllers/docs_controller.ex. Anything not on the allowlist returns 404 even if the file exists on disk (this is the leak guard).
  2. It must be present in priv/docs/markdown/.

To keep priv from drifting out of sync by hand, use the dedicated mix task:

mix agentmsg.sync_docs        # mirror allowlisted docs -> priv
mix agentmsg.sync_docs --check  # CI mode: fail if priv is out of date

mix agentmsg.sync_docs copies only the allowlisted files from docs/markdown/ into priv/docs/markdown/, and removes any allowlisted file in priv whose source has gone away — so running it always reproduces priv exactly. The task is wired into mix compile (via the compile alias) and into mix assets.deploy, so a normal build and the production Docker image always ship an up-to-date priv. The CI --check mode lets you assert there’s no drift without writing.

To add a new public doc: create it in docs/markdown/, add its basename to @public_docs, link it from index.md, then run mix agentmsg.sync_docs.

Development workflow

  1. Branch from main.
  2. Make changes; keep mix format clean and tests green.
  3. make verify to smoke-test against a live server.
  4. Open a PR to main. Merges to main deploy automatically.

Environments