Runtimes

AgentSchema provides official runtime libraries for multiple programming languages, making it easy to load, create, and manipulate agent definitions programmatically.

Installation

Python

pip install agentschema

Or using uv:

uv add agentschema

TypeScript

npm install agentschema

Or using other package managers:

yarn add agentschema
pnpm add agentschema

.NET

dotnet add package AgentSchema

Or via NuGet Package Manager:

Install-Package AgentSchema

Go

go get github.com/microsoft/agentschema-go/agentschema

Loading from YAML

Parse a YAML string into an agent definition:

Python

from agentschema import AgentDefinition

yaml_content = """
name: my-agent
model: gpt-4o
instructions: You are a helpful assistant.
"""

agent = AgentDefinition.from_yaml(yaml_content)
print(agent.name)  # "my-agent"

TypeScript

import { AgentDefinition } from 'agentschema';

const yamlContent = `
name: my-agent
model: gpt-4o
instructions: You are a helpful assistant.
`;

const agent = AgentDefinition.fromYaml(yamlContent);
console.log(agent.name);  // "my-agent"

.NET

using AgentSchema;

var yamlContent = @"
name: my-agent
model: gpt-4o
instructions: You are a helpful assistant.
";

var agent = AgentDefinition.FromYaml(yamlContent);
Console.WriteLine(agent.Name);  // "my-agent"

Go

package main

import (
    "fmt"
    "github.com/microsoft/agentschema-go/agentschema"
)

func main() {
    yamlContent := `
name: my-agent
kind: prompt
model: gpt-4o
instructions: You are a helpful assistant.
`
    agent, _ := agentschema.PromptAgentFromYAML(yamlContent)
    fmt.Println(agent.Name)  // "my-agent"
}

Loading from Files

Load agent definitions directly from files:

Python

from agentschema import AgentDefinition

# Load from YAML file
agent = AgentDefinition.from_yaml_file("agent.yaml")

# Load from JSON file
agent = AgentDefinition.from_json_file("agent.json")

TypeScript

import { AgentDefinition } from 'agentschema';
import { readFileSync } from 'fs';

// Load from YAML file
const yaml = readFileSync('agent.yaml', 'utf-8');
const agent = AgentDefinition.fromYaml(yaml);

// Load from JSON file
const json = readFileSync('agent.json', 'utf-8');
const agentFromJson = AgentDefinition.fromJson(json);

.NET

using AgentSchema;

// Load from YAML file
var yaml = File.ReadAllText("agent.yaml");
var agent = AgentDefinition.FromYaml(yaml);

// Load from JSON file
var json = File.ReadAllText("agent.json");
var agentFromJson = AgentDefinition.FromJson(json);

Go

package main

import (
    "os"
    "github.com/microsoft/agentschema-go/agentschema"
)

func main() {
    // Load from YAML file
    yamlBytes, _ := os.ReadFile("agent.yaml")
    agent, _ := agentschema.PromptAgentFromYAML(string(yamlBytes))

    // Load from JSON file
    jsonBytes, _ := os.ReadFile("agent.json")
    agentFromJson, _ := agentschema.PromptAgentFromJSON(string(jsonBytes))
}

Programmatic Construction

Create agent definitions using strongly-typed classes:

Python

from agentschema import AgentDefinition, FunctionTool, Property

agent = AgentDefinition(
    name="weather-agent",
    description="Helps users check the weather",
    model="gpt-4o",
    instructions="You help users check the weather.",
    tools={
        "get_weather": FunctionTool(
            name="get_weather",
            description="Get current weather for a location",
            parameters={
                "location": Property(
                    kind="string",
                    description="City name",
                    required=True,
                ),
            },
        ),
    },
)

TypeScript

import { AgentDefinition, FunctionTool, Property } from 'agentschema';

const agent = new AgentDefinition({
  name: 'weather-agent',
  description: 'Helps users check the weather',
  model: 'gpt-4o',
  instructions: 'You help users check the weather.',
  tools: {
    get_weather: new FunctionTool({
      name: 'get_weather',
      description: 'Get current weather for a location',
      parameters: {
        location: new Property({
          kind: 'string',
          description: 'City name',
          required: true,
        }),
      },
    }),
  },
});

.NET

using AgentSchema;

var agent = new AgentDefinition
{
    Name = "weather-agent",
    Description = "Helps users check the weather",
    Model = "gpt-4o",
    Instructions = "You help users check the weather.",
    Tools = new Dictionary<string, Tool>
    {
        ["get_weather"] = new FunctionTool
        {
            Name = "get_weather",
            Description = "Get current weather for a location",
            Parameters = new Dictionary<string, Property>
            {
                ["location"] = new Property
                {
                    Kind = "string",
                    Description = "City name",
                    Required = true,
                },
            },
        },
    },
};

Go

package main

import "github.com/microsoft/agentschema-go/agentschema"

func strPtr(s string) *string { return &s }
func boolPtr(b bool) *bool { return &b }

