Get AI Tool Schema - Gentility AI Documentation

Get AI tool schema

curl --request GET \
  --url https://api.gentility.ai/api/profile/{profile_id}/room/{room_id}/tools \
  --header 'Authorization: Bearer <token>'

{
  "profile_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "room_id": "<string>",
  "instance_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "instance_status": "<string>",
  "tools": [
    {
      "name": "<string>",
      "description": "<string>",
      "parameters": {}
    }
  ]
}

GET

api

profile

{profile_id}

room

{room_id}

tools

Get AI tool schema

curl --request GET \
  --url https://api.gentility.ai/api/profile/{profile_id}/room/{room_id}/tools \
  --header 'Authorization: Bearer <token>'

{
  "profile_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "room_id": "<string>",
  "instance_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "instance_status": "<string>",
  "tools": [
    {
      "name": "<string>",
      "description": "<string>",
      "parameters": {}
    }
  ]
}

Returns AI tool schema definitions for the VM environment, including available tools and environment capabilities. This endpoint is designed to provide AI agents with the exact tool schemas they need to interact with the development environment.

Use Cases

AI Agent Integration: Provide tool schemas directly to AI agents for code execution
Dynamic Capability Discovery: Determine what tools and packages are available in a specific environment
Environment Introspection: Understand the capabilities and configuration of a VM instance
Tool Configuration: Get structured information about available development tools

Response Structure

The response includes comprehensive information about the instance and available tools:

{
  "profile_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "room_id": "ai-session-123",
  "instance_id": "550e8400-e29b-41d4-a716-446655440000",
  "instance_status": "ready",
  "tools": [
    {
      "name": "execute",
      "description": "Execute a command in the VM shell environment. Returns output, exit code, and tracks file changes.",
      "parameters": {
        "type": "object",
        "required": ["command"],
        "properties": {
          "command": {
            "type": "string",
            "description": "Shell command to execute in the VM environment"
          }
        },
        "additionalProperties": false
      }
    },
    {
      "name": "read_file", 
      "description": "Read the contents of a file from the VM filesystem",
      "parameters": {
        "type": "object",
        "required": ["file_path"],
        "properties": {
          "file_path": {
            "type": "string",
            "description": "Path to the file to read (absolute or relative to home directory)"
          }
        },
        "additionalProperties": false
      }
    }
  ]
}

Tool Schema Examples

Python Data Science Environment

For a profile configured with Python, pandas, matplotlib, and Jupyter:

{
  "tools": [
    {
      "name": "execute",
      "description": "Execute Python code, shell commands, or data analysis scripts. Environment includes pandas, matplotlib, scikit-learn, and Jupyter.",
      "parameters": {
        "type": "object", 
        "required": ["command"],
        "properties": {
          "command": {
            "type": "string",
            "description": "Command to execute (python scripts, pip install, data processing, etc.)",
            "examples": [
              "python -c 'import pandas as pd; df = pd.read_csv(\"data.csv\"); print(df.head())'",
              "pip install requests numpy",
              "jupyter notebook --generate-config"
            ]
          }
        }
      }
    }
  ]
}

Node.js Development Environment

For a Node.js profile with npm, Express, and development tools:

{
  "tools": [
    {
      "name": "execute",
      "description": "Execute Node.js code, npm commands, or JavaScript applications. Environment includes Node.js 18+, npm, Express, and common development packages.",
      "parameters": {
        "type": "object",
        "required": ["command"], 
        "properties": {
          "command": {
            "type": "string",
            "description": "Command to execute (node scripts, npm operations, package builds, etc.)",
            "examples": [
              "node -e 'console.log(process.version)'",
              "npm init -y && npm install express",
              "npm run build && npm test"
            ]
          }
        }
      }
    }
  ]
}

Dynamic Schema Generation

The tool schemas are dynamically generated based on:

Profile Configuration: Base packages and language runtime
Installed Packages: Detected packages and their versions
Environment Capabilities: Available tools and utilities
Usage Examples: Context-aware examples based on the environment

Integration Patterns

OpenAI Function Calling

The schemas are compatible with OpenAI’s function calling format:

import openai

# Get tool schema from Gentility API
response = requests.get(f"https://api.gentility.ai/api/profile/{profile_id}/room/{room_id}/tools")
tools = response.json()["tools"]

# Use with OpenAI
client = openai.OpenAI()
completion = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Analyze this data file"}],
    tools=[{"type": "function", "function": tool} for tool in tools]
)

Anthropic Claude

The schemas work with Claude’s tool use:

import anthropic

# Get tools and format for Claude
response = requests.get(f"https://api.gentility.ai/api/profile/{profile_id}/room/{room_id}/tools") 
tools = response.json()["tools"]

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-3-sonnet-20240229",
    max_tokens=1000,
    tools=tools,
    messages=[{"role": "user", "content": "Help me process this dataset"}]
)

Error Responses

Instance Not Ready

{
  "error": "instance_not_ready",
  "message": "Instance is still provisioning, current status: vm_started"
}

Instance Not Found

{
  "error": "instance_not_found",
  "message": "No instance found for profile 6ba7b810-9dad-11d1-80b4-00c04fd430c8 and room ai-session-123"
}

Best Practices

Schema Caching: Tool schemas are relatively stable - cache them to reduce API calls
Environment Verification: Check the instance_status to ensure the instance is ready
Tool Selection: Use appropriate tools based on the available environment capabilities
Error Handling: Always verify the instance exists and is ready before using tool schemas
Profile Matching: Different profiles will have different tool capabilities - choose the right profile for your use case

Authorizations

Authorization

string

header

required

API key authentication using Bearer token format: 'Bearer rk_live_'

Path Parameters

profile_id

string<uuid>

required

UUID of the profile

room_id

string

required

Room identifier

Response

200 - application/json

Tool schema retrieved successfully

profile_id

string<uuid>

required

room_id

string

required

instance_id

string<uuid>

required

instance_status

string

required

Current instance status

tools

object[]

required

Available AI tools for this environment

Show child attributes

Read File from VM Get Profile Schema

Documentation Index

​Use Cases

​Response Structure

​Tool Schema Examples

​Python Data Science Environment

​Node.js Development Environment

​Dynamic Schema Generation

​Integration Patterns

​OpenAI Function Calling

​Anthropic Claude

​Error Responses

​Instance Not Ready

​Instance Not Found

​Best Practices

Authorizations

Path Parameters

Response

Use Cases

Response Structure

Tool Schema Examples

Python Data Science Environment

Node.js Development Environment

Dynamic Schema Generation

Integration Patterns

OpenAI Function Calling

Anthropic Claude

Error Responses

Instance Not Ready

Instance Not Found

Best Practices