Can I use Braintrust as a CLI?

Yes. KosmoKrator exposes a Braintrust CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Braintrust through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Braintrust tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Braintrust credentials stored?

Braintrust credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Braintrust MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

analytics

Braintrust Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Braintrust KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.braintrust.*. Use lua_read_doc("integrations.braintrust") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Braintrust workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.braintrust.list_projects({}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("braintrust"))' --json
kosmo integrations:lua --eval 'print(docs.read("braintrust.list_projects"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua

local braintrust = app.integrations.braintrust
local result = braintrust.list_projects({})

dump(result)

Run the workflow

kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json

Namespace note. integrations:lua exposes app.integrations.braintrust, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.braintrust.default.* or app.integrations.braintrust.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Braintrust, use the narrower mcp:lua command.

MCP Lua command

# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Braintrust

Namespace: braintrust

Braintrust provides LLM evals, observability logs, datasets, prompts, functions, scorers, and AI proxy calls. This integration uses the Braintrust REST API with Authorization: Bearer <api_key> against your configured data plane URL.

Default data plane URLs:

US: https://api.braintrust.dev
EU: https://api-eu.braintrust.dev
Self-hosted: your Braintrust universal API URL

Usage notes

List endpoints accept a query object. Complex query values such as metadata are JSON-encoded before being sent because Braintrust documents metadata filters as JSON strings.
Write endpoints accept a body object that matches the official Braintrust API request schema. This keeps the integration current as Braintrust adds fields without exposing unsupported fake parameters.
Fetch, insert, feedback, eval, function invoke, BTQL, and proxy tools require a non-empty body object.
Returned data is parsed JSON when the API returns JSON. Empty delete responses are normalized to { success = true, status = <http_status> }.

Core tools

braintrust_list_projects, braintrust_create_project, braintrust_get_project, braintrust_update_project, braintrust_delete_project
braintrust_insert_logs, braintrust_fetch_logs, braintrust_feedback_logs
braintrust_list_experiments, braintrust_create_experiment, braintrust_get_experiment, braintrust_update_experiment, braintrust_delete_experiment, braintrust_insert_experiment, braintrust_fetch_experiment, braintrust_feedback_experiment, braintrust_summarize_experiment
braintrust_list_datasets, braintrust_create_dataset, braintrust_get_dataset, braintrust_update_dataset, braintrust_delete_dataset, braintrust_insert_dataset, braintrust_fetch_dataset, braintrust_feedback_dataset, braintrust_summarize_dataset
braintrust_list_prompts, braintrust_create_prompt, braintrust_upsert_prompt, braintrust_get_prompt, braintrust_update_prompt, braintrust_delete_prompt
braintrust_list_functions, braintrust_create_function, braintrust_upsert_function, braintrust_get_function, braintrust_update_function, braintrust_delete_function, braintrust_invoke_function
braintrust_query_btql, braintrust_launch_eval
braintrust_proxy_chat_completions, braintrust_proxy_completions, braintrust_proxy_embeddings, braintrust_proxy_auto
braintrust_list_project_scores, braintrust_list_project_tags, braintrust_list_dataset_snapshots, braintrust_list_groups, braintrust_list_roles, braintrust_list_users, braintrust_list_organizations

Examples

List projects:

local projects = braintrust_list_projects({
  query = { limit = 10 }
})

Filter experiments by nested metadata:

local experiments = braintrust_list_experiments({
  query = {
    project_id = "00000000-0000-0000-0000-000000000000",
    metadata = { env = "test", model = { name = "gpt-5-mini" } }
  }
})

Insert dataset rows:

local result = braintrust_insert_dataset({
  dataset_id = "00000000-0000-0000-0000-000000000000",
  body = {
    events = {
      {
        id = "row-1",
        input = { question = "What is 2+2?" },
        expected = "4"
      }
    }
  }
})

Query BTQL:

local rows = braintrust_query_btql({
  body = {
    query = "SELECT id, input, output FROM project_logs('00000000-0000-0000-0000-000000000000') LIMIT 10",
    fmt = "json"
  }
})

Invoke a function:

