FAQ

Product

What is Touba useful for?

Touba is used to write, prepare, run, trace, and audit governed agentic workflows. The .tb language describes orchestration and authority; AIR, manifest, runtime, handlers, locks, and traces make execution observable.

Multi-agent composition and recovery

Can multiple agents run in parallel?

Yes. A strategy declares parallel AgentName over a typed list, with max_concurrency, max_items and an ordered into result. Imported agents with explicit signatures are supported. Each branch retains its caller and scopes; all share run budgets. An agent can also select an authorized strategy containing the group. See Strategy.

Does one approval authorize every branch or iteration?

No. Each decision targets a specific occurrence. Resume preserves stacks, completed branches and budgets without repeating completed calls. Human checkpoints, group checkpoints and sequential operation recovery have distinct scopes; see the recovery guide.

Why does Touba emphasize explicit artifacts?

Because an agentic workflow must be able to explain who called what, with which capabilities, secrets, memories, limits, and traces. Touba therefore centers concrete artifacts: .tb source, AIR, manifest, run plan, supply-chain lock, traces, and reports.

Is Touba only a research project?

No. Probabilistic Agentic Programming provides the scientific frame, while Touba targets robust agentic workflows for real teams. Touba defines explicit contracts for tools, handlers, secrets, agents, memories, triggers, budgets, audits, and refusals before external effects.

Language

Why not put JavaScript or Python directly in .tb?

Because .tb remains the language of governed orchestration. Code that performs an external effect lives in a host handler explicitly connected by manifest. This separation keeps AIR as a multi-runtime contract and avoids turning Touba into a polyglot file that is difficult to analyze.

What is the difference between a file and a module?

The file is the physical artifact. The module is the logical identity declared in the source. In a Touba project, a file such as src/examples/search.tb can declare module examples.search. The module is then used to qualify AIR references.

Does every .tb file need a handler?

No. A Touba file without tool can contain pure functions, interactions, skills, agents, or strategies without a handler. A handler becomes necessary when a tool must perform an external effect: network access, database work, LLM call, business system integration, or another host integration.

Does every .tb file need a manifest?

No. A manifest becomes necessary when the program connects a tool, trigger, resource binding, execution profile, or another explicit runtime authority. A simple program without external effects can be compiled and run without a binding manifest.

Can tool, skill, agent, strategy, and memory be imported?

Yes. An import makes a declaration available for composition, but it never grants a handler, grant, secret, memory scope, agent caller, active trigger, or runtime authority. The importing project remains responsible for the manifest, profiles, run plan, supply-chain lock, and traces.

Why are show and ask forbidden in function?

A Touba function remains pure. show and ask are observable interactions with the user, so they belong to effectful blocks such as skill, agent, or strategy.

How do I display a value in a show message?

Use a text expression with concatenation and explicit conversion:

show
    with message as "Age prochain: " ++ text(next_age)

You can also write f"Age: {text(age)}". The f prefix enables interpolation; text(...) makes conversion explicit. See the syntax reference.

Why does ask not always read the terminal automatically?

To keep execution explicit and replayable. In the CLI, the host can provide answers with --user-inputs or request interactive mode with --interactive-user-inputs. In VS Code or another host application, the surface must provide user input to the runtime instead of leaving it implicit.

Why do two consecutive give statements not return two results?

A give terminates the current block. Instructions placed after a give, stop, or terminal branch are unreachable and must be rejected by Touba diagnostics. To return multiple pieces of information, define a result type that contains several fields and return one structured value.

Runtime, Manifest, and Project Preparation

Is the manifest discovered automatically by the runtime?

No. The runtime does not scan the project to guess a manifest. The manifest is provided explicitly, often after generation or update by touba prepare or touba manifest generate.

What is touba prepare for?

touba prepare prepares project artifacts without executing handlers: AIR, assembled manifest, run plan, binding fragments, dev/prod profiles, and handler skeletons according to the options used. It reduces manual configuration while keeping authority explicit.

What is a run plan?

A run plan explicitly describes how a project should be executed: module, entrypoint, profiles, manifest, secrets, lock, or other expected artifacts. It must not contain secrets or sensitive payloads.

What is a binding fragment?

A binding fragment describes part of a project's wiring, for example a handler or a resource. It must be assembled into a manifest before runtime. The runtime refuses unassembled fragments as a direct source of authority.

