Structured Output

The built-in generate_object tool asks the configured LLM for a JSON value, validates the response against a JSON Schema you supply, and returns the validated value only on a zero-exit result. Use it whenever you need machine-readable results: extraction, classification, config generation, or feeding another program.

You can call it directly through session.tool('generate_object', ...). The tool result carries the validated object as JSON on result.output — parse it and read the object field. The same tool also supports agent-driven invocation, where the model decides to call it during a send.

Direct tool call

The simplest path: call generate_object directly, check the tool exit code, and parse the validated object out of the result.

Rust

Node.js

Python

Rust

use a3s_code_core::Agent;
use serde_json::{json, Value};

#[tokio::main]
async fn main() -> a3s_code_core::Result<()> {
    let agent = Agent::new("agent.acl").await?;
    let session = agent.session_builder(".").build().await?;

    let result = session
        .tool(
            "generate_object",
            json!({
                "schema": {
                    "type": "object",
                    "required": ["name", "age", "skills"],
                    "properties": {
                        "name": { "type": "string" },
                        "age": { "type": "integer", "minimum": 0 },
                        "skills": {
                            "type": "array",
                            "items": { "type": "string" },
                            "minItems": 1
                        }
                    }
                },
                "prompt": "Extract: \"Alice is 28, skilled in Rust, TypeScript, and Python.\"",
                "schema_name": "developer",
                "mode": "tool"
            }),
        )
        .await?;
    if result.exit_code != 0 {
        return Err(a3s_code_core::CodeError::Tool {
            tool: "generate_object".into(),
            message: result.output,
        });
    }

    let value: Value = serde_json::from_str(&result.output)?;
    println!("{}", value["object"]);

    session.close().await;
    agent.close().await;
    Ok(())
}

TypeScript

import { Agent } from '@a3s-lab/code';

const agent = await Agent.create('agent.acl');
const session = agent.session('.');

const result = await session.tool('generate_object', {
  schema: {
    type: 'object',
    required: ['name', 'age', 'skills'],
    properties: {
      name: { type: 'string' },
      age: { type: 'integer', minimum: 0 },
      skills: {
        type: 'array',
        items: { type: 'string' },
        minItems: 1,
      },
    },
  },
  prompt: 'Extract: "Alice is 28, skilled in Rust, TypeScript, and Python."',
  schema_name: 'developer',
  mode: 'tool',
});

if (result.exitCode !== 0) {
  throw new Error(result.output);
}

const { object } = JSON.parse(result.output);
console.log(object);
// { name: "Alice", age: 28, skills: ["Rust", "TypeScript", "Python"] }

session.close();

Python

import json
from a3s_code import Agent

agent = Agent.create('agent.acl')
session = agent.session('.')

result = session.tool("generate_object", {
    "schema": {
        "type": "object",
        "required": ["name", "age", "skills"],
        "properties": {
            "name": {"type": "string"},
            "age": {"type": "integer", "minimum": 0},
            "skills": {
                "type": "array",
                "items": {"type": "string"},
                "minItems": 1,
            },
        },
    },
    "prompt": 'Extract: "Alice is 28, skilled in Rust, TypeScript, and Python."',
    "schema_name": "developer",
    "mode": "tool",
})

if result.exit_code != 0:
    raise RuntimeError(result.output)

obj = json.loads(result.output)["object"]
print(obj)
# {"name": "Alice", "age": 28, "skills": ["Rust", "TypeScript", "Python"]}

session.close()

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"

	code "github.com/A3S-Lab/Code/sdk/go/v6"
)

func main() {
	ctx := context.Background()
	agent, err := code.Create(ctx, "agent.acl")
	if err != nil {
		log.Fatal(err)
	}
	defer agent.Close(context.Background())
	session, err := agent.Session(ctx, ".", nil)
	if err != nil {
		log.Fatal(err)
	}
	defer session.Close(context.Background())

	result, err := session.Tool(ctx, "generate_object", map[string]any{
		"schema": map[string]any{
			"type":     "object",
			"required": []string{"name", "age", "skills"},
			"properties": map[string]any{
				"name": map[string]any{"type": "string"},
				"age":  map[string]any{"type": "integer", "minimum": 0},
				"skills": map[string]any{
					"type": "array", "items": map[string]any{"type": "string"},
					"minItems": 1,
				},
			},
		},
		"prompt":      `Extract: "Alice is 28, skilled in Rust, TypeScript, and Python."`,
		"schema_name": "developer",
		"mode":        "tool",
	})
	if err != nil {
		log.Fatal(err)
	}
	if result.ExitCode != 0 {
		log.Fatal(result.Output)
	}
	var value struct {
		Object map[string]any `json:"object"`
	}
	if err := json.Unmarshal([]byte(result.Output), &value); err != nil {
		log.Fatal(err)
	}
	fmt.Println(value.Object)
}

