ASTRA Programming Language

1. Getting Started

  • Quick Start
    • What you’ll need
    • Create your first project
    • Run it
    • ASTRA and IDE Integration
    • Make your first change
    • Where next?
  • Check your setup
    • Confirm Java and Maven
    • Choose an editor
    • Know which files to edit
    • If the first run fails
    • Continue

2. Programming with ASTRA

  • Guide overview
  • Understanding an agent
    • Read a complete program
    • Follow the reasoning cycle
    • Keep the model small
  • Representing knowledge
    • Types and bindings
    • Combine facts and conditions
    • Maintain consistent state
    • Further Details
      • Beliefs and inference
        • How to model some knowledge as a belief
        • Logical Expressions
        • Inference Rules
      • Types and operators
        • Types
        • Operators
  • Writing plans
    • Choose between plans and conditions
    • Work with lists
    • Distinguish goals from actions
    • Make execution understandable
    • Further Details
      • Variables, choice and repetition
        • Variables in ASTRA
        • Choice in ASTRA
        • Repetition in ASTRA
        • Dynamic goal invocation
      • Working with lists
        • Declaring Lists
        • Iterating through Lists
        • A Larger Example
        • Shuffle and Sort Example
        • Summary
  • Designing goal-directed behaviour
    • Develop the mental model
    • Give each plan a role
    • Model prerequisites explicitly
    • Keep the boundary visible
    • Further Details
      • Practical reasoning programming style
        • Why “Practical Reasoning”?
        • The plan types at a glance
        • The running example
        • Principle 1: Deliberation Plans
        • Principle 2: Means-End Reasoning Plans
        • Principle 3: Repair Plans
        • Principle 4: Keep goals and actions apart
        • Principle 5: Recovery Plans
        • Principle 6: Reactive Plans
        • Principle 7: Domain Modelling
        • Example 1: Light Switch
        • Example 2: Towerworld
        • Checklist
        • References
  • Observing and acting
    • Create the device module
    • Use the device from an agent
    • Choose an observation mechanism
    • Further Details
      • Custom actions and output parameters
        • Declaring a Custom Module
        • Creating an Action
        • Returning an Output Value
        • Action Execution and Shared State
        • Using the Module
      • Custom terms and formulae
        • Creating a Custom Term
        • Creating a Custom Formula
        • Choosing Between Terms, Formulae and Beliefs
        • Using the Module
      • Sensors and observed beliefs
        • Starting Point
        • Using the Module
        • Polling and External Changes
        • Ownership and Consistency
      • Custom events and unification
        • Defining a Custom Event
        • Implementing an EventUnifier
        • Linking the Event to the Module
        • Using the Module
        • Sensors or Events?
  • Handling uncertainty and failure
    • Choose a knowledge check
    • Bound external waits
    • Recover at the right level
    • Preserve evidence and progress
    • Further Details
      • Test goals
        • How a test goal is evaluated
        • Writing test goal plans
        • Example
        • Test goals compared with other checks
        • Things to know
      • Failure handling
        • What counts as a failure
        • try / recover
        • Goal failure events
        • Which handler is used?
        • Unhandled failures
        • Choosing between them
  • Managing ongoing activities
    • Choose the execution model
    • See continuous selection in a small example
    • Protect concurrent updates
    • Make lifetimes explicit
    • Further Details
      • Encapsulated goals
        • Syntax
        • How an encapsulated goal runs
        • Example: stopping a long-running activity
        • Example: a goal that reacts to events
        • Example: succeed or give up
        • Ending a goal
        • References
      • Teleo-reactive functions
        • Syntax
        • How a function runs
        • Actions
        • Example: counting to a target
        • Calling other functions
        • Starting and stopping functions from plans
        • Errors
        • Functions and inheritance
        • References
      • Synchronization and atomic plans
        • Synchronized blocks
        • Synchronized plans
        • Atomic plans
        • Choosing a mechanism
  • Reusing behaviour
    • Share declarations
    • Inherit behavior deliberately
    • Invoke goals represented as data
    • Test the boundary
    • Further Details
      • Multiple inheritance
        • Single Inheritance
        • Multiple Inheritance
      • Callable goals and dynamic invocation
        • Invoking a goal represented as text
        • Native subgoal semantics
        • Callable metadata
        • Goals module reference
        • Using callable goals with MCP
  • Building cooperating agents
    • Agree on message meaning
    • Implement the controller
    • Create the controller and make a request
    • Grow the conversation safely
    • Further Details
      • Agent creation and lifecycle
        • Overview
        • Create a Replicator agent
        • Create a Main agent
        • Run the application
        • Summary
        • See Also
      • Message semantics and syntax
        • Messages as actions
        • The parts of a message
        • Performatives
        • Sending messages
        • Receiving messages
        • Example: asking for prices
        • Things to know
      • Interaction protocols and timeouts
        • An Authentication Agent
        • Integrating Timeouts into Conversations
        • Prewritten Protocols
  • Testing, building and running
    • Run the guide examples
    • Test observable behavior
    • Understand the build boundary
    • Finish the application lifecycle
    • Further Details
      • Testing ASTRA programs
        • Setting up a project
        • Writing a test
        • Assertions
        • Testing multi-agent behaviour
        • Running the tests
      • Building and deploying ASTRA programs
        • Creating a project from scratch
        • How ASTRA builds work
        • Understanding the Hello World program
        • Running a “non-default” Agent Program
        • Summary
        • See Also

