agentlang
Version:
The easiest way to build the most reliable AI agents - enterprise-grade teams of AI agents that collaborate with each other and humans
52 lines • 20.4 kB
TypeScript
import { IfPattern } from '../../language/syntax.js';
export declare const PlannerInstructions = "Agentlang is a very-high-level declarative language that makes it easy to define business applications as 'models'.\nThe model of a business application consists of entity definitions and workflows defined in \"modules\". \nA module is be encoded in a syntax inspired by JavaScript and JSON. Example of a simple module follows:\n\nmodule Erp\n\nentity Employee {\n employeeId UUID @id @default(uuid()),\n firstName String,\n lastName String,\n salary Number,\n email Email @indexed\n}\n\nThe Empoyee entity is part of the \"Erp\" module and it has four attributes: 'employeeId', 'firstName', 'lastName', 'salary' and 'email'. \nThe 'employeeId' attribute uniquely identifies an instance of the Employee entity and it's automatically filled-in by the system by calling the \"uuid()\" function. \nIn the place of the keyword 'entity', the keyword 'record' may also be used. The difference between an entity and a record is that, \ninstances of an entity is persisted to the database, instances of records are not.\n\nThis is an example of a record:\n\nrecord EmailMessage {\n to Email,\n from Email,\n subject String,\n body String\n}\n\nAnother major construct in Agentlang is the 'workflow'. Workflows contains JSON \"patterns\" that perform CRUD operations on entities. \nFor example, here's is a workflow that creates a new instance of the Employee entity:\n\nworkflow CreateEmployee {\n {Erp/Employee {firstName CreateEmployee.firstName,\n lastName CreateEmployee.lastName,\n salary CreateEmployee.salary,\n email CreateEmployee.email}}\n}\n\nThe attribute-values of the new Employee are derived from the \"event\" that triggers the workflow. In this example the event is called \"CreateEmployee\".\nAn event need not have an explicit schema, because its attributes can always be inferred from the workflow definition. But a model may also contain\nexplicit definitions of events, as follows,\n\nevent CreateEmployee {\n firstName String,\n lastName String,\n salary Number,\n email Email\n}\n\nA workflow attached to an event is invoked by creating an instance of the event, e.g:\n\n{Erp/CreateEmployee {firstName \"Sam\", lastName \"K\", salary 1400, email \"samk@acme.com\"}}\n\nThis means a workflow can be invoked from another workflow, simply by having the event-creation pattern.\n\nOther than the create-pattern for entities and events, some of the most useful patterns (related to entities) that can appear in a workflow are:\n1. Query - e.g: '{Erp/Employee {employeeId? \"56392e13-0d9a-42f7-b556-0d7cd9468a24\"}}'. The attributes by which the query happens must end with a '?' character.\n To lookup all instances of an entity, use the syntax: '{EntityName?: {}}'.\n2. Update - e.g: '{Erp/Employee {employeeId? \"56392e13-0d9a-42f7-b556-0d7cd9468a24\", firstName \"Joe\"}}'. This pattern updates the firstName of the employee\n with the given employeeId.\n3. Upsert - e.g: '{Erp/Employee {employeeId \"56392e13-0d9a-42f7-b556-0d7cd9468a24\", firstName \"Joe\"}, @upsert}'. The 'upsert' pattern will create a new\n instance, if the instance does not already exist.\n4. Delete - e.g: 'delete {Erp/Employee {employeeId? \"56392e13-0d9a-42f7-b556-0d7cd9468a24\"}}'\n\nThe default query operator is equals. So an expression like 'employeeId? \"56392e13-0d9a-42f7-b556-0d7cd9468a24\"' means,\n'where employeeId equals \"56392e13-0d9a-42f7-b556-0d7cd9468a24\"'. Other comparison operators has to be specified explicitly, as in\n'{age?< 50}' - which means 'where age less-than 50'. The comparison operators supported by a query pattern are:\n\n!= - not-equals\n< - less-than\n<= - less-than or equals\n> - greater-than\n>= - greater-than or equals\nin - membership check (argument must be an array)\nlike - string-ends-with?\nbetween - between given values (argument must be an array)\n\nTwo comparison expressions can be combined together by the logical operators 'or' and 'and'. The comparison and logical expressions produce a boolean\nresult, represented by 'true' or 'false'. A boolean value can be inversed by using the 'not' expression, e.g: 'not(some-value)'\n\nIn addition to the basic CRUD patterns, you can execute conditional-logic with the help of the 'if' pattern. An example follows,\n\nworkflow IncrementSalary {\n if (IncrementSalary.percentage > 10) {\n {Erp/Employee {employeeId IncrementSalary.employeeId, salary salary + salary * IncrementSalary.percentage}}\n } else {\n {Erp/Employee {employeeId IncrementSalary.employeeId, salary salary + 1500}}\n }\n}\n\nNote the value passed to the 'salary' attribute - it's an arithmetic expression. All normal arithmetic expressions are supported by workflow patterns.\n\nAnother example of the 'if' pattern:\n\nworkflow validateLicense {\n {checkLicenseNumber {number validateLicense.number}} @as response;\n if (response == \"ok\") {\n {license {number? validateLicense.number, status \"active\"}}\n } else {\n {license {number? validateLicense.number, status \"canceled\"}}\n }\n}\n\nAlso note the use of the '@as' keyword - this binds the result of a pattern to an 'alias'.\n\nA successful query pattern will return an array of instances. The 'for' pattern can be used to iterate over an array. An example follows:\n\nworkflow NotifyEmployees {\n {Erp/Employee {salary?> 1000}} @as employees;\n for emp in employees {\n {Erp/SendMail {email emp.email, body \"You are selected for an increment!\"}}\n }\n}\n\nHere the result of the query is bound to the alias named 'employees'. Any pattern can have an alias, including 'if' and 'for'. An alias can be used to refer to the attributes of the instance, \nvia the dot(.) notation. Aliases can also be used to destructure a query result - here's an example:\n\nworkflow FindFirstTwoEmployees {\n {Erp/Employee {salary?> 1000}} @as [emp1, emp2];\n [emp1, emp2]\n}\n\nThis alias will bind the first two instances to 'a' and 'b' and the rest of the instances to an array named 'xs':\n\n{SomeEntity {id?> 1}} @as [a, b, _, xs]\n\nExamples of binding aliases to 'if' and 'for':\n\nif (IncrementSalary.percentage > 10) {\n {Erp/Employee {employeeId IncrementSalary.employeeId, salary salary + salary * IncrementSalary.percentage}}\n} else {\n {Erp/Employee {employeeId IncrementSalary.employeeId, salary salary + 1500}}\n} @as emp\n\nfor emp in employees {\n {Erp/SendMail {email emp.email, body \"You are selected for an increment!\"}}\n} @as emails\n\nMake sure all references based on a preceding pattern is based either on an actual alias or the name of the workflow. For example, the following sequence of patterns\nare invalid, because the alias 'employee' is not defined:\n\n{Employee {id? 101}};\n{SendEmail {to employee.email, body \"hello\"}}\n\nA fix for the reference-error is shown below:\n\n{Employee {id? 101}} @as [employee];\n{SendEmail {to employee.email, body \"hello\"}}\n\nNote that the alias for the query is '[employee]' so that the resultset is destructured to select exactly one instance of Employee \nselected into the reference. You must follow this pattern if your goal is to select exactly a single instance.\n\nKeep in mind that the only valid syntax for the 'if' condition is:\n\nif (<expr>) {\n <patterns>\n} else if (<expr>) {\n <patterns>\n} else {\n <patterns>\n}\n\nThe following usage is NOT valid:\n\n<pattern> if (<expr>)\n\nA pattern may execute asynchronously and its eventual result can be handled by patterns provided in the '@then' clause. An example is shown below:\n\n{sendChatMessage {to \"amy\", \"text\" \"hello\"}} @as response @then {\n {saveResponse {from \"amy\", \"text\" response}}\n}\n\nIf you are instructed that a particular event will be called asynchronously, always provide the patterns that follows in its '@then' clause. You must add the \n'@then' clause only if an event's documentation or instruction explicitly requires to do so.\n\nEntities in a module can be connected together in relationships. There are two types of relationships - 'contains' and 'between'.\n'Contains' relationship is for hierarchical data, as in a Library entity containing Books. 'Between' relationship is for graph-like data,\nlike two Profiles in a social media app is connected as friends. A 'between' relationship can be one of the following three types - 'one_one' (one-to-one),\n'one_many' (one-to-many) and 'many_many' (many-to-many), which is the default.\n\nThe following example shows how additional profile data for an employee could be defined as a new entity and attached to the Employee entity as a between-relationship:\n\nentity Profile {\n id UUID @id @default(uuid()),\n address String @optional,\n photo URL @optional,\n dateOfBirth DateTime @optional\n}\n\nrelationship EmployeeProfile between (Erp/Employee, Erp/Profile) @one_one\n\nThe '@one_one' annotation means exactly one Employee and Profile can be related to each other via 'EmployeeProfile'.\n\nHere's the 'CreateEmployee' workflow updated to create the Employee with the his/her Profile attached:\n\nworkflow CreateEmployee {\n {Erp/Employee {firstName CreateEmployee.firstName,\n lastName CreateEmployee.lastName,\n salary CreateEmployee.salary,\n email CreateEmployee.email},\n Erp/EmployeeProfile {Erp/Profile {address CreateEmployee.address,\n photo CreateEmployee.photo,\n dateOfBirth CreateEmployee.dateOfBirth}}}\n}\n\nThe following pattern can be user to query an Employee along with his Profile:\n\n{Erp/Employee {employeeId? \"56392e13-0d9a-42f7-b556-0d7cd9468a24\"},\n Erp/EmployeeProfile {Erp/Profile? {}}}\n\nAs an example of 'contains' relaionships, consider modelling task-assignments for an Employee as folllows:\n\nentity TaskAssignment {\n id UUID @id @default(uuid()),\n description String,\n assignmentDate DateTime @default(now())\n}\n\nrelationship EmployeeTaskAssignment contains (Erp/Employee, Erp/TaskAssignment)\n\nThe following workflow shows how to assign a new task to an Employee:\n\nworkflow AssignNewTask {\n {Erp/Employee {employeeId? AssignNewTask.employeeId},\n Erp/EmployeeTaskAssignment {Erp/TaskAssignment {description AssignNewTask.description}}}\n}\n\nThe following workflow queries an Employee along with all his tasks:\n\nworkflow GetEmployeeTaskAssignments {\n {Erp/Employee {employeeId? GetEmployeeTaskAssignments.employeeId},\n Erp/EmployeeTaskAssignment {Erp/TaskAssignment? {}}}\n}\n\nA general rule regarding generating workflows - as much as possible, do not include references to the workflow event in the patterns. Try to\nfill-in values from the available context. For example, if your instruction is \"create a workflow to send an email to employee 101 with this message - \n'please call me as soon as possible'\", the best workflow to return is:\n\nworkflow sendEmail {\n {employee {id? 101}} @as emp;\n {email {to emp.email body \"please call me as soon as possible\"}}\n}\n\nbecause all the information needed is available in the context. If the instruction is \"create a workflow to send an email by employee-id with this message - \n'please call me as soon as possible'\", then you can return:\n\nworkflow sendEmail {\n {employee {id? sendEmail.employeeId}} @as emp;\n {email {to emp.email body \"please call me as soon as possible\"}}\n}\n\nThe point is, use the immediate context to fill-in values in generated patterns, as much as possible.\n\nAlso generate a workflow only if required explicitly by the user or the contextual information is incomplete. Otherwise, just return an array of patterns.\nAs an example, if the user request is \"send an email to employee 101 with this message - 'please call me as soon as possible'\", you must return:\n\n[{employee {id? 101}} @as emp;\n {email {to emp.email, body \"please call me as soon as possible\"}}]\n\nYou MUST separate each pattern in the array with a semi-colon (;) and never use a comma (,) for this purpose.\n\nNow consider the following module definition and generate appropriate patterns in response to the user instructions. You must return only valid patterns or workflows,\nno other descriptive text or comments are needed.\n";
export declare const FlowExecInstructions = "The following is the textual representation of a flowchart. \n\ncheckOrder --> \"ProductA\" acceptOrder\ncheckOrder --> \"ProductB\" acceptOrder\ncheckOrder --> \"ProductC\" rejectOrder\nacceptOrder --> sendPaymentLinkToCustomer\nrejectOrder --> sendRejectionEmailToCustomer\n\nAlong with this flowchart, you'll be passed a \"context\", which contain the steps in the flowchart that was executed so far, along with\ntheir results. Based on the context, you need to return the name of the step that needs to execute next. If you have reached the end\nof the chart, return 'DONE'. \n\nAt the beginning of the execution, the context will contain only the order information, say something like:\n\nOrderNo: 101, Item: \"ProductB\", customerEmail: \"manager@acme.com\"\n\nThis means you have to return 'checkOrder' as the next step (i.e you move the root node of the flowchart).\nAfter the step checkOrder executes, you'll be passed the following context:\n\norderNo: 101, Item: \"ProductB\", customerEmail: \"manager@acme.com\"\ncheckOrder --> \"ProductB\"\n\nNow you can infer from the context that if the result of checkOrder is either \"ProductA\" or \"ProductB\", you must move to the step 'acceptOrder'.\nSo you return 'acceptOrder'. After this, you'll return the updated context as:\n\nOrderNo: 101, Item: \"ProductB\", customerEmail: \"manager@acme.com\"\ncheckOrder --> \"ProductB\"\nacceptOrder --> {orderNo: 101, customerEmail: \"manager@acme.com\", acceptedOn: \"2025-07-01\"}\n\nYou see that 'acceptOrder' has produced the result '{orderNo: 101, customerEmail: \"manager@acme.com\", acceptedOn: \"2025-07-01\"}' - but from the flowchart you know that, whatever the result of 'acceptOrder',\nyou have to move to the 'sendPaymentLinkToCustomer' step and so you return 'sendPaymentLinkToCustomer'.\n\nThe next context you'll see will be:\n\nOrderNo: 101, Item: \"ProductB\", customerEmail: \"manager@acme.com\"\ncheckOrder --> \"ProductB\"\nacceptOrder --> {orderNo: 101, customerEmail: \"manager@acme.com\", acceptedOn: \"2025-07-01\"}\nsendPaymentLinkToCustomer --> \"manager@acme.com\"\n\nThe 'sendPaymentLinkToCustomer' has returned the customer email. You look at the flowchart and detect that, whatever the return value of\n'sendPaymentLinkToCustomer' there is nothing else to do. So you return 'DONE'.\n\nGenerally a flowchart has the following two types of entries:\n 1. a --> b, meaning after step 'a' do step 'b'.\n 2. a --> \"x\" b - this means if 'a' returns the string \"x\", then do step 'b'.\nIf you detect that you have reached the end of the chart, return 'DONE'. Otherwise, return only the name of the next step. Never return\nany additional description, direction or comments.\n\nNote that a flow-step could be represented as a simple name, like 'checkOrder' or a complex object as in '{sendPaymentLinkToCustomer: {email: acceptOrder.customerEmail}}'.\nAlways return the full-specification of the flow-step; if it's a name - return the name, if it's an object - return the object.\n";
export declare const DecisionAgentInstructions = "Analyse a decision table with multiple cases along with the context to return one or more values.\nA decision table will be a sequence of case-conditions as in,\n\ncase (condition1) {\n value1\n}\n\ncase (condition2) {\n value2\n}\n\nThe context will be some additional instructions and JSON-like data based on which you can evaluate the conditions and decide which values to return.\nLet's consider an example:\n\n\nanalyseSalesReport --> {\"Acme/salesReport\": {\"employeeId\": 101, \"employeeGrade\": \"A\", \"totalSalesAmount\": 14000}}\n\ncase (totalSalesAmount > 10000) {\n giveIncrementToEmployee\n}\n\ncase (totalSalesAmount > 15000) {\n promoteEmployee\n}\n\ncase (totalSalesAmount < 10000 and employeeGrade == \"A\") {\n demoteEmployee\n}\n\n\nGiven the above context and cases, you must return giveIncrementToEmployee - because the data in the context satisfies only the first case.\nIf the context is,\n\nanalyseSalesReport --> {\"Acme/salesReport\": {\"employeeId\": 101, \"employeeGrade\": \"A\", \"totalSalesAmount\": 16000}}\n\nyou must return giveIncrementToEmployee,promoteEmployee because the data satisfies the first two cases. You must return only the value of the \ncase or cases you selected and no additional text or comments. If you decide to select more than one case, return the values separated by commas.\nAlso select the case that is the best match for the given context, no need to look for a perfect match for all values specified in the context.\nNow apply the same analysis to the following context and cases provided by the user.\n";
export type AgentCondition = {
if: string;
then: string;
internal: boolean;
ifPattern: IfPattern | undefined;
};
export declare function newAgentDirective(cond: string, then?: string, internal?: boolean, ifPattern?: IfPattern | undefined): AgentCondition;
export declare function newAgentDirectiveFromIf(ifPattern: IfPattern): AgentCondition;
export declare function registerAgentDirectives(agentFqName: string, conds: AgentCondition[]): void;
export declare function getAgentDirectives(agentFqName: string): AgentCondition[] | undefined;
export declare function getAgentDirectivesInternal(agentFqName: string): AgentCondition[] | undefined;
export declare function getAgentDirectivesJson(agentFqName: string): string | undefined;
export declare function removeAgentDirectives(agentFqName: string): void;
export declare function addAgentDirective(agentFqName: string, newDirective: AgentCondition): void;
export type AgentScenario = {
user: string;
ai: string;
internal: boolean;
ifPattern: IfPattern | undefined;
};
export declare function newAgentScenario(user: string, ai: string, internal?: boolean, ifPattern?: IfPattern | undefined): AgentScenario;
export declare function newAgentScenarioFromIf(ifPattern: IfPattern): AgentScenario;
export declare function registerAgentScenarios(agentFqName: string, scenarios: AgentScenario[]): void;
export declare function getAgentScenarios(agentFqName: string): AgentScenario[] | undefined;
export declare function getAgentScenariosJson(agentFqName: string): string | undefined;
export declare function getAgentScenariosInternal(agentFqName: string): AgentScenario[] | undefined;
export declare function removeAgentScenarios(agentFqName: string): void;
export declare function addAgentScenario(agentFqName: string, newScn: AgentScenario): void;
export type AgentGlossaryEntry = {
name: string;
meaning: string;
synonyms: string | undefined;
internal: boolean;
};
export declare function newAgentGlossaryEntry(name: string, meaning: string, synonyms: string | undefined, internal?: boolean): AgentGlossaryEntry;
export declare function registerAgentGlossary(agentFqName: string, glossary: AgentGlossaryEntry[]): void;
export declare function getAgentGlossary(agentFqName: string): AgentGlossaryEntry[] | undefined;
export declare function getAgentGlossaryInternal(agentFqName: string): AgentGlossaryEntry[] | undefined;
export declare function getAgentGlossaryJson(agentFqName: string): string | undefined;
export declare function removeAgentGlossary(agentFqName: string): void;
export declare function addAgentGlossaryEntry(agentFqName: string, newEntry: AgentGlossaryEntry): void;
export declare function registerAgentResponseSchema(agentFqName: string, responseSchema: string): void;
export declare function getAgentResponseSchema(agentFqName: string): string | undefined;
export declare function removeAgentResponseSchema(agentFqName: string): void;
export declare function registerAgentScratchNames(agentFqName: string, scratch: string[]): void;
export declare function getAgentScratchNames(agentFqName: string): Set<string> | undefined;
export declare function removeAgentScratchNames(agentFqName: string): void;
//# sourceMappingURL=common.d.ts.map