Struct OpenApiToolset 

pub struct OpenApiToolset { /* private fields */ }

A set of tools generated from an OpenAPI specification.

Each operation in the spec becomes a tool that can be registered with a rig agent. The toolset is designed to be parsed once and reused across requests.

Implementations

impl OpenApiToolset

pub fn from_file(path: impl AsRef<Path>) -> Result<Self>

Parse an OpenAPI spec from a YAML or JSON file.

Examples found in repository

examples/jsonplaceholder.rs (line 9)

async fn main() -> anyhow::Result<()> {
    let openai = rig::providers::openai::Client::from_env();

    let toolset = OpenApiToolset::from_file("examples/openapi.yaml")?;
    println!("Loaded {} tools from OpenAPI spec", toolset.len());

    let agent = openai
        .agent("gpt-4o")
        .preamble("You have access to API tools. Use them when asked.")
        .tools(toolset.into_tools())
        .build();

    let response: String = agent
        .prompt("Use the API tool to get user 1 and summarize the result.")
        .await?;

    println!("{response}");

    Ok(())
}

pub fn from_spec_str(spec_str: &str) -> Result<Self>

Parse an OpenAPI spec from a YAML or JSON string.

pub fn builder(spec_str: &str) -> OpenApiToolsetBuilder

Start building a toolset from a YAML or JSON string with configuration options.

pub fn builder_from_file( path: impl AsRef<Path>, ) -> Result<OpenApiToolsetBuilder>

Start building a toolset from a file with configuration options.

Examples found in repository

examples/petstore.rs (line 12)

async fn main() -> anyhow::Result<()> {
    let openai = rig::providers::openai::Client::from_env();

    // Parse once at startup — reuse across requests
    let toolset = OpenApiToolset::builder_from_file("examples/petstore.json")?
        .base_url("https://petstore3.swagger.io/api/v3")
        .build()?;

    println!("Loaded {} tools from Petstore spec\n", toolset.len());

    // Simulate a per-request context (e.g. from a logged-in user session)
    let visible_ctx = HashMap::from([
        ("username".to_string(), "user1".to_string()),
        ("preferred_status".to_string(), "available".to_string()),
    ]);
    let context_preamble = OpenApiToolset::context_preamble(&visible_ctx);

    let preamble = format!(
        "You have access to the Swagger Petstore API. \
         Use the available tools to answer questions about the pet store.\n\n\
         {context_preamble}"
    );

    // Create agent with per-request tools (cheap clone)
    let agent = openai
        .agent("gpt-4o")
        .preamble(&preamble)
        .tools(toolset.tools_with_context(&HashMap::new()))
        .build();

    let prompts = [
        "What pets are currently available in the store? Show me the first 3.",
        "How many dogs are in the store?",
        "Look up my user profile and summarize it.",
    ];

    for prompt in prompts {
        println!(">>> {prompt}");
        let response: String = agent.prompt(prompt).await?;
        println!("{response}\n");
    }

    Ok(())
}

examples/context.rs (line 16)

