agentconf

agentconf

English

泛用的多模型配置管理SDK，适用于单用户的终端AI应用的各类模型的供应商聚合。

基于 Pydantic + SQLite，支持 Any2Any 多模态模型能力标记。

特性

• 层级化配置：Provider(BaseURL+APIKEY) → Model Instance(ModelName+ModelType+Capabilities) → Agent，上层配置自动继承
• 多模态能力标记：通过 model_type 和 capabilities 描述模型能力（视觉、函数调用、嵌入、TTS、ASR 等）
• 安全存储：API Key 通过 SecretStr 保护
• 类型安全：全链路 Pydantic 校验，支持判别多模态和不同类型的模型
• 简洁 API：直觉化的 CRUD + 配置解析接口
• 用户级配置：一处配置，多应用读取且一致

接下来的计划

• 连接代理层(缺少的加密与保护的解决方案)
• 本地化

限制

1. 仅配置

这个SDK只提供配置信息的管理，配置信息需要结合具体的模型SDK（如 OpenAI、LangChain）来实例化模型。

对于应用层的细节实现，比如超时、重试、Prompt 等不包含在支持的范围内。

2. 无加密

生成的SqliteDB本身是没有加密的，它仅能保证APIKEY不会出现在你的代码文件中，如果使用sql语句查询或者print(), 仍有可能意外的打印出APIKEY！

快速开始

安装

uv add agentconf

使用方式

agentconf 提供两种使用方式：

1. TUI 工具 - 适合可视化的交互式的管理和查看配置
2. Python SDK - 适合程序化配置管理

---

Python SDK 使用

基础用法

from agentconf import AgentsConfig, ProviderType

with AgentsConfig() as config:
    # 创建 Provider（提供商）
    config.create_provider(
        name="openai",
        provider_type=ProviderType.OPENAI,
        base_url="https://api.openai.com/v1",
        api_key="sk-your-api-key",
    )

    # 创建 Model Instance（模型实例）
    config.create_model(
        provider_name="openai",
        name="gpt4o",
        model_name="gpt-4o",
        model_type="llm",
    )

    # 创建 Agent（代理）
    config.create_agent(
        name="code-reviewer",
        model_name="gpt4o",
        temperature=0.3,
        top_p=0.9,
    )

    # 解析完整配置（含继承和覆盖）
    resolved = config.resolve_agent("code-reviewer")
    print(resolved.model_dump())

多模态能力标记

from agentconf import AgentsConfig, ProviderType
from agentconf.models.capabilities import LLMCapabilities, EmbeddingCapabilities

with AgentsConfig() as AgentsConfig:
    config.create_provider(
        name="openai",
        provider_type=ProviderType.OPENAI,
        base_url="https://api.openai.com/v1",
        api_key="sk-xxx",
    )

    # 创建带视觉能力的 LLM
    config.create_model(
        provider_name="openai",
        name="gpt4o-vision",
        model_name="gpt-4o",
        model_type="llm",
        capabilities=LLMCapabilities(
            input_modalities=["text", "image"],
            supports_vision=True,
            supports_function_calling=True,
            max_context_length=128000,
        ),
    )

    # 创建 Embedding 模型
    config.create_model(
        provider_name="openai",
        name="text-embed",
        model_name="text-embedding-3-large",
        model_type="embedding",
        capabilities=EmbeddingCapabilities(dimensions=1536),
    )

    # 也可以传入 dict 作为 capabilities
    config.create_model(
        provider_name="openai",
        name="rerank-v1",
        model_name="rerank-v1",
        model_type="rerank",
        capabilities={"top_n": 5, "max_input_length": 4096},
    )

    # 按能力筛选模型
    vision_models = config.find_models_by_capability("supports_vision")
    function_call_models = config.find_models_by_capability("supports_function_calling")
    image_input_models = config.find_models_by_capability("input_modality:image")
    audio_output_models = config.find_models_by_capability("output_modality:audio")

    # 按类型筛选
    llm_models = config.list_models(model_type="llm")
    embed_models = config.list_models(model_type="embedding")

SDK API 参考

agentconf 客户端