local output = braintrust_invoke_function({
  function_id = "00000000-0000-0000-0000-000000000000",
  body = {
    input = { text = "Summarize this safely." },
    environment = "production"
  }
})

Use the proxy for chat completions:

local completion = braintrust_proxy_chat_completions({
  body = {
    model = "openai/gpt-4o-mini",
    messages = {
      { role = "user", content = "Write a concise release note." }
    }
  }
})

Coverage notes

This package intentionally exposes stable REST operations that are useful to agents and safe to shape through JSON bodies. It does not expose raw credential management, service token mutation, AI secret mutation, or ACL mutation tools yet, because those are high-risk administrative surfaces that should get separate least-privilege UX and tests before being enabled for agents.

Raw agent markdown

# Braintrust

Namespace: `braintrust`

Braintrust provides LLM evals, observability logs, datasets, prompts, functions,
scorers, and AI proxy calls. This integration uses the Braintrust REST API with
`Authorization: Bearer <api_key>` against your configured data plane URL.

Default data plane URLs:

- US: `https://api.braintrust.dev`
- EU: `https://api-eu.braintrust.dev`
- Self-hosted: your Braintrust universal API URL

## Usage notes

- List endpoints accept a `query` object. Complex query values such as
  `metadata` are JSON-encoded before being sent because Braintrust documents
  metadata filters as JSON strings.
- Write endpoints accept a `body` object that matches the official Braintrust
  API request schema. This keeps the integration current as Braintrust adds
  fields without exposing unsupported fake parameters.
- Fetch, insert, feedback, eval, function invoke, BTQL, and proxy tools require
  a non-empty `body` object.
- Returned data is parsed JSON when the API returns JSON. Empty delete responses
  are normalized to `{ success = true, status = <http_status> }`.

## Core tools

- `braintrust_list_projects`, `braintrust_create_project`,
  `braintrust_get_project`, `braintrust_update_project`,
  `braintrust_delete_project`
- `braintrust_insert_logs`, `braintrust_fetch_logs`,
  `braintrust_feedback_logs`
- `braintrust_list_experiments`, `braintrust_create_experiment`,
  `braintrust_get_experiment`, `braintrust_update_experiment`,
  `braintrust_delete_experiment`, `braintrust_insert_experiment`,
  `braintrust_fetch_experiment`, `braintrust_feedback_experiment`,
  `braintrust_summarize_experiment`
- `braintrust_list_datasets`, `braintrust_create_dataset`,
  `braintrust_get_dataset`, `braintrust_update_dataset`,
  `braintrust_delete_dataset`, `braintrust_insert_dataset`,
  `braintrust_fetch_dataset`, `braintrust_feedback_dataset`,
  `braintrust_summarize_dataset`
- `braintrust_list_prompts`, `braintrust_create_prompt`,
  `braintrust_upsert_prompt`, `braintrust_get_prompt`,
  `braintrust_update_prompt`, `braintrust_delete_prompt`
- `braintrust_list_functions`, `braintrust_create_function`,
  `braintrust_upsert_function`, `braintrust_get_function`,
  `braintrust_update_function`, `braintrust_delete_function`,
  `braintrust_invoke_function`
- `braintrust_query_btql`, `braintrust_launch_eval`
- `braintrust_proxy_chat_completions`, `braintrust_proxy_completions`,
  `braintrust_proxy_embeddings`, `braintrust_proxy_auto`
- `braintrust_list_project_scores`, `braintrust_list_project_tags`,
  `braintrust_list_dataset_snapshots`, `braintrust_list_groups`,
  `braintrust_list_roles`, `braintrust_list_users`,
  `braintrust_list_organizations`

## Examples

List projects:

```lua
local projects = braintrust_list_projects({
  query = { limit = 10 }
})
```

Filter experiments by nested metadata:

```lua
local experiments = braintrust_list_experiments({
  query = {
    project_id = "00000000-0000-0000-0000-000000000000",
    metadata = { env = "test", model = { name = "gpt-5-mini" } }
  }
})
```

Insert dataset rows:

```lua
local result = braintrust_insert_dataset({
  dataset_id = "00000000-0000-0000-0000-000000000000",
  body = {
    events = {
      {
        id = "row-1",
        input = { question = "What is 2+2?" },
        expected = "4"
      }
    }
  }
})
```

Query BTQL:

```lua
local rows = braintrust_query_btql({
  body = {
    query = "SELECT id, input, output FROM project_logs('00000000-0000-0000-0000-000000000000') LIMIT 10",
    fmt = "json"
  }
})
```

Invoke a function:

```lua
local output = braintrust_invoke_function({
  function_id = "00000000-0000-0000-0000-000000000000",
  body = {
    input = { text = "Summarize this safely." },
    environment = "production"
  }
})
```

Use the proxy for chat completions:

```lua
local completion = braintrust_proxy_chat_completions({
  body = {
    model = "openai/gpt-4o-mini",
    messages = {
      { role = "user", content = "Write a concise release note." }
    }
  }
})
```

## Coverage notes

This package intentionally exposes stable REST operations that are useful to
agents and safe to shape through JSON bodies. It does not expose raw credential
management, service token mutation, AI secret mutation, or ACL mutation tools
yet, because those are high-risk administrative surfaces that should get
separate least-privilege UX and tests before being enabled for agents.

Metadata-derived Lua example

local result = app.integrations.braintrust.list_projects({})
print(result)

Functions

list_projects Read

List Braintrust projects.

Lua path: app.integrations.braintrust.list_projects
Full name: braintrust.braintrust_list_projects

Parameter	Type	Required	Description
No parameters.

create_project Write

Create a Braintrust project.

Lua path: app.integrations.braintrust.create_project
Full name: braintrust.braintrust_create_project

Parameter	Type	Required	Description
No parameters.

get_project Read

Retrieve a Braintrust project by ID.

Lua path: app.integrations.braintrust.get_project
Full name: braintrust.braintrust_get_project

Parameter	Type	Required	Description
No parameters.

update_project Write

Patch a Braintrust project.

Lua path: app.integrations.braintrust.update_project
Full name: braintrust.braintrust_update_project

Parameter	Type	Required	Description
No parameters.

delete_project Write

Delete a Braintrust project.

Lua path: app.integrations.braintrust.delete_project
Full name: braintrust.braintrust_delete_project

Parameter	Type	Required	Description
No parameters.

insert_logs Write

Insert project log events.

Lua path: app.integrations.braintrust.insert_logs
Full name: braintrust.braintrust_insert_logs

Parameter	Type	Required	Description
No parameters.

fetch_logs Read

Fetch project log events.

Lua path: app.integrations.braintrust.fetch_logs
Full name: braintrust.braintrust_fetch_logs

Parameter	Type	Required	Description
No parameters.

feedback_logs Write

Record feedback on project logs.

Lua path: app.integrations.braintrust.feedback_logs
Full name: braintrust.braintrust_feedback_logs

Parameter	Type	Required	Description
No parameters.

list_experiments Read

List Braintrust experiments.

Lua path: app.integrations.braintrust.list_experiments
Full name: braintrust.braintrust_list_experiments

Parameter	Type	Required	Description
No parameters.

create_experiment Write

Create a Braintrust experiment.

Lua path: app.integrations.braintrust.create_experiment
Full name: braintrust.braintrust_create_experiment

Parameter	Type	Required	Description
No parameters.

get_experiment Read

Retrieve a Braintrust experiment.

Lua path: app.integrations.braintrust.get_experiment
Full name: braintrust.braintrust_get_experiment

Parameter	Type	Required	Description
No parameters.

update_experiment Write

Patch a Braintrust experiment.

Lua path: app.integrations.braintrust.update_experiment
Full name: braintrust.braintrust_update_experiment

Parameter	Type	Required	Description
No parameters.

delete_experiment Write

Delete a Braintrust experiment.

Lua path: app.integrations.braintrust.delete_experiment
Full name: braintrust.braintrust_delete_experiment

Parameter	Type	Required	Description
No parameters.

insert_experiment_rows Write

Insert events into an experiment.

Lua path: app.integrations.braintrust.insert_experiment_rows
Full name: braintrust.braintrust_insert_experiment

