Agent Connector Quickstart

Run an AI agent as a LittleHorse task worker using the Agent Connector. In this quickstart, a workflow passes a text request to a local Qwen model, which can call a restricted Yahoo Finance MCP tool, then stores the agent's response.

The runnable code and configuration are in the Developer Hub Agent Connector quickstart.

What You Will Build

input (STR) -> text-to-text-agent -> output (STR)

The text-to-text-example WfSpec declares a required input string and assigns the result of text-to-text-agent to an output string. The connector registers the TaskDef and runs its worker; the Java example only registers the workflow. Workflow-authoring code does not run the model itself.

Docker Compose runs LittleHorse Server, Dashboard, Kafka, Ollama, and the connector. LittleHorse and the connector use prebuilt 1.3.0 images, and workflow registration uses the Java SDK 1.3.0. No connector build, host Ollama installation, or paid model API key is required.

Prerequisites

• Docker with Docker Compose v2 and a running Docker daemon.
• Java 21 and lhctl 1.3.0 or newer. See system setup for installation instructions.
• Internet access for image, dependency, and model downloads and the third-party MCP endpoint.
• Docker memory and disk space for LittleHorse, the Java connector, and qwen3:4b. The model download is approximately 2.5 GB; inference needs additional memory. The default Compose configuration uses CPU inference, which can be slow.
• Available host ports 2023 and 8080. Stop a standalone LittleHorse container from earlier quickstarts before proceeding.

Use a shell without cloud-specific LHC_* authentication settings. This example connects to a local plaintext server.

1. Set Up The Services And Workflow

Clone the Developer Hub and run setup from its repository root:

git clone https://github.com/littlehorse-enterprises/lh-developer-hub.git
cd lh-developer-hub
./examples/agent-connector/00-quickstart/setup.sh

The setup script:

1. Starts ghcr.io/littlehorse-enterprises/littlehorse/lh-standalone:1.3.0, containing LittleHorse Server, Dashboard, and Kafka.
2. Starts Ollama in Compose and pulls qwen3:4b into its model-cache volume.
3. Starts ghcr.io/littlehorse-enterprises/lh-agent-connector:1.3.0 with TEXT input/output and the MCP configuration.
4. Waits for the connector's text-to-text-agent TaskDef, then registers text-to-text-example using the Java SDK.

Services stay running in the background. Setup does not start a workflow run. The Dashboard is available at http://localhost:8080.

Model And Tool Configuration

The connector calls Ollama through its OpenAI-compatible API. It includes only the MCP server's get_quote tool, presented to the model as yahoo_get_quote. Its system message asks the model to use tools for market data and explain unavailable capabilities rather than guess.

Third-party tool

The endpoint at https://gateway.mcpservers.org/yahoo-finance/mcp is a third-party service, not an officially supported Yahoo Finance MCP server. Its availability and data are outside LittleHorse's control. The tool catalog loads lazily, so successful setup does not prove that a subsequent tool call will succeed.

The quickstart keeps the source example's qwen3:4b model because tool selection and instruction following are important here. Smaller models have not been verified for this scenario. To experiment, set OLLAMA_MODEL when running setup; this changes both the model download and the connector's model configuration:

OLLAMA_MODEL=qwen3:1.7b ./examples/agent-connector/00-quickstart/setup.sh

Each model call has a four-minute timeout and one attempt. The workflow's agent task has a five-minute total timeout. Slow CPU inference or multiple model/tool calls can exceed that task budget.

2. Run The Workflow

Use the supplied local CLI configuration explicitly, so an existing cloud configuration cannot redirect the commands. This does not overwrite your LittleHorse configuration file. Run all commands from the Developer Hub repository root:

lhctl --configFile examples/agent-connector/00-quickstart/littlehorse.config \
  run text-to-text-example input \
  "What is Apple's latest available stock price and how does it compare with its previous close?"

The agent can call yahoo_get_quote and save its natural-language comparison in output. Responses are model-generated, not fixed expected strings.

3. Inspect The Result

Use the WfRun ID printed by the run command:

lhctl --configFile examples/agent-connector/00-quickstart/littlehorse.config \
  get wfRun <wf-run-id>
lhctl --configFile examples/agent-connector/00-quickstart/littlehorse.config \
  get variable <wf-run-id> 0 output

You can also inspect the workflow and its task execution in the Dashboard at http://localhost:8080.

Try An Excluded Capability

Only quote lookup is available. Run a request requiring the excluded quote_summary tool:

lhctl --configFile examples/agent-connector/00-quickstart/littlehorse.config \
  run text-to-text-example input \
  "Retrieve Apple's company profile and latest full-time employee count from Yahoo Finance."

The connector does not expose that tool. Its system message asks the model to explain the limitation in output; model compliance is not guaranteed.

If a run fails, inspect the task error and the connector logs:

docker compose -p lh-agent-quickstart \
  -f examples/agent-connector/00-quickstart/compose.yaml logs agent

Check the MCP endpoint's availability and Docker resource limits. For slow inference, increase the task timeout in AgentWorkflow.java and rerun workflow registration as described in the Developer Hub README.

Cleanup

From the Developer Hub repository root:

./examples/agent-connector/00-quickstart/setup.sh --clean

This removes the quickstart's containers and volumes, including workflow definitions, run history, and cached Ollama models. It does not stop other Docker projects or a host Ollama service.

For the full configuration and source-file walkthrough, see the Developer Hub README. Learn more about combining agents with workflow orchestration in the Decision Worker Pattern.