### Run Documentation Site Locally

Source: https://github.com/microsoft/agentschema/blob/main/docs/README.md

Navigate to the docs directory, install dependencies, and start the development server to view the documentation site locally. The site will be accessible at http://localhost:4321/.

```bash
cd docs
npm install
npm run dev
```

--------------------------------

### Install AgentSchema (Go)

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/index.mdx

Get the AgentSchema Go module using the go get command.

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

--------------------------------

### Install Project Dependencies

Source: https://github.com/microsoft/agentschema/blob/main/README.md

Installs dependencies for the emitter and Python runtime. Ensure you have the necessary SDKs (dotnet, Node.js, Python, Go) installed.

```bash
npm install
```

```bash
npm install
```

```bash
uv venv
uv sync --all-extras
```

--------------------------------

### Install AgentSchema

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/python.md

Install the AgentSchema library using pip or uv.

```bash
pip install agentschema
```

```bash
uv add agentschema
```

--------------------------------

### YAML Example of a Property

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/Property.md

Example demonstrating the full YAML structure for defining a string property with default, example, and enumeration values.

```yaml
name: my-input
kind: string
description: A description of the input property
required: true
default: default value
example: example value
enumValues:
  - value1
  - value2
  - value3
```

--------------------------------

### McpTool Yaml Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/McpTool.md

An example of how to configure an McpTool in YAML format.

```APIDOC
## Yaml Example

This is an example of the McpTool configuration in YAML format.

```yaml
kind: mcp
connection:
  kind: reference
serverName: My MCP Server
serverDescription: This tool allows access to MCP services.
approvalMode:
  kind: always
allowedTools:
  - operation1
  - operation2
```
```

--------------------------------

### OpenApiTool Yaml Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/OpenApiTool.md

An example of how to configure an OpenApiTool in YAML format.

```APIDOC
## Yaml Example

This is an example of an `OpenApiTool` configuration in YAML format:

```yaml
kind: openapi
connection:
  kind: reference
specification: full_sepcification_here
```
```

--------------------------------

### AgentSchema File Tree Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/guides/index.mdx

Illustrates the directory structure for AgentSchema examples, including agent definitions and manifests.

```text
- examples/
  - analyst/ Sales data analysis with Code Interpreter
    - **analyst.yaml**
    - analyst_manifest.yaml
  - qna/ Q&A with Azure CLU
    - **qna.yml**
    - qna_manifest.yml
  - travel/ Travel planning with APIs
    - **travel.yaml**
    - travel_manifest.yaml
```

--------------------------------

### AgentSchema TypeScript SDK Setup

Source: https://github.com/microsoft/agentschema/blob/main/runtime/typescript/agentschema/README.md

Install project dependencies using npm.

```bash
npm install
```

--------------------------------

### Install AgentSchema with uv

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/index.mdx

Install the AgentSchema library using uv for Python projects.

```bash
uv add agentschema
```

--------------------------------

### Install AgentSchema

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/typescript.md

Install the AgentSchema library using npm, yarn, or pnpm.

```bash
npm install agentschema
# or
yarn add agentschema
# or
pnpm add agentschema
```

--------------------------------

### Install agentschema-emitter

Source: https://github.com/microsoft/agentschema/blob/main/agentschema-emitter/README.md

Install the agentschema-emitter package using npm.

```bash
npm install agentschema-emitter
```

--------------------------------

### CodeConfiguration Yaml Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/CodeConfiguration.md

Example of how to configure a hosted agent for code-based deployment using YAML. Specifies the runtime, entry point, and dependency resolution method.

```yaml
runtime: python_3_11
entryPoint: main.py
dependencyResolution: remote_build
```

--------------------------------

### ContainerResources YAML Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/ContainerResources.md

Example of how to define CPU and memory resources for a container in YAML format.

```yaml
cpu: "1"
memory: 2Gi

```

--------------------------------

### Constructing a Runtime

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/index.mdx

Example of programmatically constructing a runtime configuration. Ensure all necessary components are correctly initialized.

```rust
    let runtime = Runtime::builder()
        .with_default_tool_registry()
        .build();

        Ok(())
    }
    ```
```

--------------------------------

### Tool Yaml Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/Tool.md

Example of how to define a tool in YAML format. This includes the tool's name, kind, description, and input bindings.

```yaml
name: my-tool
kind: function
description: A description of the tool
bindings:
  input: value
```

--------------------------------

### AgentManifest YAML Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/AgentManifest.md

Example of an AgentManifest in YAML format, demonstrating configuration for a basic prompt agent.

```yaml
name: basic-prompt
displayName: My Basic Prompt
description: A basic prompt that uses the GPT-3 chat API to answer questions
metadata:
  authors:
    - sethjuarez
    - jietong
  tags:
    - example
    - prompt
template:
  kind: prompt
  model: "{{model_name}}"
  instructions: You are a poet named {{agent_name}}. Rhyme all your responses.
parameters:
  strict: true
  properties:
    - name: model_name
      kind: string
      value: gpt-4o
    - name: agent_name
      kind: string
      value: Research Agent
