Skip to main content

tina

tina logo

License

一个轻量、模块化的 AI 智能体框架,基于 OpenAI API 格式构建。

安装

# 基础安装(需要 Python >= 3.10)
pip install tina-python

# 如果需要使用 MCP(模型上下文协议)服务
pip install tina-python[mcp]

# 如果需要 TUI 终端界面(独立发行包 tina-tui)
pip install tina-python[tui]

# 如果需要多 Agent 环境 + Web 调试控制台(独立发行包 tina-multi-agent)
pip install tina-python[multi-agent]

# 一次装齐所有可选功能(TUI + 多 Agent + MCP)
pip install tina-python[all]

# 如果需要运行测试
pip install tina-python[test]

快速开始

from tina import Agent, Tools
from tina.llm import BaseAPI

# 1. 实例化大模型(支持通过 tina.env 文件配置)
llm = BaseAPI(
    api_key="your-api-key",
    base_url="https://api.openai.com/v1",
    model="gpt-4o"
)

# 2. 创建工具集并注册工具
tools = Tools()

@tools.register()
def get_weather(city: str):
    """
    查询城市天气
    Args:
        city (str): 城市名称
    """
    return f"{city}今天天气晴朗,温度25°C"

# 3. 创建 Agent 并运行
agent = Agent(
    llm=llm,
    tools=tools,
    system_prompt="你是一个有用的助手"
)

# 流式对话
result = agent.predict(instruction="今天的北京天气怎么样?", stream=True)
for chunk in result:
    print(chunk.content, end="", flush=True)

目录


tina 是什么

tina 是一个轻量、模块化的 AI 智能体框架,专注于让开发者以最少的代码实现大模型应用的原型验证。

设计理念:

  • 简单直观:不需要复杂的 Chain 或 Graph 概念,像调用函数一样使用大模型
  • 模块化:LLM、Tools、Agent 各层独立,可按需使用
  • 轻量依赖:核心仅依赖 httpx 和 python-dotenv
  • 注释即描述:通过 Google 风格的注释自动生成工具 JSON Schema

tina 是我大学期间兴趣使然开发的练习作品,适合快速原型验证。如果需要生产级的稳定性,请使用 LangChain 等成熟框架。

特性概览

模块 功能 说明
BaseAPI API 调用 支持流式/非流式、工具调用、多种采样参数
BaseMultimodalAPI 多模态调用 支持图片、音频、URL 输入
Tools 工具管理 注册、合并、执行,自动生成 Schema
Agent 智能体 自动维护对话、执行工具、事件回调
MultimodalAgent 多模态智能体 继承 Agent,支持多媒体输入与多模态工具
MCPClient MCP 集成 连接 MCP 服务器生态(stdio/SSE)
ContextManager 上下文管理 滚动窗口策略,自动截断
AgentEvents 事件系统 贯穿 Agent 生命周期的回调钩子
TUI(可选) 终端界面 独立包 tina-tui:测试 Agent 的交互控制台,也可当作自己的 TUI 使用
多 Agent(可选) 多 Agent 环境 独立包 tina-multi-agent:消息总线 + Web 调试控制台

一、LLM 层 —— 调用大模型

tina 使用 httpx 直接调用 OpenAI 格式的 API,不依赖 OpenAI SDK。

1.1 快速使用

from tina.llm import BaseAPI

# 推荐:使用 tina.env 文件(自动从当前目录查找 .env 或 tina.env)
llm = BaseAPI()

# 或者:手动传入参数
llm = BaseAPI(
    api_key="your-api-key",
    base_url="https://api.openai.com/v1",
    model="gpt-4o"
)

tina.env 文件示例:

LLM_API_KEY="your-api-key"
BASE_URL="https://api.openai.com/v1"
MODEL_NAME="gpt-4o"

