Graal Script Agent User Manual

The example requires Java 25. Add Graal Script Agent, its LangChain4j adapter, the LangChain4j OpenAI implementation, the Polyglot API, and the isolated GraalJS runtime to your application.

The scriptagent artifact contains the core API. scriptagent-langchain4j connects its provider-independent model API to LangChain4j. The OpenAI artifact supplies the model implementation used below. polyglot supplies the embedding API, and js-isolate-community supplies the isolated JavaScript runtime required by Sandbox.UNTRUSTED. The Polyglot API and guest runtime must use the same version.

Set your OpenAI API key in the environment rather than putting it in source code:

Read the key and create the model used during authoring:

OpenAiOfficialResponsesStreamingChatModel uses OpenAI’s Responses API. The example uses gpt-5.5; substitute the latest model you want to use that supports streaming and tool calling.

LangChainModel adapts the LangChain4j model to Graal Script Agent’s provider-independent Model interface. Model configuration, credentials, rate limits, and cost remain the application’s responsibility.

Add the ticket-routing contract to a GettingStarted class:

The host application owns this interface. It is part of the application and written by the developer. It is also the plugin contract and the host-application boundary for the extension.

Router is the root extension point. Ticket is the input supplied by the host, and Queue bounds the possible result. The application exposes this deliberately narrow contract instead of arbitrary services or its complete object graph.

At the start of main, use JavaDiscovery.discover(Class) to derive a Schema and print it before making a model request:

Graal Script Agent discovers the Router method, the Ticket fields, the Queue enum values, and the return type. It also attaches the reflection-backed host binding that will later connect the script to Java values.

Inspect this schema when designing an extension point. It is the allowlist shared by authoring and execution: it tells the model which types and members exist, and it bounds what the generated script can access at runtime. Make sure it contains the intended types and does not expose unintended capabilities.

The output is a compact tree. This excerpt abbreviates the fingerprint and helper details:

Use a ScriptAgent with the same schema to request a JavaScript implementation:

Behind the scenes, Graal Script Agent turns the discovered schema into instructions for the model. The agent then runs an authoring loop until it has produced a valid script artifact for the Router contract or reports that it cannot complete the request.

The result is a Script<Router>, not an active Router. It contains the generated guest source and the schema against which that source was authored.

Print the generated JavaScript:

A generated implementation might look like this:

The exact source can differ between runs. The types.Queue helper exposes the enum values declared by the schema.

You can inspect generated source for learning, diagnostics, or product features. Source review is not required for confinement. The script is still treated as untrusted and must execute behind the schema, host binding, sandbox, and application-policy boundaries.

Create an untrusted context with Sandbox.newContext(String), bind the script with Script.bind(Context), and call it through the Java interface:

As requested by the prompt, this prints:

This is the important part: the model writes the plugin, but it does not directly run the plugin. After generation, router.route(…​) is a local call into a sandboxed script that implements Router. Production tickets are not sent to the model.

Keep the Context open for as long as you use the bound Router. Do not retain or invoke the proxy after closing its context.

Sandbox.UNTRUSTED is appropriate when prompts or generated scripts may be malicious. If prompts come only from generally trusted users, Sandbox.CONSTRAINED may be sufficient. In either case, expose only capabilities that are safe for that extension point.

The sandbox constrains guest code, but exposed Java methods are still real application capabilities. If the host exposes a dangerous operation, the sandbox cannot make that operation safe. Host methods must still enforce authorization, validation, tenant boundaries, bounded resource use, and side-effect policy.

A small schema and a clear prompt are often enough for a trivial router. Larger extension points benefit from tools that let the model inspect the application’s world, run its draft, and respond to validation feedback.

Replace the minimal generate(…​) call with a AuthoringTools configuration:

These tools ground authoring in several layers:

Mock execution provides evidence to the model; host-defined tests decide whether the behavior is accepted. For meaningful application rules, test the expected outcomes rather than only checking that calls complete.

The complete source for this guide is GettingStarted.java.

GraalVM JDK 25 is the recommended runtime. OpenJDK 25 can also use every sandbox mode when the application includes a Polyglot Isolate language dependency. See the GraalVM documentation for Polyglot Isolates.

Verify that your build uses JDK 25:

Select either the LangChain4j or Spring AI dependency set. Guest-language dependencies are added separately at the end of this chapter.