resources:
  gptModelDeployment:
    kind: model
    id: gpt-4o
  webSearchInstance:
    kind: tool
    id: web-search
    options:
      apiKey: my-api-key
```

--------------------------------

### Verify Installation with Full Build

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/contributing/setup.mdx

Execute build and test commands for all AgentSchema components to verify the installation.

```bash
# Build the emitter
cd agentschema-emitter
npx tsc
cp -r src/templates dist/src/

# Generate all code
cd ../agentschema
npm run generate

# Run all tests
cd ../runtime/csharp && dotnet test
cd ../python/agentschema && uv run pytest tests/
cd ../../typescript/agentschema && npm test
cd ../../go/agentschema && go test ./...
cd ../../rust/agentschema && cargo test
```

--------------------------------

### Example Connection Configuration

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/Connection.md

A YAML configuration snippet demonstrating the structure for a connection, including kind, authentication mode, and usage description.

```yaml
kind: reference
authenticationMode: system
usageDescription: This will allow the agent to respond to an email on your behalf

```

--------------------------------

### Install AgentSchema with pnpm

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/index.mdx

Install the AgentSchema library using pnpm for TypeScript projects.

```bash
pnpm add agentschema
```

--------------------------------

### Resource YAML Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/Resource.md

Example of how to define a resource in YAML format. This snippet shows a basic resource with a name and kind.

```yaml
name: my-resource
kind: model
```

--------------------------------

### Install AgentSchema (Python)

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/index.mdx

Install the AgentSchema Python package using pip.

```bash
pip install agentschema
```

--------------------------------

### Use AgentSchema as an Axum Handler in Rust

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/rust.md

Demonstrates how to load an AgentDefinition and expose its properties via a GET endpoint using the Axum web framework. This example sets up a basic Axum server with shared application state.

```rust
use agentschema::AgentDefinition;
use axum::{routing::get, Json, Router};
use std::fs;
use std::sync::Arc;

struct AppState {
    agent: AgentDefinition,
}

async fn agent_handler(
    axum::extract::State(state): axum::extract::State<Arc<AppState>>,
) -> Json<serde_json::Value> {
    Json(serde_json::json!({
        "name": state.agent.name,
        "model": state.agent.model,
        "instructions": state.agent.instructions,
    }))
}

#[tokio::main]
async fn main() {
    let yaml = fs::read_to_string("agent.yaml").unwrap();
    let agent = AgentDefinition::from_yaml(&yaml).unwrap();
    let state = Arc::new(AppState { agent });

    let app = Router::new()
        .route("/agent", get(agent_handler))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}
```

--------------------------------

### Install AgentSchema (TypeScript)

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/index.mdx

Install the AgentSchema TypeScript package using npm.

```bash
npm install agentschema
```

--------------------------------

### ProtocolVersionRecord Yaml Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/ProtocolVersionRecord.md

Example of how to define a ProtocolVersionRecord in YAML format. This specifies the protocol and its version.

```yaml
protocol: responses
version: v0.1.1
```

--------------------------------

### ToolResource Yaml Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/ToolResource.md

Example of how to define a tool resource in YAML format. Specify the 'kind' as 'tool', provide a unique 'id', and include any necessary 'options' for the tool's configuration.

```yaml
kind: tool
id: web-search
options:
  myToolResourceProperty: myValue
```

--------------------------------

### Install AgentSchema with yarn

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/index.mdx

Install the AgentSchema library using yarn for TypeScript projects.

```bash
yarn add agentschema
```

--------------------------------

### Process Agent and Get Tools

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/python.md

Demonstrates type hinting for AgentDefinition and Tool, and how to extract tools from an agent.

```python
from agentschema import AgentDefinition, Tool

def process_agent(agent: AgentDefinition) -> list[Tool]:
    """Process an agent and return its tools."""
    return agent.tools or []

# IDE provides full autocomplete and type checking
agent = AgentDefinition(
    name="my-agent",      # str
    model="gpt-4o",       # str
    instructions="...",   # str
    tools=[],             # list[Tool]
)
```

--------------------------------

### PropertySchema YAML Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/PropertySchema.md

Illustrates the structure of a PropertySchema in YAML format, including example records, strictness setting, and property definitions.

```yaml
examples:
  - key: value
strict: true
properties:
  firstName:
    kind: string
    sample: Jane
  lastName:
    kind: string
    sample: Doe
  question:
    kind: string
    sample: What is the meaning of life?
```

--------------------------------

### ContainerAgent Yaml Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/ContainerAgent.md

Example YAML configuration for a ContainerAgent, specifying its kind, protocols, image, Dockerfile path, resources, and environment variables.

```yaml
kind: hosted
protocols:
  - protocol: responses
    version: v0.1.1
image: myregistry.azurecr.io/my-agent
dockerfilePath: ./Dockerfile
resources:
  cpu: "1"
  memory: 2Gi
environmentVariables:
  - name: MY_ENV_VAR
    value: my-value
```

--------------------------------

### Simplified String Input Construction

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/Property.md

Demonstrates the simplified YAML syntax for creating a string property, equivalent to a full definition with kind and example.

```yaml
input: "example"
```

--------------------------------

### ObjectProperty Yaml Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/ObjectProperty.md

This example demonstrates how to define an ObjectProperty in YAML, specifying nested properties with their kinds.

```yaml
properties:
  property1:
    kind: string
  property2:
    kind: number