func main() {
    agent := agentschema.PromptAgent{
        Kind:         "prompt",
        Name:         "weather-agent",
        Description:  strPtr("Helps users check the weather"),
        Model:        agentschema.Model{Name: "gpt-4o"},
        Instructions: strPtr("You help users check the weather."),
        Tools: []agentschema.Tool{
            agentschema.FunctionTool{
                Kind:        "function",
                Name:        "get_weather",
                Description: strPtr("Get current weather for a location"),
                Parameters: map[string]agentschema.Property{
                    "location": {
                        Kind:        "string",
                        Description: strPtr("City name"),
                        Required:    boolPtr(true),
                    },
                },
            },
        },
    }
}

Saving Agent Definitions

Export agent definitions to YAML or JSON:

Python

# Convert to YAML string
yaml_str = agent.to_yaml()

# Convert to JSON string
json_str = agent.to_json(indent=2)

# Save to files
agent.to_yaml_file("output.yaml")
agent.to_json_file("output.json")

# Convert to dictionary
data = agent.save()

TypeScript

import { writeFileSync } from 'fs';

// Convert to YAML string
const yamlStr = agent.toYaml();

// Convert to JSON string
const jsonStr = agent.toJson();

// Save to files
writeFileSync('output.yaml', agent.toYaml());
writeFileSync('output.json', agent.toJson());

// Convert to object
const data = agent.save();

.NET

// Convert to YAML string
var yamlStr = agent.ToYaml();

// Convert to JSON string
var jsonStr = agent.ToJson();

// Save to files
File.WriteAllText("output.yaml", agent.ToYaml());
File.WriteAllText("output.json", agent.ToJson());

// Convert to dictionary
var data = agent.Save();

Go

import "os"

// Convert to YAML string
yamlStr, _ := agent.ToYAML()

// Convert to JSON string
jsonStr, _ := agent.ToJSON()

// Save to files
os.WriteFile("output.yaml", []byte(yamlStr), 0644)
os.WriteFile("output.json", []byte(jsonStr), 0644)

// Convert to map
ctx := agentschema.NewSaveContext()
data := agent.Save(ctx)

Context Objects

Customize loading and saving behavior with context objects:

Python

from agentschema import AgentDefinition, LoadContext, SaveContext

# Custom load processing
def pre_process(data: dict) -> dict:
    print(f"Loading: {data.get('name')}")
    return data

load_ctx = LoadContext(pre_process=pre_process)
agent = AgentDefinition.from_yaml(yaml_content, load_ctx)

# Custom save formatting
save_ctx = SaveContext(
    collection_format="object",  # Use object format
    use_shorthand=True,          # Use shorthand notation
)
yaml_str = agent.to_yaml(save_ctx)

TypeScript

import { AgentDefinition, LoadContext, SaveContext } from 'agentschema';

// Custom load processing
const loadCtx = new LoadContext({
  preProcess: (data) => {
    console.log(`Loading: ${data.name}`);
    return data;
  },
});
const agent = AgentDefinition.fromYaml(yamlContent, loadCtx);

// Custom save formatting
const saveCtx = new SaveContext({
  collectionFormat: 'object',
  useShorthand: true,
});
const yamlStr = agent.toYaml(saveCtx);

.NET

using AgentSchema;

// Custom load processing
var loadCtx = new LoadContext
{
    PreProcess = (data) =>
    {
        Console.WriteLine($"Loading: {data["name"]}");
        return data;
    },
};
var agent = AgentDefinition.FromYaml(yamlContent, loadCtx);

// Custom save formatting
var saveCtx = new SaveContext
{
    CollectionFormat = CollectionFormat.Object,
    UseShorthand = true,
};
var yamlStr = agent.ToYaml(saveCtx);

Go

import "github.com/microsoft/agentschema-go/agentschema"

// Custom load processing
loadCtx := agentschema.NewLoadContext()
loadCtx.PreProcess = func(data map[string]interface{}) map[string]interface{} {
    fmt.Printf("Loading: %v\n", data["name"])
    return data
}

// Custom save formatting
saveCtx := agentschema.NewSaveContext()
saveCtx.CollectionFormat = agentschema.CollectionFormatObject
saveCtx.UseShorthand = true
data := agent.Save(saveCtx)

Choosing a Runtime

Choose the runtime that matches your development environment:

• Python - For data science workflows, AI/ML pipelines, or Python-based backends
• TypeScript/JavaScript - For Node.js applications, serverless functions, or web applications
• C# / .NET - For enterprise applications, Azure Functions, or .NET-based services
• Go - For high-performance services, CLI tools, or cloud-native applications

For detailed API documentation, select your language:

Python Runtime

Full API reference with async support and type hints.

View Details →

TypeScript Runtime

Full API reference with TypeScript types.

View Details →

C# Runtime

Full API reference with .NET integration.

View Details →

Go Runtime

Full API reference with type-safe structs.

View Details →