Graal Script Agent has a provider-independent Model API. Select either LangChain4j or Spring AI to connect that API to OpenAI. Both examples use gpt-5.5 and read the API key from OPENAI_API_KEY.

Both connectors can use Anthropic or another tool-capable provider. Follow the corresponding framework documentation:

LangChain4j delegates must implement StreamingChatModel. Spring AI delegates must provide a ChatModel whose options support tool definitions.

Graal Script Agent does not bundle JavaScript or Python. It is compiled against Polyglot 25.0.0 as its compatibility baseline. Applications select their GraalVM runtime version by declaring org.graalvm.polyglot:polyglot directly and using that exact version for the guest-language artifact. In Gradle builds with competing GraalVM dependencies, use strict version constraints so conflict resolution cannot upgrade only one artifact.

Artifacts ending in -community use the community/open-source distribution. Artifacts without that suffix use the GraalVM Free Terms and Conditions. The isolate artifacts work on GraalVM JDK 25 and OpenJDK 25. Use a non-isolated artifact when choosing Sandbox.CONSTRAINED on GraalVM JDK.

The recommended default, matching the Getting Started example, is the community JavaScript isolate:

Choose another artifact from the table by replacing the guest-runtime artifact name. Keep both Polyglot and the guest runtime at version 25.1.3.

Most extension points should begin with a public Java interface. Non-sealed interfaces represent behavior that a generated script can implement.

Use Java type shapes according to their purpose:

An abstract base interface that is not itself a valid implementation should be sealed. Its permitted subtypes tell discovery, and therefore the authoring model, which alternatives are available.

Names should carry as much of the contract as possible. Add @SchemaDoc where domain meaning, constraints, or relationships are not clear from a type or member name. Use @SchemaExclude to omit an incidental public member, but prefer a dedicated narrow contract over discovering a broad type and excluding most of it.

JavaDiscovery derives a Schema from a public Java entry point and its reachable types:

Discovery preserves the nominal Java contract, including interfaces, records, methods, enums, sealed hierarchies, and supported collection shapes. A non-sealed interface is treated as implementable by a generated script. A sealed interface is treated as a closed set of permitted alternatives.

Each callable on a schema surface needs a unique script-visible name. JavaDiscovery assigns deterministic names when Java overloads or other members collide. Scripts use the names rendered in the discovered schema; inspect that schema rather than deriving them.

ScriptAgent.generate(Class, String) performs this discovery automatically. Call JavaDiscovery.discover(…​) directly when you want to inspect or print the schema, configure discovery, or reuse the schema across authoring operations.

JavaDiscoveryConfig customizes how the reachable Java API becomes a schema:

Configuration can control:

Use configuration to narrow or adapt an application-owned contract. Do not use it to turn a third-party API into an extension point.

Java API discovery is currently the only built-in discovery path. Graal Script Agent does not provide Kotlin- or Scala-aware discovery.

An application or future integration can add language-aware discovery by producing the same two artifacts: a Schema describing the script-visible contract and a matching HostBinding implementing it. This allows Kotlin or Scala discovery to compose with the existing authoring and execution model without requiring either subsystem to understand those languages.

JavaDiscovery processes Graal Script Agent’s schema annotations by default. Use them for durable information about the extension-point contract instead of repeating that information in authoring prompts.

These annotations can also annotate application-defined annotations. This allows an application annotation to contribute consistent schema metadata wherever it is used. JavaDiscoveryConfig can alternatively map existing annotations on members to tags or attributes.

Descriptions, render modes, tags, and attributes are part of the logical schema and affect its fingerprint. Changing them can make the schema incompatible with persisted scripts.

@SchemaDoc, @SchemaTag, @SchemaAttribute, and @SchemaPromptRender describe or render the contract. They do not remove runtime access or enforce application policy. Use dedicated contract types, @SchemaExclude, and JavaDiscoveryConfig to shape the discovered API.

Prefer annotations for stable facts about the extension point. Reserve ScriptAgent.Builder.instructions(String) for stable authoring guidance that is not already expressed by schema documentation.

Applications often need information about a generated plugin in addition to its source code. For example, an application may need a short description to:

Script properties let the authoring model provide this information when it creates the plugin. The application can then read it directly from the resulting Script without executing the plugin or making another model request.

Use script properties primarily for short human-readable descriptions rather than as a general metadata system.

Declare a description property on the root extension-point type:

@SchemaProperty can only be declared on the root extension-point type. Every declared script property is a required string. The authoring model supplies its value when it completes the script.