```

--------------------------------

### Model YAML Configuration

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/Model.md

Example of how to configure a model using YAML, specifying provider, API type, connection details, and options like temperature and max tokens.

```yaml
id: gpt-35-turbo
provider: azure
apiType: chat
connection:
  kind: key
  endpoint: https://{your-custom-endpoint}.openai.azure.com/
  key: "{your-api-key}"
options:
  type: chat
  temperature: 0.7
  maxTokens: 1000
```

--------------------------------

### Install Schema Compiler Dependencies

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/contributing/setup.mdx

Install Node.js dependencies for the agentschema compiler package.

```bash
cd ../agentschema
npm install
```

--------------------------------

### Install AgentSchema (.NET)

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/index.mdx

Add the AgentSchema package to your .NET project using the dotnet CLI.

```bash
dotnet add package AgentSchema
```

--------------------------------

### PromptAgent Yaml Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/PromptAgent.md

Defines a PromptAgent using pure YAML. Instructions are provided in a multi-line string, encompassing system and user prompt details.

```yaml
kind: prompt
model:
  id: gpt-35-turbo
  connection:
    kind: key
    endpoint: https://{your-custom-endpoint}.openai.azure.com/
    key: "{your-api-key}"
tools:
  - name: getCurrentWeather
    kind: function
    description: Get the current weather in a given location
    parameters:
      location:
        kind: string
        description: The city and state, e.g. San Francisco, CA
      unit:
        kind: string
        description: The unit of temperature, e.g. Celsius or Fahrenheit
instructions: |-
  system:
  You are an AI assistant who helps people find information.
  As the assistant, you answer questions briefly, succinctly,
  and in a personable manner using markdown and even add some 
  personal flair with appropriate emojis.

  # Customer
  You are helping {{firstName}} {{lastName}} to find answers to 
  their questions. Use their name to address them in your responses.
  user:
  {{question}}

```

--------------------------------

### Configure Model Options with YAML

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/ModelOptions.md

Example of how to configure ModelOptions using YAML syntax, specifying various generation parameters and custom properties.

```yaml
frequencyPenalty: 0.5
maxOutputTokens: 2048
presencePenalty: 0.3
seed: 42
temperature: 0.7
topK: 40
topP: 0.9
stopSequences:
  - |+
    
  - "###"
allowMultipleToolCalls: true
additionalProperties:
  customProperty: value
  anotherProperty: anotherValue

```

--------------------------------

### Full String Input Construction

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/Property.md

Illustrates the complete YAML structure for defining a string property, including kind and example.

```yaml
input:
  kind: string
  example: "example"
```

--------------------------------

### ModelResource Yaml Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/ModelResource.md

Example of how to define a ModelResource in YAML format. Specifies the kind and id of the model.

```yaml
kind: model
id: gpt-4o
```

--------------------------------

### OpenApiTool YAML Configuration

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/OpenApiTool.md

Example of how to configure an OpenAPI tool in YAML format. Specify the 'kind' as 'openapi', provide connection details, and the OpenAPI 'specification'.

```yaml
kind: openapi
connection:
  kind: reference
specification: full_sepcification_here
```

--------------------------------

### Array Collection Format Example

Source: https://github.com/microsoft/agentschema/blob/main/runtime/csharp/AgentSchema/README.md

Illustrates the 'array' collection format in YAML, where collections are lists of objects.

```yaml
tools:
  - name: my_tool
    kind: function
    description: A tool
```

--------------------------------

### McpTool YAML Configuration

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/McpTool.md

Example of how to configure an McpTool in YAML format. This includes specifying the tool kind, connection details, server information, approval mode, and allowed tools.

```yaml
kind: mcp
connection:
  kind: reference
serverName: My MCP Server
serverDescription: This tool allows access to MCP services.
approvalMode:
  kind: always
allowedTools:
  - operation1
  - operation2
```

--------------------------------

### Full Integer Input Construction

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/Property.md

Illustrates the complete YAML structure for defining an integer property, including kind and example.

```yaml
input:
  kind: integer
  example: 5
```

--------------------------------

### Simplified Float32 Input Construction

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/Property.md

Demonstrates the simplified YAML syntax for creating a float property, equivalent to a full definition with kind and example.

```yaml
input: 3.14
```

--------------------------------

### ApiKeyConnection Yaml Configuration

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/ApiKeyConnection.md

Example of how to configure an ApiKeyConnection using YAML. Replace placeholders with your actual endpoint and API key.

```yaml
kind: key
endpoint: https://{your-custom-endpoint}.openai.azure.com/
apiKey: your-api-key
```

--------------------------------

### ReferenceConnection Yaml Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/ReferenceConnection.md

Defines a reference connection for an AI service, specifying its kind, name, and target resource.

```yaml
kind: reference
name: my-reference-connection
target: my-target-resource
```

--------------------------------

### FoundryConnection Yaml Configuration

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/FoundryConnection.md

Example YAML configuration for a FoundryConnection, specifying the kind, endpoint, name, and connectionType.

```yaml
kind: foundry
endpoint: https://myresource.services.ai.azure.com/api/projects/myproject
name: my-openai-connection
connectionType: model
```

--------------------------------

### Customize Root Object for Generation (CLI)

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/guides/code-generation.mdx

Demonstrates how to use the CLI to generate code starting from a specific object within the schema, useful for creating subsets of the generated code.

```bash
# Generate only AgentDefinition and its dependencies
npx agentschema-generate -o ./lib -r AgentSchema.AgentDefinition
```

--------------------------------

### CodeInterpreterTool YAML Configuration

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/CodeInterpreterTool.md

Example of how to configure a CodeInterpreterTool in YAML format, specifying its kind and associated file IDs.

```yaml
kind: code_interpreter
fileIds:
  - file1
  - file2