The validated value lives on the object key of the parsed output. When result.exitCode (Node) / result.exit_code (Python) is zero, fields declared in required have passed runtime validation. If the model cannot satisfy the schema after repair attempts, the tool reports a non-zero exit code.

Enum classification

Constrain a field to a fixed set with enum. This turns a free-form model classification into a schema-gated result.

Rust

Node.js

Python

Rust

use serde_json::{json, Value};

let result = session
    .tool(
        "generate_object",
        json!({
            "schema": {
                "type": "object",
                "required": ["sentiment", "confidence"],
                "properties": {
                    "sentiment": {
                        "type": "string",
                        "enum": ["positive", "negative", "neutral"]
                    },
                    "confidence": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1
                    }
                }
            },
            "prompt": "Classify sentiment: \"This is the worst product I have ever used.\"",
            "schema_name": "sentiment"
        }),
    )
    .await?;
let value: Value = serde_json::from_str(&result.output)?;
println!(
    "{} {}",
    value["object"]["sentiment"],
    value["object"]["confidence"]
);

TypeScript

const result = await session.tool('generate_object', {
  schema: {
    type: 'object',
    required: ['sentiment', 'confidence'],
    properties: {
      sentiment: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
      confidence: { type: 'number', minimum: 0, maximum: 1 },
    },
  },
  prompt: 'Classify sentiment: "This is the worst product I have ever used."',
  schema_name: 'sentiment',
});

const { object } = JSON.parse(result.output);
console.log(object.sentiment, object.confidence); // "negative" 0.97

Python

result = session.tool("generate_object", {
    "schema": {
        "type": "object",
        "required": ["sentiment", "confidence"],
        "properties": {
            "sentiment": {"type": "string", "enum": ["positive", "negative", "neutral"]},
            "confidence": {"type": "number", "minimum": 0, "maximum": 1},
        },
    },
    "prompt": 'Classify sentiment: "This is the worst product I have ever used."',
    "schema_name": "sentiment",
})

obj = json.loads(result.output)["object"]
print(obj["sentiment"], obj["confidence"])  # "negative" 0.97

result, err := session.Tool(ctx, "generate_object", map[string]any{
	"schema": map[string]any{
		"type":     "object",
		"required": []string{"sentiment", "confidence"},
		"properties": map[string]any{
			"sentiment": map[string]any{
				"type": "string", "enum": []string{"positive", "negative", "neutral"},
			},
			"confidence": map[string]any{
				"type": "number", "minimum": 0, "maximum": 1,
			},
		},
	},
	"prompt":      `Classify sentiment: "This is the worst product I have ever used."`,
	"schema_name": "sentiment",
})
if err != nil {
	return err
}
var value struct {
	Object map[string]any `json:"object"`
}
if err := json.Unmarshal([]byte(result.Output), &value); err != nil {
	return err
}
fmt.Println(value.Object["sentiment"], value.Object["confidence"])

Nested schemas and arrays

Schemas can nest objects and arrays within the runtime's bounded schema-depth limit, and the runtime validates the whole structure. This models real config files, manifests, or API payloads in one call.

Rust

Node.js

Python

Rust

use serde_json::{json, Value};

let result = session
    .tool(
        "generate_object",
        json!({
            "schema": {
                "type": "object",
                "required": ["items"],
                "properties": {
                    "items": {
                        "type": "array",
                        "minItems": 3,
                        "maxItems": 5,
                        "items": {
                            "type": "object",
                            "required": ["name", "category"],
                            "properties": {
                                "name": { "type": "string" },
                                "category": {
                                    "type": "string",
                                    "enum": ["fruit", "vegetable", "grain"]
                                }
                            }
                        }
                    }
                }
            },
            "prompt": "List 3 food items with their categories.",
            "schema_name": "food_list"
        }),
    )
    .await?;
let value: Value = serde_json::from_str(&result.output)?;
let items = value["object"]["items"].as_array().unwrap();
println!("{} {:?}", items.len(), items);

TypeScript