from agentconf import AgentsConfig

# 初始化（默认使用 ~/.agentconf/config.db）
config = AgentsConfig()
# 或使用自定义路径
config = AgentsConfig(db_path="/path/to/config.db")

# 使用上下文管理器自动关闭连接
with AgentsConfig() as config:
    # 操作...
    pass

Provider 操作

# 创建
provider = config.create_provider(
    name="openai-main",
    provider_type=ProviderType.OPENAI,  # 或 "openai"
    base_url="https://api.openai.com/v1",
    api_key="sk-xxx",
)

# 查询
provider = config.get_provider("openai-main")
providers = config.list_providers()

# 更新
provider = config.update_provider("openai-main", base_url="https://new-url.com")

# 删除（级联删除关联的 Model 和 Agent）
config.delete_provider("openai-main")

Model Instance 操作

from agentconf.models.capabilities import LLMCapabilities

# 创建
model = config.create_model(
    provider_name="openai-main",
    name="gpt4o",
    model_name="gpt-4o",
    model_type="llm",  # 默认 "llm"，可选: embedding, rerank, tts, stt, asr, image_gen
    base_url="https://proxy.com/v1",  # 可选：覆盖 Provider
    api_key="sk-proxy-key",          # 可选：覆盖 Provider
    capabilities=LLMCapabilities(     # 可选：能力标记
        supports_vision=True,
        max_context_length=128000,
    ),
)

# 查询
model = config.get_model("gpt4o")
models = config.list_models()
models = config.list_models(provider_name="openai-main")  # 按 Provider 筛选
models = config.list_models(model_type="embedding")       # 按类型筛选

# 按能力筛选
vision_models = config.find_models_by_capability("supports_vision")

# 更新
model = config.update_model("gpt4o", model_name="gpt-4o-turbo")

# 删除（级联删除关联的 Agent）
config.delete_model("gpt4o")

Agent 操作

# 创建
agent = config.create_agent(
    name="code-reviewer",
    model_name="gpt4o",
    temperature=0.3,
    top_p=0.9,
    top_k=40,
    max_tokens=2000,
    extra_params={"stop": ["\n\n"]},
)

# 查询
agent = config.get_agent("code-reviewer")
agents = config.list_agents()

# 更新
agent = config.update_agent("code-reviewer", temperature=0.5)
agent = config.update_agent("code-reviewer", model_name="gpt35")  # 更换 Model

# 删除
config.delete_agent("code-reviewer")

配置解析

# 解析 Model 完整配置（含 Provider 继承和 Model 覆盖）
resolved_model = config.resolve_model("gpt4o")
print(resolved_model.api_key)        # 完整的 API Key
print(resolved_model.model_type)     # 模型类型
print(resolved_model.capabilities)   # 能力标记

# 解析 Agent 完整配置（完整继承链）
resolved_agent = config.resolve_agent("code-reviewer")
print(resolved_agent.model.base_url)   # 最终使用的 URL
print(resolved_agent.temperature)       # Agent 参数
print(resolved_agent.model.capabilities)  # 模型能力

数据模型

Provider（提供商）

Model Instance（模型实例）

Agent（代理）

模型能力标记（Capabilities）

每个 model_type 对应不同的能力描述类，包含特定于该类型的能力字段：

Modality（模态枚举）

LLMCapabilities（大语言模型）

EmbeddingCapabilities（向量嵌入）

RerankCapabilities（重排序）

TTSCapabilities（文本转语音）

STTCapabilities（语音转文本 / ASR）

ImageGenCapabilities（图像生成）

配置解析优先级

Agent → Model Instance → Provider（下层覆盖上层）

# Model Instance 可覆盖 Provider 的 base_url 和 api_key
config.create_model(
    provider_name="openai",
    name="gpt4o-proxy",
    model_name="gpt-4o",
    base_url="https://proxy.example.com/v1",  # 覆盖
    api_key="sk-proxy-key",                      # 覆盖
)

开发

# 安装开发依赖
uv sync --extra dev

# 运行测试
uv run pytest -v

# 运行 main.py 以启动TUI
uv run python main.py 

License

Apache-2.0