```

--------------------------------

### WebSearchTool YAML Configuration

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/WebSearchTool.md

Example configuration for the WebSearchTool in YAML format, specifying the search engine kind, connection details, and search options.

```yaml
kind: bing_search
connection:
  kind: reference
options:
  instanceName: MyBingInstance
  market: en-US
  setLang: en
  count: 10
  freshness: Day

```

--------------------------------

### Construct Agent Definition in Go

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/index.mdx

Define an agent using the PromptAgent struct in Go. This example demonstrates setting up an agent with a function tool and its parameters, including helper functions for pointer creation.

```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),
                    },
                },
            },
        },
    }
}
```

--------------------------------

### Set Up Python Environment

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/contributing/setup.mdx

Create and synchronize a Python virtual environment using uv for the agentschema runtime.

```bash
cd ../runtime/python/agentschema
uv venv
uv sync --all-extras
```

--------------------------------

### Simplified Integer Input Construction

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/Property.md

Shows the simplified YAML syntax for creating an integer property, equivalent to a full definition with kind and example.

```yaml
input: 5
```

--------------------------------

### PromptAgent Markdown Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/PromptAgent.md

Defines a PromptAgent using markdown frontmatter. Includes model configuration, tools, and a template with system and user prompts.

```markdown
---
kind: prompt
model:
  id: gpt-35-turbo
  connection:
    kind: key
    endpoint: https://{your-custom-endpoint}.openai.azure.com/
    key: "{your-api-key}"
tools:
  - name: getCurrentWeather
    kind: function
    description: Get the current weather in a given location
    parameters:
      location:
        kind: string
        description: The city and state, e.g. San Francisco, CA
      unit:
        kind: string
        description: The unit of temperature, e.g. Celsius or Fahrenheit
template:
  format: mustache
  parser: prompty
---
system:
You are an AI assistant who helps people find information.
As the assistant, you answer questions briefly, succinctly,
and in a personable manner using markdown and even add some 
personal flair with appropriate emojis.

# Customer
You are helping {{firstName}} {{lastName}} to find answers to 
their questions. Use their name to address them in your responses.
user:
{{question}}

```

--------------------------------

### Add AgentSchema NuGet Package

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/csharp.md

Install the AgentSchema NuGet package using the .NET CLI or Package Manager Console.

```bash
dotnet add package AgentSchema
```

```powershell
Install-Package AgentSchema
```

--------------------------------

### Build Documentation Site for Production

Source: https://github.com/microsoft/agentschema/blob/main/docs/README.md

Execute this command to build the documentation site for production deployment. This command optimizes assets and generates static files.

```bash
npm run build
```

--------------------------------

### YAML Collection Format Example

Source: https://github.com/microsoft/agentschema/blob/main/runtime/csharp/AgentSchema/README.md

Illustrates the 'object' collection format in YAML, where collections use the item's name as the key.

```yaml
tools:
  my_tool:
    kind: function
    description: A tool
```

--------------------------------

### Full Float32 Input Construction

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/Property.md

Illustrates the complete YAML structure for defining a float property, including kind and example.

```yaml
input:
  kind: float
  example: 3.14
```

--------------------------------

### Load Agent Definitions from Files in Go

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/index.mdx

Use `os.ReadFile` to get byte slices of file content, then convert to string and parse using `agentschema.PromptAgentFromYAML` or `agentschema.PromptAgentFromJSON`. Error handling is omitted for brevity.

```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))
}
```

--------------------------------

### McpServerToolSpecifyApprovalMode YAML Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/McpServerToolSpecifyApprovalMode.md

This YAML configuration defines the 'specify' approval mode, listing tools that always require approval and those that never require approval.

```yaml
kind: specify
alwaysRequireApprovalTools:
  - operation1
neverRequireApprovalTools:
  - operation2
```

--------------------------------

### Basic Prompt Agent Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/AgentDefinition.md

Defines a simple prompt agent named 'basic-prompt' that uses the GPT-3 chat API. Includes metadata, input schema with default values, and an output schema.

```yaml
kind: prompt
name: basic-prompt
displayName: Basic Prompt Agent
description: A basic prompt that uses the GPT-3 chat API to answer questions
metadata:
  authors:
    - sethjuarez
    - jietong
  tags:
    - example
    - prompt