Read the description with Script.requireProperty(String):

Script properties describe the generated plugin; they are not execution inputs. Data that changes between executions belongs in extension-point method parameters.

@SchemaDoc and @SchemaProperty serve different purposes:

Guest scripts interact with the contract declared by the Schema, not with unrestricted Java objects. A script can access only members and operations declared by schema elements and traits. Passing an object whose runtime Java class has additional public members does not make those members visible.

Java Object is discovered as Any. Unresolved generic type variables that erase to Object can also introduce Any. It allows a value whose precise type is not expressed at that position, but it does not grant reflective access to arbitrary Java objects. Host values flowing through a Java-backed Any position must be supported scalars or objects that the attached JavaHostBinding resolves to a nominal type already declared in the schema; arbitrary maps, collections, and unrelated objects are not projected. Prefer precise application-owned types or sealed alternatives. Use Any only when the value type is genuinely open, and keep it localized to the smallest part of the contract.

JavaDiscovery maps Java primitive and boxed types to schema scalar types. Conversion is strict: incompatible or lossy values are rejected rather than coerced.

Primitive type uses are non-null. Boxed scalars and other reference types are nullable by default. @NullMarked on the enclosing Java contract or package makes reference types non-null by default, while @Nullable marks an individual type use as nullable. Nullability and scalar conversion rules are presented to the authoring model as part of the schema.

Some applications expose structures that vary by tenant or user configuration, such as custom properties or configurable record types. The recommended approach is to define one static generic schema and provide representative examples for inspection, rather than constructing a different nominal schema for every concrete shape.

For example, this extension point represents arbitrary properties through one application-owned structure:

The schema remains static: every property has a name and a value. Only the concrete property names and values vary. Object maps to Any, but its use is localized to the individual property value.

Provide representative properties when authoring the script:

AuthoringTools.Builder.sampleInspection(…​) allows the authoring model to examine the available property names, scalar value types, and conventions before implementing the rule. Structured property values must use application-owned nominal types declared in the schema. The contract stays fixed while the examples provide concrete information about the current application data.

Samples are authoring-time evidence. They are not available to the completed script, do not change the schema, and do not grant additional runtime access. Supply examples that demonstrate relevant shapes and conventions, but do not treat them as proof of every possible input.

Only build a dynamic Schema with a matching custom HostBinding when a static generic structure and sample inspection cannot represent the required domain. See Build Dynamic Schemas for that advanced approach.

Use a sealed hierarchy when one authoring entry point should allow the model to select between a closed set of related extension capabilities. The sealed base groups the alternatives, while each permitted non-sealed interface defines one implementable capability:

Use the sealed hierarchy directly as the authoring root. JavaDiscovery exposes Router and Reply as permitted alternatives. The generated script selects and implements one of them; it cannot implement TicketExtension directly.

Identify the selection through its nominal subtype rather than the generated proxy class. Use a sealed hierarchy when the alternatives form one conceptual choice and share the same lifecycle and review process. Prefer separate root extension points when the application chooses the capability before authoring or when alternatives require different prompts, validation, persistence, or review.

Use ScriptAgent.generate(Class, String) for a standalone request. It creates a short-lived authoring session, produces one completed Script<T>, and does not retain the conversation after returning.

The following example uses the Router extension point from Getting Started:

generate(Class<T>, String) discovers the schema from the Java interface. Use the overload that accepts a Schema when the application supplies the schema explicitly.

Use a ScriptAgent.Session<T> when users need to inspect, critique, or refine a script through multiple prompts. Each successful turn retains the current script and complete model transcript for the next turn:

The second request builds on the first request and its completed script. Use separate one-shot generate(…​) calls instead when requests do not share context.

Use ScriptAgent.revise(Script, String) to start a new one-shot authoring run from an existing script:

The existing script supplies the initial source and schema. Its original model conversation is not part of the Script<T> artifact. Use ScriptAgent.newSession(Script) instead when several follow-up revisions should share one new conversation.

Describe the behavior the completed extension should implement. Include relevant outcomes, priorities, boundary cases, and examples that are not already expressed by the Java contract.

Prefer:

Avoid repeating method signatures, record fields, enum values, or authoring-tool instructions. ScriptAgent already renders the schema and tool contract for the model. Repeating them increases prompt size and risks contradicting the actual contract.

