AI Agents

Simulation only: Agent methods do not connect to an AI provider. Model names are configuration strings, not verified provider integrations. No API keys are read by the current runtime.

Agents are first-class values in Joa. They encapsulate an AI model configuration and expose methods for querying and vision tasks, without requiring HTTP clients or SDK imports.

Declaration

agent AgentName {
    model: "model-identifier",
    temperature: 0.2,
    instructions: "System prompt for the agent."
}

All properties are optional and stored as values. Common configuration names are shown below. Temperature and mode are not validated or used for inference:

agent SecurityMonitor {
    model: "example-model",
    temperature: 0.1,
    instructions: "You are a security analyst. Be terse and precise."
}

agent VisionCore {
    model: "vision-pro",
    mode: "computer-vision"
}

Agent Methods

.ask(prompt)

Prints the agent name, configured model, and prompt. Returns "[simulated response from MODEL]" as a String. With no prompt, returns null.

let verdict = SecurityMonitor.ask("Is this payload malicious: " + payload)
print(verdict)

.detect_objects(frame)

Prints a detection notice and returns ["unknown_object"]. The supplied frame is not processed.

let found = VisionCore.detect_objects(frame)
if found.contains("unauthorized_person") {
    trigger_alert(location: "Server Room B")
}

Accessing Agent Properties

Properties declared in the agent block are readable as normal member access:

print(SecurityMonitor.model)        // example-model
print(SecurityMonitor.temperature)  // 0.1

The Semantic Match Operator with Agents

A common pattern combines the ~ operator with an agent for layered threat detection:

let payload = "GET /admin?token=leaked_token HTTP/1.1"

if payload ~ "authentication bypass credential theft" {
    let analysis = SecurityMonitor.ask("Classify threat level: " + payload)
    print(analysis)
}