async fn main() -> anyhow::Result<()> {
    let openai = rig::providers::openai::Client::from_env();

    // ---------------------------------------------------------------
    // 1. Visible context — LLM sees the values and uses them in calls
    // ---------------------------------------------------------------
    println!("=== Visible context ===\n");

    let toolset = OpenApiToolset::builder_from_file("examples/petstore.json")?
        .base_url("https://petstore3.swagger.io/api/v3")
        .build()?;

    println!("Loaded {} tools from Petstore spec\n", toolset.len());

    // The LLM sees these values in its preamble and uses them
    // when calling tools. For example, it will pass `username` to getUserByName.
    let visible_ctx = HashMap::from([
        ("username".to_string(), "user1".to_string()),
        ("preferred_status".to_string(), "available".to_string()),
    ]);
    let context_preamble = OpenApiToolset::context_preamble(&visible_ctx);

    let preamble = format!(
        "You have access to the Swagger Petstore API.\n\n\
         {context_preamble}\n\n\
         When I refer to \"my\" profile or data, use the username from the context above."
    );

    let agent = openai
        .agent("gpt-4o")
        .preamble(&preamble)
        .tools(toolset.tools_with_context(&HashMap::new()))
        .build();

    // The LLM picks up username=user1 from the preamble
    // and calls getUserByName with username "user1".
    println!(">>> Look up my user profile and summarize it.");
    let response: String = agent
        .prompt("Look up my user profile and summarize it.")
        .await?;
    println!("{response}\n");

    // The LLM picks up preferred_status=available from the preamble
    // and calls findPetsByStatus with status "available".
    println!(">>> Find pets matching my preferred status.");
    let response: String = agent
        .prompt("Find pets matching my preferred status.")
        .await?;
    println!("{response}\n");

    // ---------------------------------------------------------------
    // 2. Hidden context — auto-injected, LLM never sees the values
    // ---------------------------------------------------------------
    println!("=== Hidden context ===\n");

    // Hidden context is useful for secrets, user IDs, or any parameter
    // the LLM should NOT decide — it's injected automatically at execution
    // time and removed from the tool schema so the LLM can't see or override it.

    // Static hidden context set at build time (e.g. API key for the upstream service)
    let toolset = OpenApiToolset::builder_from_file("examples/petstore.json")?
        .base_url("https://petstore3.swagger.io/api/v3")
        .hidden_context("api_key", "special-key")
        .build()?;

    // Per-request hidden context (e.g. current user from session).
    // The LLM won't see `username` in the tool schema — it's filled in
    // automatically, so it can't hallucinate a different user.
    let per_request_ctx = HashMap::from([("username".to_string(), "user1".to_string())]);

    let agent = openai
        .agent("gpt-4o")
        .preamble(
            "You have access to the Swagger Petstore API. \
             Use the available tools to answer questions about the pet store.",
        )
        .tools(toolset.tools_with_context(&per_request_ctx))
        .build();

    // The LLM calls getUserByName without providing `username` —
    // it's not in the schema. The library injects username=user1 automatically.
    println!(">>> Get my profile.");
    let response: String = agent.prompt("Get my profile.").await?;
    println!("{response}\n");

    Ok(())
}

pub fn len(&self) -> usize

Return the number of tools parsed from the spec.

Examples found in repository

examples/jsonplaceholder.rs (line 10)

async fn main() -> anyhow::Result<()> {
    let openai = rig::providers::openai::Client::from_env();

    let toolset = OpenApiToolset::from_file("examples/openapi.yaml")?;
    println!("Loaded {} tools from OpenAPI spec", toolset.len());

    let agent = openai
        .agent("gpt-4o")
        .preamble("You have access to API tools. Use them when asked.")
        .tools(toolset.into_tools())
        .build();

    let response: String = agent
        .prompt("Use the API tool to get user 1 and summarize the result.")
        .await?;

    println!("{response}");

    Ok(())
}

examples/petstore.rs (line 16)

async fn main() -> anyhow::Result<()> {
    let openai = rig::providers::openai::Client::from_env();

    // Parse once at startup — reuse across requests
    let toolset = OpenApiToolset::builder_from_file("examples/petstore.json")?
        .base_url("https://petstore3.swagger.io/api/v3")
        .build()?;

    println!("Loaded {} tools from Petstore spec\n", toolset.len());

    // Simulate a per-request context (e.g. from a logged-in user session)
    let visible_ctx = HashMap::from([
        ("username".to_string(), "user1".to_string()),
        ("preferred_status".to_string(), "available".to_string()),
    ]);
    let context_preamble = OpenApiToolset::context_preamble(&visible_ctx);

    let preamble = format!(
        "You have access to the Swagger Petstore API. \
         Use the available tools to answer questions about the pet store.\n\n\
         {context_preamble}"
    );

    // Create agent with per-request tools (cheap clone)
    let agent = openai
        .agent("gpt-4o")
        .preamble(&preamble)
        .tools(toolset.tools_with_context(&HashMap::new()))
        .build();

    let prompts = [
        "What pets are currently available in the store? Show me the first 3.",
        "How many dogs are in the store?",
        "Look up my user profile and summarize it.",
    ];

    for prompt in prompts {
        println!(">>> {prompt}");
        let response: String = agent.prompt(prompt).await?;
        println!("{response}\n");
    }

    Ok(())
}

examples/context.rs (line 20)