Parameter	Type	Required	Description
No parameters.

fetch_experiment_rows Read

Fetch experiment events.

Lua path: app.integrations.braintrust.fetch_experiment_rows
Full name: braintrust.braintrust_fetch_experiment

Parameter	Type	Required	Description
No parameters.

feedback_experiment Write

Record feedback on experiment rows.

Lua path: app.integrations.braintrust.feedback_experiment
Full name: braintrust.braintrust_feedback_experiment

Parameter	Type	Required	Description
No parameters.

summarize_experiment Read

Summarize experiment metrics.

Lua path: app.integrations.braintrust.summarize_experiment
Full name: braintrust.braintrust_summarize_experiment

Parameter	Type	Required	Description
No parameters.

list_datasets Read

List Braintrust datasets.

Lua path: app.integrations.braintrust.list_datasets
Full name: braintrust.braintrust_list_datasets

Parameter	Type	Required	Description
No parameters.

create_dataset Write

Create a Braintrust dataset.

Lua path: app.integrations.braintrust.create_dataset
Full name: braintrust.braintrust_create_dataset

Parameter	Type	Required	Description
No parameters.

get_dataset Read

Retrieve a Braintrust dataset.

Lua path: app.integrations.braintrust.get_dataset
Full name: braintrust.braintrust_get_dataset

Parameter	Type	Required	Description
No parameters.

update_dataset Write

Patch a Braintrust dataset.

Lua path: app.integrations.braintrust.update_dataset
Full name: braintrust.braintrust_update_dataset

Parameter	Type	Required	Description
No parameters.

delete_dataset Write

Delete a Braintrust dataset.

Lua path: app.integrations.braintrust.delete_dataset
Full name: braintrust.braintrust_delete_dataset

Parameter	Type	Required	Description
No parameters.

insert_dataset_rows Write

Insert records into a dataset.

Lua path: app.integrations.braintrust.insert_dataset_rows
Full name: braintrust.braintrust_insert_dataset

Parameter	Type	Required	Description
No parameters.

fetch_dataset_rows Read

Fetch dataset records.

Lua path: app.integrations.braintrust.fetch_dataset_rows
Full name: braintrust.braintrust_fetch_dataset

Parameter	Type	Required	Description
No parameters.

feedback_dataset Write

Record feedback on dataset rows.

Lua path: app.integrations.braintrust.feedback_dataset
Full name: braintrust.braintrust_feedback_dataset

Parameter	Type	Required	Description
No parameters.

summarize_dataset Read

Summarize dataset contents.

Lua path: app.integrations.braintrust.summarize_dataset
Full name: braintrust.braintrust_summarize_dataset

Parameter	Type	Required	Description
No parameters.

list_prompts Read

List Braintrust prompts.

Lua path: app.integrations.braintrust.list_prompts
Full name: braintrust.braintrust_list_prompts

Parameter	Type	Required	Description
No parameters.

create_prompt Write

Create a Braintrust prompt.

Lua path: app.integrations.braintrust.create_prompt
Full name: braintrust.braintrust_create_prompt

Parameter	Type	Required	Description
No parameters.

upsert_prompt Write

Create or update a Braintrust prompt.

Lua path: app.integrations.braintrust.upsert_prompt
Full name: braintrust.braintrust_upsert_prompt

Parameter	Type	Required	Description
No parameters.

get_prompt Read

Retrieve a Braintrust prompt.

Lua path: app.integrations.braintrust.get_prompt
Full name: braintrust.braintrust_get_prompt

Parameter	Type	Required	Description
No parameters.

update_prompt Write

Patch a Braintrust prompt.

Lua path: app.integrations.braintrust.update_prompt
Full name: braintrust.braintrust_update_prompt

Parameter	Type	Required	Description
No parameters.

delete_prompt Write

Delete a Braintrust prompt.

Lua path: app.integrations.braintrust.delete_prompt
Full name: braintrust.braintrust_delete_prompt

Parameter	Type	Required	Description
No parameters.

list_functions Read

List Braintrust functions, tools, and scorers.

Lua path: app.integrations.braintrust.list_functions
Full name: braintrust.braintrust_list_functions

