SDK v1 — Documentação Legacy
Esta página documenta o Actions SDK v1. Para a versão atual (v2), consulte a documentação do SDK v2.
Knowledge
O módulo Knowledge fornece um cliente simples para consultar as bases de conhecimento internas da Tech4.ai. Ele encapsula a chamada HTTP para o endpoint interno e retorna um objeto tipado com a resposta, incluindo a resposta gerada pelo LLM e os trechos (chunks) mais relevantes.
📋 Método Principal
query(query, knowledge_base_id, top_k=5, rerank=False, extra_context=None, project_prompt=None)
Realiza a consulta à base de conhecimento e retorna QueryResponse.
Parâmetros:
query(str): Consulta em linguagem naturalknowledge_base_id(UUID | str): ID da base de conhecimento a ser consultadatop_k(int): Quantidade de resultados a retornar (padrão: 5)rerank(bool): Se deve reordenar os resultados (padrão:False)extra_context(dict | None): Contexto adicional enviado no payload quando preenchidoproject_prompt(str | None): Contexto específico do projeto injetado no prompt RAG (ver Project prompt)
Retorno (QueryResponse):
query_id(UUID | None)status(RetrieveStatus):OKouLOW_SCOREchunks(RetrieveResults):chunk_search_results(List[ChunkSearchResult])score_threshold(float)
answer(str): Resposta gerada pelo LLM (pode ser vazia quandoLOW_SCORE)blocked(bool): Indica se a consulta foi bloqueada por guardrails (padrão:False)blocked_reason(str | None): Motivo do bloqueio, quando aplicável
Project prompt
O project_prompt é um campo opcional que permite enviar contexto específico do projeto (glossário, intenções e terminologia do domínio) junto com cada consulta. Esse contexto é injetado no pipeline RAG durante a geração de respostas, melhorando a precisão e relevância das respostas ao fornecer ao LLM informações sobre o domínio do projeto.
Quando usar Project Prompt
O project_prompt é útil quando você precisa:
- Definir terminologia específica: Explicar termos técnicos ou de negócio que podem ter significados diferentes em contextos distintos (ex.: "contemplação" em um consórcio vs. uso geral)
- Estabelecer o propósito do projeto: Informar ao LLM qual é a intenção do sistema (atendimento ao cliente, suporte técnico, RH, etc.)
- Fornecer contexto de domínio: Adicionar informações sobre o contexto de negócio que não estão necessariamente nos documentos da base de conhecimento
Uso via Agents SDK
A forma mais prática de usar o project_prompt é através do Knowledge.query, que já gerencia a comunicação com o endpoint interno:
# Realizar consulta com project_prompt
response = knowledge.query(
query="O que é contemplação?",
knowledge_base_id=kb_id,
top_k=5,
project_prompt="Este sistema é um assistente de consórcio. Glossário:\n"
"- Cota: unidade de participação no grupo\n"
"- Contemplação: sorteio ou lance que libera o crédito ao cotista"
)
Integração direta (referência)
Para integrações diretas com o endpoint interno, o project_prompt pode ser incluído no payload da requisição:
Endpoint:
POST https://api.tech4.ai/internal/query
Payload com project_prompt:
{
"query": "Qual o prazo para contemplação?",
"knowledge_base_id": "uuid",
"agent_id": "uuid",
"top_k": 5,
"project_prompt": "Este sistema é um assistente de consórcio. Glossário:\n- Cota: unidade de participação no grupo\n- Contemplação: sorteio ou lance que libera o crédito"
}
Payload sem project_prompt (comportamento padrão):
{
"query": "Qual o prazo para contemplação?",
"knowledge_base_id": "uuid",
"agent_id": "uuid",
"top_k": 5
}
Comportamento e Retrocompatibilidade
| Situação | Comportamento |
|---|---|
project_prompt presente e preenchido | O contexto é injetado no prompt RAG na seção # Contexto do Projeto: antes do contexto dos chunks |
project_prompt ausente ou None | O comportamento é idêntico ao padrão, sem alterações no prompt RAG |
project_prompt vazio ("") | Tratado como ausente, comportamento padrão |
Retrocompatibilidade
O campo project_prompt é totalmente opcional e retrocompatível. Consultas que não incluem o campo funcionam exatamente como antes, sem nenhum impacto no comportamento existente.
Referência técnica
- Tipo:
string(opcional) - Disponibilidade: Apenas no endpoint
/internal/query(uso via Agents SDK ou integração direta) - Validação: Não passa pelo guardrail de entrada (é conteúdo de sistema confiável)
- Observabilidade: O
project_prompté registrado nos traces do Langfuse para rastreamento - Persistência: Não é persistido na base de conhecimento; deve ser enviado a cada consulta
📥 Exemplo de Entrada e Saída
Entrada
{
"query": "O que é Sql"
}
Saída (exemplo real, resumida)
{
"query_id": "0c82f6e3-f990-4b65-87ff-e9302c25e58d",
"status": "ok",
"chunks": {
"chunk_search_results": [
{
"id": "5a398b62-0dd5-5e2a-95cf-bd1ac4891014",
"document_id": "f8888748-cb70-4909-bd1f-2fa5e5ea6629",
"score": 0.5716894524282553,
"text": "# Integração da linguagem SQL com as aplicações (parte 3)\n\n## SQL Estendida\n- Extensão da SQL criada para incluir estruturas procedurais à linguagem ...",
"metadata": {
"chunk_order": 9,
"document_type": "pdf",
"page_number": 10,
"semantic_rank": null,
"full_text_rank": null,
"associated_query": "O que é Sql"
}
},
{
"id": "d2535bbd-dae4-5935-8ab5-93a31cb498b0",
"document_id": "8914b5c0-f107-4977-8a11-3ac8b61e4ff5",
"score": 0.5637222528457642,
"text": "# Integração da linguagem SQL com as aplicações (parte 3)\n\n- SQL Estendida ...",
"metadata": {
"chunk_order": 9,
"document_type": "pdf",
"page_number": 10,
"semantic_rank": null,
"full_text_rank": null,
"associated_query": "O que é Sql"
}
},
{
"id": "2208f7fc-bf13-5a76-b719-50b790c72c3f",
"document_id": "65d8d169-5e1c-475a-b5a4-6c26e82a79aa",
"score": 0.5490762264087075,
"text": "# Comandos SQL\n- begin (begin transaction) ...",
"metadata": {
"chunk_order": 3,
"document_type": "pdf",
"page_number": 4,
"semantic_rank": null,
"full_text_rank": null,
"associated_query": "O que é Sql"
}
}
],
"score_threshold": 0.45
},
"answer": "Com base no contexto fornecido, 'SQL' pode se referir a: SQL Estendida (PL/SQL, PL/pgSQL, Transact-SQL) ... também menciona comandos de transação como begin, commit, rollback ..."
}
📝 Exemplo Prático
Consultar base de conhecimento com formatação de resposta
def consultar_base_de_conhecimento(consulta: str):
"""
Consulta a base de conhecimento através da API de conhecimento
"""
try:
query_span = action_span.span("consulta na base", {"query": consulta})
response = knowledge.query(
query=consulta,
knowledge_base_id=secrets["KNOWLEDGE_BASE_ID"],
)
query_span.end({"response": response.model_dump()})
action_span.event("response", {"status": response.status, "ans": response.answer})
# Compare sempre com o Enum, não com string
if response.status != RetrieveStatus.OK or not response.answer:
return ResponseToUser(
message="Não encontrei informações específicas sobre sua consulta.",
status=ResponseStatus.SUCCESS, # SUCCESS para fluxo normal sem resposta específica
)
message = response.answer
if response.chunks.chunk_search_results:
sources_count = len(response.chunks.chunk_search_results)
message += f"\n\n*Baseado em {sources_count} fonte(s) da base de conhecimento.*"
return ResponseToUser(message=message, status=ResponseStatus.SUCCESS)
except Exception as e:
action_span.event("error", {"error": str(e)})
return ResponseToUser(
message=(
"Peço desculpas, estamos enfrentando problemas técnicos no momento. "
"Tente novamente em alguns instantes."
),
status=ResponseStatus.ERROR,
metadata={
"error_type": "knowledge_api_error",
"error_message": str(e),
},
)
💡 Dicas de Uso
Melhores Práticas
- Enum de status: compare com
RetrieveStatus.OKem vez de strings top_k: ajuste para balancear precisão e cobertura (3–5 costuma funcionar bem)
📊 Estruturas de Dados
Enums e Classes Principais
RetrieveStatus(Enum):OK,LOW_SCOREChunkMetadata: metadados do trecho (ordem, tipo de documento, página, ranks, query associada)ChunkSearchResult:id,document_id,score,text,metadataRetrieveResults:chunk_search_results(lista deChunkSearchResult),score_thresholdRetrieveResponse:query_id,status,chunksQueryResponse(extendsRetrieveResponse):answer,blocked,blocked_reason