async fn main() -> anyhow::Result<()> {
    let openai = rig::providers::openai::Client::from_env();

    // ---------------------------------------------------------------
    // 1. Visible context — LLM sees the values and uses them in calls
    // ---------------------------------------------------------------
    println!("=== Visible context ===\n");

    let toolset = OpenApiToolset::builder_from_file("examples/petstore.json")?
        .base_url("https://petstore3.swagger.io/api/v3")
        .build()?;

    println!("Loaded {} tools from Petstore spec\n", toolset.len());

    // The LLM sees these values in its preamble and uses them
    // when calling tools. For example, it will pass `username` to getUserByName.
    let visible_ctx = HashMap::from([
        ("username".to_string(), "user1".to_string()),
        ("preferred_status".to_string(), "available".to_string()),
    ]);
    let context_preamble = OpenApiToolset::context_preamble(&visible_ctx);

    let preamble = format!(
        "You have access to the Swagger Petstore API.\n\n\
         {context_preamble}\n\n\
         When I refer to \"my\" profile or data, use the username from the context above."
    );

    let agent = openai
        .agent("gpt-4o")
        .preamble(&preamble)
        .tools(toolset.tools_with_context(&HashMap::new()))
        .build();

    // The LLM picks up username=user1 from the preamble
    // and calls getUserByName with username "user1".
    println!(">>> Look up my user profile and summarize it.");
    let response: String = agent
        .prompt("Look up my user profile and summarize it.")
        .await?;
    println!("{response}\n");

    // The LLM picks up preferred_status=available from the preamble
    // and calls findPetsByStatus with status "available".
    println!(">>> Find pets matching my preferred status.");
    let response: String = agent
        .prompt("Find pets matching my preferred status.")
        .await?;
    println!("{response}\n");

    // ---------------------------------------------------------------
    // 2. Hidden context — auto-injected, LLM never sees the values
    // ---------------------------------------------------------------
    println!("=== Hidden context ===\n");

    // Hidden context is useful for secrets, user IDs, or any parameter
    // the LLM should NOT decide — it's injected automatically at execution
    // time and removed from the tool schema so the LLM can't see or override it.

    // Static hidden context set at build time (e.g. API key for the upstream service)
    let toolset = OpenApiToolset::builder_from_file("examples/petstore.json")?
        .base_url("https://petstore3.swagger.io/api/v3")
        .hidden_context("api_key", "special-key")
        .build()?;

    // Per-request hidden context (e.g. current user from session).
    // The LLM won't see `username` in the tool schema — it's filled in
    // automatically, so it can't hallucinate a different user.
    let per_request_ctx = HashMap::from([("username".to_string(), "user1".to_string())]);

    let agent = openai
        .agent("gpt-4o")
        .preamble(
            "You have access to the Swagger Petstore API. \
             Use the available tools to answer questions about the pet store.",
        )
        .tools(toolset.tools_with_context(&per_request_ctx))
        .build();

    // The LLM calls getUserByName without providing `username` —
    // it's not in the schema. The library injects username=user1 automatically.
    println!(">>> Get my profile.");
    let response: String = agent.prompt("Get my profile.").await?;
    println!("{response}\n");

    Ok(())
}

pub fn is_empty(&self) -> bool

Returns true if no operations were found in the spec.

pub fn into_tools(self) -> Vec<Box<dyn ToolDyn>>

Consume the toolset and return tools for use with rig’s AgentBuilder::tools().

Examples found in repository

examples/jsonplaceholder.rs (line 15)

async fn main() -> anyhow::Result<()> {
    let openai = rig::providers::openai::Client::from_env();

    let toolset = OpenApiToolset::from_file("examples/openapi.yaml")?;
    println!("Loaded {} tools from OpenAPI spec", toolset.len());

    let agent = openai
        .agent("gpt-4o")
        .preamble("You have access to API tools. Use them when asked.")
        .tools(toolset.into_tools())
        .build();

    let response: String = agent
        .prompt("Use the API tool to get user 1 and summarize the result.")
        .await?;

    println!("{response}");

    Ok(())
}

pub fn tools_with_context( &self, context: &HashMap<String, String>, ) -> Vec<Box<dyn ToolDyn>>

Clone the tools with per-request context injected as hidden parameters. The LLM will not see these parameters in tool schemas, but they will be auto-injected into every tool call at execution time.

This is the primary way to add per-request state (user ID, session info, etc.) while reusing the parsed toolset across requests.

Examples found in repository

examples/petstore.rs (line 35)