const result = await session.tool('generate_object', {
  schema: {
    type: 'object',
    required: ['items'],
    properties: {
      items: {
        type: 'array',
        minItems: 3,
        maxItems: 5,
        items: {
          type: 'object',
          required: ['name', 'category'],
          properties: {
            name: { type: 'string' },
            category: { type: 'string', enum: ['fruit', 'vegetable', 'grain'] },
          },
        },
      },
    },
  },
  prompt: 'List 3 food items with their categories.',
  schema_name: 'food_list',
});

const { items } = JSON.parse(result.output).object;
console.log(
  items.length,
  items.map((i) => i.name),
);

Python

result = session.tool("generate_object", {
    "schema": {
        "type": "object",
        "required": ["items"],
        "properties": {
            "items": {
                "type": "array",
                "minItems": 3,
                "maxItems": 5,
                "items": {
                    "type": "object",
                    "required": ["name", "category"],
                    "properties": {
                        "name": {"type": "string"},
                        "category": {"type": "string", "enum": ["fruit", "vegetable", "grain"]},
                    },
                },
            },
        },
    },
    "prompt": "List 3 food items with their categories.",
    "schema_name": "food_list",
})

items = json.loads(result.output)["object"]["items"]
print(len(items), [i["name"] for i in items])

result, err := session.Tool(ctx, "generate_object", map[string]any{
	"schema": map[string]any{
		"type":     "object",
		"required": []string{"items"},
		"properties": map[string]any{
			"items": map[string]any{
				"type": "array", "minItems": 3, "maxItems": 5,
				"items": map[string]any{
					"type":     "object",
					"required": []string{"name", "category"},
					"properties": map[string]any{
						"name": map[string]any{"type": "string"},
						"category": map[string]any{
							"type": "string",
							"enum": []string{"fruit", "vegetable", "grain"},
						},
					},
				},
			},
		},
	},
	"prompt":      "List 3 food items with their categories.",
	"schema_name": "food_list",
})
if err != nil {
	return err
}
var value struct {
	Object struct {
		Items []map[string]any `json:"items"`
	} `json:"object"`
}
if err := json.Unmarshal([]byte(result.Output), &value); err != nil {
	return err
}
fmt.Println(len(value.Object.Items), value.Object.Items)

Agent-driven invocation

You can also let the agent decide when to use structured output. Ask it to call generate_object during a send; it gathers context first, then emits the object.

Rust

Node.js

Python

Rust

let result = session
    .send(
        "Use generate_object to extract the movie title, year, and genre from: \
         The movie \"Inception\" was released in 2010 and is a sci-fi thriller.",
        None,
    )
    .await?;

println!(
    "tool calls: {}, tokens: {}",
    result.tool_calls_count,
    result.usage.total_tokens
);

Python

result = session.send(
    'Use the generate_object tool to produce a JSON object with schema '
    '{"type":"object","required":["language","paradigm"],"properties":'
    '{"language":{"type":"string"},"paradigm":{"type":"string"}}} '
    'for: "Rust is a systems programming language with a focus on safety."'
)

print(f"tool calls: {result.tool_calls_count}, tokens: {result.total_tokens}")

Schema validation coverage

The built-in validator supports:

type (including nullable arrays like ["string", "null"])
required, properties, additionalProperties
enum, const
$ref with local $defs or definitions
allOf, anyOf, oneOf
minLength, maxLength, pattern
minimum, maximum, exclusiveMinimum, exclusiveMaximum
minItems, maxItems, items
Nested object and array validation, including root arrays and scalar values

Notes

The validated value is on the object key of the parsed result.output. auto selects forced-tool mode when the provider declares that capability and otherwise uses the prompt+schema fallback. Explicit strict and json modes use provider-native response formats only when supported, then safely fall back to forced-tool or prompt mode.
List every field you depend on in required — the runtime enforces it, so missing or mistyped fields fail validation instead of silently returning partial data.
generate_object is a built-in tool registered independently of built-in skills.
Direct session.tool(...) calls are host control-plane calls. Use permissionPolicy when you let the model choose tools inside send / run / stream; use host authorization before direct SDK calls.

A runnable version ships at sdk/node/examples/basic/test_generate_object.ts and sdk/python/examples/test_generate_object.py.

#Structured Output

#Direct tool call

#Enum classification

#Nested schemas and arrays

#Agent-driven invocation

#Schema validation coverage

#Notes

Structured Output

Direct tool call

Enum classification

Nested schemas and arrays

Agent-driven invocation

Schema validation coverage

Notes