inputSchema:
  properties:
    firstName:
      kind: string
      value: Jane
    lastName:
      kind: string
      value: Doe
    question:
      kind: string
      value: What is the meaning of life?
outputSchema:
  properties:
    answer:
      kind: string
      description: The answer to the user's question.

```

--------------------------------

### Integration with Azure OpenAI

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/csharp.md

Example of using an AgentDefinition with the Azure OpenAI SDK to create chat completions. Ensure your `agent.yaml` contains model and instructions.

```csharp
using AgentSchema;
using Azure.AI.OpenAI;

var agent = AgentDefinition.FromYamlFile("agent.yaml");

var client = new OpenAIClient(
    new Uri("https://your-resource.openai.azure.com/"),
    new AzureKeyCredential("your-key")
);

var options = new ChatCompletionsOptions
{
    DeploymentName = agent.Model,
    Messages = 
    {
        new ChatRequestSystemMessage(agent.Instructions),
        new ChatRequestUserMessage("Hello!"),
    },
    Temperature = (float)(agent.ModelOptions?.Temperature ?? 0.7),
};

var response = await client.GetChatCompletionsAsync(options);
```

--------------------------------

### AgentManifest Example for a Configurable Template

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/guides/example.md

An AgentManifest acts as a parameterized template for creating agents dynamically. It uses `{{parameter}}` syntax for values that can be substituted at runtime, enabling reusability and configuration.

```yaml
name: customer-support-template
displayName: "Customer Support Template"
description: "Configurable customer support agent template"

template:
  kind: prompt
  name: "{{agent_name}}"
  displayName: "{{display_name}}"
  description: "{{agent_description}}"
  
  model: "{{model_name}}"
  
  instructions: |
    You are a {{agent_role}}. {{custom_instructions}}
    
  tools:
    knowledge_base:
      kind: function
      description: "Search {{company_name}} knowledge base"
      connection: "{{kb_connection}}"

parameters:
  properties:
    - name: agent_name
      kind: string
      description: "Internal agent identifier"
      required: true
    - name: display_name
      kind: string
      description: "Human-readable agent name"
      required: true
    - name: agent_description
      kind: string
      description: "Agent description"
      required: true
    - name: model_name
      kind: string
      value: "gpt-4o"
      description: "AI model to use"
    - name: agent_role
      kind: string
      value: "customer support agent"
      description: "Agent's role description"
    - name: custom_instructions
      kind: string
      description: "Additional instructions"
    - name: company_name
      kind: string
      required: true
      description: "Company name for personalization"
    - name: kb_connection
      kind: string
      required: true
      description: "Knowledge base connection identifier"

resources:
  - name: gpt-model
    kind: model
    id: "{{model_name}}"
  - name: knowledge-base-tool
    kind: tool
    id: function-tool
```

--------------------------------

### Install Emitter Dependencies

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/contributing/setup.mdx

Install Node.js dependencies for the agentschema-emitter package.

```bash
cd agentschema-emitter
npm install
```

--------------------------------

### Example Conversation for Travel Agent

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/guides/travel-agent.md

Illustrates a sample user interaction with the Travel Agent, showing a request for travel recommendations and the assistant's structured response.

```yaml
metadata:
  example:
    - role: user
      content: |-
        I'm planning a trip to Paris for 5 days. Can you recommend some 
        must-see attractions, good places to eat, and nice hotels to stay at?
    - role: assistant
      content: |-
        Sure! Here are some recommendations for your 5-day trip to Paris:
        Attractions:
        1. Eiffel Tower - Iconic landmark with stunning views of the city.
        2. Louvre Museum - Home to the Mona Lisa and other masterpieces.
        3. Notre-Dame Cathedral - Beautiful Gothic architecture.
        4. Montmartre - Charming neighborhood with art studios and the Sacré-Cœur Basilica.
        5. Seine River Cruise - Relaxing way to see the city from the water.
```

--------------------------------

### Integration with Semantic Kernel

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/csharp.md

Demonstrates integrating an AgentDefinition with Semantic Kernel for AI prompt execution. This example uses Azure OpenAI as the chat completion service.

```csharp
using AgentSchema;
using Microsoft.SemanticKernel;

var agent = AgentDefinition.FromYamlFile("agent.yaml");

var kernel = Kernel.CreateBuilder()
    .AddAzureOpenAIChatCompletion(
        deploymentName: agent.Model,
        endpoint: "https://your-resource.openai.azure.com/",
        apiKey: "your-key"
    )
    .Build();

var result = await kernel.InvokePromptAsync(agent.Instructions);
```

--------------------------------

### Full Binding Construction from Simplified

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/Binding.md

Demonstrates the full YAML representation that is equivalent to the simplified string construction for a Binding.

```yaml
value:
  input: "example"
```

--------------------------------

### Go HTTP Handler for Agent Information

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/go.md

Example of creating an HTTP handler in Go that serves agent details (name, model, instructions) as JSON. This is useful for exposing agent configuration via an API.

```go
package main

import (
    "encoding/json"
    "net/http"
    "os"
    
    "github.com/microsoft/agentschema-go/agentschema"
)

var agent agentschema.PromptAgent