Use ScriptAgent.Builder.instructions(String) for brief, stable guidance that applies to every script authored by an agent. Keep task-specific requirements in the prompt:

Do not use global instructions to restate schema documentation or encode behavior that belongs in an individual extension request.

Each generation or revision run maintains one guest-language source file. The model reads, replaces, or edits that draft through authoring tools. Draft mutations carry a revision number; an edit based on a stale revision is rejected so the model can inspect the current source before trying again.

Each authoring step sends the current conversation and available tool definitions to the model. The model may inspect additional schema details, update the draft, and use configured tools to gather evidence about its behavior.

Authoring finishes through an explicit terminal tool call. Plain assistant text is not completion. Before returning a Script<T>, completion validates the source and runs any completion checks supplied by the configured AuthoringTools.

Authoring-tool failures and rejected completion checks return structured feedback so the model can revise the draft and try again. An explicit terminal failure, exhausted configured bound, or non-retryable model failure ends the run without replacing an existing Script<T>.

See Improve Authoring with Tools to add mock execution, sample inspection, tests, and custom tools.

Generation and revision are blocking operations. Configure ScriptAgent.Builder to bound retries, authoring steps, and periods without model progress:

ScriptAgent.Builder.maxRetries(int) bounds retries after retryable model failures or invalid model responses. ScriptAgent.Builder.maxAuthoringSteps(int) bounds the model-and-tool loop within an attempt.

ScriptAgent.Builder.responseTimeout(Duration) is an inactivity timeout. Non-empty streaming progress resets it; it is not a total duration limit for the complete authoring run. Whether progress is available depends on the provider, model, and adapter.

Interrupting the calling thread stops the local wait and interrupts the model invocation. A timeout does the same and ignores late events or responses. Provider-side cancellation is best effort: remote work may continue temporarily and may still consume provider capacity or tokens.

A session replays the complete typed transcript of its successful turns on every subsequent generation. A failed generation does not add a turn or replace the session’s current script. History is not automatically truncated, compacted, or summarized. Long-lived sessions therefore increase model context use, latency, and cost, and may eventually reach the provider’s context-window limit.

Prefer short-lived sessions scoped to one authoring task. Session.clear() discards the accumulated history and current script, so the next prompt starts without either. Try-with-resources scopes session use, but Session.close() currently does not clear its state. Sessions are in-memory objects and cannot currently be serialized or restored. Persist the completed Script<T> when it must outlive the session.

The rendered schema, authoring request, draft source, retained conversation, tool definitions, and tool results can all become visible to the configured model provider. Samples and application data exposed through authoring tools can also become model-visible. Supply only data that is appropriate for that provider, using synthetic or sanitized examples where necessary.

Mock execution, sample inspection, and completion tests serve different purposes:

Combine them when the extension requires both domain understanding and host-controlled acceptance:

These configurations remain independent. Sample objects are not automatically injected into mock scenarios or completion tests.

AuthoringTools.Builder.promptTokenLimit(int) limits the estimated size of the rendered system prompt and defaults to 10,000 tokens. This guards against unexpectedly large model requests and their cost. If the required prompt cannot fit within the limit, script generation fails before making a model request.

When the complete schema rendering does not fit, Graal Script Agent replaces deeper type details with an explicit marker. For example, a larger routing schema could contain:

Before using that type, the model can call schema_detail_request:

The result contains the full language-specific rendering of CustomerHistory. The model can then use its members without requiring the entire schema to be present in the initial prompt.

The target extension type and required authoring instructions are never silently removed. If required content still cannot fit, authoring fails before making a model request. Increase the budget or simplify the schema in that case.

Implementing a custom AuthoringTool is covered in the advanced topics. See Advanced Topics.

The following example uses the Router extension point from Getting Started:

Script.bind(Context) evaluates the guest source in the supplied context and returns an implementation of the script’s target Java interface. The application owns the context and must close it.

The bound implementation remains associated with that context. Do not invoke or retain it after the context is closed.

Bind a script once per context and reuse the returned interface. Calls through that interface share guest state. When scripts or executions should not share guest state, create a fresh context and binding for each. Separate contexts normally keep guest state apart, but shared host objects or other process-wide state can still connect them.

Treat generated source as having the same trust level as the prompt and other input that shaped it. Use Sandbox.UNTRUSTED whenever that input can be influenced by someone who is not trusted to supply executable code, such as an ordinary user of a hosted application. Sandbox.CONSTRAINED is appropriate only when everyone controlling the script is trusted to run code in the host environment and accidental bugs, rather than hostile code, are the threat. One example is a single-user desktop application whose user already controls that environment.