base_url 规则(0.7.0 起):只写服务根地址即可(如 https://api.openai.com/v1),tina 会自动补上 /chat/completions;写完整地址(.../chat/completions)也依然兼容。旧文档要求"必须自带 /chat/completions"的说法已作废。

1.2 非流式调用

result = llm.predict(
    input_text="帮我翻译这句话:Hello tina",
    sys_prompt="你是一位专业的翻译家",
    stream=False
)
print(result["content"])

1.3 流式调用

result = llm.predict(
    input_text="讲一个故事",
    stream=True
)
for chunk in result:
    print(chunk["content"], end="")

1.4 多轮对话

messages = [
    {"role": "system", "content": "你是一个有用的助手"},
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "你好!有什么可以帮助你的吗?"}
]

result = llm.predict(
    input_text="北京天气怎么样?",  # 自动追加到 messages
    messages=messages,
    stream=True
)

1.5 异步调用

result = await llm.apredict(
    input_text="你好",
    stream=False
)

# 异步流式:先 await 拿到异步生成器
result = await llm.apredict(input_text="讲个故事", stream=True)
async for chunk in result:
    print(chunk["content"], end="")

1.6 predict 参数说明

参数名 类型 默认值 说明
input_text str None 用户输入文本
sys_prompt str "你的工作非常的出色!" 系统提示词
messages list None 历史消息列表
temperature float 1.0 随机性 (0.0~1.0)
top_p float 0.9 核采样
top_k int None Top-K 采样
min_p float None 最小概率采样
max_tokens int None 最大生成 token 数
presence_penalty float None 存在惩罚 (-2.0~2.0)
frequency_penalty float None 频率惩罚 (-2.0~2.0)
stream bool False 是否流式输出
format str "text" 输出格式:"text" 或 "json"
tools list None 工具列表
timeout int 180 超时时间(秒)

1.7 返回值格式

# 非流式
{
    "role": "assistant",
    "content": "回复内容",
    # 有工具调用时会出现
    "tool_calls": [
        {
            "index": 0,
            "function": {"name": "...", "arguments": "{}"},
            "type": "function",
            "id": "call_xxx"
        }
    ]
}

# 流式:逐块返回片段,工具调用以 tool_name / tool_arguments 片段给出;
# 推理模型的思维链在 reasoning_content 中,末尾可能带有 usage

1.8 获取可用模型列表

# 仅适用于标准 OpenAI API
models = llm.get_models()
print(models["available_models"])

二、Tools 层 —— 工具注册与管理

Tools 是 tina 的工具管理核心,支持注册、查询、合并和执行。

2.1 创建工具集

from tina import Tools

# 简单使用(不指定名称)
tools = Tools()

# 命名工具集(用于包管理和合并)
tools = Tools(name="my_tools", metadata={"author": "me"})

指定 name 后会给工具添加命名空间前缀({name}_{函数名}),方便工具包合并时避免名称冲突。

2.2 注册工具

装饰器方式(推荐)

tools = Tools()

@tools.register()
def get_weather(city: str):
    """
    查询城市天气
    Args:
        city (str): 城市名称
    """
    return f"{city}今天天气晴朗"

@tools.register(
    description="手动描述(可选)",
    require_confirmation=True,  # 需要用户确认
    return_image=False,         # 多模态:返回图片
    return_audio=False,         # 多模态:返回音频
    return_url=False,           # 多模态:返回 URL
)
def delete_file(path: str):
    """删除文件(高危操作)"""
    ...

方法方式

def add(a: int, b: int):
    """两数相加"""
    return a + b

tools.register_tool(tool=add)

注册不带功能实现的工具

tools.register_no_function(
    name="search",
    description="搜索引擎",
    required_parameters=["query"],
    parameters={
        "query": {
            "type": "string",
            "description": "搜索关键词"
        }
    }
)

2.3 注销工具

tools.unregister("get_weather")

2.4 工具包合并(命名空间隔离)

适用于分发和组合工具包:

from tina import Tools

search_tools = Tools(name="search")
@search_tools.register()
def web(query: str):
    """网页搜索"""
    return f"搜索结果:{query}"