func init() {
    yamlBytes, _ := os.ReadFile("agent.yaml")
    agent, _ = agentschema.PromptAgentFromYAML(string(yamlBytes))
}

func agentHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(map[string]interface{}{
        "name":         agent.Name,
        "model":        agent.Model.Name,
        "instructions": agent.Instructions,
    })
}

func main() {
    http.HandleFunc("/agent", agentHandler)
    http.ListenAndServe(":8080", nil)
}
```

--------------------------------

### View agentschema-emitter CLI help

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/guides/emitter.mdx

Use npx to run the agentschema-emitter CLI and view its help information.

```bash
npx agentschema-emitter --help
```

--------------------------------

### Install TypeScript Test Dependencies

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/contributing/setup.mdx

Install Node.js dependencies for the agentschema TypeScript package.

```bash
cd ../../typescript/agentschema
npm install
```

--------------------------------

### Run Tests in Go

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/contributing/testing.mdx

Navigate to the Go agentschema directory and use 'go test ./...' to run all tests. Employ '-run "TestName"' to filter by test name and '-v' for verbose output.

```bash
cd runtime/go/agentschema
go test ./...                         # All tests
go test -run "TestModel"              # Filter by name
go test -v ./...                      # Verbose output
```

--------------------------------

### ArrayProperty Yaml Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/ArrayProperty.md

This is an example of how to define an ArrayProperty in YAML format. It specifies that the array will contain items of type 'string'.

```yaml
items:
  kind: string
```

--------------------------------

### Load Agent Definition from YAML and JSON

Source: https://github.com/microsoft/agentschema/blob/main/runtime/go/README.md

Demonstrates loading an agent definition from both YAML and JSON strings using the SDK. Ensure correct data format for successful parsing.

```go
package main

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

func main() {
    // From YAML
    yamlData := `
name: my-agent
kind: prompt
model: gpt-4o
instructions: You are a helpful assistant.
`
    
    agent, err := agentschema.PromptAgentFromYAML(yamlData)
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Agent: %s\n", agent.Name)

    // From JSON
    jsonData := `{
        "name": "my-agent",
        "kind": "prompt",
        "model": "gpt-4o",
        "instructions": "You are a helpful assistant."
    }`
    
    jsonAgent, err := agentschema.PromptAgentFromJSON(jsonData)
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Agent: %s\n", jsonAgent.Name)
}
```

--------------------------------

### Install AgentSchema with NuGet Package Manager

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/index.mdx

Install the AgentSchema package using the NuGet Package Manager in PowerShell for .NET projects.

```powershell
Install-Package AgentSchema
```

--------------------------------

### Using Load/Save Context

Source: https://github.com/microsoft/agentschema/blob/main/runtime/typescript/agentschema/README.md

Illustrates how to customize the loading and saving processes using `LoadContext` and `SaveContext` objects.

```APIDOC
## Using Load/Save Context

Customize the loading and saving process with context objects:

```typescript
import { AgentDefinition, LoadContext, SaveContext } from "agentschema";

// Custom load context with preprocessing
const loadContext = new LoadContext({
  preProcess: (data) => {
    // Transform input data before loading
    console.log("Loading agent:", data["name"]);
    return data;
  },
  postProcess: (result) => {
    // Transform result after loading
    console.log("Loaded successfully");
    return result;
  },
});

const agent = AgentDefinition.fromYaml(yamlContent, loadContext);

// Custom save context
const saveContext = new SaveContext({
  collectionFormat: "object", // Use object format for collections (name as key)
  useShorthand: true, // Use shorthand notation when possible
});

const output = agent.toYaml(saveContext);
```
```

--------------------------------

### FunctionTool Yaml Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/FunctionTool.md

Example of how to define a FunctionTool in YAML format. It specifies the tool's kind, parameters with their properties, and the strict validation flag.

```yaml
kind: function
parameters:
  properties:
    firstName:
      kind: string
      value: Jane
    lastName:
      kind: string
      value: Doe
    question:
      kind: string
      value: What is the meaning of life?
strict: true
```

--------------------------------

### Build and Generate with Emitter

Source: https://github.com/microsoft/agentschema/blob/main/README.md

Builds the agent schema emitter and generates documentation, schemas, and code. Run these commands from the `agentschema-emitter` directory.

```bash
npm run build
npm run generate
```

--------------------------------

### Install AgentSchema (Rust)

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/index.mdx

Add AgentSchema as a dependency in your Rust project's Cargo.toml file.

```toml
[dependencies]
agentschema = "1.0.0-beta.7"
```

--------------------------------

### Create Agent Programmatically and Save

Source: https://github.com/microsoft/agentschema/blob/main/runtime/python/agentschema/README.md

Create a `PromptAgent` programmatically with tools and input schema, then save it to YAML or JSON.

```python
from agentschema.core import (
    PromptAgent,
    Model,
    FunctionTool,
    PropertySchema,
    Property,
    SaveContext,
)

