Skip to content
ctxmesh

Quickstart

This is the happy path, start to finish. You’ll give an agent a model, deploy it, and talk to it.

0. Make a namespace to work in

Section titled “0. Make a namespace to work in”

Every manifest below lands in my-team. Create it, and a token that may build and run agents there (the same steps as signing in to the console, for this namespace):

Terminal window
kubectl create namespace my-team
kubectl -n my-team create serviceaccount ctxmesh-builder
kubectl -n my-team create rolebinding ctxmesh-builder --clusterrole=ctxmesh-developer --serviceaccount=my-team:ctxmesh-builder
TOKEN=$(kubectl -n my-team create token ctxmesh-builder --duration=8h)
kubectl -n ctxmesh port-forward svc/ctxmesh-bff 9090:9090 &   # the console and its API

1. Give agents a model

Section titled “1. Give agents a model”

Agents call the gateway with a model alias; a ModelRoute (whose name is the alias) resolves it. For a zero-key first run, use the built-in mock provider:

apiVersion: agents.ctxmesh.ai/v1beta1
kind: ModelRoute
metadata:
  name: default-model
  namespace: my-team
spec:
  providers:
    - provider: mock            # deterministic mock — no API key needed
      model: mock-default
      priority: 1
Terminal window
kubectl apply -f modelroute.yaml
kubectl wait modelroute/default-model -n my-team --for=condition=Ready --timeout=5m

(Swap in a real provider + a SecretBinding later — see Connect a model provider.)

2. Deploy the agent

Section titled “2. Deploy the agent”
apiVersion: agents.ctxmesh.ai/v1beta1
kind: AgentDeployment
metadata:
  name: hello-agent
  namespace: my-team
spec:
  image: ghcr.io/ctxmesh/echo-agent:v0.1.0-beta.8
  executionModel: serving
  env:
    - name: MODEL_ROUTE       # the ModelRoute from step 1; without it this agent only echoes
      value: default-model
Terminal window
kubectl apply -f hello-agent.yaml
kubectl get agentdeployment hello-agent -n my-team -w
# wait for Ready=True

3. Talk to it

Section titled “3. Talk to it”

Call the agent through the control plane, which mints the run’s capability:

Terminal window
curl -s -X POST http://localhost:9090/api/invoke -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"agent":"hello-agent","namespace":"my-team","input":"hello"}'

The reply carries the mock model’s answer and the run’s traceId. (The agent’s own URL in status.url answers a direct request too, but that call skips the control plane: no capability, no record.)

4. See what it did

Section titled “4. See what it did”

Per-step traces and cost come from a trace backend, which a stock install does not include. Connect one and the console’s Runs page lists this run with its step → tool → model tree and its cost: see Observability backends.

You’ve done it

Section titled “You’ve done it”

You deployed a governed, autoscaled agent and called it through the control plane. Next, make it real: