Hugging Face

Configuration for the Hugging Face model provider.

The huggingface sub-block configures the Hugging Face provider and its router for chat completion models. Model names use the identifiers accepted by Hugging Face, such as google/gemma-2-2b-it or meta-llama/Meta-Llama-3.1-8B-Instruct.

Fields

Field	Type	Required	runtime()	Description
`models`	list	no	no	Allowlist of Hugging Face model identifiers. Each entry is a plain string or a config object with `name` and `params`. When omitted, no allowlist is enforced.
`config`	block	no		Connection configuration.
`config.api_key`	string	no	yes	Hugging Face API token. Wrap in `secret(runtime(...))` to keep it out of build artifacts.
`config.base_url`	string	no	yes	Hugging Face router or compatible API base URL.
`params`	block	no		Provider-level inference parameter defaults. Applied to every request unless overridden at the model level.

The config block is optional. When omitted, the client reads credentials from the HUGGINGFACE_API_KEY environment variable and uses the default Hugging Face router endpoint.

params

The params block sets inference parameter defaults for all models under this provider. All fields are optional and support runtime().

Field	Type	runtime()	Description
`max_tokens`	integer	yes	Maximum number of tokens to generate.
`temperature`	float	yes	Sampling temperature.
`top_p`	float	yes	Nucleus sampling probability.
`top_k`	integer	yes	Top-K sampling limit.
`stop_sequences`	list of strings	yes	Sequences that stop generation.
`frequency_penalty`	float	yes	Penalty for token frequency.
`presence_penalty`	float	yes	Penalty for token presence.
`seed`	integer	yes	Seed for deterministic sampling.
`provider_params`	object	yes	Provider-specific parameters passed directly to the API.

Example

agent.acl

providers {
  huggingface {
    models = [
      "google/gemma-2-2b-it",
      {
        name = "meta-llama/Meta-Llama-3.1-8B-Instruct"
        params {
          max_tokens  = 8192
          temperature = 0.7
        }
      }
    ]

    config {
      api_key  = secret(runtime("HUGGINGFACE_API_KEY"))
      base_url = runtime("HUGGINGFACE_BASE_URL", "https://router.huggingface.co")
    }

    params {
      max_tokens  = 4096
      temperature = 0.5
    }
  }
}

agent "assistant" {
  graph {
    type = "react"
  }

  model {
    provider = "huggingface"
    name     = "google/gemma-2-2b-it"
  }
}

tip

Always wrap API tokens in secret(runtime(...)). This prevents the token from appearing in build artifacts and the output of agentc inspect.

Hugging Face

Configuration for the Hugging Face model provider.

Fields

Field	Type	Required	runtime()	Description
`models`	list	no	no	Allowlist of Hugging Face model identifiers. Each entry is a plain string or a config object with `name` and `params`. When omitted, no allowlist is enforced.
`config`	block	no		Connection configuration.
`config.api_key`	string	no	yes	Hugging Face API token. Wrap in `secret(runtime(...))` to keep it out of build artifacts.
`config.base_url`	string	no	yes	Hugging Face router or compatible API base URL.
`params`	block	no		Provider-level inference parameter defaults. Applied to every request unless overridden at the model level.

The config block is optional. When omitted, the client reads credentials from the HUGGINGFACE_API_KEY environment variable and uses the default Hugging Face router endpoint.

params

The params block sets inference parameter defaults for all models under this provider. All fields are optional and support runtime().

Field	Type	runtime()	Description
`max_tokens`	integer	yes	Maximum number of tokens to generate.
`temperature`	float	yes	Sampling temperature.
`top_p`	float	yes	Nucleus sampling probability.
`top_k`	integer	yes	Top-K sampling limit.
`stop_sequences`	list of strings	yes	Sequences that stop generation.
`frequency_penalty`	float	yes	Penalty for token frequency.
`presence_penalty`	float	yes	Penalty for token presence.
`seed`	integer	yes	Seed for deterministic sampling.
`provider_params`	object	yes	Provider-specific parameters passed directly to the API.

Example

agent.acl

providers {
  huggingface {
    models = [
      "google/gemma-2-2b-it",
      {
        name = "meta-llama/Meta-Llama-3.1-8B-Instruct"
        params {
          max_tokens  = 8192
          temperature = 0.7
        }
      }
    ]

    config {
      api_key  = secret(runtime("HUGGINGFACE_API_KEY"))
      base_url = runtime("HUGGINGFACE_BASE_URL", "https://router.huggingface.co")
    }

    params {
      max_tokens  = 4096
      temperature = 0.5
    }
  }
}

agent "assistant" {
  graph {
    type = "react"
  }

  model {
    provider = "huggingface"
    name     = "google/gemma-2-2b-it"
  }
}

tip

Always wrap API tokens in secret(runtime(...)). This prevents the token from appearing in build artifacts and the output of agentc inspect.

Hugging Face

Fields

params

Example

Search docs

Hugging Face

Fields

params

Example

Search docs