# Create a simple prompt-based agent
agent = PromptAgent(
    name="my-assistant",
    description="A helpful assistant that can answer questions",
    model=Model(
        name="gpt-4o",
    ),
    instructions="You are a helpful assistant. Answer questions clearly and concisely.",
    tools=[
        FunctionTool(
            name="get_weather",
            description="Get the current weather for a location",
        ),
    ],
    inputSchema=PropertySchema(
        properties={
            "question": Property(
                type="string",
                description="The user's question",
            ),
        },
    ),
)

# Save to YAML
yaml_output = agent.to_yaml()
print(yaml_output)

# Save to JSON
json_output = agent.to_json()
print(json_output)
```

--------------------------------

### EnvironmentVariable YAML Definition

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/EnvironmentVariable.md

Example of how to define an environment variable in YAML format. This is used for configuring agents.

```yaml
name: MY_ENV_VAR
value: my-value
```

--------------------------------

### Binding Yaml Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/Binding.md

A standard YAML representation of a Binding, specifying the name and the input property to bind.

```yaml
name: my-tool
input: input-variable
```

--------------------------------

### Template YAML Example

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/Template.md

Defines a template with 'mustache' as both the rendering format and parser kind. This is a basic configuration for a template.

```yaml
format:
  kind: mustache
parser:
  kind: mustache
```

--------------------------------

### Create and Push All Runtime Tags

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/contributing/publishing.mdx

A consolidated command sequence to create and push annotated tags for multiple runtimes simultaneously, useful for publishing a coordinated release.

```bash
# Create all tags
git tag -a "csharp-v1.0.0-beta.6" -m "C# SDK v1.0.0-beta.6"
git tag -a "python-v1.0.0b6" -m "Python SDK v1.0.0-beta.6"
git tag -a "typescript-v1.0.0-beta.6" -m "TypeScript SDK v1.0.0-beta.6"
git tag -a "go-v1.0.0-beta.6" -m "Go SDK v1.0.0-beta.6"

# Push all tags
git push origin --tags
```

--------------------------------

### CustomTool Yaml Configuration

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/CustomTool.md

Example YAML configuration for a CustomTool, specifying connection details and options such as timeout and retries.

```yaml
connection:
  kind: reference
options:
  timeout: 30
  retries: 3

```

--------------------------------

### Create Agent Programmatically

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/go.md

Construct agent definitions using Go structs, defining properties like instructions, description, and tools with parameters.

```go
package main

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

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

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

--------------------------------

### Go Integration with Azure OpenAI SDK

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/go.md

Shows how to load an agent definition from YAML and use it to construct a chat completion request with the Azure OpenAI SDK for Go.

```go
package main

import (
    "context"
    "fmt"
    "os"
    
    "github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
    "github.com/Azure/azure-sdk-for-go/sdk/azcore"
    "github.com/microsoft/agentschema-go/agentschema"
)

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

    // Create Azure OpenAI client
    keyCredential := azcore.NewKeyCredential(os.Getenv("AZURE_OPENAI_KEY"))
    client, _ := azopenai.NewClientWithKeyCredential(
        os.Getenv("AZURE_OPENAI_ENDPOINT"),
        keyCredential,
        nil,
    )

    // Build chat request using agent config
    messages := []azopenai.ChatRequestMessageClassification{
        &azopenai.ChatRequestSystemMessage{
            Content: agent.Instructions,
        },
        &azopenai.ChatRequestUserMessage{
            Content: azopenai.NewChatRequestUserMessageContent("Hello!"),
        },
    }

    resp, _ := client.GetChatCompletions(
        context.Background(),
        azopenai.ChatCompletionsOptions{
            DeploymentName: &agent.Model.Name,
            Messages:       messages,
        },
        nil,
    )

    fmt.Println(*resp.Choices[0].Message.Content)
}
```

--------------------------------

### Full Boolean Input Construction

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/Property.md

Illustrates the complete YAML structure for defining a boolean property, including kind and example.

```yaml
input:
  kind: boolean
  example: true
```

--------------------------------

### Run Runtime Tests

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/contributing/publishing.mdx

Execute tests for each runtime package before publishing. Navigate to the respective runtime directory and run the test commands.

```bash
cd runtime/csharp && dotnet test
cd runtime/python/agentschema && uv run pytest tests/ 
cd runtime/typescript/agentschema && npm test
cd runtime/go/agentschema && go test ./...
```

--------------------------------

### Load Agent Definition from YAML and JSON

Source: https://github.com/microsoft/agentschema/blob/main/runtime/rust/agentschema/README.md

Demonstrates loading agent definitions from both YAML and JSON string formats using `PromptAgent::from_yaml` and `PromptAgent::from_json`. Ensure the input data is valid AgentSchema.

```rust
use agentschema::PromptAgent;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // From YAML
    let yaml_data = r#"
name: my-agent
kind: prompt
model: gpt-4o
instructions: You are a helpful assistant.
"#;
    
    let agent = PromptAgent::from_yaml(yaml_data)?;
    println!("Agent: {}", agent.name);

    // From JSON
    let json_data = r#"{ 
        \"name\": \"my-agent\",
        \"kind\": \"prompt\",
        \"model\": \"gpt-4o\",
        \"instructions\": \"You are a helpful assistant.\"
    }""#;
    
    let json_agent = PromptAgent::from_json(json_data)?;
    println!("Agent: {}", json_agent.name);
    
    Ok(())
}
```