async fn main() -> anyhow::Result<()> {
    let openai = rig::providers::openai::Client::from_env();

    // Parse once at startup — reuse across requests
    let toolset = OpenApiToolset::builder_from_file("examples/petstore.json")?
        .base_url("https://petstore3.swagger.io/api/v3")
        .build()?;

    println!("Loaded {} tools from Petstore spec\n", toolset.len());

    // Simulate a per-request context (e.g. from a logged-in user session)
    let visible_ctx = HashMap::from([
        ("username".to_string(), "user1".to_string()),
        ("preferred_status".to_string(), "available".to_string()),
    ]);
    let context_preamble = OpenApiToolset::context_preamble(&visible_ctx);

    let preamble = format!(
        "You have access to the Swagger Petstore API. \
         Use the available tools to answer questions about the pet store.\n\n\
         {context_preamble}"
    );

    // Create agent with per-request tools (cheap clone)
    let agent = openai
        .agent("gpt-4o")
        .preamble(&preamble)
        .tools(toolset.tools_with_context(&HashMap::new()))
        .build();

    let prompts = [
        "What pets are currently available in the store? Show me the first 3.",
        "How many dogs are in the store?",
        "Look up my user profile and summarize it.",
    ];

    for prompt in prompts {
        println!(">>> {prompt}");
        let response: String = agent.prompt(prompt).await?;
        println!("{response}\n");
    }

    Ok(())
}

examples/context.rs (line 39)

async fn main() -> anyhow::Result<()> {
    let openai = rig::providers::openai::Client::from_env();

    // ---------------------------------------------------------------
    // 1. Visible context — LLM sees the values and uses them in calls
    // ---------------------------------------------------------------
    println!("=== Visible context ===\n");

    let toolset = OpenApiToolset::builder_from_file("examples/petstore.json")?
        .base_url("https://petstore3.swagger.io/api/v3")
        .build()?;

    println!("Loaded {} tools from Petstore spec\n", toolset.len());

    // The LLM sees these values in its preamble and uses them
    // when calling tools. For example, it will pass `username` to getUserByName.
    let visible_ctx = HashMap::from([
        ("username".to_string(), "user1".to_string()),
        ("preferred_status".to_string(), "available".to_string()),
    ]);
    let context_preamble = OpenApiToolset::context_preamble(&visible_ctx);

    let preamble = format!(
        "You have access to the Swagger Petstore API.\n\n\
         {context_preamble}\n\n\
         When I refer to \"my\" profile or data, use the username from the context above."
    );

    let agent = openai
        .agent("gpt-4o")
        .preamble(&preamble)
        .tools(toolset.tools_with_context(&HashMap::new()))
        .build();

    // The LLM picks up username=user1 from the preamble
    // and calls getUserByName with username "user1".
    println!(">>> Look up my user profile and summarize it.");
    let response: String = agent
        .prompt("Look up my user profile and summarize it.")
        .await?;
    println!("{response}\n");

    // The LLM picks up preferred_status=available from the preamble
    // and calls findPetsByStatus with status "available".
    println!(">>> Find pets matching my preferred status.");
    let response: String = agent
        .prompt("Find pets matching my preferred status.")
        .await?;
    println!("{response}\n");

    // ---------------------------------------------------------------
    // 2. Hidden context — auto-injected, LLM never sees the values
    // ---------------------------------------------------------------
    println!("=== Hidden context ===\n");

    // Hidden context is useful for secrets, user IDs, or any parameter
    // the LLM should NOT decide — it's injected automatically at execution
    // time and removed from the tool schema so the LLM can't see or override it.

    // Static hidden context set at build time (e.g. API key for the upstream service)
    let toolset = OpenApiToolset::builder_from_file("examples/petstore.json")?
        .base_url("https://petstore3.swagger.io/api/v3")
        .hidden_context("api_key", "special-key")
        .build()?;

    // Per-request hidden context (e.g. current user from session).
    // The LLM won't see `username` in the tool schema — it's filled in
    // automatically, so it can't hallucinate a different user.
    let per_request_ctx = HashMap::from([("username".to_string(), "user1".to_string())]);

    let agent = openai
        .agent("gpt-4o")
        .preamble(
            "You have access to the Swagger Petstore API. \
             Use the available tools to answer questions about the pet store.",
        )
        .tools(toolset.tools_with_context(&per_request_ctx))
        .build();

    // The LLM calls getUserByName without providing `username` —
    // it's not in the schema. The library injects username=user1 automatically.
    println!(">>> Get my profile.");
    let response: String = agent.prompt("Get my profile.").await?;
    println!("{response}\n");

    Ok(())
}

pub fn context_preamble(context: &HashMap<String, String>) -> String

Generate a preamble snippet describing the visible context for the LLM. Include this in your agent’s .preamble() so the LLM knows about available context values it can use when calling tools.

Examples found in repository

examples/petstore.rs (line 23)

