# =============================================================================
# AetherShell Agent API Integration Examples
# =============================================================================
# This file demonstrates how to use the Agent API with various AI providers.
# The Agent API server runs on port 3002 and provides a JSON-based interface
# for AI agents to interact with AetherShell's typed shell capabilities.
# Start the Agent API server in a separate terminal:
# ae --agent-api
# or with a custom port:
# ae --agent-api --agent-port 3003
# =============================================================================
# 1. Basic API Usage
# =============================================================================
# Test if the API is running
# This example talks to a running agent API server. Without one it says so
# and stops, rather than failing on a field access against a null response.
# Start the server with `ae agent serve --port 3002`, then set
# AE_AGENT_API=1 to run this end to end.
if env("AE_AGENT_API") == null {
print("Skipping: start the agent API (ae agent serve --port 3002) and set AE_AGENT_API=1 to run this example.")
}
if env("AE_AGENT_API") == null { exit(0) }
let api_base = "http://localhost:3002"
# Simple eval request
let eval_result = http.json_post(api_base, {
"action": "eval",
"code": "1 + 2 * 3"
})
print("Eval result: ${eval_result}")
# List available builtins
let builtins = http.json_post(api_base, {
"action": "list_builtins"
})
print("Available builtins: ${builtins.result | length}")
# =============================================================================
# 2. OpenAI Integration (GPT-5, o3, o4-mini)
# =============================================================================
# Generate schema for OpenAI function calling
let openai_schema = http.json_post(api_base, {
"action": "schema",
"format": "openai"
})
# Use with OpenAI's API
let openai_messages = [
{"role": "system", "content": "You are a helpful assistant that uses shell commands."},
{"role": "user", "content": "List files in the current directory"}
]
# This would be sent to OpenAI's API:
# curl https://api.openai.com/v1/chat/completions \
# -H "Authorization: Bearer $OPENAI_API_KEY" \
# -H "Content-Type: application/json" \
# -d '{
# "model": "gpt-5",
# "messages": [...],
# "tools": <openai_schema.result.tools>
# }'
print("OpenAI schema generated with tools for:")
print(openai_schema.result.tools | map(fn(t) => t.function.name))
# =============================================================================
# 3. Claude Integration (Claude 4.5 Opus/Sonnet/Haiku)
# =============================================================================
# Generate schema for Claude's tool_use format
let claude_schema = http.json_post(api_base, {
"action": "schema",
"format": "claude"
})
# Claude uses a different format - input_schema instead of parameters
print("Claude schema uses Anthropic tool_use format")
print("Compatible models: ${claude_schema.result.compatible_models}")
# Example Claude API request structure:
# {
# "model": "claude-4.5-sonnet",
# "max_tokens": 1024,
# "tools": <claude_schema.result.tools>,
# "messages": [{"role": "user", "content": "..."}]
# }
# =============================================================================
# 4. Gemini Integration (Gemini 2.5 Pro/Flash)
# =============================================================================
let gemini_schema = http.json_post(api_base, {
"action": "schema",
"format": "gemini"
})
# Gemini uses function_declarations format
print("Gemini schema uses Google's function_declarations format")
print("Declarations count: ${gemini_schema.result.function_declarations | length}")
# =============================================================================
# 5. Open Source Models (Llama 4, Mistral, Qwen)
# =============================================================================
# Llama 4 (400B Scout, 200B Maverick)
let llama_schema = http.json_post(api_base, {
"action": "schema",
"format": "llama"
})
print("Llama 4 compatible models: ${llama_schema.result.compatible_models}")
# Mistral (Large 2501, Codestral 2501)
let mistral_schema = http.json_post(api_base, {
"action": "schema",
"format": "mistral"
})
print("Mistral compatible models: ${mistral_schema.result.compatible_models}")
# Qwen 3 (235B A22B, 32B, Coder)
let qwen_schema = http.json_post(api_base, {
"action": "schema",
"format": "qwen"
})
print("Qwen 3 compatible models: ${qwen_schema.result.compatible_models}")
# =============================================================================
# 6. Inference Platforms (Together, Groq, Fireworks)
# =============================================================================
# Together AI - run open source models
let together_schema = http.json_post(api_base, {
"action": "schema",
"format": "together"
})
print("Together API base: ${together_schema.result.api_base}")
# Groq - ultra low latency inference
let groq_schema = http.json_post(api_base, {
"action": "schema",
"format": "groq"
})
print("Groq ultra low latency: ${groq_schema.result.ultra_low_latency}")
# Fireworks - fast inference
let fireworks_schema = http.json_post(api_base, {
"action": "schema",
"format": "fireworks"
})
print("Fireworks fast inference: ${fireworks_schema.result.fast_inference}")
# =============================================================================
# 7. Local Models (Ollama, vLLM)
# =============================================================================
# Ollama - local model serving
let ollama_schema = http.json_post(api_base, {
"action": "schema",
"format": "ollama"
})
print("Ollama endpoint: ${ollama_schema.result.endpoint}")
print("Ollama models: ${ollama_schema.result.compatible_models}")
# vLLM - high-performance local inference
let vllm_schema = http.json_post(api_base, {
"action": "schema",
"format": "vllm"
})
print("vLLM endpoint: ${vllm_schema.result.endpoint}")
# =============================================================================
# 8. Multi-Provider (OpenRouter)
# =============================================================================
# OpenRouter provides unified access to many models
let openrouter_schema = http.json_post(api_base, {
"action": "schema",
"format": "openrouter"
})
print("OpenRouter API base: ${openrouter_schema.result.api_base}")
print("OpenRouter tool-capable models include models from:")
print(" - OpenAI (gpt-5, o3)")
print(" - Anthropic (claude-4.5-opus, claude-4.5-sonnet)")
print(" - Google (gemini-2.5-pro, gemini-2.5-flash)")
print(" - Meta (llama-4-400b-scout)")
print(" - And many more...")
# =============================================================================
# 9. Chinese AI Providers (Kimi, GLM, Yi)
# =============================================================================
# Kimi/Moonshot (K2, V2)
let kimi_schema = http.json_post(api_base, {
"action": "schema",
"format": "kimi"
})
print("Kimi API base: ${kimi_schema.result.api_base}")
# GLM/ChatGLM (GLM-5, CodeGeeX 4)
let glm_schema = http.json_post(api_base, {
"action": "schema",
"format": "glm"
})
print("GLM models: ${glm_schema.result.compatible_models}")
# =============================================================================
# 10. Reasoning Models (DeepSeek R1)
# =============================================================================
let deepseek_schema = http.json_post(api_base, {
"action": "schema",
"format": "deepseek"
})
print("DeepSeek reasoning support: ${deepseek_schema.result.reasoning_support}")
print("DeepSeek models: ${deepseek_schema.result.compatible_models}")
# =============================================================================
# 11. Executing Tool Calls
# =============================================================================
# When an AI model returns a tool call, execute it:
let tool_call = {
"name": "ls",
"arguments": {"path": "."}
}
# Execute via Agent API
let result = http.json_post(api_base, {
"action": "call",
"builtin": tool_call.name,
"args": tool_call.arguments
})
# A block holds a single expression, so the two messages are one call.
# result.result carries the structured output.
if result.success {
print("Tool execution successful — result type: ${result.result_type}")
} else {
print("Tool execution failed: ${result.error}")
}
# =============================================================================
# 12. Pipeline Execution
# =============================================================================
# Execute multi-step pipelines
let pipeline_result = http.json_post(api_base, {
"action": "pipeline",
"steps": [
{"builtin": "ls", "args": {"path": "."}},
{"eval": "where(fn(f) => f.size > 1000)"},
{"eval": "select(\"name\", \"size\")"}
]
})
print("Pipeline result (files > 1KB):")
print(pipeline_result.result)
# =============================================================================
# 13. Type Information
# =============================================================================
# Get type information for better function calls
let type_info = http.json_post(api_base, {
"action": "type_info"
})
print("Available types in AetherShell:")
print(type_info.result.types)
# Get specific type info
let array_type = http.json_post(api_base, {
"action": "type_info",
"type_name": "Array"
})
print("Array type info: ${array_type.result}")
# =============================================================================
# 14. Streaming API (Server-Sent Events)
# =============================================================================
# The Agent API supports Server-Sent Events (SSE) for streaming responses.
# This is useful for long-running operations like pipelines.
# Streaming endpoints:
# POST /api/v1/stream/execute - Stream any request
# POST /api/v1/stream/pipeline - Stream pipeline execution with progress
# POST /api/v1/stream/eval - Stream code evaluation
# Example: Stream a pipeline with curl
# curl -N -X POST http://localhost:3002/api/v1/stream/pipeline \
# -H "Content-Type: application/json" \
# -d '{
# "steps": [
# {"builtin": "ls", "args": {"path": "."}},
# {"eval": "where(fn(f) => f.size > 1000)"},
# {"eval": "select(\"name\", \"size\")"}
# ]
# }'
# SSE events format:
# event: start
# data: {"message": "Starting pipeline with 3 steps"}
#
# event: progress
# data: {"current": 1, "total": 3, "percentage": 33.33, "message": "Processing step 1/3: ls"}
#
# event: progress
# data: {"current": 2, "total": 3, "percentage": 66.66, "message": "Processing step 2/3: where"}
#
# event: progress
# data: {"current": 3, "total": 3, "percentage": 100, "message": "Processing step 3/3: select"}
#
# event: complete
# data: {"success": true, "result": [...], "result_type": "Array"}
# JavaScript/TypeScript example for consuming SSE:
# const eventSource = new EventSource('http://localhost:3002/api/v1/stream/pipeline', {
# method: 'POST',
# headers: { 'Content-Type': 'application/json' },
# body: JSON.stringify({ steps: [...] })
# });
#
# eventSource.addEventListener('progress', (event) => {
# const data = JSON.parse(event.data);
# console.log(`Progress: ${data.percentage}% - ${data.message}`);
# });
#
# eventSource.addEventListener('complete', (event) => {
# const data = JSON.parse(event.data);
# console.log('Result:', data.result);
# });
print("Streaming endpoints available at /api/v1/stream// ")
//
// # =============================================================================
// # Summary
// # =============================================================================
//
// print("")
// print("=== Agent API Summary ===")
// print("Supported schema formats: 26+")
// print("Including: OpenAI, Claude, Gemini, Llama, Mistral, Cohere, Grok,")
// print(" DeepSeek, Bedrock, Azure OpenAI, Qwen, Kimi, Yi, GLM,")
// print(" Reka, AI21, Perplexity, Together, Groq, Fireworks,")
// print(" Ollama, vLLM, HuggingFace, OpenRouter, JSON, Ontology")
// print("")
// print("Latest models supported:")
// print(" - GPT-5, o3, o4-mini (OpenAI)")
// print(" - Claude 4.5 Opus/Sonnet/Haiku (Anthropic)")
// print(" - Gemini 2.5 Pro/Flash (Google)")
// print(" - Llama 4 400B/200B (Meta)")
// print(" - DeepSeek R1/V3 with reasoning")
// print(" - Grok 3 (xAI)")
// print(" - And many more!")
//