Prompts
Reference for client.prompts in the Future AGI Python and TypeScript SDKs: prompts.add_draft, prompts.commit, prompts.create, prompts.create_draft, prompts.delete, prompts.generate and 16 more.
client.prompts on fi.Client (Python) and client.prompts on Client from @future-agi/sdk (TypeScript), with the nested resources client.prompts.labels, client.prompts.versions. The models these methods return are on Prompts response models; how arguments, pagination, errors and strict mode work is in the overview.
Methods
| Method | Description |
|---|---|
prompts.add_draft | Add new draft versions to a prompt template. |
prompts.commit | Commit the current draft of a prompt template as a named version, optionally making it the default. |
prompts.create | Create a prompt template in the current workspace. |
prompts.create_draft | Create a prompt template together with its first draft version (messages, model configuration, variables). |
prompts.delete | Delete a prompt template and all its versions. |
prompts.generate | Generate a prompt from a plain-language statement of what it should do. |
prompts.get | Open a prompt template by its identifier, creating its workbench draft if needed. |
prompts.get_by_name | Fetch a prompt template by name; the default version unless version is given. |
prompts.history | List past prompt executions, optionally for one template. |
prompts.improve | Rewrite an existing prompt according to the given improvement requirements. |
prompts.list | List prompt templates available in the current workspace. |
prompts.run | Run a configured prompt version by supplying version and is_run=“prompt”. |
prompts.run_status | Read workbench prompt execution status and outputs. |
prompts.update | Update selected fields on an existing prompt template. |
prompts.labels.assign | Assign a label to one version of a prompt template. |
prompts.labels.create | Create a prompt label. |
prompts.labels.for_template | List the labels assigned to a prompt template’s versions. |
prompts.labels.get_template | Fetch the prompt template version a label points to, by template name and label (or version). |
prompts.labels.list | List prompt labels (e.g. |
prompts.labels.remove | Remove a label from a prompt template version. |
prompts.labels.set_default | Make a version the default for a prompt template, by template name. |
prompts.versions.list | List versions of a prompt template. |
client.prompts
prompts.add_draft
Add new draft versions to a prompt template. Each entry carries prompt_config, variable_names, evaluation_configs, metadata and placeholders.
/model-hub/prompt-templates/{id}/add-new-draft/ result = client.prompts.add_draft("your-id", new_prompts=[])const result = await client.prompts.addDraft("your-id", { new_prompts: [] }); Signature
client.prompts.add_draft(
id: str,
*,
new_prompts: list[dict[str, Any]],
extra_query: dict[str, Any] | None = None,
extra_body: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> Anyclient.prompts.addDraft(id: string, params: PromptsAddDraftParams, options?: RequestOptions): Promise<unknown>
export interface PromptsAddDraftParams {
new_prompts: Array<Record<string, unknown>>;
} Parameters
A UUID string identifying this prompt template.
Returns
The decoded response. The contract does not describe its shape, so it is untyped.
prompts.commit
Commit the current draft of a prompt template as a named version, optionally making it the default.
/model-hub/prompt-templates/{id}/commit/ result = client.prompts.commit("your-id", version_name="your-version-name")const result = await client.prompts.commit("your-id", { version_name: "your-version-name" }); Signature
client.prompts.commit(
id: str,
*,
version_name: str,
message: str | None | NotGiven = NOT_GIVEN,
set_default: bool | None | NotGiven = NOT_GIVEN,
is_draft: bool | None | NotGiven = NOT_GIVEN,
metadata: dict[str, Any] | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
extra_body: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> Anyclient.prompts.commit(id: string, params: PromptsCommitParams, options?: RequestOptions): Promise<unknown>
export interface PromptsCommitParams {
version_name: string;
message?: string | null;
set_default?: boolean | null;
is_draft?: boolean | null;
metadata?: Record<string, unknown> | null;
} Parameters
A UUID string identifying this prompt template.
Returns
The decoded response. The contract does not describe its shape, so it is untyped.
prompts.create
Create a prompt template in the current workspace.
/model-hub/prompt-templates/ MCP tool: create_prompt_template
result = client.prompts.create(name="your-name")const result = await client.prompts.create({ name: "your-name" }); Signature
client.prompts.create(
*,
name: str,
description: str | None | NotGiven = NOT_GIVEN,
variable_names: dict[str, Any] | None | NotGiven = NOT_GIVEN,
prompt_folder: str | None | NotGiven = NOT_GIVEN,
placeholders: dict[str, Any] | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
extra_body: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> models.PromptTemplateclient.prompts.create(params: PromptsCreateParams, options?: RequestOptions): Promise<models.PromptTemplate>
export interface PromptsCreateParams {
name: string;
description?: string | null;
variable_names?: Record<string, unknown> | null;
prompt_folder?: string | null;
placeholders?: Record<string, unknown> | null;
} Parameters
Returns
prompts.create_draft
Create a prompt template together with its first draft version (messages, model configuration, variables).
/model-hub/prompt-templates/create-draft/ result = client.prompts.create_draft(name="your-name", prompt_config=[])const result = await client.prompts.createDraft({
name: "your-name",
prompt_config: [],
}); Signature
client.prompts.create_draft(
*,
name: str,
prompt_config: list[dict[str, Any]],
variable_names: dict[str, Any] | None | NotGiven = NOT_GIVEN,
evaluation_configs: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN,
metadata: dict[str, Any] | None | NotGiven = NOT_GIVEN,
placeholders: dict[str, Any] | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
extra_body: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> models.PromptTemplateclient.prompts.createDraft(params: PromptsCreateDraftParams, options?: RequestOptions): Promise<models.PromptTemplate>
export interface PromptsCreateDraftParams {
name: string;
prompt_config: Array<Record<string, unknown>>;
variable_names?: Record<string, unknown> | null;
evaluation_configs?: Array<Record<string, unknown>> | null;
metadata?: Record<string, unknown> | null;
placeholders?: Record<string, unknown> | null;
} Parameters
Returns
prompts.delete
Delete a prompt template and all its versions.
/model-hub/prompt-templates/{id}/ result = client.prompts.delete("your-id")const result = await client.prompts.delete("your-id"); Signature
client.prompts.delete(
id: str,
*,
extra_query: dict[str, Any] | None = None,
extra_body: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> Anyclient.prompts.delete(id: string, options?: RequestOptions): Promise<unknown> Parameters
A UUID string identifying this prompt template.
Returns
The decoded response. The contract does not describe its shape, so it is untyped.
prompts.generate
Generate a prompt from a plain-language statement of what it should do.
/model-hub/prompt-templates/generate-prompt/ result = client.prompts.generate(statement="your-statement")const result = await client.prompts.generate({ statement: "your-statement" }); Signature
client.prompts.generate(
*,
statement: str,
extra_query: dict[str, Any] | None = None,
extra_body: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> Anyclient.prompts.generate(params: PromptsGenerateParams, options?: RequestOptions): Promise<unknown>
export interface PromptsGenerateParams {
statement: string;
} Parameters
Returns
The decoded response. The contract does not describe its shape, so it is untyped.
prompts.get
Open a prompt template by its identifier, creating its workbench draft if needed.
/model-hub/prompt-templates/{id}/ MCP tool: get_prompt_template
result = client.prompts.get("your-id")const result = await client.prompts.get("your-id"); Signature
client.prompts.get(
id: str,
*,
extra_query: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> models.PromptTemplateclient.prompts.get(id: string, options?: RequestOptions): Promise<models.PromptTemplate> Parameters
A UUID string identifying this prompt template.
Returns
prompts.get_by_name
Fetch a prompt template by name; the default version unless version is given.
/model-hub/prompt-templates/get-template-by-name/ result = client.prompts.get_by_name()const result = await client.prompts.getByName(); Signature
client.prompts.get_by_name(
*,
name: str | None | NotGiven = NOT_GIVEN,
version: str | None | NotGiven = NOT_GIVEN,
created_at: str | None | NotGiven = NOT_GIVEN,
search: str | None | NotGiven = NOT_GIVEN,
ordering: str | None | NotGiven = NOT_GIVEN,
page: int | None | NotGiven = NOT_GIVEN,
limit: int | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> Anyclient.prompts.getByName(params: PromptsGetByNameParams = {}, options?: RequestOptions): Promise<unknown>
export interface PromptsGetByNameParams {
name?: string | null;
version?: string | null;
created_at?: string | null;
/** A search term. */
search?: string | null;
/** Which field to use when ordering the results. */
ordering?: string | null;
/** A page number within the paginated result set. */
page?: number | null;
/** Number of results to return per page. */
limit?: number | null;
} Parameters
A search term.
Which field to use when ordering the results.
A page number within the paginated result set.
Number of results to return per page.
Returns
The decoded response. The contract does not describe its shape, so it is untyped.
prompts.history
List past prompt executions, optionally for one template.
/model-hub/prompt-history-executions/ Paginated: returns a pager (how pagination works)
for item in client.prompts.history():
print(item)for await (const item of client.prompts.history()) {
console.log(item);
} Signature
client.prompts.history(
*,
template_name: str | None | NotGiven = NOT_GIVEN,
template_version: str | None | NotGiven = NOT_GIVEN,
created_at: str | None | NotGiven = NOT_GIVEN,
search: str | None | NotGiven = NOT_GIVEN,
ordering: str | None | NotGiven = NOT_GIVEN,
limit: int | None | NotGiven = NOT_GIVEN,
template_id: str | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> SyncPager[models.PromptHistoryExecution]client.prompts.history(params: PromptsHistoryParams = {}, options?: RequestOptions): Pager<models.PromptHistoryExecution>
export interface PromptsHistoryParams {
template_name?: string | null;
template_version?: string | null;
created_at?: string | null;
/** A search term. */
search?: string | null;
/** Which field to use when ordering the results. */
ordering?: string | null;
/** Number of results to return per page. */
limit?: number | null;
template_id?: string | null;
} Parameters
A search term.
Which field to use when ordering the results.
Number of results to return per page.
The pager sends page itself; pass limit to change the page size.
Returns
A pager of PromptHistoryExecution items: iterate it, or call to_list() (Python) / toArray() (TypeScript).
prompts.improve
Rewrite an existing prompt according to the given improvement requirements.
/model-hub/prompt-templates/improve-prompt/ result = client.prompts.improve(existing_prompt="your-existing-prompt", improvement_requirements="your-improvement-requirements")const result = await client.prompts.improve({
existing_prompt: "your-existing-prompt",
improvement_requirements: "your-improvement-requirements",
}); Signature
client.prompts.improve(
*,
existing_prompt: str,
improvement_requirements: str,
extra_query: dict[str, Any] | None = None,
extra_body: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> Anyclient.prompts.improve(params: PromptsImproveParams, options?: RequestOptions): Promise<unknown>
export interface PromptsImproveParams {
existing_prompt: string;
improvement_requirements: string;
} Parameters
Returns
The decoded response. The contract does not describe its shape, so it is untyped.
prompts.list
List prompt templates available in the current workspace.
/model-hub/prompt-templates/ Paginated: returns a pager (how pagination works) · MCP tool: list_prompt_templates
for item in client.prompts.list():
print(item)for await (const item of client.prompts.list()) {
console.log(item);
} Signature
client.prompts.list(
*,
name: str | None | NotGiven = NOT_GIVEN,
version: str | None | NotGiven = NOT_GIVEN,
created_at: str | None | NotGiven = NOT_GIVEN,
search: str | None | NotGiven = NOT_GIVEN,
ordering: str | None | NotGiven = NOT_GIVEN,
limit: int | None | NotGiven = NOT_GIVEN,
modality: list[str] | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> SyncPager[models.PromptTemplate]client.prompts.list(params: PromptsListParams = {}, options?: RequestOptions): Pager<models.PromptTemplate>
export interface PromptsListParams {
name?: string | null;
version?: string | null;
created_at?: string | null;
/** A search term. */
search?: string | null;
/** Which field to use when ordering the results. */
ordering?: string | null;
/** Number of results to return per page. */
limit?: number | null;
modality?: Array<string> | null;
} Parameters
A search term.
Which field to use when ordering the results.
Number of results to return per page.
The pager sends page itself; pass limit to change the page size.
Returns
A pager of PromptTemplate items: iterate it, or call to_list() (Python) / toArray() (TypeScript).
prompts.run
Run a configured prompt version by supplying version and is_run=“prompt”. Optionally replace prompt_config or variable_names. Returns an asynchronous receipt; read get_prompt_run with template_version for status and output.
/model-hub/prompt-templates/{id}/run_template/ MCP tool: run_prompt
result = client.prompts.run("your-id")const result = await client.prompts.run("your-id"); Signature
client.prompts.run(
id: str,
*,
name: str | None | NotGiven = NOT_GIVEN,
version: str | None | NotGiven = NOT_GIVEN,
prompt_config: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN,
variable_names: dict[str, Any] | None | NotGiven = NOT_GIVEN,
placeholders: Any | None | NotGiven = NOT_GIVEN,
evaluation_configs: list[Any] | None | NotGiven = NOT_GIVEN,
source: str | None | NotGiven = NOT_GIVEN,
is_run: Any | None | NotGiven = NOT_GIVEN,
is_sdk: bool | None | NotGiven = NOT_GIVEN,
run_index: int | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
extra_body: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> models.PromptsRunResultclient.prompts.run(id: string, params: PromptsRunParams = {}, options?: RequestOptions): Promise<models.PromptsRunResult>
export interface PromptsRunParams {
name?: string | null;
version?: string | null;
prompt_config?: Array<Record<string, unknown>> | null;
variable_names?: Record<string, unknown> | null;
placeholders?: JsonValue | null;
evaluation_configs?: Array<JsonValue> | null;
source?: string | null;
is_run?: JsonValue | null;
is_sdk?: boolean | null;
run_index?: number | null;
} Parameters
A UUID string identifying this prompt template.
Returns
prompts.run_status
Read workbench prompt execution status and outputs. Supply template_version matching the version returned by run_prompt to read that version, otherwise the API chooses the default/latest version.
/model-hub/prompt-templates/{id}/get-run-status/ MCP tool: get_prompt_run
result = client.prompts.run_status("your-id")const result = await client.prompts.runStatus("your-id"); Signature
client.prompts.run_status(
id: str,
*,
template_version: str | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> models.PromptRunStatusResultclient.prompts.runStatus(id: string, params: PromptsRunStatusParams = {}, options?: RequestOptions): Promise<models.PromptRunStatusResult>
export interface PromptsRunStatusParams {
template_version?: string | null;
} Parameters
A UUID string identifying this prompt template.
Returns
prompts.update
Update selected fields on an existing prompt template.
/model-hub/prompt-templates/{id}/ MCP tool: update_prompt_template
result = client.prompts.update("your-id")const result = await client.prompts.update("your-id"); Signature
client.prompts.update(
id: str,
*,
name: str | None | NotGiven = NOT_GIVEN,
description: str | None | NotGiven = NOT_GIVEN,
variable_names: dict[str, Any] | None | NotGiven = NOT_GIVEN,
prompt_folder: str | None | NotGiven = NOT_GIVEN,
placeholders: dict[str, Any] | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
extra_body: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> models.PromptTemplatePatchclient.prompts.update(id: string, params: PromptsUpdateParams = {}, options?: RequestOptions): Promise<models.PromptTemplatePatch>
export interface PromptsUpdateParams {
name?: string | null;
description?: string | null;
variable_names?: Record<string, unknown> | null;
prompt_folder?: string | null;
placeholders?: Record<string, unknown> | null;
} Parameters
A UUID string identifying this prompt template.
Returns
client.prompts.labels
TypeScript: client.prompts.labels.
prompts.labels.assign
Assign a label to one version of a prompt template.
/model-hub/prompt-labels/{template_id}/{label_id}/assign-label-by-id/ result = client.prompts.labels.assign(
"your-template-id",
"your-label-id",
version="your-version",
)const result = await client.prompts.labels.assign("your-template-id", "your-label-id", { version: "your-version" }); Signature
client.prompts.labels.assign(
template_id: str,
label_id: str,
*,
version: str,
extra_query: dict[str, Any] | None = None,
extra_body: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> Anyclient.prompts.labels.assign(templateId: string, labelId: string, params: PromptsLabelsAssignParams, options?: RequestOptions): Promise<unknown>
export interface PromptsLabelsAssignParams {
version: string;
} Parameters
Positional argument template_id.
Positional argument label_id.
Returns
The decoded response. The contract does not describe its shape, so it is untyped.
prompts.labels.create
Create a prompt label.
/model-hub/prompt-labels/ result = client.prompts.labels.create(name="your-name", type="system")const result = await client.prompts.labels.create({
name: "your-name",
type: "system",
}); Signature
client.prompts.labels.create(
*,
name: str,
type: Literal['system', 'custom'],
metadata: dict[str, Any] | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
extra_body: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> models.PromptLabelclient.prompts.labels.create(params: PromptsLabelsCreateParams, options?: RequestOptions): Promise<models.PromptLabel>
export interface PromptsLabelsCreateParams {
name: string;
type: "system" | "custom";
metadata?: Record<string, unknown> | null;
} Parameters
systemcustom Returns
prompts.labels.for_template
List the labels assigned to a prompt template’s versions.
/model-hub/prompt-labels/template-labels/ result = client.prompts.labels.for_template()const result = await client.prompts.labels.forTemplate(); Signature
client.prompts.labels.for_template(
*,
page: int | None | NotGiven = NOT_GIVEN,
limit: int | None | NotGiven = NOT_GIVEN,
template_id: str | None | NotGiven = NOT_GIVEN,
template_name: str | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> Anyclient.prompts.labels.forTemplate(params: PromptsLabelsForTemplateParams = {}, options?: RequestOptions): Promise<unknown>
export interface PromptsLabelsForTemplateParams {
/** A page number within the paginated result set. */
page?: number | null;
/** Number of results to return per page. */
limit?: number | null;
template_id?: string | null;
template_name?: string | null;
} Parameters
A page number within the paginated result set.
Number of results to return per page.
Returns
The decoded response. The contract does not describe its shape, so it is untyped.
prompts.labels.get_template
Fetch the prompt template version a label points to, by template name and label (or version).
/model-hub/prompt-labels/get-by-name/ result = client.prompts.labels.get_template()const result = await client.prompts.labels.getTemplate(); Signature
client.prompts.labels.get_template(
*,
page: int | None | NotGiven = NOT_GIVEN,
limit: int | None | NotGiven = NOT_GIVEN,
name: str | None | NotGiven = NOT_GIVEN,
label: str | None | NotGiven = NOT_GIVEN,
version: str | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> Anyclient.prompts.labels.getTemplate(params: PromptsLabelsGetTemplateParams = {}, options?: RequestOptions): Promise<unknown>
export interface PromptsLabelsGetTemplateParams {
/** A page number within the paginated result set. */
page?: number | null;
/** Number of results to return per page. */
limit?: number | null;
name?: string | null;
label?: string | null;
version?: string | null;
} Parameters
A page number within the paginated result set.
Number of results to return per page.
Returns
The decoded response. The contract does not describe its shape, so it is untyped.
prompts.labels.list
List prompt labels (e.g. production, staging) in the organization.
/model-hub/prompt-labels/ Paginated: returns a pager (how pagination works)
for item in client.prompts.labels.list():
print(item)for await (const item of client.prompts.labels.list()) {
console.log(item);
} Signature
client.prompts.labels.list(
*,
limit: int | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> SyncPager[models.PromptLabel]client.prompts.labels.list(params: PromptsLabelsListParams = {}, options?: RequestOptions): Pager<models.PromptLabel>
export interface PromptsLabelsListParams {
/** Number of results to return per page. */
limit?: number | null;
} Parameters
Number of results to return per page.
The pager sends page itself; pass limit to change the page size.
Returns
A pager of PromptLabel items: iterate it, or call to_list() (Python) / toArray() (TypeScript).
prompts.labels.remove
Remove a label from a prompt template version.
/model-hub/prompt-labels/remove/ result = client.prompts.labels.remove(label_id="your-label-id", version_id="your-version-id")const result = await client.prompts.labels.remove({
label_id: "your-label-id",
version_id: "your-version-id",
}); Signature
client.prompts.labels.remove(
*,
label_id: str,
version_id: str,
extra_query: dict[str, Any] | None = None,
extra_body: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> Anyclient.prompts.labels.remove(params: PromptsLabelsRemoveParams, options?: RequestOptions): Promise<unknown>
export interface PromptsLabelsRemoveParams {
label_id: string;
version_id: string;
} Parameters
Returns
The decoded response. The contract does not describe its shape, so it is untyped.
prompts.labels.set_default
Make a version the default for a prompt template, by template name.
/model-hub/prompt-labels/set-default/ result = client.prompts.labels.set_default(template_name="your-template-name", version="your-version")const result = await client.prompts.labels.setDefault({
template_name: "your-template-name",
version: "your-version",
}); Signature
client.prompts.labels.set_default(
*,
template_name: str,
version: str,
extra_query: dict[str, Any] | None = None,
extra_body: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> Anyclient.prompts.labels.setDefault(params: PromptsLabelsSetDefaultParams, options?: RequestOptions): Promise<unknown>
export interface PromptsLabelsSetDefaultParams {
template_name: string;
version: string;
} Parameters
Returns
The decoded response. The contract does not describe its shape, so it is untyped.
client.prompts.versions
TypeScript: client.prompts.versions.
prompts.versions.list
List versions of a prompt template.
/model-hub/prompt-templates/{id}/versions/ Paginated: returns a pager (how pagination works) · MCP tool: list_prompt_versions
for item in client.prompts.versions.list("your-id"):
print(item)for await (const item of client.prompts.versions.list("your-id")) {
console.log(item);
} Signature
client.prompts.versions.list(
id: str,
*,
limit: int | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> SyncPager[Any]client.prompts.versions.list(id: string, params: PromptsVersionsListParams = {}, options?: RequestOptions): Pager<unknown>
export interface PromptsVersionsListParams {
limit?: number | null;
} Parameters
A UUID string identifying this prompt template.
The pager sends page itself; pass limit to change the page size.
Returns
The decoded response. The contract does not describe its shape, so it is untyped.
Questions & Discussion