async fn main() -> anyhow::Result<()> {
    let openai = rig::providers::openai::Client::from_env();

    // Parse once at startup — reuse across requests
    let toolset = OpenApiToolset::builder_from_file("examples/petstore.json")?
        .base_url("https://petstore3.swagger.io/api/v3")
        .build()?;

    println!("Loaded {} tools from Petstore spec\n", toolset.len());

    // Simulate a per-request context (e.g. from a logged-in user session)
    let visible_ctx = HashMap::from([
        ("username".to_string(), "user1".to_string()),
        ("preferred_status".to_string(), "available".to_string()),
    ]);
    let context_preamble = OpenApiToolset::context_preamble(&visible_ctx);

    let preamble = format!(
        "You have access to the Swagger Petstore API. \
         Use the available tools to answer questions about the pet store.\n\n\
         {context_preamble}"
    );

    // Create agent with per-request tools (cheap clone)
    let agent = openai
        .agent("gpt-4o")
        .preamble(&preamble)
        .tools(toolset.tools_with_context(&HashMap::new()))
        .build();

    let prompts = [
        "What pets are currently available in the store? Show me the first 3.",
        "How many dogs are in the store?",
        "Look up my user profile and summarize it.",
    ];

    for prompt in prompts {
        println!(">>> {prompt}");
        let response: String = agent.prompt(prompt).await?;
        println!("{response}\n");
    }

    Ok(())
}

examples/context.rs (line 28)

async fn main() -> anyhow::Result<()> {
    let openai = rig::providers::openai::Client::from_env();

    // ---------------------------------------------------------------
    // 1. Visible context — LLM sees the values and uses them in calls
    // ---------------------------------------------------------------
    println!("=== Visible context ===\n");

    let toolset = OpenApiToolset::builder_from_file("examples/petstore.json")?
        .base_url("https://petstore3.swagger.io/api/v3")
        .build()?;

    println!("Loaded {} tools from Petstore spec\n", toolset.len());

    // The LLM sees these values in its preamble and uses them
    // when calling tools. For example, it will pass `username` to getUserByName.
    let visible_ctx = HashMap::from([
        ("username".to_string(), "user1".to_string()),
        ("preferred_status".to_string(), "available".to_string()),
    ]);
    let context_preamble = OpenApiToolset::context_preamble(&visible_ctx);

    let preamble = format!(
        "You have access to the Swagger Petstore API.\n\n\
         {context_preamble}\n\n\
         When I refer to \"my\" profile or data, use the username from the context above."
    );

    let agent = openai
        .agent("gpt-4o")
        .preamble(&preamble)
        .tools(toolset.tools_with_context(&HashMap::new()))
        .build();

    // The LLM picks up username=user1 from the preamble
    // and calls getUserByName with username "user1".
    println!(">>> Look up my user profile and summarize it.");
    let response: String = agent
        .prompt("Look up my user profile and summarize it.")
        .await?;
    println!("{response}\n");

    // The LLM picks up preferred_status=available from the preamble
    // and calls findPetsByStatus with status "available".
    println!(">>> Find pets matching my preferred status.");
    let response: String = agent
        .prompt("Find pets matching my preferred status.")
        .await?;
    println!("{response}\n");

    // ---------------------------------------------------------------
    // 2. Hidden context — auto-injected, LLM never sees the values
    // ---------------------------------------------------------------
    println!("=== Hidden context ===\n");

    // Hidden context is useful for secrets, user IDs, or any parameter
    // the LLM should NOT decide — it's injected automatically at execution
    // time and removed from the tool schema so the LLM can't see or override it.

    // Static hidden context set at build time (e.g. API key for the upstream service)
    let toolset = OpenApiToolset::builder_from_file("examples/petstore.json")?
        .base_url("https://petstore3.swagger.io/api/v3")
        .hidden_context("api_key", "special-key")
        .build()?;

    // Per-request hidden context (e.g. current user from session).
    // The LLM won't see `username` in the tool schema — it's filled in
    // automatically, so it can't hallucinate a different user.
    let per_request_ctx = HashMap::from([("username".to_string(), "user1".to_string())]);

    let agent = openai
        .agent("gpt-4o")
        .preamble(
            "You have access to the Swagger Petstore API. \
             Use the available tools to answer questions about the pet store.",
        )
        .tools(toolset.tools_with_context(&per_request_ctx))
        .build();

    // The LLM calls getUserByName without providing `username` —
    // it's not in the schema. The library injects username=user1 automatically.
    println!(">>> Get my profile.");
    let response: String = agent.prompt("Get my profile.").await?;
    println!("{response}\n");

    Ok(())
}