Parameter	Type	Required	Description
No parameters.

create_function Write

Create a Braintrust function.

Lua path: app.integrations.braintrust.create_function
Full name: braintrust.braintrust_create_function

Parameter	Type	Required	Description
No parameters.

upsert_function Write

Create or update a Braintrust function.

Lua path: app.integrations.braintrust.upsert_function
Full name: braintrust.braintrust_upsert_function

Parameter	Type	Required	Description
No parameters.

get_function Read

Retrieve a Braintrust function.

Lua path: app.integrations.braintrust.get_function
Full name: braintrust.braintrust_get_function

Parameter	Type	Required	Description
No parameters.

update_function Write

Patch a Braintrust function.

Lua path: app.integrations.braintrust.update_function
Full name: braintrust.braintrust_update_function

Parameter	Type	Required	Description
No parameters.

delete_function Write

Delete a Braintrust function.

Lua path: app.integrations.braintrust.delete_function
Full name: braintrust.braintrust_delete_function

Parameter	Type	Required	Description
No parameters.

invoke_function Write

Invoke a Braintrust prompt, tool, or scorer.

Lua path: app.integrations.braintrust.invoke_function
Full name: braintrust.braintrust_invoke_function

Parameter	Type	Required	Description
No parameters.

query_btql Read

Query logs, experiments, and datasets with Braintrust SQL.

Lua path: app.integrations.braintrust.query_btql
Full name: braintrust.braintrust_query_btql

Parameter	Type	Required	Description
No parameters.

launch_eval Write

Launch a Braintrust eval run.

Lua path: app.integrations.braintrust.launch_eval
Full name: braintrust.braintrust_launch_eval

Parameter	Type	Required	Description
No parameters.

proxy_chat_completions Write

Call Braintrust AI proxy chat completions.

Lua path: app.integrations.braintrust.proxy_chat_completions
Full name: braintrust.braintrust_proxy_chat_completions

Parameter	Type	Required	Description
No parameters.

proxy_completions Write

Call Braintrust AI proxy completions.

Lua path: app.integrations.braintrust.proxy_completions
Full name: braintrust.braintrust_proxy_completions

Parameter	Type	Required	Description
No parameters.

proxy_embeddings Write

Call Braintrust AI proxy embeddings.

Lua path: app.integrations.braintrust.proxy_embeddings
Full name: braintrust.braintrust_proxy_embeddings

Parameter	Type	Required	Description
No parameters.

proxy_auto Write

Call the Braintrust proxy auto endpoint.

Lua path: app.integrations.braintrust.proxy_auto
Full name: braintrust.braintrust_proxy_auto

Parameter	Type	Required	Description
No parameters.

list_project_scores Read

List project score definitions.

Lua path: app.integrations.braintrust.list_project_scores
Full name: braintrust.braintrust_list_project_scores

Parameter	Type	Required	Description
No parameters.

list_project_tags Read

List project tags.

Lua path: app.integrations.braintrust.list_project_tags
Full name: braintrust.braintrust_list_project_tags

Parameter	Type	Required	Description
No parameters.

list_dataset_snapshots Read

List dataset snapshots.

Lua path: app.integrations.braintrust.list_dataset_snapshots
Full name: braintrust.braintrust_list_dataset_snapshots

Parameter	Type	Required	Description
No parameters.

list_groups Read

List Braintrust groups.

Lua path: app.integrations.braintrust.list_groups
Full name: braintrust.braintrust_list_groups

Parameter	Type	Required	Description
No parameters.

list_roles Read

List Braintrust roles.

Lua path: app.integrations.braintrust.list_roles
Full name: braintrust.braintrust_list_roles

Parameter	Type	Required	Description
No parameters.

list_users Read

List Braintrust users.

Lua path: app.integrations.braintrust.list_users
Full name: braintrust.braintrust_list_users

Parameter	Type	Required	Description
No parameters.

list_organizations Read

List Braintrust organizations.

Lua path: app.integrations.braintrust.list_organizations
Full name: braintrust.braintrust_list_organizations

Parameter	Type	Required	Description
No parameters.