3. Environments

  • Environments Overview
    • Choose an environment interface
    • Related guides
  • CArtAgO Environments
    • Concepts
    • Project setup
    • Use the environment
      • Build a counter artifact
      • Use the artifact from ASTRA
    • Observations and events
    • Share the environment
    • Results and failures
    • API reference
    • Further reading
  • EIS Environments
    • Concepts
    • Project setup
    • Use the environment
    • Observations and events
    • Share the environment
    • Results and failures
    • API reference
    • Further reading

4. LLM Integration

  • Introducing LLM Integration
    • Two libraries
    • How the parts fit together
    • What ASTRA contributes
    • Where to start
    • Background
  • Your First LLM Agent
    • Set up a project
    • Make an LLM request
    • Choose a provider
    • The LLMAgent class
    • Test without a provider
    • Where next?
  • Prompts, Responses and Beliefs
    • Create and reuse prompts
    • Extract and validate responses
    • Include beliefs in a prompt
    • Combine templates
    • Where next?
  • The Reasoning Architecture
    • The strategy classes
    • The solve contract
    • Answers and fallbacks
    • Run the examples
    • Choosing a strategy
    • Origin of the reasoning agents
  • Prompting and Chain of Thought
    • Direct prompting
    • Zero-shot chain of thought
    • Few-shot chain of thought
    • Where next?
  • Pipelines
    • Multi-step chain of thought
    • Using Pipeline directly
    • Changing the steps at run time
    • Where next?
  • ReAct: Reasoning with Tools
    • Declaring tools
    • Example: answering from beliefs
    • What happens on each turn
    • Writing good tools
    • Where next?
  • MCP and Callable Goals
    • Local goal registration
    • Remote tools and conversation control
  • Thread and Tree of Thoughts
    • Thread of Thoughts
    • Tree of Thoughts
      • The cost of search
    • Where next?
  • Agent-to-Agent (A2A) Communication
    • A2A concepts
    • How ASTRA fits
    • Current scope
    • In this section
  • Publishing an A2A Service
    • The project
    • Configure the service
    • Write the service agent
    • Build and run
    • Try it with curl
    • Inspect the service
    • Put a reasoning agent behind a skill
    • Where next?
  • Calling A2A Services
    • The project
    • Send a request
    • How the call works
    • Reading results
    • A2A agents as ReAct tools
    • Where next?
  • LLM API Reference
    • astra-langchain4j
      • LLMModel
      • Templater
      • BelRAG
      • Agent classes
    • Reasoning agents
    • astra-langchain4j-tools
      • A2A
      • JSONConverter
      • Inspector

5. Multi-Agent Microservices (MAMS)

  • Guide overview
    • Learn to build a service
    • Where agents fit in a microservice application
    • The brain, body and integration layer
    • Choose how resources are managed
    • Start with Java-Types resources
    • Versions and source material
    • Moving from MAMS 1.1.1 to 2.x
  • Publish your first service
    • Create the project
    • Describe the resource data
    • Create the agent and its body
    • Run the service
    • Read and update the resource
    • Troubleshooting
  • Manage resources
    • Choose an item or a collection
    • Separate a Java value from stored state
    • Decide who owns each field
    • Create a custom artifact directly
    • Choose a representation
    • Try it
    • Further Details
      • Resource operations and HTTP semantics
        • Items and collections
        • Passive request handling
        • Observe and change resource state
        • Active request handling
        • Response headers and links
        • Call another service
        • Host several agents in one service
        • Choose a resource contract
        • HTTP formats and errors
      • Collections and an HTTP client
        • Publish a passive collection
        • Run an agent as an HTTP client
      • Create a custom resource artifact
        • Implement the artifact
        • Create and initialize it from ASTRA
        • Read it and test method support
        • Extend it deliberately
      • HAL representations
      • Hydra and JSON-LD
        • Enable the representation
        • Read a collection and its members
        • Discover the context and API
        • Write using the MAMS JSON-LD profile
        • Compatibility and extensions
  • Decide how requests are handled
    • Start with passive management
    • Intercept a supported request
    • Complete the decision on every path
    • Apply the contract to delivery requests
    • Try it
    • Further Details
      • Active item and collection examples
        • A read-only item
        • A collection and its children
      • Resource API reference
        • Application and resource goals
        • Beliefs and inferences
        • Read and change resource state
        • Signals and event plans
        • Active request decisions
        • Outgoing HTTP goals
  • Connect services
    • Make one request and check its result
    • Follow the returned resource identity
    • Poll a business result
    • Subscribe when polling is unsuitable
    • Try it
    • Further Details
      • WebSub topic and callback walkthrough
        • How it works
        • A topic
        • The publisher
        • The subscriber
        • Reference
  • Build a cooperating service
    • Read the contract before the code
    • Follow one successful request
    • Keep acknowledgement and completion separate
    • Exercise failure before adding complexity
    • Choose the next extension
    • Further Details
      • Complete delivery walkthrough and source
        • Define the service boundary
        • Define the request and result
        • Protect agent-owned state
        • Submit a successful delivery
        • Exercise the failure path
        • Inspect the coordinator
        • Inspect a courier
        • Confirm the request policy
        • Extend the service
      • Agents reacting to resource creation
        • Calculate a sum
        • Ping-pong through resources
  • Test and deploy
    • Test a contract through its public interface
    • Run the guide’s checks
    • Package the service, then check readiness
    • Decide what survives shutdown
    • Try it
    • Further Details
      • Java and container deployment
        • Run the compiled application
        • Build a container
        • Run the service and client with Compose
        • Resource addresses and lifecycle
      • Automated example verification
        • Verify the audited source
        • Check published dependencies separately
        • Checks in GitLab

