Skip to main content
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