data_tools = Tools(name="data")
@data_tools.register()
def query(sql: str):
    """数据库查询"""
    return f"查询结果:{sql}"

# 合并工具包
all_tools = search_tools + data_tools
# 或
all_tools += data_tools

# 添加多个
all_tools.add_tools([search_tools, data_tools])

# 减掉工具包
all_tools -= search_tools
# 或
all_tools.sub_tools([search_tools])

2.5 执行工具

tool_calls = [
    {
        "id": "call_123",
        "type": "function",
        "function": {
            "name": "get_weather",
            "arguments": '{"city": "北京"}'
        }
    }
]
# execute 需要事件对象(Agent 内部会自动传入)
from tina import AgentEvents

results = tools.execute(tool_calls, events=AgentEvents())
# [
#   {"role": "tool", "tool_call_id": "call_123", "tool_name": "get_weather", "content": "北京今天天气晴朗"}
# ]

2.6 工具查询

# 获取所有工具 Schema
tools.get_tools()

# 获取单个工具信息
tools.get_tool_info("get_weather")

# 获取工具函数
func = tools.get_tool("get_weather")
result = func("上海")

2.7 在类中定义工具(最佳实践)

class SearchService:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.tools = Tools(name="search_service")
        self.tools.register_tool(self.web_search)

    def web_search(self, query: str):
        """
        互联网搜索
        Args:
            query (str): 搜索关键词
        """
        return f"搜索结果:{query}"

    def get_tools(self):
        return self.tools

# 使用
search = SearchService(api_key="xxx")
agent = Agent(llm=llm, tools=search.get_tools())

2.8 Google 风格注释解析

tina 会自动解析以下格式的注释生成 JSON Schema:

def tool_func(param1: str, param2: int):
    """
    工具的描述(会被提取为 description)
    Args:
        param1 (str): 参数1的描述
        param2 (int): 参数2的描述
    Returns:
        str: 返回值描述
    Raises:
        ValueError: 异常描述
    """

三、Agent 层 —— 智能体

Agent = LLM + Tools + ContextManager,自动维护对话上下文并执行工具调用循环。

3.1 实例化 Agent

from tina import Agent, Tools
from tina.llm import BaseAPI

llm = BaseAPI()
tools = Tools()

agent = Agent(
    llm=llm,
    tools=tools,
    system_prompt="你是一个有用的助手",
    name="my_agent",          # 可选:Agent 名称
    mcp=None,                 # 可选:MCPClient 实例
    events=None,              # 可选:AgentEvents 实例
    context_manager=None,     # 可选:自定义 ContextManager
    agent_runtime=None,       # 可选:自定义 AgentRuntime
    max_tool_loop=30,         # 最大工具调用循环次数
    max_context_length=100000,# 最大上下文长度(字符)
    max_tool_result_length=6000, # 工具结果最大长度
)

3.2 使用 Agent 对话

# 流式输出(默认)
result = agent.predict(instruction="今天北京天气怎么样?", stream=True)
for chunk in result:
    print(chunk.content, end="", flush=True)

# 非流式输出
result = agent.predict(instruction="你好", stream=False)
print(result.content)

# 异步流式
async for chunk in agent.apredict(instruction="你好"):
    print(chunk.content, end="")

# 异步非流式
result = await agent.apredict_no_stream(instruction="你好")

predict 参数:

参数名 类型 默认值 说明
instruction str None 用户指令
temperature float 0.5 采样温度
top_p float 0.9 核采样
top_k int 1 Top-K 采样
min_p float 0.0 最小概率采样
stream bool True 是否流式输出

3.3 Agent 状态

from tina import AgentState

# 获取当前状态
if agent.state == AgentState.IDLE:
    print("Agent 空闲中")
elif agent.state == AgentState.RESPONDING:
    print("Agent 正在输出")
elif agent.state == AgentState.THINKING:
    print("Agent 正在思考")
elif agent.state == AgentState.TOOL_CALLING:
    print("Agent 正在使用工具")
elif agent.state == AgentState.ON_TOOL_CONFIRM:
    print("Agent 等待工具确认")