See the GraalVM sandboxing guide for the security guarantees and runtime requirements of each policy.

The predefined sandboxes provide starting limits. Derive a custom sandbox with Sandbox.newBuilder(Sandbox) when the application needs different bounds:

See Set Up Your Project for the JavaScript and Python runtime artifacts required by each sandbox mode.

A sandbox is one layer of the execution boundary:

The schema is the allowlist for host values projected through Script Agent’s binding boundary. Public Java members that are not represented by schema elements or traits remain inaccessible through that projection.

A sandbox cannot make a dangerous exposed host operation safe. Keep host APIs narrow and enforce application policy independently of guest isolation.

Graal Script Agent includes built-in JavaScript and Python language adapters. It injects schema-derived types and language utilities when the script is bound.

Scripts are designed to be self-contained and run without external guest libraries. Bind them to an otherwise unmodified context created by the selected Sandbox; do not enable package loading or filesystem access, and do not inject ad hoc host globals. Expose application interaction exclusively through schema-backed host APIs.

Failures can occur while creating the context, binding the source, or invoking the returned interface:

Guest, host, and resource failures may surface as PolyglotException:

After resource exhaustion, cancellation, guest exit, or an internal error, treat the context as disposable. Do not return it to a pool or continue invoking interfaces bound to it.

The host application classifies each operation. Generated code must not classify its own changes as reversible. If a group contains any irreversible or uncertain operation, review the entire group before execution.

Treat database changes cautiously. Rolling back an open transaction is different from undoing a committed user operation. Cascades, concurrent updates, dependent data, and external effects often make complete restoration difficult. If the application cannot provide a dependable Undo operation, use review before execution.

Serialize a completed script with Script.toJson():

Store the resulting JSON in the application’s database, object store, or other durable storage. It contains:

It does not contain the target Java interface or the full schema. The application supplies both when restoring the script.

For a Java extension point, rediscover the schema from the current interface and pass it to Script.fromJson(Class, String, Schema):

The discovered schema includes the reflection-backed host binding, so the restored script can be bound and executed normally.

The script stores the schema fingerprint used during authoring. Script.fromJson(…​) requires an exact match with the supplied schema and rejects restoration when the Java API’s schema has changed.

When the schema still matches, restore the script and use ScriptAgent.revise(Script, String, AuthoringTools) to continue authoring from its current source:

revise(…​) targets the existing script’s schema. It is appropriate for behavioral changes while the extension point remains unchanged.

When the Java API’s schema has changed, create a replacement against the current interface. Pass the persisted script JSON as context so the model can adapt its previous implementation:

This is a new generation against the current schema, not a call to revise(…​). Use the current authoring tools and acceptance tests to validate the migrated behavior, then persist the replacement script after generation succeeds.

Script persistence stores the completed source and its properties. It does not preserve a bound interface, Polyglot context, guest runtime state, authoring session, model conversation, or authoring-time tests. Create a suitable sandboxed context for each runtime lifecycle, and configure tests again when revising or migrating a script.

Persisted scripts remain untrusted executable code. Protect who may store and execute them, and follow Execute Scripts Safely whenever a restored script is bound.

Add traceStatus(…​) to the agent builder to write progress for every authoring run created by that agent:

A simple run might produce:

The exact milestones depend on the authoring tools and whether the run retries or fails. Routine model and streaming activity is omitted. Built-in tool messages describe host-observed work rather than rendering model-provided tool names or arguments.

Custom authoring tools may supply their own status messages. The status trace writes them as supplied after format validation, so they can expose sensitive content if the tool includes it. Treat status output as sensitive unless every custom status message has been reviewed.

Register eventListener(…​) when the application needs structured updates:

One uninterrupted run follows this lifecycle:

A retry emits turn_end with a retry outcome, followed by retry and another attempt. Normal failures still close the message, turn, and run. A listener failure is different: it aborts dispatch immediately, so later closing events are not guaranteed.

Every event provides schemaVersion(), type(), runId(), sequence(), and timestamp(). ScriptAgent.TurnEvent additionally provides zero-based attempt() and step() values.

Use the fields as follows:

ScriptAgent.MessageUpdate reports streamed text, thinking, and tool-call updates when the model adapter provides them. Streaming updates are observational. Only the completed model response is authoritative, and tool execution begins after ScriptAgent.MessageEnd.

Event classes and discriminator values may grow over time. Include a default branch when switching over events, and tolerate fields or update types that the application does not recognize.

Listeners configured on ScriptAgent.Builder observe every run created by that agent. Add listeners or traces to ScriptAgent.SessionBuilder when they should observe only that session:

Registrations are additive. Agent listeners run first, followed by session listeners, and registration order is preserved within each scope.

Event delivery is synchronous. Callbacks run on the thread dispatching the event, and independent sessions may emit concurrently. Keep shared listener state thread-safe and keep callbacks short; a blocking listener also blocks authoring progress. Do not call Session.generate(String) or Session.clear() on the same session from one of its listeners.

A listener exception aborts the active authoring run. Catch failures inside a listener when telemetry should be best effort, or enqueue the immutable event for asynchronous processing and return promptly.

Use traceEvents(…​) when detailed diagnostics are required:

The output is UTF-8 JSONL with one normalized event object per line. Each object starts with the event schema version, type, run ID, sequence, and timestamp, followed by fields specific to that event. Output is flushed after every line. Consumers should use schemaVersion and tolerate unknown event types and fields.

Diagnostic traces can contain system and user prompts, model responses and thinking, tool arguments and results, sample data, and complete generated source. They are not a privacy or security boundary. Restrict access, retention, and export according to the most sensitive application data that authoring can expose.

Both tracing methods add synchronous listeners and do not close the supplied OutputStream. The application owns the stream. A trace write failure aborts authoring just like any other listener failure.

Use the standard GraalVM Native Build Tools integration for your build system:

Follow those guides for plugin configuration, executable entry points, build arguments, and native test support. The scriptagent JAR enables its Native Image feature automatically, so no --features option or separate Script Agent build-tool plugin is required. Keep the Script Agent, model connector, and guest-language dependencies described in Set Up Your Project.

For the normal JavaDiscovery workflow, annotate each extension-point root with @DefaultSchemaDiscovery. For example, add the annotation to the Router from Getting Started:

Continue discovering and using the schema normally:

During image analysis, the Script Agent feature performs the same default discovery for Router. It registers the schema’s Java classes and bound fields, methods, and constructors for reflection. It also registers the interface proxies required to bind generated implementations. Records, enums, nested types, and sealed hierarchies reached from the root are included automatically. For these registered schemas, do not maintain reflect-config.json or proxy-config.json entries.

Annotate only the discovery root, not every type in its schema. Annotate each root separately when an application has multiple extension points.

The annotated root must be reachable to Native Image. Passing Router.class to JavaDiscovery, ScriptAgent.generate(…​), or another runtime path normally establishes that reachability. The annotation does not retain an otherwise unused extension point.

@DefaultSchemaDiscovery always corresponds to JavaDiscovery.discover(Class): it uses the public lookup and JavaDiscoveryConfig.DEFAULT. Use a provider when runtime discovery uses a custom lookup or configuration.

Implement SchemaReflection when the application customizes Java discovery. Its contribute(SchemaReflectionRegistry) callback runs at image build time and contributes each schema to the registry.

Keep schema construction in one place so build-time registration and runtime discovery cannot drift. This example uses a package-scoped discovery boundary and a lookup with access to the application package:

Use that same method from the application and the build-time provider:

On the class path, register the provider through ServiceLoader.

In a named module, declare the provider in module-info.java instead:

A provider may call SchemaReflectionRegistry.register(Schema) more than once. Register every schema variant that the executable can select at runtime. The provider contributes only Native Image metadata; the application still constructs its schema normally when it authors, restores, or executes a script.

See the org.graalvm.scriptagent.nativeimage package for the complete API.

Prefer the static generic schema approach described in Design Extension Points. Build a dynamic schema only when the contract itself must vary at runtime and representative samples cannot express that variation. More complete guidance for dynamic schemas is planned for a future release.

For now, construct the contract with Schema and its builders. Implement HostBinding to map the declared schema elements to host operations, then attach it through Schema.Builder.hostBinding(HostBinding) or supply it through Script.bind(Context, HostBinding). Keep the schema and binding aligned: the schema is the complete guest-visible surface, and raw Polyglot Value objects must not cross the binding API.

