README
¶
DriftlessAF agentic AI infrastructure
This directory contains tools and agents for AI use with DriftlessAF.
They can be used independently but are best used together with the DriftlessAF
workqueue found in /workqueue and the reconciler bots found in /reconcilers.
The following components are available:
- AI executors: Production-ready executors for Google Gemini and Anthropic
Claude models in
agents/executor/. - Evaluation framework: Testing and monitoring agent quality with
comprehensive metrics in
agents/evals/. - OpenTelemetry metrics: Built-in observability for AI operations in
agents/metrics/. - Prompt building: Utilities for constructing and managing prompts in
agents/promptbuilder/. - Tool calling: Helpers for function/tool calling with Claude and Gemini
in
agents/toolcall/. - Result parsing: Structured output extraction from model responses in
agents/result/.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package agenttrace provides tracing infrastructure for AI agent interactions.
|
Package agenttrace provides tracing infrastructure for AI agent interactions. |
|
payloadcrypt
Package payloadcrypt seals the sensitive free-text fields of an agent trace (prompt, completion, tool params/results, reasoning) before they leave the emitting process, so the CloudEvent — and the BigQuery row the recorder derives from it — carries ciphertext rather than plaintext.
|
Package payloadcrypt seals the sensitive free-text fields of an agent trace (prompt, completion, tool params/results, reasoning) before they leave the emitting process, so the CloudEvent — and the BigQuery row the recorder derives from it — carries ciphertext rather than plaintext. |
|
payloadcrypt/kmsseal
Package kmsseal provides the Cloud KMS-backed wrap for payloadcrypt.
|
Package kmsseal provides the Cloud KMS-backed wrap for payloadcrypt. |
|
Package anthropicauth builds the anthropic.Client used by the Claude agent and judge executors, selecting the authentication backend from a caller-supplied Config.
|
Package anthropicauth builds the anthropic.Client used by the Claude agent and judge executors, selecting the authentication backend from a caller-supplied Config. |
|
Package checkpoint defines the provider-neutral suspend/resume primitive for DriftlessAF agents: a serializable Envelope that captures everything needed to rebuild a paused conversation, a Suspension error value that travels out of an executor's Execute loop the same way workqueue's requeue errors do, and a Store contract (with compare-and-swap Token semantics) for durably parking exactly one envelope per {identity}/{key}.
|
Package checkpoint defines the provider-neutral suspend/resume primitive for DriftlessAF agents: a serializable Envelope that captures everything needed to rebuild a paused conversation, a Suspension error value that travels out of an executor's Execute loop the same way workqueue's requeue errors do, and a Store contract (with compare-and-swap Token semantics) for durably parking exactly one envelope per {identity}/{key}. |
|
gcsstore
Package gcsstore implements checkpoint.Store over a Google Cloud Storage bucket, for durably parking suspended agent envelopes across the human-wait.
|
Package gcsstore implements checkpoint.Store over a Google Cloud Storage bucket, for durably parking suspended agent envelopes across the human-wait. |
|
jsonlstore
Package jsonlstore provides an append-only, JSONL-file checkpoint.Store for local development.
|
Package jsonlstore provides an append-only, JSONL-file checkpoint.Store for local development. |
|
memstore
Package memstore provides an in-memory checkpoint.Store for tests and single-process demos.
|
Package memstore provides an in-memory checkpoint.Store for tests and single-process demos. |
|
storetest
Package storetest provides a reusable conformance suite for checkpoint.Store implementations, in the style of workqueue/conformance.
|
Package storetest provides a reusable conformance suite for checkpoint.Store implementations, in the style of workqueue/conformance. |
|
Package effort defines the provider-neutral reasoning-effort scale shared by the Claude, Gemini, and OpenAI-compatible executor backends.
|
Package effort defines the provider-neutral reasoning-effort scale shared by the Claude, Gemini, and OpenAI-compatible executor backends. |
|
Package evals provides observers and validation helpers for evaluating completed agent traces.
|
Package evals provides observers and validation helpers for evaluating completed agent traces. |
|
report
Package report provides report generation functionality for evaluation results.
|
Package report provides report generation functionality for evaluation results. |
|
testevals
Package testevals provides a testing.T adapter for the evals framework.
|
Package testevals provides a testing.T adapter for the evals framework. |
|
executor
|
|
|
claudeexecutor
Package claudeexecutor provides a generic executor for Claude-based agents that reduces boilerplate while maintaining flexibility for agent-specific logic.
|
Package claudeexecutor provides a generic executor for Claude-based agents that reduces boilerplate while maintaining flexibility for agent-specific logic. |
|
googleexecutor
Package googleexecutor provides a generic Google AI (Gemini) executor for AI agents.
|
Package googleexecutor provides a generic Google AI (Gemini) executor for AI agents. |
|
internal/execshared
Package execshared holds behavior shared by the executor implementations (claudeexecutor, googleexecutor, openaiexecutor) so each backend applies identical semantics: prompt-suffix handling, resource-label defaults, the submit routing predicate, the bounded tool-call dispatch pool, and the submit-gate validation tail.
|
Package execshared holds behavior shared by the executor implementations (claudeexecutor, googleexecutor, openaiexecutor) so each backend applies identical semantics: prompt-suffix handling, resource-label defaults, the submit routing predicate, the bounded tool-call dispatch pool, and the submit-gate validation tail. |
|
internal/telemetry
Package telemetry provides the shared GenAI metrics recorder used by the executor implementations (claudeexecutor, googleexecutor, openaiexecutor) so each backend emits identically-shaped metrics, differing only in the gen_ai.provider.name attribute.
|
Package telemetry provides the shared GenAI metrics recorder used by the executor implementations (claudeexecutor, googleexecutor, openaiexecutor) so each backend emits identically-shaped metrics, differing only in the gen_ai.provider.name attribute. |
|
openaiexecutor
Package openaiexecutor provides a multi-turn conversation executor for OpenAI-compatible chat completion APIs, including Vertex AI's partner model endpoint.
|
Package openaiexecutor provides a multi-turn conversation executor for OpenAI-compatible chat completion APIs, including Vertex AI's partner model endpoint. |
|
retry
Package retry provides exponential backoff retry logic for handling transient errors.
|
Package retry provides exponential backoff retry logic for handling transient errors. |
|
Package judge provides LLM-based evaluation of model outputs using structured rubrics.
|
Package judge provides LLM-based evaluation of model outputs using structured rubrics. |
|
Package metaagent provides a generic framework for building AI agents.
|
Package metaagent provides a generic framework for building AI agents. |
|
Package metrics provides OpenTelemetry metrics instrumentation for generative AI operations.
|
Package metrics provides OpenTelemetry metrics instrumentation for generative AI operations. |
|
Package promptbuilder provides a safe, injection-resistant prompt construction library that leverages Go's standard encoding packages to automatically handle escaping and formatting.
|
Package promptbuilder provides a safe, injection-resistant prompt construction library that leverages Go's standard encoding packages to automatically handle escaping and formatting. |
|
Package rag provides embedding generation, vector storage, and semantic retrieval for driftlessAF agents.
|
Package rag provides embedding generation, vector storage, and semantic retrieval for driftlessAF agents. |
|
Package result extracts a JSON result from free-form model text.
|
Package result extracts a JSON result from free-form model text. |
|
Package schema provides JSON schema generation utilities for AI agent tool definitions.
|
Package schema provides JSON schema generation utilities for AI agent tool definitions. |
|
schematest
Package schematest provides test helpers for comparing JSON schemas.
|
Package schematest provides test helpers for comparing JSON schemas. |
|
Package submitresult provides tool definitions for AI agents to submit their final results.
|
Package submitresult provides tool definitions for AI agents to submit their final results. |
|
Package suspend orchestrates the question/answer lifecycle and halt/wake loop that sits on top of the checkpoint primitive.
|
Package suspend orchestrates the question/answer lifecycle and halt/wake loop that sits on top of the checkpoint primitive. |
|
githubquestions
Package githubquestions implements suspend.QuestionStore over GitHub PR (or issue) comments, so the human half of an ask-a-friend pause happens where humans already are: the question appears as a comment on the conversation the paused run belongs to, and a collaborator answers by replying
|
Package githubquestions implements suspend.QuestionStore over GitHub PR (or issue) comments, so the human half of an ask-a-friend pause happens where humans already are: the question appears as a comment on the conversation the paused run belongs to, and a collaborator answers by replying |
|
memquestions
Package memquestions provides an in-memory suspend.QuestionStore for tests and single-process demos.
|
Package memquestions provides an in-memory suspend.QuestionStore for tests and single-process demos. |
|
Package toolcall defines composable tool providers for AI agents.
|
Package toolcall defines composable tool providers for AI agents. |
|
callbacks
Package callbacks provides lightweight callback types for AI agent tool operations.
|
Package callbacks provides lightweight callback types for AI agent tool operations. |
|
claudetool
Package claudetool converts unified toolcall.Tool definitions into Claude-compatible anthropic.ToolParam metadata for use with the [claudeexecutor].
|
Package claudetool converts unified toolcall.Tool definitions into Claude-compatible anthropic.ToolParam metadata for use with the [claudeexecutor]. |
|
googletool
Package googletool converts unified toolcall.Tool definitions into Gemini-compatible genai.FunctionDeclaration metadata for use with the [googleexecutor].
|
Package googletool converts unified toolcall.Tool definitions into Gemini-compatible genai.FunctionDeclaration metadata for use with the [googleexecutor]. |
|
openaistool
Package openaistool converts unified toolcall.Tool definitions into OpenAI-compatible openai.ChatCompletionToolParam metadata for use with the [openaiexecutor].
|
Package openaistool converts unified toolcall.Tool definitions into OpenAI-compatible openai.ChatCompletionToolParam metadata for use with the [openaiexecutor]. |
|
params
Package params provides shared parameter extraction and error formatting utilities used by both Claude and Google tool implementations.
|
Package params provides shared parameter extraction and error formatting utilities used by both Claude and Google tool implementations. |
Click to show internal directories.
Click to hide internal directories.