elif agent.state == AgentState.ERROR:
    print("Agent 出错")

3.4 消息管理

# 获取消息列表
messages = agent.get_messages()

# 清空全部消息(含系统提示词,之后需重新 set_system_prompt)
agent.clear_messages()

# 获取系统提示词
prompt = agent.get_system_prompt()

# 设置系统提示词
agent.set_system_prompt("新的系统提示词")

# 添加单条消息
agent.add_message(role="user", content="你好")

# 添加消息列表
agent.add_messages([
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "你好!"}
])

# 获取工具调用信息
last_call = agent.get_last_tool_call()
last_result = agent.get_last_tool_result()
tool_calls = agent.get_tools_call()
tool_results = agent.get_tools_call_result()

3.5 事件回调(Event Hooks)

Agent 提供了丰富的生命周期事件:

# 1. 用户指令处理前(可修改输入)
@agent.before_user_instruction()
def on_before_user(user_message: str):
    return f"【增强】{user_message}"  # 返回修改后的输入

# 2. 用户指令处理后
@agent.after_user_instruction()
def on_after_user(user_message: str, assistant_message: str):
    print(f"问:{user_message}")
    print(f"答:{assistant_message}")

# 3. 工具调用前(可修改参数)
@agent.before_tool_call()
def on_before_tool(tool_name: str, tool_arguments: dict):
    return tool_name, tool_arguments  # 必须返回两个参数

# 4. 工具调用后(可修改结果)
@agent.after_tool_call()
def on_after_tool(tool_name: str, tool_arguments: dict, tool_result: any):
    return tool_name, tool_arguments, tool_result  # 必须返回三个参数

# 5. 工具需要确认时
@agent.on_tool_confirmation()
def on_confirm(tool_name: str, tool_arguments: dict):
    return True    # 放行
    # return False  # 拦截
    # return (False, "自定义拒绝理由")  # 拦截并说明理由

# 6. 流式片段监听
@agent.on_stream_chunk()
def on_stream(chunk):
    print(chunk.content, end="", flush=True)

# 7. 工具序列监听
@agent.before_tool_calls()
def on_before_calls(tool_calls: list):
    print(f"模型准备调用 {len(tool_calls)} 个工具")

@agent.after_tool_calls()
def on_after_calls(tool_calls: list):
    print(f"工具调用完成")

# 8. 推理轮次结束
@agent.on_turn_end()
def on_turn_end():
    print("本轮推理完成")

注意:

  • 事件处理函数可以是同步或异步的。异步函数仅在 apredict 时执行
  • 拦截型事件(before_xxx)如果有返回值,必须原样返回对应数量的参数

3.6 多 Agent 连接

agent_a = Agent(llm=llm, tools=tools, name="agent_a")
agent_b = Agent(llm=llm, tools=tools, name="agent_b")

# 关联另一个 Agent(记录到 other_agents,目前不会自动共享消息列表)
agent_a.connect_agent(agent_b)

# 断开连接
agent_a.disconnect_agent(agent_b)

3.7 自定义事件管理

from tina import AgentEvents

events = AgentEvents()

@events.on_stream_chunk()
def on_stream(chunk):
    print(chunk.content, end="")

@events.on_turn_end()
def on_end():
    print("完成")

agent = Agent(
    llm=llm,
    tools=tools,
    events=events
)

3.8 输出格式(流式)

Agent 流式输出的每一帧是一个 AgentResponse 对象,包含以下可能的字段:

# 1. 普通文本输出
AgentResponse(role="assistant", content="回复内容")

# 2. 推理模型输出
AgentResponse(role="assistant", content="", reasoning_content="推理链")

# 3. 工具调用通知
AgentResponse(role="assistant", content="", tool_name="get_weather")

# 4. 工具参数片段
AgentResponse(role="assistant", content="", tool_name="get_weather", tool_arguments='{"city": "北京"}')

# 5. 完整工具调用
AgentResponse(role="assistant", content="", tool_calls=[...])