--------------------------------

### Create and Serialize Agent Definition

Source: https://github.com/microsoft/agentschema/blob/main/runtime/rust/agentschema/README.md

Shows how to programmatically create a `PromptAgent` instance, set its properties, and then serialize it to both YAML and JSON formats using `to_yaml` and `to_json` methods.

```rust
use agentschema::PromptAgent;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut agent = PromptAgent::new();
    agent.name = "my-agent".to_string();
    agent.model = "gpt-4o".to_string();
    agent.instructions = Some("You are a helpful assistant.".to_string());

    // Convert to YAML
    let yaml = agent.to_yaml()?;
    println!("{}", yaml);

    // Convert to JSON
    let json = agent.to_json()?;
    println!("{}", json);
    
    Ok(())
}
```

--------------------------------

### Create and Save a Prompt Agent Programmatically

Source: https://github.com/microsoft/agentschema/blob/main/runtime/csharp/AgentSchema/README.md

Programmatically create a PromptAgent with specified models, instructions, tools, and input schema, then save it to YAML or JSON.

```csharp
using AgentSchema;

// Create a simple prompt-based agent
var agent = new PromptAgent
{
    Name = "my-assistant",
    Description = "A helpful assistant that can answer questions",
    Model = new Model
    {
        Id = "gpt-4o"
    },
    Instructions = "You are a helpful assistant. Answer questions clearly and concisely.",
    Tools =
    [
        new FunctionTool
        {
            Name = "get_weather",
            Description = "Get the current weather for a location"
        }
    ],
    InputSchema = new PropertySchema
    {
        Properties =
        [
            new Property
            {
                Name = "question",
                Kind = "string",
                Description = "The user's question"
            }
        ]
    }
};

// Save to YAML
var yamlOutput = agent.ToYaml();
Console.WriteLine(yamlOutput);

// Save to JSON
var jsonOutput = agent.ToJson();
Console.WriteLine(jsonOutput);
```

--------------------------------

### Dependency Injection of AgentDefinition

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/runtimes/csharp.md

Shows how to register AgentDefinition as a singleton service using dependency injection and how to inject it into other services.

```csharp
using AgentSchema;
using Microsoft.Extensions.DependencyInjection;

services.AddSingleton(sp =>
{
    return AgentDefinition.FromYamlFile("agent.yaml");
});

// Inject into your services
public class AgentService
{
    private readonly AgentDefinition _agent;
    
    public AgentService(AgentDefinition agent)
    {
        _agent = agent;
    }
}
```

--------------------------------

### Simplified Boolean Input Construction

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/Property.md

Shows the simplified YAML syntax for creating a boolean property, equivalent to a full definition with kind and example.

```yaml
input: true
```

--------------------------------

### Create Annotated Git Tags for Publishing

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/contributing/publishing.mdx

Create annotated Git tags with descriptive messages for each runtime package. Ensure the tag format matches the conventions for the specific runtime.

```bash
# TypeSpec Emitter / npm (agentschema-emitter)
git tag -a "emitter-v0.1.11" -m "Emitter v0.1.11: description of changes"

# C# / NuGet
git tag -a "csharp-v1.0.0-beta.6" -m "C# SDK v1.0.0-beta.6: description of changes"

# Python / PyPI (note PEP 440 format)
git tag -a "python-v1.0.0b6" -m "Python SDK v1.0.0-beta.6: description of changes"

# TypeScript / npm
git tag -a "typescript-v1.0.0-beta.6" -m "TypeScript SDK v1.0.0-beta.6: description of changes"

# Go
git tag -a "go-v1.0.0-beta.6" -m "Go SDK v1.0.0-beta.6: description of changes"

# Documentation
git tag -a "docs-v1.0.0-beta.6" -m "Docs v1.0.0-beta.6: description of changes"
```

--------------------------------

### TypeSpec Emitter Configuration

Source: https://github.com/microsoft/agentschema/blob/main/agentschema-emitter/README.md

Configure agentschema-emitter as a TypeSpec emitter in tspconfig.yaml. This example specifies the root object and output directories for different targets.

```yaml
emit:
  - "agentschema-emitter"
options:
  "agentschema-emitter":
    root-object: "AgentSchema.AgentManifest"
    emit-targets:
      - type: Python
        output-dir: "./python"
      - type: CSharp
        output-dir: "./csharp"
```

--------------------------------

### Full McpServerApprovalMode Construction

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/reference/McpServerApprovalMode.md

Illustrates the equivalent full YAML representation for constructing McpServerApprovalMode instances, including nested 'kind' property.

```yaml
kind:
  kind: "example"
```

--------------------------------

### Run Tests in C#

Source: https://github.com/microsoft/agentschema/blob/main/docs/src/content/docs/contributing/testing.mdx

Navigate to the C# runtime directory and execute 'dotnet test' to run all tests. Use '--filter "ClassName"' to target specific test classes.

```bash
cd runtime/csharp
dotnet test                           # All tests
dotnet test --filter "ClassName"      # Specific class
```