Does grants mean sandbox?

No. A grant is contract-level authorization verified by Touba Engine before dispatch. A binding can separately require sandbox.required: true; the runtime applies an available OS backend compatible with that policy, or refuses execution. See the platform requirements. Grants alone remain logical admission checks, not OS isolation.

What are payload constraints for?

Payload constraints (PC-1 / PC-2) add portable rules to the manifest: non-empty values, lengths, numeric bounds, and allowed values. The runtime can refuse an input or output before handler execution or before publishing the result.

What is handler supply-chain verification for?

Handler supply-chain verification (SC-1 / SC-2 / SC-3) checks consistency between AIR, manifest, handlers, SDK metadata, and handler_package identity through an explicit lock. It can also cover handler package files, declared dependency artifacts, provenance, and declared review. It is a guardrail against wiring drift and missing review discipline; it is not a signature or certification.

Handlers and SDK

Is the handler the main source of security?

No. The handler executes domain code. Touba Engine must refuse before handler execution when the required tool, grant, secret, memory scope, payload, caller, or lock is invalid. A handler can repeat checks as defense in depth, but it is not the primary authority.

Is a handler skeleton an SDK?

No. A skeleton is a starter file generated to help development. The SDK is the library that hides the handler protocol, exposes defineTool, provides ToubaEngine, and helps write structured decision providers.

Does the SDK replace the Touba runtime?

The SDK facilitates JavaScript or Python integration. The runtime remains the authority for AIR, manifests, secrets, scopes, payloads, agentic decisions, budgets, triggers, and traces.

Which SDK should I use?

Choose your application’s language: JavaScript with @touba/sdk, or Python with touba_sdk. Both provide handlers, ToubaEngine, providers and test helpers.

Secrets and Agents

Do agents see secrets?

No. Agents and prompts must not receive secret values. The runtime resolves handles, injects only granted secrets into the minimal environment of the authorized handler, and traces handle names, never values.

Must every key be exported for every test?

No. The secret resolution file states where each handle should be found: env, dotenv, or touba_store. A dev profile can recommend touba_store or .env, while a prod profile can point to env or another mechanism scoped later. Touba does not infer dev/prod behavior automatically.

Is an OpenAI key required to use Touba?

Choose the provider for your application: OpenAI, Anthropic, Gemini, or a provider adapted to your infrastructure. Compilation and deterministic workflows run without a model key. See the decision interfaces.

Can an agent choose multiple resources?

Yes, in a bounded sequential loop when a decision provider is configured. The runtime exposes the resources declared in uses, verifies or refuses each choice, executes the authorized capability, and returns a structured observation to the provider if the loop continues.

What is the difference between human.approve and agent-requested review?

human.approve is a barrier written in the program. Agent-requested review is a dynamic action proposed by the provider during execution. In both cases, the runtime traces the pause and resumes only with an explicit decision.

Memory and Resources

Is memory a database?

No. A memory is a logical Touba resource. A PostgreSQL database, HTTP service, or another backend can perform memory access through authorized handlers and an explicit resource binding.

Is PostgreSQL a native Touba memory backend?

No. The PostgreSQL scenario demonstrates controlled integration with a real host backend: read/write scopes, resource binding, secret handle, SDK handler, refusals before external effects, and traces. A Touba memory remains a logical resource; PostgreSQL remains a host backend connected by handler.

Are memory read and write permissions separated?

Yes. Touba validates read and write scopes separately. An agent or tool authorized to read does not automatically receive write permission.

Triggers

Are triggers real?

Yes. Touba covers schedule -> strategy with an explicit foreground runner and request -> strategy with a webhook service, durable queue, typed payload mapping, and optional HMAC signatures. Both paths go through AIR, manifest, limits, TD-1 state, and trigger_* traces.

Do triggers already cover webhooks, queues, or a permanent daemon?

Yes for the webhook, the durable touba-trigger-queue-v1 queue, bounded retries, and the explicit service started by touba trigger serve. Distributed schedulers, distributed queues, cloud ingress, and system supervision are deployment layers.

Documentation and Surfaces

Is VS Code the only way to use Touba?

No. VS Code is a convenient surface for editing, diagnostics, and inspection. The CLI and Touba artifacts remain the reference path for compiling, preparing, running, auditing, and validating.