# 6. 工具执行结果
AgentResponse(role="tool", content="工具返回结果", tool_name="get_weather")

四、MCP 支持 —— 模型上下文协议

tina 支持通过 MCP(Model Context Protocol)连接外部工具生态。

4.1 安装 MCP 依赖

pip install tina-python[mcp]

想一次装齐所有可选功能(TUI + 多 Agent + MCP):pip install tina-python[all]

4.2 使用 MCP 客户端

from tina.mcp import MCPClient

mcp = MCPClient()

# 添加 stdio 类型 MCP 服务
mcp.add_server(
    server_id="playwright",
    type="stdio",
    command="npx",
    args=["@playwright/mcp@latest"],
)

# 添加 Streamable HTTP 类型 MCP 服务(推荐,取代旧 SSE)
mcp.add_server(
    server_id="my-service",
    type="http",  # 也支持 streamable_http / streamableHttp
    url="http://localhost:8080/mcp",
    headers={"Authorization": "Bearer YOUR_API_KEY"},  # 可选
)

# 添加 SSE 类型 MCP 服务(旧传输,仍兼容)
mcp.add_server(
    server_id="my-legacy-service",
    type="sse",
    url="http://localhost:8080/sse",
    headers={"Authorization": "Bearer YOUR_API_KEY"},  # 可选
)

type 为必填项,用于区分传输类型;command/args/env 与 url/headers 分别对应 stdio 与远程类型,编辑器会根据 type 给出对应的参数提示。

4.3 在 Agent 中使用 MCP

from tina import Agent, Tools
from tina.llm import BaseAPI
from tina.mcp import MCPClient

mcp = MCPClient()
mcp.add_server(
    server_id="playwright",
    type="stdio",
    command="npx",
    args=["@playwright/mcp@latest"],
)

llm = BaseAPI()
tools = Tools()

agent = Agent(
    llm=llm,
    tools=tools,
    mcp=mcp,
    system_prompt="你是一个浏览器自动化助手"
)

result = agent.predict(instruction="导航到 bing.com 并搜索 tina", stream=True)
for chunk in result:
    print(chunk.content, end="")

4.4 MCP 服务管理

# 添加服务(参数与 MCPClient.add_server 一致)
agent.add_mcp_server("server_id", type="http", url="http://localhost:8080/mcp")

# 移除服务
agent.remove_mcp_server("server_id")

# 获取服务信息
info = agent.get_mcp_server_info("server_id")

# 获取所有服务信息
all_info = agent.get_mcp_server_info()

4.5 MCP 工具转换

MCPClient 会自动将 MCP 工具转换为 Tina 工具格式,Agent 可直接调用。


五、多模态支持

5.1 多模态 LLM

from tina.llm import BaseMultimodalAPI

mllm = BaseMultimodalAPI()

# 图片输入
result = mllm.predict(
    input_text="这张图里有什么?",
    input_image="path/to/image.jpg",
    stream=False
)

# 多图片 + 音频
result = mllm.predict(
    input_text="描述这些内容",
    input_image=["image1.jpg", "image2.png"],
    input_audio="audio.mp3",
)

5.2 多模态 Agent

from tina import MultimodalAgent, Tools
from tina.llm import BaseMultimodalAPI

mllm = BaseMultimodalAPI()
tools = Tools()

magent = MultimodalAgent(
    llm=mllm,
    tools=tools
)

result = magent.predict(
    instruction="这张图显示了什么天气?",
    image="weather.jpg",
)

5.3 多模态工具

注册工具时指定返回类型,tina 会自动处理多媒体数据转换:

@tools.register(return_image=True)
def capture_screenshot(url: str):
    """
    截取网页截图
    Args:
        url (str): 网页地址
    """
    return "screenshot.png"  # 自动转为 Base64 给模型

@tools.register(return_audio=True)
def text_to_speech(text: str):
    """
    文本转语音
    Args:
        text (str): 要朗读的文本
    """
    return "speech.mp3"

