Lesson 8: Talking to Your Agent

chat, invoke and serve - three ways to run the exact same built agent.

Talking to Your Agent

Once you've built your project (Lesson 7), there are three ways to run it - all load the exact same GeneratedAgentFactory.bx and build the exact same agent tree, so they never diverge from each other.

chat - an interactive REPL

bxAgents chat                                  # fast, in-process
bxAgents chat --server [--port=<port>]         # full app, own throwaway server
bxAgents chat --connect=http://127.0.0.1:8080  # full app, server you already run

Uses BoxLang's own MiniConsole for line reading. Requires a real interactive terminal (it shells out to stty for raw mode - it won't work piped or non-interactively). Type exit or quit to leave.

The default mode loads the generated factory directly in this process - fastest, but without anything ColdBox brings (no models/, no scheduler, no interceptors, no gateway registry). When that matters, --server boots a real miniserver and drives the REPL over HTTP against your project's always-on agent route, and --connect does the same against a server you already have running. Both HTTP modes stream the reply token by token and carry the server's threadId across turns, so a session is one conversation rather than a series of unrelated first messages.

invoke - one non-interactive turn

bxAgents invoke --message="What's the weather in Boston?" [--json]

Exists for scripting and CI, where chat's TTY requirement is a hard blocker. By default this loads the generated factory in-process, the same path chat uses internally, just without the REPL loop - no serve prerequisite at all. --json prints {"response": "..."} instead of plain text.

Add --server to instead launch a real, throwaway boxlang-miniserver process and send the message as a genuine HTTP request through your project's exposed route - useful once you've added a gateways/ entry (see Lesson 13).

serve - a real HTTP server

bxAgents serve --port=8080

Requires a prior build and requires boxlang-miniserver on PATH (see Lesson 3). Launches a real server process pointed at .build/app, scoped to its own .build/runtime BoxLang home so each project's compiled-class cache stays isolated.

Testing without a real API key

Every one of these needs a real model to talk to a real provider - but you don't need one yet. Add a test() override to Agent.bx (covered fully in Lesson 19):

function test() {
	return { model : "mock/mock-model" };
}

then bxAgents build --environment=test && bxAgents chat runs entirely against bx-ai's built-in mock provider - no network call, no API key.

Try it

export OPENAI_API_KEY=sk-...   # or use the mock override above
bxAgents chat

Say hello to the agent you scaffolded and wrote instructions for in Lessons 4-6. It's a real, running agent - you just haven't given it anything to do yet. That starts next lesson.

Full reference: Quick Start, CLI Reference.

Next: Lesson 9 - Giving Your Agent Tools