Tool Use

Quick start example

Export your API key as an environment variable in your terminal.

export INCEPTION_API_KEY="your_api_key_here"

set INCEPTION_API_KEY="your_api_key_here"

curl https://api.inceptionlabs.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $INCEPTION_API_KEY" \
  -d '{
    "model": "mercury-2",
    "messages": [{"role": "user", "content": "What'"'"'s the weather like in San Francisco?"}],
    "tools": [{"type": "function", "function": {"name": "get_weather", "description": "Get the current weather in a given location", "parameters": {"type": "object", "properties": {"location": {"type": "string", "description": "City and state, e.g., '"'"'San Francisco, CA'"'"'"}, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}}, "required": ["location", "unit"]}}}]
  }'

from inceptionai import Inception

client = Inception()  # reads INCEPTION_API_KEY from the environment

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and state, e.g., 'San Francisco, CA'"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"]
                }
            },
            "required": ["location", "unit"]
        }
    }
}]

completion = client.chat.completions.create(
    model="mercury-2",
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
    tools=tools,
)
tool_call = completion.choices[0].message.tool_calls[0].function

print(f"Function called: {tool_call.name}")
print(f"Arguments: {tool_call.arguments}")

import Inception from 'inceptionai';

const client = new Inception(); // reads INCEPTION_API_KEY from the environment

const tools = [
  {
    type: 'function',
    function: {
      name: 'get_weather',
      description: 'Get the current weather in a given location',
      parameters: {
        type: 'object',
        properties: {
          location: { type: 'string', description: "City and state, e.g., 'San Francisco, CA'" },
          unit: { type: 'string', enum: ['celsius', 'fahrenheit'] },
        },
        required: ['location', 'unit'],
      },
    },
  },
];

const completion = await client.chat.completions.create({
  model: 'mercury-2',
  messages: [{ role: 'user', content: "What's the weather like in San Francisco?" }],
  tools,
});
const toolCall = completion.choices[0]?.message.tool_calls?.[0]?.function;

console.log(`Function called: ${toolCall?.name}`);
console.log(`Arguments: ${toolCall?.arguments}`);

Tool calling parameters

tool_choice Use tool_choice to enforce the tool calling behavior that you desire. By default, tool_choice is set to "auto". This means that the model will choose to either emit tool calls or output text. if set to "none", tool calls are prevented. if set to "required", the model is forced to emit a tool call in that turn. Use this to enforce the behavior you desire. Just add tool_choice to the payload to use it. See below for an example:

payload = {
    "model": MODEL,
    "messages": messages,
    "tools": TOOLS,
    "tool_choice": "auto", # <- add this line: "auto" or "required" or "none"
}
body = requests.post(API_URL, headers=HEADERS, json=payload).json()

strict Use strict to force the model to output the correct tool calling schema that you have specified. We recommend setting this field to True for best results. To do this, add "strict": True to your tool definition. See below for an example.

{
    "type": "function",
    "function": {
        "name": "list_directory",
        "description": "List the entries (files and subdirectories) inside a directory.",
        "strict": True, # <- add this line here
        "parameters": {
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "Absolute directory path, e.g. '/repo'.",
                },
            },
            "required": ["path"],
            "additionalProperties": False,
        },
    },
}

Coding agent tool calling demo

See how you can use tool calling with Mercury 2 with the following simple coding agent example. We assume a small codebase of the following structure:

### structure ###
/repo
  ├── main.py
  └── stats.py
#################

### stats.py ###
def compute_average(values):
    """Return the arithmetic mean of a list of numbers."""
    if not values:
        return 0.0
    return sum(values) / len(values)
#################

### main.py ###
from stats import compute_average

print(compute_average([1, 2, 3]))
#################

Define tools

First, define your tools. Here, we define two tools for a read-only coding agent: list_directory and read_file.

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "list_directory",
            "description": "List the entries (files and subdirectories) inside a directory.",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {
                        "type": "string",
                        "description": "Absolute directory path, e.g. '/repo'.",
                    },
                },
                "required": ["path"],
                "additionalProperties": False,
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "Return the full text contents of a file.",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {
                        "type": "string",
                        "description": "Absolute file path, e.g. '/repo/stats.py'.",
                    },
                },
                "required": ["path"],
                "additionalProperties": False,
            },
        },
    },
]

Prompt your model

We prompt the model to search the code base for a specific function and return its definition to the user.

SYSTEM_PROMPT = (
    "You are a coding assistant with access to a small filesystem via two tools: "
    "`list_directory` and `read_file`. Use tools to explore the repo before answering. "
    "When you have enough information, reply in plain text with the answer."
)

USER_PROMPT = (
    "The repo lives at `/repo`. Find the definition of the function "
    "`compute_average` and quote its body back to me."
)

messages = [
    {"role": "system", "content": SYSTEM_PROMPT},
    {"role": "user", "content": USER_PROMPT},
]

Run your agent

# setup
API_URL = "https://api.inceptionlabs.ai/v1/chat/completions"
MODEL = "mercury-2"
HEADERS = {
    "Authorization": f"Bearer {os.environ["INCEPTION_API_KEY"]}",
    "Content-Type": "application/json",
}

# agent loop
for turn in range(3):
    payload = {
        "model": MODEL,
        "messages": messages,
        "tools": TOOLS,
    }
    body = requests.post(API_URL, headers=HEADERS, json=payload).json()
    # 1. parse body for content and tool_calls.
    # 2. execute tools in tool_calls.
    # 3. append model output and tool call results to messages.

Results

When we run the above code, we get the following results: Step 1: Model’s tool call:

{'name': 'list_directory', 'arguments': '{"path": "/repo"}'}

Tool call output:

{"path": "/repo", "entries": ["main.py", "stats.py", "README.md"]}

Step 2: Model’s tool call:

{'name': 'read_file', 'arguments': '{"path": "/repo/stats.py"}'}

Tool call output:

{"path": "/repo/stats.py", "contents": "def compute_average(values):\n    \"\"\"Return the arithmetic mean of a list of numbers.\"\"\"\n    if not values:\n        return 0.0\n    return sum(values) / len(values)\n"}

Step 3: Model’s output:

Here is the definition of `compute_average` from **/repo/stats.py**:

```python
def compute_average(values):
    """Return the arithmetic mean of a list of numbers."""
    if not values:
        return 0.0
    return sum(values) / len(values)
```

See the full demo’s code in this cookbook. Currently, the Inception API only supports sequential tool calling. Parallel tool calling will be supported soon!

Getting Started

API reference

Capabilities

Resources

Support

Quick start example

Tool calling parameters

Coding agent tool calling demo

Define tools

Prompt your model

Run your agent

Results

​Quick start example

​Tool calling parameters

​Coding agent tool calling demo

​Define tools

​Prompt your model

​Run your agent

​Results

Quick start example

Tool calling parameters

Coding agent tool calling demo

Define tools

Prompt your model

Run your agent

Results