Implement PersistentHostBinding only when a serialized custom schema must retain binding metadata. For Native Image, account separately for any metadata required by the custom binding; @DefaultSchemaDiscovery covers default Java discovery, as described in Build a Native Image.

The built-in authoring tools cover normal generation and revision. Implement AuthoringTool only when the model needs application-specific evidence. This example exposes the current queue precedence as structured feedback:

AuthoringTools.Builder.tool(Supplier) creates a separate tool instance for each authoring run, and Graal Script Agent invokes AuthoringTool.close() afterward. Validate any arguments the tool uses, minimize model-visible application data, and return narrow, actionable results.

This extension point is still evolving. If you have an authoring-tool use case that the current API does not serve well, open an issue and share it with the project.

Implement Model to adapt another provider client or create a deterministic model for integration tests. Its Model.generate(ModelRequest, ModelEventSink) method receives each complete request. Follow the contracts of ModelRequest, ModelResponse, and ModelEventSink, then pass the implementation to the agent:

Implement LanguageSupport to add another Polyglot guest language or different language conventions. Its rendering methods use PromptBuilder to describe the schema, while LanguageSupport.bind(…​) evaluates source and exposes the runtime roots using the same conventions. Select it with ScriptAgent.Builder.language(LanguageSupport) during authoring and pass it to Script.bind(Context, LanguageSupport) during execution.

Graal Script Agent is an early-preview library. Its public Java APIs and authoring workflows may change incompatibly between preview releases. Applications should pin the Script Agent version and evaluate the required source and integration changes before upgrading.

JavaDiscovery is currently the only built-in API-discovery implementation. It uses Java reflection and does not provide Kotlin- or Scala-aware discovery.

This limits automatic discovery, not the rest of Script Agent. An application can support another JVM language by using the public Schema and HostBinding APIs to produce an aligned script-visible contract and runtime binding. Authoring and execution then use those artifacts without needing to understand the source JVM language. Contributions that add built-in discovery for other JVM languages are welcome; see the contribution guide.

A stateful authoring session retains and replays the complete transcript of every successful turn. It does not automatically compact, truncate, or summarize that history. Long-lived sessions therefore consume progressively more model context, increasing latency and cost until they may reach the provider’s context-window limit.

Keep sessions scoped to one authoring task. Session.clear() discards both retained history and the current script. To preserve current work without its conversational history, retain or persist the latest Script<T> and start a new revision or session from that artifact. See Generate and Revise Scripts for session guidance.

This limitation will likely be lifted in the future.

ScriptAgent.generate(Class, String), ScriptAgent.revise(Script, String), and ScriptAgent.Session.generate(String) can throw ScriptAuthoringException when the model reports that it cannot implement the request or the authoring loop reaches its configured step bound without completing a script.

Catch this exception at the application boundary and present its message to the requesting user as plain text so they can revise the request. Keep any previous script unchanged, log the exception for diagnosis, and never execute an unfinished draft.

Authoring stops before a model request if the complete system prompt exceeds AuthoringTools.Builder.promptTokenLimit(int) and schema_detail_request is unavailable. Without that tool, Graal Script Agent cannot safely omit schema type details because the model could not retrieve them later.

Standard AuthoringTools configurations include schema_detail_request. This error therefore indicates an unexpected custom or incompatible tool configuration. Check that configuration, increase promptTokenLimit, or expose a smaller schema.

Use Sandbox.isSupported() before offering a sandbox configuration. If it returns false, creating a context or engine with that sandbox throws IllegalStateException. Use GraalVM JDK 25 or add the matching Polyglot Isolate guest-language dependency described in Set Up Your Project.

On a runtime without sandbox support, only Sandbox.TRUSTED without resource limits is available. Do not silently downgrade generated or otherwise untrusted source to that mode; reject the operation until an appropriate runtime is available. See Execute Scripts Safely for choosing a sandbox from the source and input trust boundaries.

On OpenJDK or Oracle JDK with Polyglot 25.1 or later, the engine can report that its fallback runtime does not support runtime compilation to machine code. The script can still run, but repeated guest execution may be significantly slower. Use the recommended GraalVM JDK 25 when runtime optimization matters.

For intentionally small workloads, the warning can be hidden with -Dpolyglot.engine.WarnInterpreterOnly=false or the corresponding engine.WarnInterpreterOnly=false engine option. Suppressing it does not enable optimization. See the GraalVM runtime optimization warning documentation for the supported runtime configurations and remedies.