@tools.register(return_url=True)
def search_product(query: str):
    """
    搜索商品
    Args:
        query (str): 搜索词
    """
    return "https://example.com/product/123"

magent = MultimodalAgent(llm=mllm, tools=tools)

5.4 构建多模态消息

from tina.utils import build_multimodal_message

message = build_multimodal_message(
    input_text="描述这张图",
    input_image="image.jpg",
    input_audio="audio.mp3",
    input_url="https://example.com/image.png",
    image_detail="high",  # 细节:low / high / auto
)


六、快速开发工具

tina 提供了一些开箱即用的工具函数和工具包,帮助你快速搭建应用。

6.1 后台工作器 AgentWorker

AgentWorker 将 Agent 包装为异步后台服务,通过消息队列接收外部指令并持续处理:

from tina import Agent, Tools
from tina.llm import BaseAPI
from tina.utils import AgentWorker

llm = BaseAPI()
tools = Tools()
agent = Agent(llm=llm, tools=tools)

worker = AgentWorker(agent=agent, max_queue_size=20)

# 添加流式输出处理器
def on_chunk(chunk):
    print(chunk.content, end="", flush=True)

worker.add_stream_chunk_handler(on_chunk)

# 在其他协程中向工作器推送指令
import asyncio

async def main():
    # 启动工作器
    asyncio.create_task(worker.run())

    # 推送指令
    await worker.put("你好,请帮我查一下天气")
    await worker.put("现在几点了?")

    # 查看队列状态
    print(f"队列中待处理消息数: {worker.get_queue_size()}")

asyncio.run(main())

AgentWorker 还会将自身的 put 方法自动注册为 Agent 的工具,方便多 Agent 场景下互相调用。

6.2 终端交互控制台 run_agent_in_cli

快速启动一个 Agent 交互式终端,适合调试和测试:

from tina import Agent, Tools
from tina.llm import BaseAPI
from tina.utils.run_agent_in_cli import run_agent_in_cli

# 搭建你的 Agent
llm = BaseAPI()
tools = Tools()
agent = Agent(llm=llm, tools=tools)

# 一键启动交互终端
run_agent_in_cli(agent)

启动后可在终端直接与 Agent 对话,支持以下指令:

指令 功能
#context 查看当前对话上下文(消息列表)
#clear 清屏
exit / quit 退出对话(#exit 不支持,会被当作普通输入)

6.3 多模态消息构建器 build_multimodal_message

用于灵活构建包含多模态内容的消息:

from tina.utils import build_multimodal_message

message = build_multimodal_message(
    input_text="描述这张图片",
    input_image="path/to/image.jpg",
    input_audio="path/to/audio.mp3",
    input_url=["https://example.com/image1.png", "https://example.com/image2.png"],
    image_detail="high",  # low / high / auto
    role="user"
)
print(message)
# {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image_url", ...}]}

七、拓展包(可选)

除核心之外的可选能力:有随主包提供的(编码工具),也有拆成独立发行包的(终端界面、多 Agent 环境),按需安装、可独立更新与发布。主包内不再包含后者的实现(仅保留 tina.utils.* 兼容转发壳)。

7.1 终端界面 TUI(tina-tui)

终端界面由配套包 tina-tui(基于 Textual)提供,作为可选扩展单独发行:方便你测试自己写的 Agent,也可以直接当作自己的 TUI 来用。核心不依赖它,需要额外安装:

pip install tina-python[tui]   # 等价于安装 tina-tui

开箱即用的 tinacode 命令:装好后可以在任意目录直接起一个编码 agent,不用写 Python:

cd <你的项目>
tinacode
  • 工作目录 = 你敲命令时所在的目录(code_* 工具的相对路径以它为准)
  • 会话历史存到 <cwd>/.tina/chat_sessions/,按目录隔离
  • 模型配置读 <cwd>/tina.env 或 .env,没有则回退全局 ~/.tina/tina.env
  • 目录里的 .tinacode.md / AGENTS.md / .tina.md 自动注入系统提示(目录级定制不用改代码)
  • 工具集是 CodingTools(见 7.3)

自己组装 Agent 再交给 TUI:

from tina import Agent, Tools
from tina.llm import BaseAPI
from tina_tui import run_agent_in_tui

agent = Agent(llm=BaseAPI(), tools=Tools())

run_agent_in_tui(agent, max_tokens=32000)

# 想不受上下文长度限制(不裁剪历史、不截断工具结果):
# run_agent_in_tui(agent, unlimited_context=True)

特性:

  • 助手正文流式渲染(Markdown),推理内容与工具调用卡片均可折叠
  • 消费与渲染解耦(定时渲染泵):极快或极长的输出都不掉帧
  • 自动为 Agent 注册工具确认事件(require_confirmation=True 的工具会弹出选择条)
  • 上下文 token 占用与上限进度(显示百分比,≥80% 变黄、超限变红警告),运行时显示动画
  • Esc 可打断本轮回复;已生成的部分正文写回上下文,进行中的工具调用记为「该次调用被打断」
  • 输入框支持多行与粘贴;Enter 发送、Shift+Enter 换行、Tab 补全命令与会话 id
  • 底部粘性滚动:在底部时自动跟随输出,向上滚动查看历史时不会被打扰,滚回底部自动恢复
  • 会话自动归档到 <项目>/.tina/chat_sessions/:可切换 / 重命名 / 删除,首轮结束后自动起名
  • 可选 unlimited_context=True:用 tina 提供的无限制上下文管理器替换 Agent 的(不裁剪历史、不截断工具结果)
指令 功能
#help 查看可用命令
#tools 查看当前工具、描述与参数
#context 查看当前上下文
#model 查看当前模型信息
#tokens 查看当前上下文 token 占用
#sessions 列出已保存的会话(可跟关键字过滤)
#switch 切换会话(按 id / id 前缀 / 标题)
#new 新建会话(当前会话自动保存)
#rename 重命名当前会话
#delete 删除会话
#compact 压缩上下文(让 Agent 自我总结并并入 system)
#clear 清空上下文与界面
#exit 退出

快捷键:Ctrl+↑/↓ 跳转消息、Ctrl+Home/End 首/末条、Ctrl+R 折叠思考、Ctrl+T 折叠工具与结果、Ctrl+O 查看完整工具参数、Esc 关闭弹窗/取消确认 / 打断本轮回复。

界面是可选的:数据层 TuiMessageStore(渲染块列表)和 TokenCounter(token 计数)在 tina_tui 里不依赖 textual,可以单独导入,用来接入你自己的界面。

完整说明(安装、指令、快捷键、自建界面)见 docs/tui.md。

7.2 多 Agent 环境(tina-multi-agent)

多 Agent 场景由独立发行包 tina-multi-agent 提供:把多个各自独立的 Agent(含 MultimodalAgent)注册进一个「环境」,通过消息总线互相通信,并带一个 Web 调试控制台用于观测与介入。

pip install tina-python[multi-agent]   # 等价于安装 tina-multi-agent
from tina import Agent
from tina.llm import BaseAPI
from tina_multi_agent import MultiAgentEnvironment, MultiAgentWeb

llm = BaseAPI()

env = MultiAgentEnvironment(name="room")
env.add_agent(Agent(llm=llm, name="alice", system_prompt="你是 alice"))
env.add_agent(Agent(llm=llm, name="bob", system_prompt="你是 bob"))

# 带 Web 控制台启动(自动启动环境):打开 http://127.0.0.1:7077
MultiAgentWeb(env, port=7077).run()
  • 每个 Agent 一个收信队列;外部指令走 add_user_message,同伴消息作为带 name 的 assistant 消息注入。
  • 支持回合中途注入(before_llm_call)、打断(env.interrupt)、工具确认与权限表。
  • Web 控制台能力、消息总线、POST /instruction、WS /ws 事件等完整说明见 packages/tina-multi-agent/README.md。

兼容提示:旧路径 tina.utils.multi_agent 仍可用(主包内保留转发壳);未安装 tina-multi-agent 时会提示安装。

7.3 编码工具(CodingTools)

面向「写代码」的主包内置能力(命名空间 code),像普通工具包一样按需搭配到任意 Agent:一个编码工具包 + 一个项目感知的上下文管理器。提供可靠的局部编辑(精确文本匹配 + 唯一性校验 + 原子写)、搜索增强与命令输出截断。

from tina import Agent
from tina.utils.coding_tools import CodingTools

tools = CodingTools(root=".").get_tools()   # code_read / code_glob / code_grep / code_write / code_edit / code_patch / code_bash
agent = Agent(llm=llm, tools=tools)
工具 说明 需确认
code_read 按行读取(offset/limit、行号、总行数与截断提示) 否
code_glob 按 glob 查找文件(如 **/*.py) 否
code_grep 正则搜索(include / 上下文行 / 忽略大小写) 否
code_write 整文件写入(.py 写前语法校验) ✅
code_edit 精确文本替换(命中多次需 replace_all,返回 diff) ✅
code_patch 应用 unified diff 补丁(一次多处/跨行改动,行号可偏差、上下文对不上则整体中止) ✅
code_bash 执行命令(首尾截断、带 exit code) ✅

配套的项目感知上下文管理器(自动注入 AGENTS.md / .tinacode.md / .tina.md、工作目录与目录结构摘要,可用 refresh_project_context() 刷新):

既可在构造时传入,也可之后替换:

from tina import Agent
from tina.utils.coding_context import CodingContextManager

agent = Agent(llm=llm, tools=tools, context_manager=CodingContextManager(root="."))
# 或:agent.set_context_manager(CodingContextManager(root="."))

未显式传 system_prompt 时,Agent 会保留 context_manager 自带的系统提示(不再用默认提示覆盖);显式传 system_prompt 才会覆盖它。


附录

环境配置

tina 支持通过环境文件配置 API 信息,自动从当前目录查找 .env 或 tina.env:

LLM_API_KEY="your-api-key"
BASE_URL="https://api.openai.com/v1"
MODEL_NAME="gpt-4o"
MAX_INPUT=8000

依赖说明

用途 依赖
核心功能 httpx, python-dotenv
MCP 支持 mcp
TUI 界面(可选,tina-tui) textual
多 Agent(可选,tina-multi-agent) fastapi, uvicorn, websockets
测试 pytest, pytest-asyncio, pytest-cov

许可证

Apache License 2.0

贡献

欢迎提交 Issue 和 PR!项目地址:https://github.com/XIMOCY/tina

Metadata

Release files for tina-python 0.7.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tina-python 0.7.2
File Size Uploaded Provenance Actions
tina_python-0.7.2.tar.gz 123.4 kB Without provenance Details for tina_python-0.7.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tina-python 0.7.2
File Interpreter ABI Platform Actions
tina_python-0.7.2-py3-none-any.whl Python 3 none any Details for tina_python-0.7.2-py3-none-any.whl

Total release size: 241.2 kB

Release files / tina_python-0.7.2.tar.gz

Download URL tina_python-0.7.2.tar.gz
Size 123.4 kB
Tags Source
SHA-256 checksum
How to use checksums
2ed30839fe87f67e9f2b5a9bd2d776a8a9c1124df406fa1e1661f0f1cf84bed1
BLAKE2b-256 checksum
How to use checksums
30d39a83610ace5810b78ff070d3587fbc3679107ae4e129eb1114e333809e4c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

Release files / tina_python-0.7.2-py3-none-any.whl

Download URL tina_python-0.7.2-py3-none-any.whl
Size 117.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4561f0c670f36c62672258350766d28fc3738b75c410005da20694fa0667d6bd
BLAKE2b-256 checksum
How to use checksums
ae28b8d0b8f78b1c52590000b1908bdb97d8dbe04cdf36420d6d5c9a6c133ecf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

Security for tina-python 0.7.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page