6. Examples

  • Choose an example
    • Use a project with its walkthrough
  • ASTRA examples
    • Hello World
      • Run the example
        • Hello.astra
      • Expected output
      • How it works
      • Try a change
    • Thermostat
      • Run the example
        • Thermostat.astra
      • Expected output
      • How it works
      • Try a change
    • Parcel Delivery
      • Run the example
        • Courier.astra
      • Expected output
      • How it works
      • Try a change
    • Shared Charging Station
      • Run the example
        • Station.astra
        • ChargingRobot.astra
        • ChargingDemo.astra
      • Expected output
      • How it works
      • Try a change
    • String Assembler
      • Run the examples
      • Define the reusable behaviours
        • Generate characters
        • Assemble a string
        • Print the result
      • Version 1: one agent
      • Version 2: a worker pipeline
        • Wait for the matching reply
      • Version 3: a manager coordinates the workers
      • Try a change
      • Verify the downloadable project
      • Relationship to the old guide
    • Bully Election Algorithm
      • Run the example
        • BullyElection.astra
      • Expected output
      • How it works
      • Try a change
    • Token Ring Election Benchmark
      • Run the example
        • Worker.astra
        • Launcher.astra
        • Timer.java
      • Expected output
      • How it works
      • Try a change
      • References
    • Java Module Example: Calculator
      • Declaring a Module
        • Approach
        • Code
        • Output
      • Creating an Action
        • Approach
        • Code
        • Output
      • Creating a Term
        • Approach
        • Code
        • Output
      • Creating a Formula
        • Approach
        • Code
        • Output
      • Creating a Sensor
        • Approach
        • Code
        • Output
      • Creating a Custom Event
        • Approach
        • Output
    • Java GUI Example
      • Start the GUI from the agent
      • Implement the Java side
      • Use an externally created GUI
  • LLM examples
    • Projects in this guide
    • Projects in the LLM examples group
  • MAMS examples
    • Choose an example
    • Changes from the upstream examples
    • Put the pieces together
    • Custom resource creation
    • Larger application case studies

7. Reference

  • AgentSpeak(L) Background
    • Introduction to AgentSpeak(L)
      • What is AgentSpeak(L)?
      • “Hello World” with AgentSpeak(L)
      • Declaring and Handling Subgoals
      • Managing Beliefs with AgentSpeak(L)
      • Recap
    • Translating AgentSpeak(L) into ASTRA
      • Types in ASTRA
      • Declaring an Agent
      • Beliefs
      • Goals
      • Events
      • Plan Rules
    • Rewriting AgentSpeak(L) Programs in ASTRA
      • Hello World
      • Subgoals
      • Belief Queries
      • Belief Update
  • Syntax at a Glance
    • Agent structure
    • Common plan triggers
    • Types and expressions
    • Statements
  • ASTRA API Reference Guide
    • Using a module
    • Module directory
    • Core modules
      • astra.lang.Console
      • astra.lang.Debug
      • astra.lang.Functions
      • astra.lang.Logic
      • astra.lang.Math
      • astra.lang.Messaging
      • astra.lang.ObjectAccess
      • astra.lang.Prelude
      • astra.lang.Reflection
      • astra.lang.Strings
      • astra.lang.System
      • astra.lang.Goals
      • astra.lang.Memory
      • astra.lang.Timer
      • astra.lang.Logger
      • astra.lang.Compiler
      • astra.lang.ExplanationAccess
      • astra.util.DB
      • astra.util.TupleSpace
      • astra.util.Logging
    • Related guides
  • Prewritten Protocols
    • FIPA Request
    • FIPA Subscribe
    • Auctions
  • Maven Plugin Options
    • Goals
    • Project properties
    • Test switches
    • Tracing agent activity

8. About and Support

  • Publications
    • Core Publications
    • AgentSpeak(ER)
    • Multi-Agent Microservices (MAMS)
    • Applications
  • Report a Bug
ASTRA Programming Language
  • Search

© Copyright University College Dublin.

Built with Sphinx using a theme provided by Read the Docs.