LLM API Reference

This page summarises the modules, agent classes, goals, beliefs and events described in this section. For implementation details, see the astra-langchain4j and astra-langchain4j-tools source.

astra-langchain4j

LLMModel

astra.langchain4j.LLMModel connects to a model. Its actions fail if the operation cannot be completed.

Operation	Purpose
`loadApiKeyFromEnv(name)`	Load the API key from an environment variable
`loadApiKeyFromFile(path)`	Load the API key from the first line of a file
`setApiKey(key)`	Set the API key directly
`initialize(model, configuration)` / `initialize(model, configuration, params)`	Create the model, using a configuration class and optional parameters such as `[temperature(0.2)]`
`chat(text, string reply)`	Send text and bind the reply
`chat(template, string reply)`	Render a template and send it. Fails if a placeholder is unbound

Templater

astra.langchain4j.Templater builds prompts and extracts values from replies. See Prompts, responses and beliefs.

Operation	Purpose
`createPromptTemplate(text)`	Create a `PromptTemplate` with `${name}` placeholders
`addBinding(template, name, value)`	Bind a placeholder
`reset(template)`	Clear the bindings for reuse
`toString(template)`	Render a template as text
`createResponseTemplate(text)`	Create a `ResponseTemplate` describing the text around values
`inferBindings(template, reply)`	Match a reply against a response template. Fails if it does not match
`getBinding(template, name)`	Read a value extracted by `inferBindings`
`createCompositeTemplate()` / `addTemplate(composite, template)`	Combine templates into one prompt

BelRAG

astra.langchain4j.BelRAG builds prompt text from beliefs. In 2.3.0, its input bindings are not substituted.

Operation	Purpose
`createRAGTemplate()` / `createRAGTemplate(text)`	Create a `RAGTemplate`
`addInput(template, query, text)`	Add a sentence template for each belief matching a query

Agent classes

Class	Purpose
`astra.langchain4j.LLMAgent`	Declares `module LLMModel model` and `!initialize(model, keyFile, configuration)` / `!initialize(model, keyFile, configuration, params)`
`OpenAIAgent`, `GeminiAgent`, `ClaudeAgent`	Extend `LLMAgent` with `!initialize(keyFile)` and `!initialize(keyFile, params)`, using a default model for the provider

Reasoning agents

The classes in astra.langchain4j.reasoning extend LLMAgent. See The reasoning architecture.

Class	Goal	Beliefs it reads
`BasicPrompting`	`!solve(question, answer)`	—
`ZeroShotChainOfThought`	`!solve(question, answer)`	—
`FewShotChainOfThought`	`!solve(question, answer)`	`example(question, reasoning, answer)`
`Pipeline`	`!runPipeline(input, transcript)`	`pipeline(list)`, `step(name, instruction)`; adds `stepOutput(input, name, output)`
`MultiStepChainOfThought`	`!solve(question, answer)`	As `Pipeline`; adds default steps if there is no `pipeline` belief
`ReAct`	`!solve(question, answer)`	`tool(name, description)`, `maxSteps(int)` (default 8); adopts `!invoke(name, input, observation)`
`ThreadOfThoughts`	`!solve(question, parts, answer)`	—
`TreeOfThoughts`	`!solve(question, answer)`	`branches(int)` (3), `beam(int)` (2), `depth(int)` (3)

In each goal, the inputs are bound when the goal is adopted, and the final argument is bound when it completes. parts is a list of strings.

astra-langchain4j-tools

A2A

astra.langchain4j.tools.a2a.A2A declares services, handles requests and calls other agents. See Agent-to-Agent communication.

Service declarations, made by the instance that receives !main(["describe"]):

Operation	Purpose
`describe(name, description, version, inputModes, outputModes)`	Set the AgentCard’s details. The content-type lists must not be empty
`skill(id, name, description, tags, examples)`	Declare a skill handled by this class. The lists must not be empty
`publish(defaultSkill)`	Publish the card, naming the default skill
`registrationFailed(reason)`	Report that the declarations could not be made

Request handling, by the worker that receives !main([id, contextId, skill, payload]):

Operation	Purpose
`listen(id, contextId, skill, payload)`	Deliver the request as a `$a2a.request` event
`progress(id, text)`	Report progress on the task
`complete(id, json)`	Complete the task with a JSON object result
`fail(id, reason)`	Fail the task with a reason
`active(id)`	Formula: true while the task is pending and within its deadline

Calling other agents:

Operation	Purpose
`send(url, skill, json, string call)`	Send a JSON object to a skill of the agent at `url`, binding a correlation identifier
`send(url, json, string call)`	Send to the agent’s default skill
`remoteUrl()`	Term: the `astra.remote` system property, or `http://localhost:8080`

Events, named after the module ($a2a for module ... A2A a2a;):

Event	Meaning
`$a2a.request(string id, string contextId, string skill, string payload)`	A request for this worker to handle
`$a2a.response(string call, string task, string result)`	A call completed with a JSON result
`$a2a.failure(string call, string task, string reason)`	A call failed
`$a2a.progress(string call, string task, string text)`	A called agent reported progress

Service configuration properties, in application.properties:

Property	Purpose
`astra.a2a.agent-class`	The ASTRA class that implements the service
`astra.a2a.url`	The URL advertised in the AgentCard

JSONConverter

astra.langchain4j.tools.JSONConverter reads and builds JSON. Paths are JSON Pointers, such as /items/0/name; bracket paths such as /items[0]/name are also accepted. Each reading operation accepts either a JSON string or a JsonNode.

Operation	Purpose
`parse(json)`	Term: parse a string into a `JsonNode`. Fails on invalid JSON, duplicate fields or trailing content
`getNode(json, path)`	Term: the node at a path
`hasField(json, path)` / `isNull(json, path)`	Formulae: test a path
`valueAsString`, `valueAsInt`, `valueAsLong`, `valueAsDouble`, `valueAsBoolean` (json, path)	Terms: read a typed value. Fail if the value is missing, null or of another type
`length(json, path)`	Term: the length of an array
`getFields(json)`	Term: the field names of an object, as a list
`compare(json, path, value)`	Formula: test a value
`object()`	Term: an empty object
`with(object, key, value)`	Term: a copy of an object with one field added or replaced. The value can be a string, number, boolean or `JsonNode`
`toJsonString(node)`	Term: the node as a JSON string

ASTRA code that declares JsonNode variables imports com.fasterxml.jackson.databind.JsonNode.

Inspector

astra.langchain4j.tools.a2a.Inspector launches a prepared checkout of the A2A Inspector.

Operation	Purpose
`start(directory)` / `start(directory, port)` / `start(directory, python, port)`	Start the Inspector, waiting up to 30 seconds for it to be ready
`stop()`	Stop the Inspector started by this module
`awaitExit()`	Block until the Inspector exits
`running()`	Formula: true while the Inspector is running
`url()`	Term: the Inspector’s URL
`directory()` / `port()`	Terms: the `astra.inspector.home` and `astra.inspector.port` properties, defaulting to `a2a-inspector` and 5001